Payler API Specifications

AED

United Arab Emirates dirham

Both

ARS

Argentine Peso

Both

AUD

Australian dollar

Both

AZN

Azerbaijani manat

Both

BRL

Brazilian real

Both

CAD

Canadian dollar

Both

CNY

Chinese yuan

Both

EUR

Euro

Both

EGP

Egyptian Pound

Both

GBP

Sterling

Both

IDR

Indonesian rupiah

Both

INR

Indian rupee

Both

KRW

South Korean won

Payments

MYR

Malaysian ringgit

Both

MAD

Moroccan Dirham

Both

NGN

Nigerian naira

Both

NZD

New Zealand dollar

Both

PKR

Pakistani rupee

Payments

PLN

Polish zloty

Payments

THB

Thai baht

Both

TRY

Turkish lira

Both

TWD

New Taiwan dollar

Payments

USD

United States dollar

Both

UZS

Uzbekistani som

Payments

VND

Vietnamese dong

Both

applepay

At checkout, a payer:

1. Selects Apple Pay and is redirected to the payment page.

2. Chooses the payment method.

3. The payment is confirmed.

Note: a refund for this payment method requires assistance from the support team. Merchants seeking a refund must directly reach out to our support team with their request.

EUR

bancontact

For payments in Belgium.

EUR

bankdeposit

Depositing funds directly into a recipient's bank account.

NGN, IDR

banktransfer

1. At checkout, a payer selects the Bank Transfer payment method.

1. Secure website with the recipient details (an account number) opens.

2. The payer makes a transfer using their banking app.

3. The payment is confirmed.

KRW, TWD, MAD

banktransfer (Brazil)

At checkout, a payer selects the banktransfer payment method, enters personal details, scans a QR code, and completes the transaction with their banking app. Note: a refund for this payment method requires assistance from the support team. Merchants seeking a refund must directly reach out to our support team with their request.

BRL

banktransferp2p

At checkout, a payer:

1. Selects BankTransferP2P and is redirected to the BankTransferP2P website.

2. Chooses a bank.

3. Logs into the online banking to complete the transfer directly.

Note: a refund for this payment method requires assistance from the support team. Merchants seeking a refund must directly reach out to our support team with their request. Only one partial refund is allowed for each transaction.

TRY

blik

Payer provides and confirms a code in their banking app.

For payments in Poland.

PLN

boleto

At checkout, a payer selects the boleto payment method, enters personal details, scans a QR code, and completes the transaction with their banking app.

Note: a refund for this payment method requires assistance from the support team. Merchants seeking a refund must directly reach out to our support team with their request.

BRL

cards

Payment is performed by entering card details linked to a debit or credit account.

All supported currencies

fastpayment

At checkout, a payer is redirected to their banking app, where they pay the invoice issued through the fast payment system.

*Check available currencies with your account manager

jazzcash

At checkout, a payer:

1. Enters their mobile number in the payment form.

2. Receives a payment request in the Jazzcash mobile app.

3. Confirms the transaction by authorizing it with their PIN.

PKR

ideal

1. To process a payment, a payer either chooses a bank and scans the QR code or provides a personal identifier.

1. After the payment is completed, the payer returns to the merchant's site with the payment confirmation.

2. The merchant receives a payment notification via a callback.

For payments in the Netherlands.

EUR

instapay

The payment is completed via Insta Pay system using the recipient's phone number or Insta Pay ID.

EGP

interac

At checkout, a payer:

• Receives payment instructions, including a deposit email, security question, and answer.

• Logs into their online banking app and completes the transfer manually.

• Once the payment is received, a webhook notifies that the order status is updated.

CAD

khipu

Khipu is an electronic payment platform that enables secure and fast online transactions. It integrates with multiple banks, allowing users to pay directly from their bank accounts without needing a credit card. Khipu provides a reliable and secure solution for handling online payments.

ARS

lemoncash

Payment is processed via Lemon Cash app through a user-initiated transfer to a system-assigned account. Funds are processed and reflected in the user's balance shortly after.

ARS

mcommerce

Payment is performed via Payment Merchant scheme by providing a phone number as a payment detail identifier. The transaction is confirmed using an authorization code sent to the client via SMS to the provided phone number

KZT

mercadopago

Payment is processed via Mercado Pago app through a user-initiated transfer to a system-assigned account. Funds are processed and reflected in the user's balance shortly after.

ARS

netbanking

Payment is performed online using bank-provided credentials, directly accessing and debiting the user's bank account. Note: multiple merchants can use the NetBanking payment method simultaneously by employing distinct credentials.

INR

openbanking

Payment is performed via an online banking interface, allowing direct bank-to-bank transactions under the user's control without sharing sensitive account details. Note: for this method, transaction limits depend on the currency.

EUR, GBP

orangecash

The payment is completed via Orange Cash system using the recipient's phone number.

EGP

p2p

Payment is carried out directly between individuals by transferring funds from one person's account to another's.

CNY

p2ppcr

At checkout, a payer:

1. Selects the payment method (phone number, card, or IBAN).

2. Receives payment details.

3. Makes a transfer using their banking app.

4. Confirms the payment

AZN, UZS, TRY

papara

At checkout, a payer:

1. Selects Papara and is redirected to the Papara website.

2. Chooses a bank.

3. Logs into the online banking to complete the transfer directly.

Note: a refund for this payment method requires assistance from the support team. Merchants seeking a refund must directly reach out to our support team with their request. Only one partial refund is allowed for each transaction.

TRY

paybol

At checkout, a payer:

1. Selects Paybol and is redirected to the Paybol website.

2. Chooses a bank.

3. Logs into the online banking to complete the transfer directly.

Note: a refund for this payment method requires assistance from the support team. Merchants seeking a refund must directly reach out to our support team with their request. Only one partial refund is allowed for each transaction.

TRY

payfix

At checkout, a payer:

1. Selects Payfix and is redirected to the Payfix website.

2. Chooses a bank.

3. Logs into the online banking to complete the transfer directly.

Note: a refund for this payment method requires assistance from the support team. Merchants seeking a refund must directly reach out to our support team with their request. Only one partial refund is allowed for each transaction

TRY

payid

The payment is performed using an easy-to-remember identifier, like a phone number or email, linked to a bank account.

AUD

payster

The payment is performed using an easy-to-remember identifier, like a phone number or email, linked to a bank account. Bank code and account number are also available.

AUD, NZD

picpays

At checkout, a payer selects the picpays payment method, enters personal details, scans a QR code, and completes the transaction with their banking app.

Note: a refund for this payment method requires assistance from the support team. Merchants seeking a refund must directly reach out to our support team with their request.

BRL

pix

At checkout, a payer selects the pix payment method, enters personal details, scans a QR code, and completes the transaction with their banking app.

Note: a refund for this payment method requires assistance from the support team. Merchants seeking a refund must directly reach out to our support team with their request.

BRL

poli

At checkout, a payer:

1. Selects POLi and is redirected to the POLi website.

2. Chooses a bank.

3. Logs into the online banking to complete the transfer directly.

NZD

qrcode

Payment is made by scanning a QR code using a smartphone.

BRL, THB, VND, IDR, MYR

rapipago

Rapipago is a prepaid online payment method that allows users in Argentina to pay for online purchases and bills in cash at convenient locations.

When using Rapipago, users receive a bill with a barcode or payment code that they can enter or scan using the RapiPago app. Payments can be made online through the app or offline at one of over 6,000 Rapipago locations.

ARS

SCP

1. At checkout, a payer selects the SCP (Supermarket Code Pay) payment method.

2. The payer selects a supermarket, e.g., IBON, Hi-Life, or FamiPort.

3. The payer receives an invoice for payment.

4. The payer pays from the invoice at the selected supermarket.

TWD

sepa

For a payment in one of the SEPA countries, a payer makes a bank transfer to the account specified in the recipient details.

EUR

sepaqr

For a payment in one of the SEPA countries, a payer scans a displayed QR code and confirms the payment in their banking app.

EUR

unionpay

Payment is performed by either:

• entering UnionPay card number,

• (if the UnionPay application is used) scanning a QR code.

CNY

upi

Payment is performed through a mobile application by entering a unique UPI ID, allowing to process money transfers without revealing bank details.

INR

vodafonecash

The payment is completed via Vodafone Cash system using the recipient's phone number.

EGP

wallet

Payment is completed using a digital wallet.

CNY

zenpay

For payments in all countries of Europe, excluding the prohibited.

EUR

banktransfer

Payout is performed by entering the customer’s bank account number with a b bank code.

KRW, TWD, MAD

cards

Payout is performed by entering card details linked to a debit or credit account.

All supported currencies

communitybank

Payout is made on a customer's bank account.

TRY

instapay

The payout is sent via Insta Pay using a phone number or Insta pay id.

EGP

interac

To initiate a payout, provide the recipient’s email and phone number along with the transfer amount. The recipient is notified via email:

• If Auto-Deposit is enabled, the funds are deposited automatically.

• Otherwise, the recipient must manually accept the transfer through their online banking.

Both the merchant and the recipient receive confirmation once the funds have been successfully added.

CAD

netbanking

Payout is performed online using bank-provided credentials, directly accessing and debiting the user's bank account.

INR

orangecash

The payout is sent via Orange Cash using a phone number.

EGP

payfix

Payout is made on a customer's PayFix wallet.

TRY

payster

Payout is performed by using an easy-to-remember identifier, like a phone number or email, linked to a bank account for transactions.

AUD, NZD

payid

Payout is performed by using an easy-to-remember identifier, like a phone number or email, linked to a bank account for transactions.

AUD

pcr

Payment is made on a customer's card or bank account.

AZN, TRY, UZS

sepainstant

For instant payouts on a customer's IBAN registered in the SEPA region.

EUR

vodafonecash

The payout is sent via Vodafone Cash using a phone number.

EGP

noPaymentsFound

The payment session is registered in the gateway, but processing hasn't started yet.

Payments

tryAnotherPayment

Internal status: the payment attempt within the session failed, yet another attempt with the same payment method is permissible.

Payments

ppTriesNumberIsExceeded

Internal status: all payment attempts with the payment method failed, but another attempt with another payment method is permissible.

Payments

rejected

All payment attempts within the payment session have failed, and no more attempts is permissible.

Both

+

expired

The time allowed to make the payment has expired.

Both

+

authorized

The payment/payout session has been successfully completed.

Both

+

preAuthorized

The first phase of a two-phase payment has been completed, the funds have been blocked.

Payments

+

refunded

The full refund of funds has been successfully processed.

Payments

+

cancelled

The funds previously blocked on the card have been fully released.

Payments

+

pending

Payment was initiated but hasn't been completed yet.

Payments

error

Unexpected error occurred. If the error keeps occuring, contact support.

Both

+

actionRequired

To continue the payment, a merchant must perform a certain action, for example:

• Redirect the client to the specified page for entering payment details or authenticating a card payment.

• Invite the client to make a payment using their banking app.

• Send the transaction confirmation code received by the client.

Description of the required action is provided in the 'action' response object.

Payments

+

waitingForCustomerAction

The payout session is active, but there are either:

• no payout atempts, or

• payout attempts are either rejected or led to an error, but there are other payout methods available for this session.

Payouts

cancelledByCustomer

Customer declined the payment or payout attempt and returned to the merchant page.

Both

+

sessionId

string[100]

R

Session identifier.

9073926b929f31c2abc9fad77ae3e8eb

orderId

string[100]

R

Order identifier within the merchant system.

d1434908-7260-483e-8254-fa43af1b835d

state

string[100]

R

Payment/payout state.

authorized

method

string[100]

R

Payment or payout method.

cards

amount

long

R

Amount of the payment, taking into account all unblockings and refunds made. Presented in the payment currency using the smallest unit of that currency. Amount may change in a new callback after a successful or rejected payment. Relevant for methods: papara, paybol, payfix, havale, payid etc. Contact please our support team to update the list of methods.

10051 (for an amounting to 100 dollars and 51 cents in USD)

updated

string[100] (ISO 8601)

R

Date and time when the status was set.

2022-02-12T11:22:33.145Z

action.type

string

O

The type of additional action expected from the merchant to continue the payment process. Filled if the status is 'actionRequired'. Possible values are:

• 'confirmPayment' - the merchant must offer the user to make a payment using the details specified in the 'action.details' parameter and, after payment, call the Confirm Payment method.

action.details

object

O

Payment details to make payment in case 'confirmPayment' type.

token

string[100]

R

Message signature.

37ca0f78f59bfd62d5d349e9666d05a405c1a6813f6fee9b666fd3e9142f2432

Content-Type

R

application/json

Original media type of the resource.

SessionTerminalKey

R

Merchant terminal identifier.

SessionTerminalPassword

R

Merchant terminal password.

session.lifetime

int

O

Session lifetime in minutes. You can set it to 20 minutes or more. The default is 20 minutes.

session.returnURLs.default.url

string[1000]

R

The URL to redirect a user if a transaction does not achieve its final status.

session.returnURLs.success.url

string[1000]

O

The URL to redirect a user if a payment is successful. If this URL is not provided, the session.returnURLs.default.url is used.

session.returnURLs.failure.url

string[1000]

O

The URL to redirect a user if the payment is not successful. If this URL is not provided, the session.returnURLs.default.url is used.

session.notificationUrl

string[1000]

O

The URL for receiving notifications (callbacks) about payment statuses. If this URL is not provided, callbacks are not sent.

session.payment.antifraud

object

O

Additional parameters for the antifraud system. A maximum of 70 elements is allowed. Both keys and values should be strings, limited to 100 Latin characters each. Keys must follow the pattern “antifraud_*”. Example: {

“antifraud_1”: “some_value1”,

“antifraud_2”: “some_value2”

}

session.payment.type

string enum

R

The possible payment types are:

• regular: a standard payment.

• tokenized: a recurring payment that uses a token from a saved card.

If the type is not specified, the default value is regular.

session.payment.createPaymentToken

bool

O

The parameter states if there is a need to create a token for recurring payments:

• true: creates a token for future payments.

• false: does not create a token.

If this parameter is not specified, or if the request is for creating a payment with an existing token, the default value is false.

session.payment.page.lang

string[2]

O

The language is always en (English).

session.order.id

string[100]

R

A unique order ID within the merchant system. Each payment session (intent) requires this ID.

Only printable ASCII characters are permitted.

session.order.currency

string[3]

R

Payment currency in the ISO 4217 format. Example: USD

session.order.amount

int

R

Order amount in the smallest unit of the currency. For example, if the payment is in EUR, the amount of 10050 means 100 EUR and 50 cents.

session.order.description

string[250]

O

Order description.

session.order.itemsType

string

O

Specific product, service, or item that is the subject of an order.

session.order.customer.id

string[100]

O*

Customer’s identifier. *Required for payid payment method

session.order.customer.email

string [100]*

R

Customer's email address.

*For banktransfer method, the max length is 45.

session.order.customer.personsData

object

R

Customer's personal data.

If customer's data (including email) is not real, payments will be rejected by antifraud system

session.order.customer.personsData.phoneNumber

string [100]*

R

Customer's phone number must adhere to the ITU-T E.123 and ITU-T E.164 standards.

*For the banktransfer method, the max length is 15.

For the applepay method, the phone number must contain numbers only, and its length must be between 8 and 15 symbols.

session.order.customer.personsData.firstName

string [100]*

O*

Customer's first name.

*For the banktransfer method, the max length is 45.

For the upi method, the max length is 40.

For the openbanking, the max length is 25. *Required for these payment methods: payid openbanking

applepay

session.order.customer.personsData.lastName

string [100]*

O*

Customer's last name.

*For the banktransfer method, the max length is 45. For the upi method, the max length is 40. For the openbanking, the max length is 25. *Required for these payment methods: payid openbanking

applepay

session.order.customer.personsData.country

string[2]

O*

Customer's country of residence in the ISO 3166-1 alpha-2 format. Example: GB

*Required for these payment methods:

applepay, netbanking, bankdeposit, qrcode, wallet, p2p, openbanking, rapipago, khipu, banktransfer, sepa, sepaqr

The parameter is also required for certain card-method transactions. Contact support for more details.

session.order.customer.personsData.state

string[100]

O*

Customer's state code.

*Required for these payment methods: netbanking, bankdeposit, qrcode, wallet, p2p

The parameter is also required for certain card-method transactions. Contact support for more details

session.order.customer.personsData.city

string [100]**

O*

Customer's city.

*Required for these payment methods: netbanking, bankdeposit, qrcode, wallet, p2p, banktransfer

The parameter is also required for certain card-method transactions. Contact support for more details. **For the banktransfer method, the max length is 45

session.order.customer.personsData.zip

string [100]**

O*

Customer's zip code.

*Required for these payment methods: netbanking, bankdeposit, qrcode, wallet, p2p, banktransfer

The parameter is also required for certain card-method transactions. Contact support for more details. **For the banktransfer method, the max length is 45.

session.order.customer.personsData.address

string [100]**

O*

Customer's address.

*Required for these payment methods: netbanking, bankdeposit, qrcode, wallet, p2p, banktransfer

The parameter is also required for certain card-method transactions. Contact support for more details. **For the banktransfer method, the max length is 45.

session.order.additionalFields.custom

array

O

Fields are defined by a merchant in a free form to describe specific properties of the order.

session.order.additionalFields.custom[x].key

string

O

Identifier of a custom field.

session.order.additionalFields.custom[x].description

string

O

Content within a custom field.

session.id

string[100]

R

Payment session ID.

9073926b929f31c2abc9fad77ae3e8eb

session.order.id

string[100]

R

Unique order ID in the merchant system.

session.order.amount

int

R

The total amount of the order expressed in the smallest unit of its currency.

10051

session.payment.page.url

string[1000]

O

A URL linking to the payment page for the current session, intended to be shared with the customer (end-user). Note that a URL is not generated for a recurring payment session using a payment token (if session.paymentType = tokenized).

Content-Type

R

application/json

Original media type of the resource.

SessionTerminalKey

R

Merchant terminal identifier.

SessionTerminalPassword

R

Merchant terminal password.

sessionId

string

R

Payment session ID.

9073926b929f31c2abc9fad77ae3e8eb

paymentToken

string

R

Token used to create recurring payments.

session.id

string[100]

R

Payment session ID.

9073926b929f31c2abc9fad77ae3e8eb

session.payment.state

string[100]

R

Payment state.

authorized

session.payment.method

string[100]

O

Payment method.

cards

Content-Type

R

application/json

Original media type of the resource.

Cache-Control

R

no-cache

Retrieving the response directly from the server, bypassing caches, guarantees the latest payment status.

session.id

string[100]

R

Payment session ID.

9073926b929f31c2abc9fad77ae3e8eb

session.payment.state

string[100]

R

Payment state.

authorized

session.payment.method

string[100]

O

Payment method.

cards

session.payment.amount

int

R

Balance of the payment, taking into account all unblockings and refunds made. Presented in the the smallest unit of the payment currency. For example, if the payment is in EUR, the amount of 10050 means 100 EUR and 50 cents.

10051 (for an amounting to 100 dollars and 51 cents in USD)

session.payment.paymentToken

string

O

Recurring payment token identifier.

Content-Type

R

application/json

Original media type of the resource.

Cache-Control

R

no-cache

Retrieving the response directly from the server, bypassing caches, guarantees the latest payment status.

SessionTerminalKey

R

Merchant terminal identifier.

SessionTerminalPassword

R

Merchant terminal password.

sessionId

string

R

Payment session ID

9073926b929f31c2abc9fad77ae3e8ey

session.refund.amount

int

R

The amount to be refunded. This value must not exceed the total amount of the original transaction (specified in session.order.amount).

Use the smallest unit of the payment currency. The minimum acceptable value is 1.

10051 (100 dollars and 51 cents if the currency is USD)

Content-Type

R

application/json

Original media type of the resource.

SessionTerminalKey

R

Merchant terminal identifier.

SessionTerminalPassword

R

Merchant terminal password.

session.lifetime

int

O

Session lifetime in minutes. You can set it to 20 minutes or more. The default is 20 minutes.

session.returnURLs.default.url

string[1000]

R

The URL to redirect a user if a transaction does not achieve its final status.

session.returnURLs.success.url

string[1000]

O

The URL to redirect a user if a payment is successful. If this URL is not provided, the session.returnURLs.default.url is used.

session.returnURLs.failure.url

string[1000]

O

The URL to redirect a user if the payment is not successful. If this URL is not provided, the session.returnURLs.default.url is used.

session.notificationUrl

string[1000]

O

The URL for receiving notifications (callbacks) about payout statuses. If this URL is not provided, callbacks are not sent.

session.payout.antifraud

object

O

Additional parameters for the antifraud system. A maximum of 70 elements is allowed. Both keys and values should be strings, limited to 100 Latin characters each. Keys must follow the pattern “antifraud_*”. Example: {

“antifraud_1”: “some_value1”,

“antifraud_2”: “some_value2”

}

session.payout.type

string enum

R

The type is always regular (standard payout).

session.payout.page.lang

string[2]

O

The language is always en (English).

session.order.id

string[100]

R

A unique order ID within the merchant system. Each payout session requires this ID.

Only printable ASCII characters are permitted.

session.order.currency

string[3]

R

Payout currency in the ISO 4217 format.

Example: USD

session.order.amount

int

R

Order amount in the smallest unit of the currency. For example, if the payout is in EUR, the amount of 10050 means 100 EUR and 50 cents.

session.order.description

string[250]

O

Additional order details.

session.order.itemsType

string

O

Specific product, service, or item that is the subject of an order.

session.order.customer.id

string[100]

O

Customer’s identifier.

session.order.customer.personsData

object

O

Customer's personal data. If customer's data (including email) is not real, payout will be rejected by antifraud system

session.order.customer.personsData.phoneNumber

string[100]

R

Customer's phone number must adhere to the ITU-T E.123 and ITU-T E.164 standards.

session.order.customer.personsData.firstName

string[100]

R

Customer's first name.

session.order.customer.personsData.lastName

string[100]

R

Customer's last name.

session.order.customer.personsData.country

string[2]

O

Customer's country of residence in the ISO 3166-1 alpha-2 format. Example: GB

session.order.customer.email

string[100]

R

Customer's email address. If customer's email is not real, payout will be rejected by antifraud system

session.order.additionalFields.custom

array

O

Fields are defined by a merchant in a free form to describe specific properties of the order.

session.order.additionalFields.custom[x].key

string

O

Identifier of a custom field.

session.order.additionalFields.custom[x].value

string

O

Content within a custom field.

session.id

string

R

Payout session ID.

9073926b929f31c2abc9fad77ae3e8eb

session.order.id

string[100]

R

Unique order ID in the merchant system.

session.order.amount

int

R

The total amount of the order expressed in the smallest unit of its currency.

10051

session.payout.page.url

string

O

A URL linking to the payout page for the current session, intended to be shared with the customer (end-user).

Content-Type

R

application/json

Original media type of the resource.

Cache-Control

R

no-cache

Retrieving the response directly from the server, bypassing caches, guarantees the latest payout status.

sessionId

string

R

Payout session ID.

9073926b929f31c2abc9fad77ae3e8eb

session.id

string[100]

R

Payout session ID.

9073926b929f31c2abc9fad77ae3e8eb

session.payout.state

string[100]

R

Payout state.

authorized

session.payout.method

string[100]

O

Payout method.

cards

session.payout.amount

long

R

Total payout amount in the smallest unit of its currency. For example, if the payout is in EUR, the amount of 10050 means 100 EUR and 50 cents.

10050

session.id

string[100]

R

Payment or payout session ID.

session.error.type

string

R

Internal error code. Use it when reaching out to technical support.

session.error.title

string

R

Error description.

malformedRequest validationError

400

Your request body didn't validate.

Includes the invalid-params array of the incorrect parameters.

invalidAmount

400

Invalid amount of the transaction.

The error occurs if:

• the provided amount isn't a positive integer,

• the refunded amount exceeds the original order amount.

duplicatedOrderId

400

Duplicated order id.

The error occurs if a payment with the same order ID already exists.

currencyNotSupported

400

This currency is not supported.

See a list of supported currencies.

methodNotSupported

400

This payment method is not supported.

See a list of payment and payout methods.

insufficientMerchantFundsToCompleteRefund

400

The refund was created. There are not enough funds on the merchant's balance to complete the refund.

invalidPaymentState

400

The payment is in an invalid state.

The error occurs if no corresponding payments were found for the refund. The payment within the session must be authorized.

multipleRefundNotSupported

400

Subsequent refunds are not supported in the automatic mode. Contact to our support team.

The error occurs in a case of a second refund appempt, which some payment providers don't support.

partialRefundNotAllowed

400

Can not refund a part of the previously charged amount.

The error occurs in a case of a partial refund appempt, which some payment providers don't support.

invalidTerminalCredentials

400

Invalid terminal key or password.

invalidTerminalSettings

400

Terminal settings are invalid.

Contact our support team.

sessionNotFound

404

There is no session with the specified id.

interfaceNotAllowed

422

This interface is not allowed.

The error occurs if the GAPI interface for the requested transaction direction (payment/payout) isn't allowed.

twoPhasePaymentIsNotSupportedByTerminal

422

Two-phase payments aren't supported by a terminal.

facadeDeclined

500

Unexpected error. Contact to our support team.

temporaryMalfunction

503

Temporary malfunction. Please try again later.

arrayHasExtraAttributes

Array attribute contains extra elements beyond the expected count.

keyHasExtraLength

Key exceeds its maximum length limit.

keyIsRequired

Mandatory attribute key is missing.

keyIsNotPermited

Unexpected attribute key is provided.

malformedRequest

Request body isn't a correct JSON object.

objectHasExtraAttributes

Object attribute contains unexpected attributes.

valueIsNotPermited

Value does not match the defined enumeration for the attribute.

valueIsRequired

Value must be provided. Empty and null values are not acceptable.

valueHasExtraLength

Value exceeds its maximum length limit.

valueHasWrongFormat

Value format differs from the expected format.

Content-Type

R

application/json

The original media type of the resource.

AuthorizationKey

R

Merchant terminal identifier.

AuthorizationPassword

R

Merchant terminal password.

order

object

R

Order parameters

order.id

string[100]

R

Unique identifier for the order within the merchant's system. Each payment (session) requires a distinct identifier. Only printable ASCII characters are allowed.

order.currency

string[3]

R

Currency of the payment.

order.amount

long

R

Order amount in the smallest units of the order's currency, as an integer.

12356

order.description

string[256]

O

Description of the order, payment.

type

string enum

R

Payment type:

• regular - standard payment;

• tokenized - recurring payment using a token from a saved card.

If the type is not specified, the default value is regular.

regular

method

string

R

Payment method. Possible values: Payment methods

interac

createPaymentToken

bool

O

Determines the need to create a token for recurring payments.

Possible values:

• true - Creates a token for future payments.

• false - Does not create a token.

If this parameter is not specified, or if the request is for creating a payment with an existing token, the default value is false.

false

details

object

O

Parameters depend on the selected payment method:

• cards

• mcommerce

• pcr

• interac

• upi

• openbanking

• boleto, picpays, pix, and banktransfer (Brazil)

You can check a list of required parameters by sending the Retrieve Payment Method Details request.

customer

object

R

Merchant's customer payment details. If customer's data (including email) is not real, payments will be rejected by antifraud system

customer.id

string[100]

O

Merchant's system identifier for the customer.

customer.email

string[100]*

R

Customer's email address. *For the banktransfer and SCP methods, the max length is 50.

customer.phoneNumber

string[100]*

R

Customer's phone number.

*For the banktransfer and SCP methods, the max length is 15.

customer.firstName

string[100]*

R

First name.

*For the banktransfer and SCP methods, the max length is 50. For the upi method, the max length is 40.

customer.lastName

string[100]*

R

Last name.

*For the banktransfer and SCP methods, the max length is 50. For the upi method, the max length is 40.

customer.documentType

string[100]

O

Type of identification document.

customer.documentNumber

string[100]

O

Identification document number.

customer.address

object

O*

Customer's billing address. *Required for a number of APM (non-cards) payment methods. The parameter is also required for certain card-method transactions. Contact support for more details.

customer.address.addressLine

string[100]**

O*

Address *Required when the merchant performs payments via one of the following payment methods: netbanking, bankdeposit, banktransfer, qrcode, wallet, p2p, SCP

**For the banktransfer and SCP methods, the max length is 50.

customer.address.city

string[100]**

O*

City *Required when the merchant performs payments via one of the following payment methods: netbanking, bankdeposit,banktransfer, qrcode, wallet, p2p, SCP

The parameter is also required for certain card-method transactions. Contact support for more details. **For the banktransfer and SCP methods, the max length is 50.

customer.address.country

string[2]

O*

Two-letter ISO country code of the customer's residence. *Required when the merchant performs payments via one of the following payment methods:

applepay, netbanking, bankdeposit, banktransfer, qrcode, wallet, p2p, openbanking, rapipago, khipu, sepa, sepaqr, SCP The parameter is also required for certain card-method transactions. Contact support for more details.

GB

customer.address.state

string[100]

O*

State/Region *Required when the merchant performs payments via one of the following payment methods: netbanking, bankdeposit, qrcode, wallet, p2p The parameter is also required for certain card-method transactions. Contact support for more details.

customer.address.postalCode

string[100]**

O*

Postal code *Required when the merchant performs payments via one of the following payment methods: netbanking, bankdeposit,banktransfer, qrcode, wallet, p2p, SCP

The parameter is also required for certain card-method transactions. Contact support for more details. **For the banktransfer and SCP methods, the max length is 10.

sessionContext

object

R

Parameters describing the customer session context.

sessionContext.ip

string[100]

R

IP address of the payer's device.

sessionContext.languageCode

string[2]

O

The language is always en (English).

sessionContext.browserParameters

object

R

Browser parameters of the payer.

sessionContext.browserParameters.accept

string[2000]

R

Browser's Accept header of the payer.

sessionContext.browserParameters.language

string[35]

R

Value representing the Browser language as defined in IETF BCP47. Returned from navigator.language property

Without special validation rules.

sessionContext.browserParameters.userAgent

string[2048]

R

Exact content of the HTTP user-agent header. Without special validation rules.

sessionContext.browserParameters.javaEnabled

bool

R

Boolean that represents the ability of the Cardholder Browser to execute Java. Without special validation rules.

sessionContext.browserParameters.javascriptEnabled

bool

R

Boolean that represents the ability of the Cardholder Browser to execute JavaScript. Without special validation rules.

sessionContext.browserParameters.screenHeight

string[6]

R

Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property.

Special validation rules: only numeric symbols

sessionContext.browserParameters.screenWidth

string[6]

R

Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property.

Special validation rules: only numeric symbols

sessionContext.browserParameters.colorDepth

string[2]

R

Value representing the bit depth of the colour palette for displaying images, in bits per pixel.

Obtained from the Cardholder Browser using the screen.colorDepth property.

Special validation rules:

possible numeric value from 1 to 99.

sessionContext.browserParameters.tz

string[5]

R

Time zone offset in minutes between UTC and the Cardholder Browser local time. Without special validation rules.

+180

returnUrls

object

R

URLs for redirecting back to the merchant's page.

returnUrls.default

string[2000]

R

Default, used for returning to the merchant's payment page from Payler's service pages if the payment is in a non-final status.

returnUrls.success

string[2000]

O

Used for returning to the merchant's payment page from Payler's service pages in case of success (if not specified, returnUrls.default will be used)

returnUrls.failure

string[2000]

O

Used for returning to the merchant's payment page from Payler's service pages in case of failure (if not specified, returnUrls.default will be used)

notificationUrl

string[2000]

O

Merchant's URL for receiving notifications about payment status changes. If not provided, notifications are not performed.

antifraudParameters

object

O

Antifraud parameters. Each property of the object represents a separate parameter, where the property name is the parameter name, and the property value is the parameter value. Properties are strings: "param_name": "param_value"

type

string, enum[“card”, “tokenized“]

R

Possible payment requisite types are:

• cards if card parameters are the requisites.

• tokenized if a payment token for the recurring payment is the requisite.

Choosing the type reflects on the parameters mentioned below.

isTwoPhase

boolean

O*

*For the card type.

The parameter states whether it’s a two-phase payment or not. False is a default value.

cardNumber

string

O*

*For the card type.

Card number must be between 13 and 19 symbols.

cardHolderName

string

O*

*For the card type.

Cardholder’s full name must:

• contain only Latin letters,

• have two or three words separated by spaces,

• have 50 symbols max.

cardSecurityCode

string

O*

*For the card type.

Card security code is between 3 and 4 symbols.

expiryMonth

int

O*

*For the card type.

Card expiry month is a 2-digit number between 01 and 12.

expiryYear

int

O*

*For the card type.

Card expiry year is a 2-digit number between 00 and 99.

paymentToken

string

O*

*For the tokenized type.

Payment token for the recurring payment.

phone

string

R

11 symbols are max for the phone number.

type

string enum [“card”, “iban”]

R

Possible payment requisite types are:

• card if card parameters are the requisites.

• iban if an IBAN is the requisite.

accountNumber

string

R

Depending on the type parameter, the account number is either a card number or an IBAN.

beneficiaryName

string

R

Beneficiary’s full name.

phone

string

O

Beneficiary’s phone number.

firstName

string

R

Payer’s first name may contain only Latin symbols, hyphen (-), and spaces between them.

lastName

string

R

Payer’s last name may contain only Latin symbols, hyphen, and spaces between them.

email

string

R

Payer’s email.

At least an email or phone number must be linked to a bank account.

phone

string

R

Payer’s phone number must be between 9 and 16 symbols. At least an email or a phone number must be linked to a bank account.

country

string

R

ISO 3166-1 alpha-2 payer’s country code.

state

string

R

Two-letter abbreviation of a payer’s state.

address

string

R

200 symbols are max for a payer’s address.

city

string

R

Payer’s city must match the country.

zip

string

R

Payer’s zip code must match the country.

city

string

R

Payer’s city.

address

string

R

200 symbols are max for a payer’s address.

accountNumber

string

R

In this case, account number’s format is similar to the email format: [username]@[bankname].

The username part must:

• contain 35 symbols max,

• contain only Latin letters, digits, and a few special symbols (“.” “,” “_”).

The bankname part must:

• contain 10 symbols max,

• contain only Latin letters or digits.

bankId

string

R

Technical code of a bank’s branch. You can find this value by sending the Retrieve Payment Method Details and Retrieve Payment Method Entities requests.

firstName

string

R

The first name must contain only Latin letters or spaces between the words. 74 symbols are the limit.

lastName

string

R

The last name must contain only Latin letters or spaces between the words. 74 symbols are the limit.

email

string

O

100 symbols are the limit for an email.

documentNumber

string

O

11-digit CPF number.

address

string

O

Customer’s street.

address2

string

O

Customer’s additional address, such as an apartment number.

addressNumber

string

O

Customer’s street number.

addressNeighborhood

string

O

Neighborhood or district. 30 symbols are the limit.

city

string

O

30 symbols are the limit for a customer’s city.

state

string

O

Two-letter abbreviation of a customer’s state.

zip

string

O

Customer’s postal or zip code.

id

string[100]

R

Payment ID (Payment session identifier)

9073926b929f31c2abc9fad77ae3e8eb

orderId

string[100]

R

Identifier of the order being paid in the merchant's system. Each payment (session) requires a unique identifier. Only printable ASCII characters are allowed.

method

string[100]

R

Payment method.

status

string[100]

R

Payment status.

amount

int

O

Balance of the payment, taking into account all unblockings and refunds made. Presented in the payment currency, using the smallest unit of that currency.

10051 (for an amounting to 100 dollars and 51 cents in USD)

description

string[255]

O

Optional description regarding the status.

redirectUrl

string[2000]

O

Filled for the status 'redirect'. Contains the address to which you need to go to continue the process. All necessary parameters are presented in the address line or in the request parameters of the prepared URL.

paymentToken

string

O

Token for creating recurring payments.

action.type

string

O

The type of additional action expected from the merchant to continue the payment process. Filled if the status is 'actionRequired'. Possible values are:

• 'redirect' - the merchant must redirect the client to the page specified in action.url parameter.

• 'confirmWithCode' - the merchant must provide a special confirmation code by calling Confirm method.

• 'confirmPayment' - the merchant must offer the user to make a payment using the details specified in the 'action.details' parameter and, after payment, call the Confirm Payment method.

action.url

string

O

Filled for the status 'actionRequired' and action.type 'redirect'. Contains the address to which the merchant must redirect the client to continue the process. All necessary parameters are presented in the address line or in the request parameters of the prepared URL.

action.details

object

O

Payment details to make payment in case 'actionRequired' status and 'confirmPayment' type.

The body of the incoming request is not a correct description of a JSON object according to JSON RFC 8259.

400

malformedRequest

Your request body didn't validate.

Additionally, the element "invalid-params":[{"name":"body","reason":"bodyMalformedAtPosXXX"}] is filled in, XXX is the line number where the first syntax validation error of the request body occurred. For example, bodyMalformedAtPos27

The body of the incoming request represents a JSON object, but it does not meet the interface requirements

400

validationError

Your request body didn't validate.

Additionally, the element "invalid-params":[{"name":"name of the problematic field","reason":"reason"}] is filled in.

The requested payment method is not included in the list of those available for the merchant.

422

methodNotSupported

This payment method is not supported.

An attempt to create a payment session with an order identifier for which a session had already been registered earlier

422

duplicatedOrderId

Duplicated order id.

The operation amount specified is incorrect: the value passed is not a positive integer

422

invalidAmount

Invalid amount of the transaction.

The currency is not supported. In particular, the currency of the order is not among the list of currencies supported by the terminal

422

currencyNotSupported

This currency is not supported.

Session creation. The terminal does not support the two-phase payment execution scheme

422

twoPhasePaymentIsNotSupportedByTerminal

Two-phase payments aren't supported by a terminal.

Merchant terminal not found when creating a session. Incorrect terminal password provided when creating a session.

422

invalidTerminalCredentials

Invalid terminal key or password.

The use of the interface (gapi, mapi) is not allowed for the requested transaction direction (payment, payout)

422

interfaceNotAllowed

This interface is not allowed.

Unforeseen errors on the service side. Prior to the creation of the session.

500

unexpectedError

Unexpected error. Contact our support team.

Content-Type

R

application/json

The original media type of the resource.

Cache-Control

R