Start Payment

Description: When a merchant requests /gapi/v1/payment-page GAPI creates a new payment page session.
A header of a request should contain a merchant's terminal key and password to authorize and determine a merchant's terminal to successfully create a new session.
The session has indigenous parameters within the request and the merchant's terminal within the request's header, which influence the entire flow of the session.
As a result, the current endpoint returns a payment page link and corresponding session parameters.
The payment page link is a shareable URL that takes your customers to a hosted payment page on the Payler side.
A payment page link can be shared with everyone and has no restrictions.
HTTP request method: POST
Endpoint: /gapi/v1/payment-page
Headers:
Attribute
R/O
Value
Description
Content-Type
R
application/json
The original media type of the resource
Authorization
R
SessionTerminalKey={key},
SessionTerminalPassword={pass}
SessionTeminalKey - merchant terminal Identifier
SessionTerminalPassword - merchant terminal password
Request attributes:
Attribute
Attribute type
Required
/
Optional
Description
Sample
session.lifetime
int
O
Session lifetime in minutes, from 1 minute or more.
Default value - 15 minutes
​
session.returnURLs.type.{key}
string[100]
O
Type of URL of merchant’s page to which user will be redirected in case of successful or fail flow.
Possible values:
“success” - success flow,
“failure” - fail flow
​
session.returnURLs.type.{key}.url
string[1000]
O
URL value of merchant’s page to which user will be redirected in case of successful or fail flow.
​
session.payment.antifraud
object
O
Additional parameters for the antifraud system.
Number of elements - 70
Key/value string length - 100 Latin characters.
​
session.payment.antifraud[x]
string[100]
pattern - ”antifraud_*”
O
Key - name of additional parameters for the anti-fraud system. You can send any parameters which starts with pattern antifraud_
​
session.payment.antifraud[x].value
string[100]
pattern - ”antifraud_*”
O
Value - value of additional parameters for the anti-fraud system.
​
session.payment.type
string enum
R
Payment type (enumeration).
Possible values:
regular
​
session.payment.isTwoPhase
boolean
O
Required confirmation to complete an operation (2-phase payment)
Default: false
​
session.payment.page.template
string[100]
O
The payment page template to be used while session. If not present, the default template is used.
​
session.payment.page.lang
string[2]
O
Preferred payment page language.
Possible values:
en - English;
ru - Russian.
Default - en
​
session.payment.page.showSavedCards
bool
O
The session feature “saved cards”. Determines the feature mode for saving card data.
If this parameter is true, customer_id must be sent within the request.
Possible values:
false — a regular payment page;
true — a payment page with the ability to select and pay via saved cards or a new card. For a saved card, the user only needs to enter a valid CVV or CVC.
Default - false
​
session.order.id
string[100]
R
An identifier of order within the merchant system to be paid by the Payler payment page.
For each payment intent (session) a unique identifier is required to be sent. Printable ASCII characters are only allowed.
​
session.order.currency
string[3]
R
Payment currency.
Default - EUR
​
session.order.amount
int
R
Order amount in order currency.
Amount should be sent in a currency’s smallest unit.
For example:
An amount of order contains 100 USD and 51 cent should be:
“10051” - an example value for USD currency
Minimal value - 1
10051
session.order.description
string[256]
O
A description of order to be paid during the session
​
session.order.itemsType
string[500]
O
An object of order (product, service etc)
​
session.order.customer.id
string[100]
O
Customer’s identifier.
Defines a user whose list of cards should be available for selection (if session.payment.page.showSavedCards = true), or for whom the card used for payment will be saved.
Must be sent if session.pay.page.showSavedCards is true.
​
session.order.customer.personsData
object
R
The customer's data object is a must to be sent.
​
session.order.customer.personsData.phoneNumber
string[100]
R
The customer's phone number
Validates due to standards:
ITU-T E.123
ITU-T E.164
​
session.order.customer.personsData.firstName
string[100]
R
The customer's name
​
session.order.customer.personsData.lastName
string[100]
R
The customer's last name
​
session.order.customer.personsData.patronymic
string[100]
O
The customer's middle name
​
session.order.customer.personsData.docType
string[100]
O
The customer's document type
​
session.order.customer.personsData.docNumber
string[100]
O
The customer's document number
​
session.order.customer.personsData.country
string[2]
R
Two-letter code of the customer's country of residence in ISO format.
Validates due to standards:
ISO 3166-1 alpha-2
​
session.order.customer.personsData.state
string[100]
R
The customer's state within country of residence
​
session.order.customer.personsData.city
string[100]
R
The customer's city within state and country of residence
​
session.order.customer.personsData.zip
string[100]
R
The customer's zip code
​
session.order.customer.personsData.address
string[100]
R
the customer's full address
​
session.order.customer.email
string[100]
R
the customer's email
​
session.order.additionalFields.quantity
int
O
Mandatory for Russia.
Number of order goods.
​
session.order.additionalFields.tax
decimal
O
Mandatory for Russia.
Tax covers the amount of order.
​
session.order.additionalFields.custom
array
O
Custom fields which desrcibe order’s properties.
To be defined by a merchant in free form.
​
session.order.additionalFields.custom[x].key
string
O
Key of custom field which contains a name of order’s propertie.
​
session.order.additionalFields.custom[x].value
string
O
Value of custom field which contains a value of order’s propertie.
​
Sample of request:
{
   "session":{
      "lifetime":15,
      "returnURLs":{
         "type":[
            {
               "success":{
                  "url":"value"
               },
               "failure":{
                  "url":"value"
               }
            }
         ]
      },
      "payment":{
         "antifraud":{
            "key":"value",
            "key":"value"
         },
         "page":{
            "template":"",
            "lang":"",
            "showSavedCards":false
         }
      },
      "order":{
         "id":"",
         "currency":"",
         "amount":10051,
         "description":"",
         "itemsType":"",
         "customer":{
            "id":"",
            "email":"",
            "personsData":{
               "phoneNumber":"",
               "firstName":"",
               "lastName":"",
               "patronymic":"",
               "docType":"",
               "docNumber":"",
               "country":"",
               "state":"",
               "city":"",
               "zip":"",
               "address":""
            }
         },
         "additionalFields":{
            "custom":[
               {
                  "key":"value",
                  "description":"value"
               },
               {
                  "key":"value",
                  "description":"value"
               }
            ]
         }
      }
   }
}
Response attributes:
Attribute
Attribute type
Required / Optional
Description
Text
session.id
string[100]
R
A session identifier.
​
session.order.id
string[100]
R
An identifier of order within the merchant system to be paid by the Payler payment page.
Corresponds to the request parameter with same name.
​
session.order.amount
int
R
Order amount in order currency.
Amount should be sent in a currency’s smallest unit.
For example:
An amount of order contains 100 USD and 51 cent should be:
“10051” - an example value for USD currency
Minimal value - 1
10051
session.payment.page.url
string[1000]
R
A link to the payment page within session.
To-be shared with customer (end-user).
​
Success sample response:
{
   "session":{
      "id":"value",
      "order":{
         "id":"value",
         "amount":10051
      },
      "payment":{
         "page":{
            "url":"https://url.com/payment_page/:sessionID"
         }
      }
   }
}
Errors
HTTP response status code: 400
session.error[x].invalid-params[x].reason
Description
valueHasExtraLength
the length of value does not meet the field's validation requirement
arrayHasExtraAttributes
the number of array attributes is exceeded within value, which does not meet the field’s validation requirement
objectHasExtraAttributes
the number of object attributes is exceeded within value, which does not meet the field’s validation requirement
valueIsNotPermited
value does not match the predefined list of field validation requirement values
valueIsRequired
value of a required parameter must not be empty according to the field's validation requirement
valueHasWrongFormat
value is not formatted according to the field's validation requirement
Sample:
{
   "session":{
      "id":null,
      "error":[
         {
            "type":"validation-error",
            "title":"Your request attributes didn't validate.",
            "invalid-params":[
               {
                  "name":"session.someKey",
                  "code":"4.20",
                  "reason":"valueHasExtraLength"
               },
               {
                  "name":"session.someKey2",
                  "code":"4.20",
                  "reason":"valueIsNotPermited"
               }
            ]
         }
      ]
   }
}
​
Attribute errors[x].invalid-params[y].name
Attribute errors[x].invalid-params[y].reason
Error code
Error description
session.order.amount
invalidAmount
4.1
An operation amount is incorrect
session.order.id
duplicate
4.3
An attempt to create a payment session with an order identifier, which already has attached to another existing session for current merchant.
session.merchant.password
invalid
4.19
Access is denied.
The provided terminal password is incorrect.
session.order.customer.email
invalid
4.403
Invalid email address value specified
{name of field}
invalidParams
4.20
One of the request parameters has an incorrect value
session.merchant.key
merchantNotFound
4.22
Merchant data not found
 session.merchant.key
terminalNotFound
4.702
The merchant terminal with the specified identifier was not found
order
paidEarlier
4.602
The merchant's order was paid earlier
returnURL
returnURLNotSet
4.701
The redirection URL to the merchant's website after making a payment is not set
session.order.currency
currencyNotSupported
4.703
This currency is not supported
session.order.amount
limitExceeded
4.1102
Maximum operation amount exceeded
session.error[x].invalid-params[x].reason
Description
keyHasExtraLength
key has excess string length
keyIsRequired
required parameter key is missing
keyIsNotPermited
the key does not match the validation structure of the request.
For example, GAPI received a request body that contains keys not provided for by the request structure (the only exception is the case with custom fields for order's properties)
Sample:
{
   "session":{
      "id":null,
      "error":[
         {
            "type":"validation-error",
            "title":"Your request attributes didn't validate.",
            "invalid-params":[
               {
                  "name":"session.someKey",
                  "code":"4.20",
                  "reason":"keyHasExtraLength"
               }
            ]
         }
      ]
   }
}
session.error[x].invalid-params[x].reason
Description
bodyMalformedAtPos{x}
The request body has syntax errors due to JSON RFC 8259.
(x) is the line number where the first request body syntax validation error occurred.
Sample:
{
   "session":{
      "id":null,
      "error":[
         {
            "type":"malformed-request",
            "title":"Your request body didn't validate.",
            "invalid-params":[
               {
                  "name":"body",
                  "code":"4.20",
                  "reason":"bodyMalformedAtPos27"
               }
            ]
         }
      ]
   }
}
Event errors:
Attribute
errors[x].type
Error code
Error description
FacadeDeclined
4.13
The gateway refused to complete the transaction. Need to contact support
NotAllowedByAPI
4.18
This Payler API method is not allowed to be used from the IP address from which the request was made
 inProgressError
4.601
The request is already being processed
 transactionIsNotTwoStep
4.605
It is impossible to perform an operation within a non-two-phase payment
TransactionIsNotAllowed
4.900
The operation is not permitted for the merchant. Need to contact support
temporaryMalfunction
4.904
Temporary problem. Try the operation later
twoPhasePaymentIsNotSupportedByTerminal 
3.2
The terminal does not support two-phase payment execution scheme
Sample:
{
   "session":{
      "id":null,
      "error":[
         {
            "type":"event-error",
            "title":"Event errors caused by the request attributes didn't validate.",
            "invalid-params":[
               {
                  "name":"facadeDeclined",
                  "code":"4.13",
                  "reason":"The gateway refused to complete the transaction. Need to contact support"
               }
            ]
         }
      ]
   }
}

Attribute	Attribute type	Required / Optional	Description	Text
session.id	string[100]	R	A session identifier.
session.order.id	string[100]	R	An identifier of order within the merchant system to be paid by the Payler payment page. Corresponds to the request parameter with same name.
session.order.amount	int	R	Order amount in order currency. Amount should be sent in a currency’s smallest unit. For example: An amount of order contains 100 USD and 51 cent should be: “10051” - an example value for USD currency Minimal value - 1	10051
session.payment.page.url	string[1000]	R	A link to the payment page within session. To-be shared with customer (end-user).

session.error[x].invalid-params[x].reason	Description
valueHasExtraLength	the length of value does not meet the field's validation requirement
arrayHasExtraAttributes	the number of array attributes is exceeded within value, which does not meet the field’s validation requirement
objectHasExtraAttributes	the number of object attributes is exceeded within value, which does not meet the field’s validation requirement
valueIsNotPermited	value does not match the predefined list of field validation requirement values
valueIsRequired	value of a required parameter must not be empty according to the field's validation requirement
valueHasWrongFormat	value is not formatted according to the field's validation requirement

Attribute errors[x].invalid-params[y].name	Attribute errors[x].invalid-params[y].reason	Error code	Error description
session.order.amount	invalidAmount	4.1	An operation amount is incorrect
session.order.id	duplicate	4.3	An attempt to create a payment session with an order identifier, which already has attached to another existing session for current merchant.
session.merchant.password	invalid	4.19	Access is denied. The provided terminal password is incorrect.
session.order.customer.email	invalid	4.403	Invalid email address value specified
{name of field}	invalidParams	4.20	One of the request parameters has an incorrect value
session.merchant.key	merchantNotFound	4.22	Merchant data not found
session.merchant.key	terminalNotFound	4.702	The merchant terminal with the specified identifier was not found
order	paidEarlier	4.602	The merchant's order was paid earlier
returnURL	returnURLNotSet	4.701	The redirection URL to the merchant's website after making a payment is not set
session.order.currency	currencyNotSupported	4.703	This currency is not supported
session.order.amount	limitExceeded	4.1102	Maximum operation amount exceeded

session.error[x].invalid-params[x].reason	Description
keyHasExtraLength	key has excess string length
keyIsRequired	required parameter key is missing
keyIsNotPermited	the key does not match the validation structure of the request. For example, GAPI received a request body that contains keys not provided for by the request structure (the only exception is the case with custom fields for order's properties)

Last modified 1h ago

Attribute	R/O	Value	Description
Content-Type	R	application/json	The original media type of the resource
Authorization	R	SessionTerminalKey={key}, SessionTerminalPassword={pass}	SessionTeminalKey - merchant terminal Identifier SessionTerminalPassword - merchant terminal password

Attribute	Attribute type	Required / Optional	Description	Sample
session.lifetime	int	O	Session lifetime in minutes, from 1 minute or more. Default value - 15 minutes
session.returnURLs.type.{key}	string[100]	O	Type of URL of merchant’s page to which user will be redirected in case of successful or fail flow. Possible values: “success” - success flow, “failure” - fail flow
session.returnURLs.type.{key}.url	string[1000]	O	URL value of merchant’s page to which user will be redirected in case of successful or fail flow.
session.payment.antifraud	object	O	Additional parameters for the antifraud system. Number of elements - 70 Key/value string length - 100 Latin characters.
session.payment.antifraud[x]	string[100] pattern - ”antifraud_*”	O	Key - name of additional parameters for the anti-fraud system. You can send any parameters which starts with pattern antifraud_
session.payment.antifraud[x].value	string[100] pattern - ”antifraud_*”	O	Value - value of additional parameters for the anti-fraud system.
session.payment.type	string enum	R	Payment type (enumeration). Possible values: regular
session.payment.isTwoPhase	boolean	O	Required confirmation to complete an operation (2-phase payment) Default: false
session.payment.page.template	string[100]	O	The payment page template to be used while session. If not present, the default template is used.
session.payment.page.lang	string[2]	O	Preferred payment page language. Possible values: en - English; ru - Russian. Default - en
session.payment.page.showSavedCards	bool	O	The session feature “saved cards”. Determines the feature mode for saving card data. If this parameter is true, customer_id must be sent within the request. Possible values: false — a regular payment page; true — a payment page with the ability to select and pay via saved cards or a new card. For a saved card, the user only needs to enter a valid CVV or CVC. Default - false
session.order.id	string[100]	R	An identifier of order within the merchant system to be paid by the Payler payment page. For each payment intent (session) a unique identifier is required to be sent. Printable ASCII characters are only allowed.
session.order.currency	string[3]	R	Payment currency. Default - EUR
session.order.amount	int	R	Order amount in order currency. Amount should be sent in a currency’s smallest unit. For example: An amount of order contains 100 USD and 51 cent should be: “10051” - an example value for USD currency Minimal value - 1	10051
session.order.description	string[256]	O	A description of order to be paid during the session
session.order.itemsType	string[500]	O	An object of order (product, service etc)
session.order.customer.id	string[100]	O	Customer’s identifier. Defines a user whose list of cards should be available for selection (if session.payment.page.showSavedCards = true), or for whom the card used for payment will be saved. Must be sent if session.pay.page.showSavedCards is true.
session.order.customer.personsData	object	R	The customer's data object is a must to be sent.
session.order.customer.personsData.phoneNumber	string[100]	R	The customer's phone number Validates due to standards: ITU-T E.123 ITU-T E.164
session.order.customer.personsData.firstName	string[100]	R	The customer's name
session.order.customer.personsData.lastName	string[100]	R	The customer's last name
session.order.customer.personsData.patronymic	string[100]	O	The customer's middle name
session.order.customer.personsData.docType	string[100]	O	The customer's document type
session.order.customer.personsData.docNumber	string[100]	O	The customer's document number
session.order.customer.personsData.country	string[2]	R	Two-letter code of the customer's country of residence in ISO format. Validates due to standards: ISO 3166-1 alpha-2
session.order.customer.personsData.state	string[100]	R	The customer's state within country of residence
session.order.customer.personsData.city	string[100]	R	The customer's city within state and country of residence
session.order.customer.personsData.zip	string[100]	R	The customer's zip code
session.order.customer.personsData.address	string[100]	R	the customer's full address
session.order.customer.email	string[100]	R	the customer's email
session.order.additionalFields.quantity	int	O	Mandatory for Russia. Number of order goods.
session.order.additionalFields.tax	decimal	O	Mandatory for Russia. Tax covers the amount of order.
session.order.additionalFields.custom	array	O	Custom fields which desrcibe order’s properties. To be defined by a merchant in free form.
session.order.additionalFields.custom[x].key	string	O	Key of custom field which contains a name of order’s propertie.
session.order.additionalFields.custom[x].value	string	O	Value of custom field which contains a value of order’s propertie.

session.error[x].invalid-params[x].reason	Description
bodyMalformedAtPos{x}	The request body has syntax errors due to JSON RFC 8259. (x) is the line number where the first request body syntax validation error occurred.

Attribute errors[x].type	Error code	Error description
FacadeDeclined	4.13	The gateway refused to complete the transaction. Need to contact support
NotAllowedByAPI	4.18	This Payler API method is not allowed to be used from the IP address from which the request was made
inProgressError	4.601	The request is already being processed
transactionIsNotTwoStep	4.605	It is impossible to perform an operation within a non-two-phase payment
TransactionIsNotAllowed	4.900	The operation is not permitted for the merchant. Need to contact support
temporaryMalfunction	4.904	Temporary problem. Try the operation later
twoPhasePaymentIsNotSupportedByTerminal	3.2	The terminal does not support two-phase payment execution scheme