# Payler API Specifications ## Payment flow Payment is a transfer from a client to a merchant account. There are two schemes for the integration with Payler API: * The [Payment Gate scheme](#payment-gate-scheme) (**GAPI**): a client enters their payment data on the Payler Gateway page. Follows **H2C** (host-to-client) flow. * The [Payment Merchant scheme](#payment-merchant-scheme) (**MAPI**): a client enters their payment data on the merchant page.\ Follows **H2H** (host-to-host) flow. ### Payment Gate scheme In the **Payment** **Gate** (**GAPI**) scheme, a client enters their payment details on the Payler Gateway page. {% hint style="info" %} In the **Payment Gate** scheme, all 3D Secure interactions occur on the Payler side, without merchant involvement. {% endhint %} \ The payment process is: 1. Merchant initiates a payment session by calling [`Start Payment Session`](#openapispecification-facade-startpaymentsession). 2. The merchant redirects a user to the payment page using the address from the [`Start Payment Session`](#openapispecification-facade-startpaymentsession) response. 3. The user selects a payment method and provides the payment details. For [3D Secure](#payment-3-d-secure) authentication, if necessary, the payment gateway redirects the user to the issuing bank's page to enter a confirmation code. 4. Once the payment is completed, the user is redirected to the address the merchant specified while creating the session in Step 1. 5. Once the user returns, the merchant calls [`Get Status`](#openapispecification-facade-getstatus) to check the order's status. 6. Optionally, merchants can set `session.notificationUrl` in [Start Payment Session](#openapispecification-facade-startpaymentsession) to get automated status updates via POST requests for key payment events such as authorization, cancellation, or refund, eliminating the need for manual status checks.

### Payment Merchant scheme In the **Payment Merchant** (MAPI) scheme, a client enters their payment details on the merchant's page. {% hint style="info" %} Compliance with the PCI DSS standard is mandatory when providing bank card information in the **Payment Merchant** scheme. {% endhint %} The payment process can be carried out according to one of the following scenarios: #### Single-phase payment with optional status re-check

#### Single-phase payment with redirect and optional status re-check

#### Single-phase payment with a request for a confirmation code

#### Single-phase payment with a request for payment based on the details provided

#### Two-phase payment with adjustment of blocked funds amount and fund withdrawal confirmation

#### Payment refund

#### Payment 3-D Secure When a request to make a payment or save a card is received, Payler checks whether the card is enrolled in 3-D Secure and determines the supported protocol version. If authentication with the 3DS 2.0 protocol is not possible, 3DS 1.0 is used. ## Payout flow Payout is a transfer from a merchant to a client account. There are two schemes for the integration with Payler API: * The [Payout Gate scheme](#payout-gate-scheme): a client enters their data on the Payler Gateway page. * The [Payout Merchant](#payout-merchant-scheme): a client enters their data on the merchant page. ### Payout Gate scheme In the **Payout** **Gate** (**GAPI**) scheme, a client enters their data on the Payler Gateway page. The payout process is: 1. Merchant initiates a payout session by calling [`Start Payout Session`](#start-payout-session). 2. The merchant redirects a user to the payout page using the address from the [`Start Payout Session`](#start-payout-session)response. 3. The user selects a payout method and, if needed, enters their details. If necessary, the payout gateway redirects the user to the payout provider to enter their details. 4. After completing the payout, the user is redirected to a predefined address on the merchant website/app. 5. Once the user returns, the merchant calls [`Get Payout Status`](#get-payout-status) to check the order's status. 6. Optionally, merchants can set `session.notificationUrl` in [`Start Payout Session`](#start-payout-session) to get automated status updates via POST requests for key payout events such as authorization, eliminating the need for manual status checks. ### Payout Merchant scheme In the **Payment Merchant** (MAPI) scheme, a client enters their data on the merchant's page. {% hint style="info" %} Compliance with the PCI DSS standard is mandatory when providing bank card information in the **Payment Merchant** scheme. {% endhint %} The payout process is: 1. Merchant lets the user choose a payout method and gets the details from the user. 2. The merchant passes the details to [`Create Payout`](#create-payout). 3. The merchant can retrieve the payout status by calling [`Get Payout Status`](#get-payout-status-1). 4. Optionally, merchants can set `session.notificationUrl` in [`Create Payout`](#create-payout) to get automated status updates via POST requests for key payout events such as authorization, eliminating the need for manual status checks.

## General This section covers the range of currencies and payment/payout methods a merchant can use, as specified in their contract. It also details the various operation statuses and the use of API callbacks for confirming payout success or failure. ### Supported currencies These currencies are supported by Payler's various [payment ](#openapispecification-facade-paymentmethods)and [payout](#payout-methods) methods: {% hint style="info" %} The currencies supported by the merchant are specified in their contract. Customers can only make payments in the currencies specified in the merchant's agreement/contract. {% endhint %}

Currency code	Currency name	Payments or Payouts?
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

### Payment methods The section provides an overview of all payment methods supported by Payler. {% hint style="info" %} The payment methods supported by the merchant are specified in their contract. Customers are limited to using the payment methods outlined in the merchant's contract. Contact support if you haven't found the methods you're looking for in the list below. {% endhint %}

Method	Description	Currencies supported
applepay	At checkout, a payer: Selects Apple Pay and is redirected to the payment page. Chooses the payment method. 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	At checkout, a payer selects the Bank Transfer payment method. Secure website with the recipient details (an account number) opens. The payer makes a transfer using their banking app. The payment is confirmed.	KRW, TWD, MAD, AED, AUD
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: Selects BankTransferP2P and is redirected to the BankTransferP2P website. Chooses a bank. 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: Enters their mobile number in the payment form. Receives a payment request in the Jazzcash mobile app. Confirms the transaction by authorizing it with their PIN.	PKR
ideal	To process a payment, a payer either chooses a bank and scans the QR code or provides a personal identifier. After the payment is completed, the payer returns to the merchant's site with the payment confirmation. 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: Selects the payment method (phone number, card, or IBAN). Receives payment details. Makes a transfer using their banking app. Confirms the payment	AZN, UZS, TRY
papara	At checkout, a payer: Selects Papara and is redirected to the Papara website. Chooses a bank. 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: Selects Paybol and is redirected to the Paybol website. Chooses a bank. 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: Selects Payfix and is redirected to the Payfix website. Chooses a bank. 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: Selects POLi and is redirected to the POLi website. Chooses a bank. 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	At checkout, a payer selects the SCP (Supermarket Code Pay) payment method. The payer selects a supermarket, e.g., IBON, Hi-Life, or FamiPort. The payer receives an invoice for payment. 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

### Payout methods The section provides an overview of all payout methods supported by Payler. Contact support if you haven't found the methods you're looking for in the list below.

Method	Description	Currencies supported
banktransfer	Payout is performed by entering the customer’s bank account number with a bank code.	KRW, TWD, MAD, AUD, AED
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

### Operation statuses The section contains all possible payment and payout operation statuses and their brief descriptions for the Gate and Merchant schemes.

Status	Description	Payments or Payouts?	Is an API callback sent when a transaction gets this status?
`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	+

### API callbacks API callbacks, also known as guaranteed notifications, are essential for informing merchants about the success or failure of payments and payouts in both Gate and Merchant schemes. The API callbacks operate as follows: 1. When an order status changes, the gateway sends a `POST` request to a pre-defined URL. The request parameters include the `orderId`. 2. If a successful response code (`2xx`) is received, the notification processing is considered complete.\ If an error occurs or the server isn't available, the attempt is retried every hour for the next 24 hours. #### Status notification callback API callbacks require the `session.notificationUrl` parameter set in: * The [Start Payment Session](#openapispecification-facade-startpaymentsession) method for the [Payment Gate scheme](#payment-gate-scheme). * The [Create Payment](#create-payment) method for the [Payment Merchant scheme](#payment-merchant-scheme). * The [Start Payout Session](#start-payout-session) method for the [Payout Gate scheme](#payout-gate-scheme). * The [Create Payout](#create-payout) method for the [Payout Merchant scheme](#payout-merchant-scheme). When the `session.notificationUrl` parameter is set, the system will post the non-transitional payment statuses to the specified notification URL. You can find a list of possible statuses in the [Operation statuses](#openapispecification-facade-operationstatuses) section. The system is waiting for a response with the HTTP 200 OK code. If no response arrives, the system retries sending the notification every hour for the next 24 hours, after which there will be no more attempts. **Entry parameters:** **Request URL:** The URL is provided in the `session.notificationUrl` parameter. **Request method:** `POST` **Request body parameters:**

Attribute	Attribute type	R/O	Description	Example
`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`

**Request examples (for both Payments and Payouts):**

{
  "sessionId": "9073926b929f31c2abc9fad77ae3e8eb",
  "orderId": "d1434908-7260-483e-8254-fa43af1b835d",
  "state": "actionRequired",
  "method": "payid",
  "amount": "100000",
  "updated": "2022-02-12T11:22:33.145Z",
  "action": {
    "type": "сonfirmPayment",
    "details": {
      "accountName": "TRKS TECHNOLOGY PTY LTD",
      "accountNumber": "987654321",
      "bsbNumber": "370370",
      "paymentDescription": "11223344"
    }
  },
  "token": "4e18d7564f6ecaaff5e2cb3d4a1be4a6a18e2094758e12853afc42e5a0a97be5"
}

**Generating and checking message token:** To generate a unique signature for each message using SHA-256 encryption: 1. In the payload block, transform all complex objects into simple top-level parameters: each final element object becomes a parameter of the payload object, the name of the new parameters receives a concatenation of the names of the object parameters on the path to each elementary element: ```json { "sessionId": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "d1434908-7260-483e-8254-fa43af1b835d", "state": "actionRequired", "method": "payid", "amount": "100000", "updated": "2022-02-12T11:22:33.145Z", "action.type": "сonfirmPayment", "action.details.accountName": "TRKS TECHNOLOGY PTY LTD", "action.details.accountNumber": "987654321", "action.details.bsbNumber": "370370", "action.details.paymentDescription": "11223344", "token": "4e18d7564f6ecaaff5e2cb3d4a1be4a6a18e2094758e12853afc42e5a0a97be5" } ``` 2. Gather all message parameters as key-value pairs, except the “token” parameter, in the following format: ```json [ {"sessionId":"9073926b929f31c2abc9fad77ae3e8eb"}, {"orderId":"d1434908-7260-483e-8254-fa43af1b835d"}, {"state":"authorized"}, {"method":"cards"}, {"amount": "100000"}, {"updated":"2022-02-12T11:22:33.145Z"}, {"action.type": "сonfirmPayment"}, {"action.details.accountName":"TRKS TECHNOLOGY PTY LTD"}, {"action.details.accountNumber":"987654321"}, {"action.details.bsbNumber":"370370"}, {"action.details.paymentDescription": "11223344"} ] ``` 3. Add a pair with “*password*” as the key and the merchant terminal password as the value of the object to the above mentioned array in the previous step: * `{"password":"PWD123456"}` 4. Sort the array by the keys. The sorted array should be similar to the one below:

[
    {"action.details.accountName": "TRKS TECHNOLOGY PTY LTD"},
    {"action.details.accountNumber": "987654321"}, 
    {"action.details.bsbNumber": "370370"}, 
    {"action.details.paymentDescription": "11223344"}, 
    {"action.type": "сonfirmPayment"}, 
    {"amount": "100000"},
    {"method": "cards"}, 
    {"orderId": "d1434908-7260-483e-8254-fa43af1b835d"}, 
    {"password": "PWD123456"},
    {"sessionId": "9073926b929f31c2abc9fad77ae3e8eb"}, 
    {"state": "authorized"}, 
    {"updated": "2022-02-12T11:22:33.145Z"}
]

5. Concatenate the values into a single string: `"TRKS TECHNOLOGY PTY LTD98765432137037011223344сonfirmPayment100000cardsd1434908-7260-483e-8254-fa43af1b835dPWD1234569073926b929f31c2abc9fad77ae3e8ebauthorized2022-02-12T11:22:33.145Z"` 6. Calculate the signature as SHA-256 of the concatenated string using UTF-8 encoding. In our example, the final signature is: `281073fefe06561170cdbe819e97205134396b113dbe7faa3c0e65c3c9ce014f` ### Data types Payler API uses these data types: * string * array * object * bool * enum * int * long ## GAPI Payment methods This section provides an overview of the main API methods used in the [**Payment Gate scheme**](#payment-gate-scheme) (**GAPI**). It includes detailed instructions for initiating a payment session, checking the payment status, and processing refunds. ### Start Payment Session Use this method to initiate a new payment session. The request's header must include the merchant's unique terminal key and password. It ensures the session is securely linked to the merchant's account. Once the session starts, it uses the settings set by a merchant to manage the payment process. If the request is successful, the API returns a link to the payment page that the merchant can share with customers. This link leads customers to the Payler secure payment page, where they can complete the transaction safely. There are no restrictions on sharing the payment page link, so it can be freely distributed to simplify the payment process. **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/gapi/v1/sessions` **Request method:** `POST` **Request headers:**

Header	R/O	Value	Description
`Content-Type`	R	application/json	Original media type of the resource.
`SessionTerminalKey`	R		Merchant terminal identifier.
`SessionTerminalPassword`	R		Merchant terminal password.

**Request body parameters:**

Attribute	Type	R/O	Description
`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.

**Request example:**

{
  "session": {
    "lifetime": 15,
    "returnURLs": {
    "default": {
        "url": "https://some.address.com/success"
      },
     "success": {
        "url": "https://some.address.com/success"
      },
      "failure": {
        "url": "https://some.address.com/failed"
      }
    },
    "notificationUrl": "https://some.address.com/notify",
    "payment": {
      "type": "regular",
      "antifraud": {
        "key": "value"
      },
      "page": {
        "lang": "en"
      },
      "createPaymentToken": false
    },
    "order": {
      "id": "9073926b929f31c2abc9fad77ae3e8eb",
      "currency": "EUR",
      "amount": 10000,
      "description": "test description",
      "itemsType": "product",
      "customer": {
        "id": "100331",
        "email": "johndoe@test.com",
        "personsData": {
          "phoneNumber": "00555555",
          "firstName": "John",
          "lastName": "Doe",
          "country": "ES",
          "state": "Madrid",
          "city": "Madrid",
          "zip": "28001",
          "address": "Test Address"
          }
      },
      "additionalFields": {
        "custom": [
          {
            "key": "value",
            "description": "value"
          },
          {
            "key": "value",
            "description": "value"
          }
        ]
      }
    }
  }
}

**Response attributes:**

Attribute	Type	R/O	Description	Example
`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`).

**Success response example:** ```json { "session": { "id": "9073926b929f31c2abc9fad77ae3e8eb", "order": { "id": "e79c24b3-857e-4cd1-91a3-654d3baee8710", "amount": 10000 }, "payment": { "page": { "url": "https://url.com/payment-page/:sessionID" } } } } ``` **Recurring payment success response example:** ```json { "session": { "id": "9073926b929f31c2abc9fad77ae3e8eb", "order": { "id": "e79c24b3-857e-4cd1-91a3-654d3baee8710", "amount": 10000 } } } ``` **Error response example:** ```json { "session": { "id": null, "error": { "type": "validationError", "title": "Your request parameters didn't validate.", "invalid-params": [ { "name": "session.someKey", "reason": "valueHasExtraLength" }, { "name": "session.someKey2", "reason": "valueIsNotPermitted" } ] } } } ``` ### Recurring Payments In this section, you can find the instruction for creating a recurring payment. The [Gate scheme](#payment-gate-scheme) supports recurring payments using payment tokens. #### **Create a payment token** 1. **Initiate a Payment Session:** Start by [creating a payment session](#openapispecification-facade-startpaymentsession) with the`regular` session type and the `createPaymentToken` parameter set to `true`. 2. **Payment Processing:** After processing the payment on the payment page, a payment token is generated. 3. **Token Retrieval:** This token is returned in the [status response](#openapispecification-facade-getstatus) and through a [notification callback](#openapispecification-facade-datatypes) as `paymentToken`. **Perform a recurring payment** 1. **Initiate a Tokenized Session:** [Create a session](#openapispecification-facade-startpaymentsession) with the `tokenized` session type. This session type bypasses the redirect to the payment page. 2. **Create Payment Using Token:** Use the [Create payment by token](#create-payment-by-token) method passing the previously obtained `paymentToken`. 3. **Payment Confirmation:** Receive payment confirmation through the [status request](#openapispecification-facade-getstatus) or [notification callback](#openapispecification-facade-datatypes). #### Create payment by token This API method enables the creation of a card payment based on a previously saved recurring payment template represented by a token. **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/gapi/v1/sessions/{sessionId}/payments` **Request method:** `POST` **Request headers:**

Header	R/O	Value	Description
`Content-Type`	R	application/json	Original media type of the resource.
`SessionTerminalKey`	R		Merchant terminal identifier.
`SessionTerminalPassword`	R		Merchant terminal password.

**Path request parameters:**

Parameter	Type	R/O	Description	Example
`sessionId`	string	R	Payment session ID.	`9073926b929f31c2abc9fad77ae3e8eb`

#### **Body request parameters:**

Parameter	Type	R/O	Description
`paymentToken`	string	R	Token used to create recurring payments.

**Request example:** ```json SessionTerminalKey: ***** SessionTerminalPassword: ***** Content-Type: application/json { "paymentToken": "rec-pay-4125a620-3842-4015-9960-27ba08c4510c" } ``` **Response parameters:**

Attribute	Type	R/O	Description	Example
`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`

**Response example:** ```json { "session": { "id": "9073926b929f31c2abc9fad77ae3e8eb", "payment": { "state": "authorized", "method": "cards" } } } ``` {% hint style="info" %} To create a recurring payment using the [Payment Merchant (MAPI) scheme](#payment-merchant-scheme), see [this section](#creating-a-recurring-payment). {% endhint %} ### Get Payment Status Use this method to retrieve the current status of a payment session using its unique `sessionId`parameter. Once invoked, the API returns the latest status of the specified payment session. **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/gapi/v1/sessions/{sessionId}/status` **Request method:** `GET` **Request headers:**

Header	R/O	Value	Description
`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.

**Path request parameters:**

Parameter	Type	R/O	Description	Example
`sessionId`	string	R	Payment session ID	`9073926b929f31c2abc9fad77ae3e8ey`

**Response parameters:**

Attribute	Type	R/O	Description	Example
`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.

**Response example:** ```json { "session": { "id": "9073926b929f31c2abc9fad77ae3e8eb", "payment": { "state": "authorized", "method": "cards", "amount": 10000, "paymentToken": "c526dccc-c5fb-4148-9f14-42bda6c61878" } } } ``` ### Refund Use this method to process refunds after a successful payment. The method requires the payment within the session to be in the `authorized` status. Upon receiving a refund request, the API facilitates either a full or partial refund of the charged amount back to the user's account. For security and for correct processing, include the merchant unique terminal key and password in the header. #### **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/gapi/v1/sessions/{sessionId}/refund` **Request method:** `POST` **Request headers:**

Header	R/O	Value	Description
`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.

#### **Path request parameters:**

Parameter	Type	R/O	Description	Example
`sessionId`	string	R	Payment session ID	`9073926b929f31c2abc9fad77ae3e8ey`

#### **Body request parameters:**

Attribute Type R/O Description Example

Attribute	Type	R/O	Description	Example
`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)

session.refund.amount

int

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)

#### **Request example:** ```json { "session":{ "refund":{ "amount": 10051 } } } ``` #### **Response parameters:**

Attribute	Type	R/O	Description	Example
`session.id`	string[100]	R	Payment session identifier.	`9073926b929f31c2abc9fad77ae3e8eb`
`session.status`	string[100]	R	Payment state.	`authorized`
`session.refund.amount`	int	R	The refunded amount specified in the smallest unit of its currency.	`10051`
`session.order.id`	string[100]	R	Order ID in the merchant system.	`d1434908-7260-483e-8254-fa43af1b8356`
`session.order.amount`	int	R	The total order amount specified in the smallest unit of its currency.	`10051`
`session.order.currency`	string[3]	R	Order currency.	`USD`
`session.payment.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. For example, if the payment is in EUR, the amount of 10050 means 100 EUR and 50 cents.	`10000`

#### **Response example:** ```json { "session": { "id": "9073926b929f31c2abc9fad77ae3e8eb", "status": "refunded", "refund": { "amount": 10000 }, "order": { "id": "d1434908-7260-483e-8254-fa43af1b835d", "amount": 10000, "currency": "USD" }, "payment": { "amount": 0 } } } ``` ## GAPI Payout methods This section provides an overview of the main API methods used in the Payler [**Payout Gate scheme**](#payout-gate-scheme) (**GAPI**). It includes detailed instructions for initiating a payout session and checking the payout status. ### Start Payout Session Use this method to initiate a new payout session. The request must include the merchant's unique terminal key and password in the header for security and identification purposes. This information ensures that the session is securely linked to the merchant's account. Once the session starts, it uses the settings set by a merchant to manage the payout process. If the request is successful, the API returns a link to the payout page that the merchant can share with customers. This link leads customers to the Payler secure payout page, where they can complete the transaction safely. There are no restrictions on sharing the payout page link, meaning it can be freely shared to facilitate the payout process. **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/gapi/payout/v1/sessions` **Request method:** `POST` **Request headers:** | Header | R/O | Value | Description | | ------------------------- | --- | ---------------- | ------------------------------------ | | `Content-Type` | R | application/json | Original media type of the resource. | | `SessionTerminalKey` | R | | Merchant terminal identifier. | | `SessionTerminalPassword` | R | | Merchant terminal password. | **Body request parameters:**

Attribute	Type	R/O	Description
`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.

**Request example:** ```json { "session": { "lifetime": 20, "returnURLs": { "default": { "url": "https://some.address.com/default" }, "success": { "url": "https://some.address.com/success" }, "failure": { "url": "https://some.address.com/failed" } }, "notificationUrl": "https://some.address.com/notify", "payout": { "type": "regular", "antifraud": { "key": "value", "key2": "value" }, "page": { "lang": "en" } }, "order": { "id": "d43850a9-c909-4580-b589-a89c1748a1dw", "currency": "USD", "amount": 10000, "description": "some description", "itemsType": "test", "customer": { "id": "ff12rte33", "email": "some@email", "personsData": { "firstName": "John", "lastName": "Doe", "phoneNumber": "00555555", "country": "GB" } }, "additionalFields": { "custom": [ { "key": "value", "description": "value" } ] } } } } ``` **Response parameters:**

Attribute	Type	R/O	Description	Example
`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).

**Success response example:** ```json { "session":{ "id":"013a32441c8b40938b291b65741a2486", "order":{ "id":"d43850a9-c909-4580-b589-a89c1748a1da", "amount":10000 }, "payout": { "page":{ "url":"https://url.com/payout-page/:sessionID" } } } } ``` **Error response example:** ```json { "error": { "type": "validationError", "title": "Your request parameters didn't validate.", "invalid-params": [ { "name": "session.someKey", "reason": "valueHasExtraLength" }, { "name": "session.someKey2", "reason": "valueIsNotPermited" } ] } } ``` ### Get Payout Status Use this method to retrieve the current status of a payout session using its unique `sessionId` parameter. Once invoked, the API returns the latest status of the specified payout session. **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/gapi/payout/v1/sessions/{sessionId}/status` **Request method:** `GET` **Request headers:** | Header | R/O | Value | Description | | --------------- | --- | ---------------- | -------------------------------------------------------------------------------------------------------- | | `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. | **Path request parameters:**

Parameter	Type	R/O	Description	Example
`sessionId`	string	R	Payout session ID.	`9073926b929f31c2abc9fad77ae3e8eb`

**Response parameters:**

Attribute	Type	R/O	Description	Example
`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`

**Response example:** ```json { "session": { "id": "9073926b929f31c2abc9fad77ae3e8eb", "payout": { "state": "authorized", "method": "cards", "amount": 10050 } } } ``` ## GAPI List of errors If a request for any of the GAPI methods fails, the response includes a detailed error description. **Error description parameters:**

Name	Type	R/O	Description
`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.

**Failed request response example:** ```json { "session": { "id": "9073926b929f31c2abc9fad77ae3e8eb", "error": { "type": "invalidAmount", "title": "Invalid amount of the transaction." } } } ``` If request input parameters lead to validation errors, the response includes the additional **invalid-params** array. Each element of this array describes the specific rule that was violated: ```json { "session": { "id": "9073926b929f31c2abc9fad77ae3e8eb", "error": { "type": "validationError", "title": "Your request parameters didn't validate.", "invalid-params": [ { "name": "session.someKey", "reason": "keyHasExtraLength" } ] } } } ``` **Error types** The table below contains possible values of the **error.type** parameter in the responses for the failed requests.

Type	Error	Title	Comment
`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.

#### **Parameter validation errors** The table below contains possible errors occurring during the validation of the input parameters. For example, if the request body is not a correct JSON object, a response with the `malformedRequest` error type is returned. The reason value will include the line number where the first error occurred, indicated as 'XX': ```json { "session": { "id": "9073926b929f31c2abc9fad77ae3e8eb", "error": { "type": "malformedRequest", "title": "Your request body didn't validate.", "invalid-params": [ { "name": "body", "reason": "bodyMalformedAtPosXX" } ] } } } ``` The possible validation errors are:

Error	Description
`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.

## MAPI Payment methods This section explains the main API methods utilized in the Payler [**Payment Merchant scheme**](#payment-merchant-scheme) (**MAPI**). It includes detailed descriptions and protocols for creating a payment, checking payment status, completing a payment, and processing refunds and reversals. ### Create Payment Use this method to initiate a payment creation request through the MAPI interface. #### **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/mapi/v2/payments` **Request method:** `POST` **Request headers:**

Header	R/O	Value	Description
`Content-Type`	R	application/json	The original media type of the resource.
`AuthorizationKey`	R		Merchant terminal identifier.
`AuthorizationPassword`	R		Merchant terminal password.

**Body request parameters:**

Parameter	Type	R/O	Description	Example
`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"

#### Payment details for the `cards` method:

Parameter	Type	R/O	Description
`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.

#### Payment details for the `mcommerce` method: | Parameter | Type | R/O | Description | | --------- | ------ | --- | ---------------------------------------- | | phone | string | R | 11 symbols are max for the phone number. | #### Payment details for the `pcr` method: | Parameter | Type | R/O | Description | | ----------------- | ----------------------------- | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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.

Parameter	Type	R/O	Description
`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.

#### Payment details for the `upi` method: | Parameter | Type | R/O | Description | | --------------- | ------ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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.

| #### Payment details for the `openbanking` method: | Parameter | Type | R/O | Description | | --------- | ------ | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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.

| #### Payment details for the `boleto, picpays, pix`and `banktransfer`*`(Brazil)`* methods: {% hint style="info" %} For the **boleto** method, **each** of the requirements is **required**. {% endhint %}

Parameter	Type	R/O	Description
`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.

#### Request example for the `cards` payment method: ```json Authorization-Key: ***** Authorization-Password: ***** Content-Type: application/json { "order": { "id": "test-d43850a9-c909-4580-b589-a89c1748a1da", "amount": 1112, "currency": "GBP", "description": "Magic staff package #5" }, "createPaymentToken": false, "type": "regular", "method": "cards", "customer": { "id": "62f66472913640cc93f49d5477840657", "firstName": "Harry", "lastName": "Potter", "email": "customer@email.com", "phone": "357 123456789" }, "details": { "type": "card", "isTwoPhase": false, "cardNumber": "4242424242424242", "cardHolderName": "Harry Potter", "cardSecurityCode": "123", "expiryMonth": 11, "expiryYear": 2025 }, "sessionContext": { "ip": "172.16.0.1", "languageCode": "en", "browserParameters": { "accept": "text/html", "language": "en-US", "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0", "javaEnabled": true, "javascriptEnabled": true, "screenHeight": "1920", "screenWidth": "1080", "colorDepth": "12", "tz": "-180" } }, "returnUrls": { "default": "https://yourwebsite.com/{someUsefulParams1}", "success": "https://yourwebsite.com/{someUsefulParams2}", "failure": "https://yourwebsite.com/{someUsefulParams3}" }, "notificationUrl": "https://yourwebsite.com/notify", "antifraudParams": { "antifraud_email": "Camryn.Roob83@gmail.com", "antifraud_param_name": "param_value" } } ``` #### Request example for the Alternative Payment Methods (APMs):

Authorization-Key: *****
Authorization-Password: *****
Content-Type: application/json

{
  "order": {
    "id": "test-d43850a9-c909-4580-b589-a89c1748a1da",
    "amount": 1112,
    "currency": "GBP",
    "description": "Magic staff package #5"
  },
  "createPaymentToken": false,
  "method": "pcr",
  
  "customer": {
    "id": "62f66472913640cc93f49d5477840657",
    "firstName": "Harry",
    "lastName": "Potter",
    "email": "customer@email.com",
    "phone": "357 123456789",
    "documentNumber": "13245678911",
    "address": {
      "addressLine": "211, Victory street, office 7B",
      "city": "Hogwarts",
      "countryCode": "GB",
      "postalCode": "01001",
      "state": "CA"
    }
  },
   
   "details": {
    "type": "iban",    
    "accountNumber": "AZ21NABZ00000000137010001944",
    "beneficiaryName": "John Doe",
  },
  
  "sessionContext": {
    "ip": "172.16.0.1",
    "languageCode": "en",
    "browserParametes": {
      "accept": "text/html",
      "language": "en-US",
      "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0",
      "javaEnabled": true,
      "javascriptEnabled": true,
      "screenHeight": "1920",
      "screenWidth": "1080",
      "colorDepth": "12",
      "tz": "-180"
    }
  },
  "returnUrls": {
    "default": "https://yourwebsite.com/{someUsefulParams1}",
    "success": "https://yourwebsite.com/{someUsefulParams2}",
    "failure": "https://yourwebsite.com/{someUsefulParams3}"
  },
  "notificationUrl": "https://yourwebsite.com/notify",
  "antifraudParams": {
    "email": "Camryn.Roob83@gmail.com",
    "param_name": "param_value"
  }
}

#### Response parameters:

Parameter	Type	R/O	Description	Example
`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.

#### Response Example: Processing ```json { "id": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "test-d43850a9-c909-4580-b589-a89c1748a1da", "method": "cards", "amount": 10051, "status": "pending" } ``` #### Response Example: Successful payment ```json { "id": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "test-d43850a9-c909-4580-b589-a89c1748a1da", "method": "cards", "amount": 10051, "status": "authorized|preAuthorized" } ``` #### Response Example: Payment rejected ```json { "id": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "test-d43850a9-c909-4580-b589-a89c1748a1da", "method": "cards", "amount": 10051, "status": "rejected", "description": "invalidCardNumber" } ``` #### Response Example: Redirection required ```json { "id": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "test-d43850a9-c909-4580-b589-a89c1748a1da", "method": "cards", "amount": 10051, "status": "actionRequired", "action": { "type": "redirect", "url": "https://some.url?some¶ms" } } ``` #### Response Example: Confirmation with a code required ```json { "id": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "test-d43850a9-c909-4580-b589-a89c1748a1da", "method": "cards", "amount": 10051, "status": "actionRequired", "action": { "type": "confirmWithCode" } } ``` #### Response Example: Confirmation of payment using the specified details required ```json { "id": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "test-d43850a9-c909-4580-b589-a89c1748a1da", "method": "cards", "amount": 10051, "status": "actionRequired", "action": { "type": "confirmPayment", "details": { "accountName": "TRKS TECHNOLOGY PTY LTD", "accountNumber": "987654321", "bsbNumber": "370370" } } } ``` #### Error types and codes

In case of	Error	Type	Title	Comment
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.

#### Creating a recurring payment Use these instructions to create a recurring payment that facilitates automated billing processes for repeat transactions. The [Merchant scheme](#payment-merchant-scheme) supports these operations using payment tokens. {% hint style="info" %} Unlike [recurring payments in the Gate scheme](#recurring-payment), in the [Merchant scheme](#payment-merchant-scheme), the same [`createPayment`](#create-payment) method is used for both generating a payment token and making subsequent payments with it. {% endhint %} Follow the instructions below to create a payment token and perform a subsequent (recurring) payment: **Creating a payment token** 1. To generate a token, call the [Create payment](#create-payment) method with the `type` parameter set to `regular` and the `createPaymentToken` parameter set to `true`. 2. This token is returned in the [status response](#get-payment-status) and through a notification callback as `paymentToken`. **Making a recurring payment** 1. Once the payment token is obtained, call the [Create payment](#create-payment) method again, but this time with `type` set to `tokenized` and the `details.paymentToken` parameter included (where `details.type` should be `paymentToken`) to create a recurring payment. 2. Receive confirmation of the payment through the [status request](#get-payment-status) or [notification callback](#openapispecification-facade-datatypes). ### Get Payment Status Use this method to request the current payment status through the MAPI interface. #### **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/mapi/v2/payments/{paymentId}` **Request method:** `GET` **Request headers:**

Header	R/O	Value	Description
`Content-Type`	R	application/json	The original media type of the resource.
`Cache-Control`	R	no-cache	Mandates retrieving the response directly from the server, bypassing caches, to guarantee the latest status.
`AuthorizationKey`	R	-	Merchant terminal identifier.
`AuthorizationPassword`	R	-	Merchant terminal password.

**Path request parameters:**

Parameter	R/O	Value	Description
`paymentId`	R	string	Unique payment identifier

#### Response parameters:

Parameter	Type	R/O	Description	Example
`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.	cards
`status`	string[100]	R	Payment status.	authorized
`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)
`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.
`description`	string	O	Comment on the status.
`paymentToken`	string	O	Token used 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.detail`	string	O	Payment details to make payment in case '`actionRequired`' status and '`confirmPayment'` type.

In case of	Error	Type	Title
No payment found with the specified ID.	404	paymentNotFound	There is no payment with the specified id.
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.
Temporary error: You might be able to do the operation successfully if you try again later.	503	temporaryMalfunction	Temporary malfunction. Please try again later.

### Confirm Payment Use this method to confirm that an action previously requested by the `'actionRequired'` status has been completed. #### **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/mapi/v2/payments/{paymentId}/confirm` **Request method:** `POST` **Request headers:**

Header	R/O	Value	Description
`Content-Type`	R	application/json	The original media type of the resource.
`Cache-Control`	R	no-cache	Mandates retrieving the response directly from the server, bypassing caches, to guarantee the latest status.
`AuthorizationKey`	R	-	Merchant terminal identifier.
`AuthorizationPassword`	R	-	Merchant terminal password.

**Path request parameters:**

Parameter	R/O	Value	Description
`paymentId`	R	string	Unique payment identifier.

**Body request parameters:**

Parameter	Type	R/ O	Description	Example
`confirmationData.code`	string	O	Confirmation code. The parameter is required if this call is made in response to receiving '`actionRequired`' status with type '`confirmWithCode`'. Otherwise, no parameters are expected in the request body.	13256
confirmationFileIds	array	O	An array containing identifiers of previously uploaded receipt files (via #upload-files-with-payment-confirmation)	[ "090919a9-67fb-4f5d-bdc9-ebcdef52c066", "138b4fca-0123-47bf-a296-75bbbf507e5b" ]

#### Request example - confirmation code provided: ```json Authorization-Key: ***** Authorization-Password: ***** Content-Type: application/json { "confirmationData": { "code": "123456" } } ``` #### Request example - confirmation file provided: ```json Authorization-Key: ***** Authorization-Password: ***** Content-Type: application/json { "confirmationFileIds": [ "1b05b1f3-18b9-4f70-b7ef-0b3c4539ea9c", "138b4fca-0123-47bf-a296-75bbbf507e5b" ] } ``` #### Response parameters: Completely identical to the response parameters of the [Get Payment Status](#get-payment-status) method #### Response Example: Successful payment ```json { "id": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "test-d43850a9-c909-4580-b589-a89c1748a1da", "method": "cards", "amount": 10051, "status": "authorized|preAuthorized|pending" } ``` #### Response Example: Payment rejected ```json { "id": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "test-d43850a9-c909-4580-b589-a89c1748a1da", "method": "cards", "amount": 10051, "status": "rejected", "description": "invalidCardNumber" } ``` #### Error types and codes

In case of	Error	Type	Title
No payment found with the specified ID.	404	paymentNotFound	There is no payment with the specified id.
The use of the interface (gapi, mapi) is not allowed for the requested transaction direction (payment, payout)	422	interfaceNotAllowed	This interface is not allowed.
The payment is not awaiting confirmation in its current state	422	invalidPaymentState	The payment is in an invalid state.
Unforeseen errors on the service side. Prior to the creation of the session.	500	unexpectedError	Unexpected error. Contact our support team.
Temporary error: You might be able to do the operation successfully if you try again later.	503	temporaryMalfunction	Temporary malfunction. Please try again later.

### Reverse Funds Use this method to adjust the amount of funds that have been blocked but not yet charged in the MAPI interface. {% hint style="warning" %} This method is implemented for the two-phase payment scheme, for payments in the `PreAuthorized` state, and is only available for the `cards` payment method. {% endhint %} #### **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/mapi/v2/payments/{paymentId}/reverse` **Request method:** `POST` **Request headers:**

Header	R/O	Value	Description
`Content-Type`	R	application/json	The original media type of the resource.
`Cache-Control`	R	no-cache	Mandates retrieving the response directly from the server, bypassing caches, to guarantee the latest status.
`AuthorizationKey`	R	-	Merchant terminal identifier.
`AuthorizationPassword`	R	-	Merchant terminal password.

**Path request parameters:**

Parameter	R/O	Value	Description
`paymentId`	R	string	Unique payment identifier

#### Request body parameters:

Parameter	Type	R/ O	Description	Example
`amount`	long	R	Amount to be reversed in the smallest units of the order's currency.	13256

#### Request example:

Authorization-Key: *****
Authorization-Password: *****
Content-Type: application/json

{
    "amount": 1112
}

#### Response parameters:

Parameter	Type	R/O	Description	Example
`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.	string[100]
`method`	string[100]	R	Payment method.	cards
`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)
`status`	string[100]	R	Payment session status.	preAuthorized

#### Response example: ```json { "id": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "test-d43850a9-c909-4580-b589-a89c1748a1da", "method": "cards", "amount": 0, "status": "cancelled" } ``` #### Error types and codes

In case of	Error	Type	Title	Comment
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.
No payment found with the specified ID.	404	paymentNotFound	There is no payment with the specified id.
Unsupported operation for the specified payment method.	422	invalidOperation	The operation is not supported for payment method {attempt.method}.
Merchant terminal not found when creating a session. Incorrect terminal password provided when creating a session.	422	invalidTerminalCredentials	Invalid terminal key or password.
The operation amount specified is incorrect: the value passed is not a positive integer	422	invalidAmount	Invalid amount of the transaction.
The use of the interface (gapi, mapi) is not allowed for the requested transaction direction (payment, payout)	422	interfaceNotAllowed	This interface is not allowed.
For the twoPhaseReverse operation - Cards API returned PARTIAL_RETRIEVE_NOT_ALLOWED	422	partialRetrieveNotAllowed	Authorization amount cannot be changed.
For the twoPhaseReverse operation - Cards API returned EXPIRED_RETRIEVE_PERIOD	422	expiredRetrievePeriod	Expired period of changing the amount of frozen funds.
Inappropriate payment state for the operation: For the refund operation, payment must be in Authorized state;	422	invalidPaymentState	The payment is in an invalid state.
Operation not permitted in a non-two-step payment process.	422	transactionNotTwoStep	Unable to perform the operation within the non two-step payment.
Unforeseen errors on the service side. Prior to the creation of the session.	500	unexpectedError	Unexpected error. Contact our support team.
Temporary error: You might be able to do the operation successfully if you try again later.	503	temporaryMalfunction	Temporary malfunction. Please try again later.

### Complete Payment Use this method to confirm the debiting of the blocked funds in the MAPI interface. {% hint style="warning" %} This method is implemented for the two-phase payment scheme, for payments in the `PreAuthorized` state, and is only available for the `cards` payment method. {% endhint %} #### **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/mapi/v2/payments/{paymentId}/complete` **Request method:** `POST` **Request headers:**

Header	R/O	Value	Description
`Content-Type`	R	application/json	The original media type of the resource.
`Cache-Control`	R	no-cache	Mandates retrieving the response directly from the server, bypassing caches, to guarantee the latest status.
`AuthorizationKey`	R	-	Merchant terminal identifier.
`AuthorizationPassword`	R	-	Merchant terminal password.

**Path request parameters:**

Parameter	R/O	Value	Description
`paymentId`	R	string	Unique payment identifier

#### Body request parameters:

Parameter	Type	R/ O	Description	Example
`amount`	long	R	Amount to be reversed in the smallest units of the order's currency.	13256

#### Request example:

Authorization-Key: *****
Authorization-Password: *****
Content-Type: application/json

{
    "amount": 1112
}

#### Response parameters:

Parameter	Type	R/O	Description	Example
`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 requires a unique identifier.	string[100]
`method`	string[100]	R	Payment method.	cards
`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.
`status`	string[100]	R	Payment status.	authorized

#### Response example: ```json { "id": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "test-d43850a9-c909-4580-b589-a89c1748a1da", "method": "cards", "amount": 10051, "status": "authorized" } ``` #### Error types and codes

In case of	Error	Type	Title	Comment
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.
No payment found with the specified ID.	404	paymentNotFound	There is no payment with the specified id.
Merchant terminal not found when creating a session. Incorrect terminal password provided when creating a session.	422	invalidTerminalCredentials	Invalid terminal key or password.
The operation amount specified is incorrect: the value passed is not a positive integer	422	invalidAmount	Invalid amount of the transaction.
The use of the interface (gapi, mapi) is not allowed for the requested transaction direction (payment, payout)	422	interfaceNotAllowed	This interface is not allowed.
Inappropriate payment state for the operation: For the refund operation, payment must be in Authorized state;	422	invalidPaymentState	The payment is in an invalid state.
For the twoPhaseComplete operation: Cards API returned an error PARTIAL_CHARGE_NOT_ALLOWED	422	partialChargeNotAllowed	Partial charge is not supported.
Unsupported operation for the specified payment method.	422	invalidOperation	The operation is not supported for payment method {attempt.method}.
Operation not permitted in a non-two-step payment process.	422	transactionNotTwoStep	Unable to perform the operation within the non two-step payment.
Unforeseen errors on the service side. Prior to the creation of the session.	500	unexpectedError	Unexpected error. Contact our support team.
Temporary error: You might be able to do the operation successfully if you try again later.	503	temporaryMalfunction	Temporary malfunction. Please try again later.

### Refund Payment Use this method to refund charged funds via the MAPI interface for payments that are in the "Authorized" state. #### **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/mapi/v2/payments/{paymentId}/refund` **Request method:** `POST` **Request headers:**

Header	R/O	Value	Description
`Content-Type`	R	application/json	The original media type of the resource.
`Cache-Control`	R	no-cache	Mandates retrieving the response directly from the server, bypassing caches, to guarantee the latest status.
`AuthorizationKey`	R	-	Merchant terminal identifier.
`AuthorizationPassword`	R	-	Merchant terminal password.

**Path request parameters:**

Parameter	R/O	Value	Description
`paymentId`	R	string	Unique payment identifier

#### Body request parameters:

Parameter	Type	R/ O	Description	Example
`amount`	long	R	Amount to be reversed in the smallest units of the order's currency.	13256

#### Request example:

Authorization-Key: *****
Authorization-Password: *****
Content-Type: application/json

{
    "amount": 1112
}

#### Response parameters:

Parameter	Type	R/O	Description	Example
`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 requires a unique identifier.	string[100]
`method`	string[100]	R	Payment method.	cards
`amount`	int	R	Balance of the payment, taking into account all unblockings and refunds made. Presented in the payment currency, using the smallest unit of that currency.	Example: `10051` (for an amounting to 100 dollars and 51 cents in USD)
`status`	string[100]	R	Payment status.	refunded

In case of	Error	Type	Title	Comment
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.
No payment found with the specified ID.	404	paymentNotFound	There is no payment with the specified id.
Merchant terminal not found when creating a session. Incorrect terminal password provided when creating a session.	422	invalidTerminalCredentials	Invalid terminal key or password.
The operation amount specified is incorrect: the value passed is not a positive integer	422	invalidAmount	Invalid amount of the transaction.
The use of the interface (gapi, mapi) is not allowed for the requested transaction direction (payment, payout)	422	interfaceNotAllowed	This interface is not allowed.
Merchant's balance is insufficient to complete the refund.	422	insufficientMerchantFundsToCompleteRefund	The refund was created. There are not enough funds on the merchant's balance to complete the refund.
Inappropriate payment state for the operation: For the refund operation, payment must be in Authorized state;	422	invalidPaymentState	The payment is in an invalid state.
For the Refund operation: Cards API returned an error MULTIPLE_REFUND_NOT_SUPPORTED	422	multipleRefundNotSupported	Subsequent refunds are not supported in automatic mode. Contact our support team.
For the Refund operation: Cards API returned an error PARTIAL_REFUND_NOT_ALLOWED	422	partialRefundNotAllowed	Cannot refund a part of the previously charged amount.
Unforeseen errors on the service side. Prior to the creation of the session.	500	unexpectedError	Unexpected error. Contact our support team.
Temporary error: You might be able to do the operation successfully if you try again later.	503	temporaryMalfunction	Temporary malfunction. Please try again later.

### Retrieve Payment Method Details Use this method to view the details you need to include in the [Create Payment > *details* object](#create-payment) to make a payment with a specific payment method. The response contains the *details.parameterIsNestedInEntity* parameter that you can use to retrieve all the instances related to the payment method and entity via the [Retrieve Payment Method Entities](#retrieve-payment-method-entities) request. For example: 1. Let's say you sent the [Retrieve Payment Method Details](#retrieve-payment-method-details) request to view the required details for the *openbaking* method: GET mapi/v2/payments/methods/openbanking/details 2. The response contains the *bankId* parameter and its *details.parameterIsNestedInEntity* is *banks.* 3. Using the details you've got in the response to the first request, you can retrieve all the instances related to the payment method (for example, *openbanking*), entity (for example, *banks*), and, if needed, a country (for example, *Sweden*) via the [Retrieve Payment Method Entities](#retrieve-payment-method-entities) request: GET /mapi/v2/payments/methods/openbanking/entities /banks?countries=SE 4. The response contains a list of instances related to specified parameters. In our example, it could be a list of banks with their details (the bank ID, the branch name, the branch country, etc.) as key-value pairs.

Retrieving payment method details and possible entities

{% hint style="info" %} Currently, this API method works for the *openbanking* payment method only. {% endhint %} **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/mapi/v2/payments/methods/{method}/details` **Request method:** `GET` **Request headers:**

Header	R/O	Value	Description
`Content-Type`	R	application/json	Original media type of the resource.
`SessionTerminalKey`	R		Merchant terminal identifier.
`SessionTerminalPassword`	R		Merchant terminal password.

#### Path request parameters:

Parameter	Type	R/O	Description	Example
`method`	string	R	Payment method. Currently, this API method works for the openbanking payment method only.	"openbanking"

#### Response parameters:

Parameter	Type	R/ O	Description	Example
`details`	array	R	List of the parameters required for the specified payment method.
`details.name`	string	R	Parameter name.	"bankId"
`details.valueIsRequestableFromApi`	boolean	R	It states whether the parameter is retrievable via API or not. In other words, if it's true, you can retrieve the parameter via the Retrieve Payment Method Entities request.	true
`details.parameterIsNestedInEntity`	string	O	It states from which entity the parameter is nested. By using this entity name, you can retrieve all the instances related to the payment method and the entity via the Retrieve Payment Method Entities request.	"banks"

#### Response example: ```json "details":[ { "name":"bankId", "valueIsRequestableFromApi":true, "parameterIsNestedInEntity":"banks" } ] ``` #### Error types and codes | In case of | Error | Type | Title | | ---------------------------------------------- | ----- | -------------------------- | ------------------ | | Invalid terminal key or password. | 404 | invalidTerminalCredentials | Invalid Terminal | | The specified payment method is not supported. | 422 | methodNotSupported | Unsupported Method | ### Retrieve Payment Method Entities Use this method to retrieve all the instances related to a specific payment method and entity. To get the entity name, check the *details.parameterIsNestedInEntity* parameter in the response for the [Retrieve Payment Method Details](#retrieve-payment-method-details) request. The retrieved instances may include, for example, a list of banks with their details, such as a bank ID, a branch name, a branch country, etc. {% hint style="info" %} Currently, the API method works for the *openbanking* payment method only. {% endhint %} **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/mapi/v2/payments/methods/{method}/entities/{entity}?countries={alpha2code},{alpha2code}` **Request method:** `GET` **Request headers:**

Header	R/O	Value	Description
`Content-Type`	R	application/json	Original media type of the resource.
`SessionTerminalKey`	R		Merchant terminal identifier.
`SessionTerminalPassword`	R		Merchant terminal password.

#### Path request parameters:

Parameter	Type	R/O	Description	Example
`method`	string	R	Payment method. Note: Currently, the API method works for the openbanking payment method only.	"openbanking"
`entity`	string	R	To get the parameter, check the details.parameterIsNestedInEntity parameter in the response to the Retrieve Payment Method Details request.	"banks"

#### Query request parameters:

Parameter	Type	R/O	Description	Example
`countries`	array	R	List of countries in the ISO 3166-1 alpha-2 format.	AU, SE

#### Response parameters:

Parameter	Type	R/ O	Description	Example
`entity`	array	R	List of instances for the specified payment method and entity.
`entity.key`	string	R	Instance identifier.	"branchName"
`entity.value`	string	R	Value within the instance.	"Swedbank"

#### Response example ```json [ { "key": "bankId", "value": "6daf14a5-d8c0-43ac-881e-33621d198414" }, { "key": "branchName", "value": "Swedbank" } ] ``` #### Error types and codes | In case of | Error | Type | Title | | ---------------------------------------------------------------------------- | ----- | --------------------------------------------------------------------- | ------------------ | | Invalid terminal key or password. | 404 | invalidTerminalCredentials | Invalid Terminal | | The specified payment method is not supported. | 422 | methodNotSupported | Unsupported Method | | The entity is not supported either by the API method or by a payment method. | 422 |

entityNotSupportedByEndpoint

entityNotSupportedByMethod

| Unsupported Entity | ### Upload files with payment confirmation This method allows uploading up to three payment-related files to internal storage for later use in payment confirmation. Each uploaded file must have its purpose specified. These files are essential for verifying and confirming the payment during processing. {% hint style="info" %} Please note that the success response will return a JSON array of objects. {% endhint %} **Entry parameters:** **Request URL:** `/mapi/v2/payments/{paymentID}/files/upload` **Request method:** `POST` #### **Request headers:**

Header	R/O	Value	Description
`Content-Type`	R	multipart/form-data	The original media type of the resource.
`AuthorizationKey`	R	-	Merchant terminal identifier.
`AuthorizationPassword`	R	-	Merchant terminal password.

Path parameters: | Parameter | Type | R/O | Description | | ----------- | ---- | ------ | -------------------------- | | `paymentId` | R | string | Unique payment identifier. | #### Parameters in form data**:** | Parameter | Type | R/O | Description | | --------- | ---------- | --- | ----------------------------- | | files | files | R | Uploaded files | | purpose | text/plain | R | Purpose of the uploaded files | #### Response Parameters **HTTP response code:** 200 **Response type:** application/json The response will return a JSON array of objects with the following parameters:

Parameter	Type	R/O	Description	Example
id	string	R	Identifier of the uploaded file for further use in the payment process	236e2d3b-2380-473c-bc5d-646b504cf614
fileName	string	R	Name of the uploaded file associated with this identifier	receipt.jpg

#### Response example ``` [ { "fileName": "receipt.jpg", "id": "78704fde-b19b-4cfa-a849-3a05aec7f2aa" }, { "fileName": "confirmation.pdf", "id": "236e2d3b-2380-473c-bc5d-646b504cf614" } ] ``` ## MAPI Payout methods This section explains the main API methods utilized in the Payler [**Payout Merchant scheme**](#payout-merchant-scheme) (**MAPI**). It includes detailed descriptions and protocols for creating a payout, checking payout status. ### Create Payout Use this method to initiate a payout creation request through the MAPI interface. **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/mapi/payout/v1/payouts` **Request method:** `POST` #### **Request headers:**

Header	R/O	Value	Description
`Content-Type`	R	application/json	The original media type of the resource.
`AuthorizationKey`	R	-	Merchant terminal identifier.
`AuthorizationPassword`	R	-	Merchant terminal password.

#### **Body request parameters:**

Parameter	Type	R/O	Description
`order`	object	R	Order parameters
`order.id`	string[100]	R	Unique identifier for the order within the merchant's system. Each payout (session) requires a distinct identifier. Only printable ASCII characters are allowed.
`order.currency`	string[3]	R	Currency of the payout in the ISO-4217 format.
`order.amount`	long	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.
`order.description`	string[256]	O	Description of the order.
`method`	string	R	Payout method.
`details`	object	R	Parameters depend on the selected payout method: cards banktransfer communitybank interac netbankning payster payid payfix pcr sepainstant mercadopago lemonacash orangecash vodafonecash instapay
`customer`	object	R	Customer's parameters. If customer's data (including email) is not real, payout will be rejected by antifraud system
`customer.id`	string	O	Customer's identifier.
`customer.email`	string	R	Customer's email address.
`customer.phoneNumber`	string	R	Customer's phone number must adhere to the ITU-T E.123 and ITU-T E.164 standards.
`customer.firstName`	string	R	Customer's first name.
`customer.lastName`	string	R	Customer's last name.
`customer.address`	object	O*	Customer's address. *Required for these methods: `netbanking`, `interac`
`customer.address.addresLine`	string[100]	O*	Customer's address. *Required for these payment methods: `netbanking`
`customer.address.countryCode`	string[2]	O*	Customer's country. * For `netbanking` method: Is required Expected value is `IN` * For `interac` method: Is required Expected value is `CA`
`sessionContext`	object	R	User session context parameters.
`sessionContext.ip`	string	R	User ip address.
`sessionContext.languageCode`	string[2]	O	The language is always `en` (English).
`returnUrls`	object	R	The URLs where the user will be redirected.
`returnUrls.default`	string	R	The URL where the user will be redirected in cases where the transaction does not achieve its final status.
`returnUrls.success`	string	O	The URL to redirect the user to in the event of a successful payout. If this URL is not provided, the default address in `returnURLs.default` will be used.
`returnUrls.failure`	string	O	The URL to redirect the user to if the payout is unsuccessful. If this URL is not provided, the default address in `returnURLs.default` will be used.
`notificationUrl`	string	O	The URL for receiving notifications about payout status (callbacks). If this URL is not provided, no callbacks will be executed.
`antifraudParameters`	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_*”`.

#### Payout Details for the “cards” method | Parameter | Type | R/O | Description | | ------------------ | --------------------- | --- | ---------------------------------------------------------------------- | | `type` | string enum \[“card”] | R | In this case, the type is always *card*. | | `cardNumber` | string\[19] | R | Card number. | | `cardHolderName` | string\[40] | R | Cardholder's full name. It may contain two or three words with spaces. | | `cardSecurityCode` | string\[4] | O | Security code (CVV). | | `expiryMonth` | int\[2] | R | Expiry month. | | `expiryYear` | int\[2] | R | Expiry year. | #### Payout details for the “vodafonecash” method

Parameter Type R/O Description Example

phone

string

Beneficiary's phone number must:

be exactly 11 digits,
contain only numbers,
not include country code.

"01212345678"

beneficiaryName string R Beneficiary's first and last name.
A string of at least two words separated by a space is expected. Up to 100 characters. "John Doe"

#### Payout details for the “orangecash” method

Parameter Type R/O Description Example

phone

string

Beneficiary's phone number must:

be exactly 11 digits,
contain only numbers,
not include country code.

"01012345678"

beneficiaryName string R Beneficiary's first and last name.
A string of at least two words separated by a space is expected. Up to 100 characters. "John Doe"

#### Payout details for the “mercadopago” method

Parameter Type R/O Description Example

accountNumber

string

Beneficiary's account number must:

be 22 symbols,
contain only numbers.

"0000168100000000000000"

beneficiaryName string R Beneficiary's first and last name.
A string of at least two words separated by a space is expected. Up to 100 characters. "John Doe"

#### Payout details for the “lemoncash” method

Parameter Type R/O Description Example

accountNumber

string

Beneficiary's account number must:

be 22 symbols,
contain only numbers.

"0000168100000000000000"

beneficiaryName string R Beneficiary's first and last name.
A string of at least two words separated by a space is expected. Up to 100 characters. "John Doe"

#### Payout details for the “instapay” method

Parameter	Type	R/O	Description	Example
type	string	R	Type of details. Possible values: • Phone • InstaPayId
`accountNumber`	string	R	The format is determined by the value of the parameter `type`: • if `type = phone` — 11 digits • if `type = instaPayId` — a string in the format `<username>@instapay`, with a maximum length of 256 characters	"12345678901" or "username@instapay"
`beneficiaryName`	string	R	Beneficiary's first and last name. A string of at least two words separated by a space is expected. Up to 100 characters.	"John Doe"

#### Payout details for the “payster” method {% hint style="info" %} The set of payout details for the *payster* method depends on the country: **Australia** or **New Zealand**. {% endhint %} For **Australia**, the parameters are:

Parameter	Type	R/O	Description	Example
`type`	string enum [“email”, “phone”, “bsbAccount“]	R	Type of details used for the “payster” method: “email“ if an email address is used as a requisite. “phone“ if a telephone number is used as a requisite. “bsbAccount“ if a bank code and bank account number are used as a requisite.	"email"
`accountHolder`	string	R	The account holder full name must: contain only Latin letters, numbers, or spaces between, have two words minimum, have between 3 and 50 symbols.	"John Doe"
`email`	string	O*	Required for the “email”* type. The email must: contain only Latin letters, numbers, or some special symbols ("_" "-" "." "+" "~"), be between 5 and 35 symbols.	"johndoe@test.com"
`phone`	string	O*	Required for the “phone”* type. The format is +{number}. The number must be between 8 and 16 symbols.	"+123456789"
`bsb`	string	O*	Required for the “bsbAccount”* type. Bank 6-digit bsb code.	“010000“
`accountNumber`	string	O*	Required for the “bsbAccount”* type. Account number must be between 6 and 12 symbols.	“12345678901234567890“

For **New Zealand**, the parameters are: | Parameter | Type | R/O | Description | Example | | ---------------------- | ------ | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | `beneficiaryFirstName` | string | R |

Beneficiary's first name must:

contain only Latin letters or spaces between them,
not exceed 48 symbols.

The overall length of the beneficiaryFirstName and beneficiaryLastName parameters must be within 50 symbols.

Beneficiary's last name must:

contain only Latin letters or spaces between them,
not exceed 48 symbols.

The overall length of the beneficiaryFirstName and beneficiaryLastName parameters must be within 50 symbols.

| "Doe" | | `accountNumber` | string | R |

Beneficiary's account number must:

be between 15 and 16 symbols,
contain only numbers.

| “1234567890123456“ | #### Payout details for the “payid” method

Parameter	Type	R/O	Description	Example
`type`	string enum [“email”, “phone”]	R	Type of details used for the “payid” method: “email“ if an email address is used as a requisite. “phone“ if a telephone number is used as a requisite.	"email"
`beneficiaryFirstName`	string	R	Beneficiary's first name must: contain only Latin letters or spaces between them, not exceed 48 symbols. The overall length of the beneficiaryFirstName and beneficiaryLastName parameters must be within 50 symbols.	"John"
`beneficiaryLastName`	string	R	Beneficiary's last name must: contain only Latin letters or spaces between them, not exceed 48 symbols. The overall length of the beneficiaryFirstName and beneficiaryLastName parameters must be within 50 symbols.	"Doe"
`email`	string	O*	Required for the “email”* type. The email must: contain only Latin letters, numbers, or some special symbols ("_" "-" "." "+" "~"), be between 5 and 35 symbols.	"johndoe@test.com"
`phone`	string	O*	Required for the “phone”* type. The format is {number}, consists of 9 digits, without country code.	"123456789"

#### Payout details for the “interac” method

Parameter	Type	R/O	Description
`firstName`	string	R	Customer’s first name. May contain only latin letters, up to 100 characters in length.
`lastName`	string	R	Customer’s last name. May contain only latin letters, up to 100 characters in length.
`email`	string	R	Customer’s email. At least an email or phone number must be linked to a bank account.
`phone`	string	R	Customer'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.

#### Payout details for the “netbanking” method | Parameter | Type | R/O | Description | Example | | ---------------------- | ---------------------------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `type` | string enum \[“bankAccount“] | R | In this case, it's always *"bankAccount"*. | | | `beneficiaryFirstName` | string | R | First name of a beneficiary mustn’t exceed 50 symbols and may contain Latin letters and spaces (excluding spaces at the beginning and at the end of the line). | "John" | | `beneficiaryLastName` | string | R | Last name of a beneficiary mustn’t exceed 50 symbols and may contain Latin letters and spaces (excluding spaces at the beginning and at the end of the line). | "Doe" | | `accountNumber` | string | R | Beneficiary's account number mustn’t exceed 100 symbols | "1234567890" | | `accountBankCode` | string | R | Code of the customer’s bank mustn’t exceed 20 symbols | "UTBI0DWK743" | | `accountBankName` | string | R | Name of the customer’s bank mustn’t exceed 100 symbols | "UNITED BANK OF INDIA" | | `accountBankBranch` | string | O | Branch of the customer’s bank mustn’t exceed 100 symbols | "DWARKA" | | `accountBankAddress` | string | O | Address of the customer’s bank mustn’t exceed 100 symbols | "BHAGAWATI PLAZA PLNO12" | #### Payout details for the “payfix” method | Parameter | Type | R/O | Description | Example | | ---------- | ----------------------- | --- | ------------------------------------------------------------------------------------------- | ------------ | | `type` | string enum \[“wallet“] | R | In this case, it's always *"wallet",* meaning a wallet ID is used as a requisite. | | | `walletId` | string | R |

Payfix wallet identifier.

10-long digit, starting at 1 or higher, is expected.

| "1234567890" | #### Payout details for the “communitybank” method | Parameter | Type | R/O | Description | | ----------------- | ---------------------------- | --- | -------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string enum \[“bankAccount“] | R | In this case, it's always *"bankAccount".* | | `iban` | string | R | IBAN. | | `swiftCode` | string | R | SWIFT/BIC code. | | `beneficiaryName` | string | R |

Beneficiary's first and last name.

A string of at least two words separated by a space is expected. Up to 200 characters.

Beneficiary's document number.

The limit is 11 digits.

| #### Payout details for the “pcr” method

Parameter	Type	R/O	Description	Example
`type`	string enum [“card”, “iban”]	R	Types of requisite details used for the “pcr” method: “card”: a card number is used as a requisite. “iban”: an IBAN is used as a requisite	“card” “iban”
`accountNumber`	string	R	If the type is “card”, the account number is a card number. If the type is “iban”, the account number is an IBAN.	“2200300103446166” (for “card”) “NL91ABNA0417164300” (for “iban”)
`beneficiaryName`	string	R	Beneficiary’s full name. A string of two words separated by a space is expected.	“John Doe”
`phone`	string	O	Beneficiary’s phone number.	“124567890”

#### Payout details for the "sepainstant" method

Parameter	Type	R/O	Description	Example
`type`	string enum [“bankAccount“]	R	In this case, the type is always “bankAccount”.	“bankAccount”
`beneficiaryEmail`	string	R	The beneficiary email mustn’t exceed 100 symbols and may contain: Latin letters. Numbers. Some special symbols: underscore (_), hyphen (-), period (.), and plus (+).	"test@test.com"
`beneficiaryBirthdate`	string	R	Birthdate in the dd-mm-yyyy format. Beneficiary must be between 18 and 60 years old on the current day.	"23-08-1978"
`beneficiaryCountryResidence`	string	R	Beneficiary country in the ISO Alpha-2 format.	"FR"
`beneficiaryFirstName`	string	R	First name of a beneficiary mustn’t exceed 100 symbols and may contain Latin letters and spaces (excluding spaces at the beginning and at the end of the line).	“John”
`beneficiaryLastName`	string	R	Last name of a beneficiary mustn’t exceed 100 symbols and may contain Latin letters and spaces (excluding spaces at the beginning and at the end of the line).	"Doe"
`iban`	string	R	Beneficiary IBAN from the SEPA region.	“FR1420041010050500013M02606”

#### Payout details for the "`banktransfer`" method

Parameter	Type	R/O	Description	Example
`bankAccount`	string	R	Bank account number must be between 8 and 24 symbols.	"4564984561151456"
`bankCode`	string	R*	Code of the customer’s bank. * Required only for bank transfers with KRW and TWD currencies.	"BUSANBANK"
beneficiaryName	string	R	Beneficiary’s full name. A string of two words separated by a space is expected. Max length - 250 characters.	"John Smith"

#### Payout details for the "`banktransfer`" (Marocco) method

Parameter	Type	R/O	Description	Example
accountNumber	string	R	Bank account number must be between 8 and 24 symbols.	"4564984561151456"
beneficiaryName	string	R	Beneficiary’s full name. A string of two words separated by a space is expected. Max length - 250 characters.	"John Smith"

#### Payout details for the "`banktransfer`" (UAE) method

Parameter	Type	R/O	Description	Example
accountNumber	string	R	Bank account number must be in IBAN format, consisting of 15 to 34 characters.	"AE020090004001079346500"
beneficiaryName	string	R	Beneficiary’s full name. A string of two words separated by a space is expected. Max length - 250 characters.	"John Smith"

#### Payout details for the "`banktransfer`" (Australia) method

Parameter	Type	R/O	Description	Example
accountNumber	string	R	Payout account number. Contains digits only, length from 8 to 24 characters.	"4564984561151456"
bankbranchcode	string	R	BSB code, consisting of 6 digits	"123456"
beneficiaryName	string	R	Beneficiary’s full name. A string of two words separated by a space is expected. Max length - 250 characters.	"John Smith"

#### Request example **for the `banktransfer` (Marocco) method**: ```json Authorization-Key: ***** Authorization-Password: ***** Content-Type: application/json { "order": { "id": "test-d43850a9-c909-4580-b589-a89c1748a1da", "amount": 123456, "currency": "MAD", "description": "some description" }, "method": "banktransfer", "details": { "accountNumber": "1234567890", "beneficiaryName": "John Doe", }, "customer": { "id": "62f66472913640cc93f49d5477840633" }, "sessionContext": { "ip": "172.16.0.1", "languageCode": "en" }, "returnUrls": { "default": "https://yourwebsite.com/{someUsefulParams1}", "success": "https://yourwebsite.com/{someUsefulParams2}", "failure": "https://yourwebsite.com/{someUsefulParams3}" }, "notificationUrl": "https://yourwebsite.com/notify", "antifraudParams": { "antifraud_email": "rms@check.com", "antifraud_param_name": "param_value" } } ``` #### Request example **for the `banktransfer` (UAE) method**: ```json Authorization-Key: ***** Authorization-Password: ***** Content-Type: application/json { "order": { "id": "test-d43850a9-c909-4580-b589-a89c1748a1da", "amount": 123456, "currency": "AED", "description": "some description" }, "method": "banktransfer", "details": { "accountNumber": "AE020090004001079346500", "beneficiaryName": "John Doe", }, "customer": { "id": "62f66472913640cc93f49d5477840633" }, "sessionContext": { "ip": "172.16.0.1", "languageCode": "en" }, "returnUrls": { "default": "https://yourwebsite.com/{someUsefulParams1}", "success": "https://yourwebsite.com/{someUsefulParams2}", "failure": "https://yourwebsite.com/{someUsefulParams3}" }, "notificationUrl": "https://yourwebsite.com/notify", "antifraudParams": { "antifraud_email": "rms@check.com", "antifraud_param_name": "param_value" } } ``` #### Request example **for the `banktransfer` (Australia) method**: ```json Authorization-Key: ***** Authorization-Password: ***** Content-Type: application/json { "order": { "id": "test-d43850a9-c909-4580-b589-a89c1748a1da", "amount": 123456, "currency": "AUD", "description": "some description" }, "method": "banktransfer", "details": { "accountNumber": "40010793465", "bankbranchcode":"123456", "beneficiaryName": "John Doe", }, "customer": { "id": "62f66472913640cc93f49d5477840633" }, "sessionContext": { "ip": "172.16.0.1", "languageCode": "en" }, "returnUrls": { "default": "https://yourwebsite.com/{someUsefulParams1}", "success": "https://yourwebsite.com/{someUsefulParams2}", "failure": "https://yourwebsite.com/{someUsefulParams3}" }, "notificationUrl": "https://yourwebsite.com/notify", "antifraudParams": { "antifraud_email": "rms@check.com", "antifraud_param_name": "param_value" } } ``` #### Request example **for the `cards` method**:

Authorization-Key: *****
Authorization-Password: *****
Content-Type: application/json

{
    "order": {
        "id": "test-d43850a9-c909-4580-b589-a89c1748a1da",
        "amount": 123456,
        "currency": "USD",
        "description": "some description"
    },
    "method": "cards",
    "details": {
        "type": "card",
        "cardNumber": "4242424242424242",
        "cardHolderName": "Card Holder",
        "cardSecurityCode": "123",
        "expiryMonth": 11,
        "expiryYear": 2025
    },
    "customer": {
        "id": "62f66472913640cc93f49d5477840657",
        "firstName": "Harry",
        "lastName": "Potter",
        "email": "customer@email.com",
        "phone": "357123456789"
     },
    "sessionContext": {
        "ip": "172.16.0.1",
        "languageCode": "en"
    },
    "returnUrls": {
      "default": "https://yourwebsite.com/{someUsefulParams1}",
      "success": "https://yourwebsite.com/{someUsefulParams2}",
      "failure": "https://yourwebsite.com/{someUsefulParams3}"
    },
    "notificationUrl": "https://yourwebsite.com/notify",
    "antifraudParams": {
        "antifraud_email": "Camryn.Roob83@gmail.com",
        "antifraud_param_name": "param_value"
    }
}

#### Request example **for the `instapay` method:** ```javascript Authorization-Key: ***** Authorization-Password: ***** Content-Type: application/json { "order": { "id": "test-d43850a9-c909-4580-b589-a89c1748a1da", "amount": 123456, "currency": "EGP", "description": "some description" }, "method": "instapay", "details": { "type":"instapayid", "accountNumber": "username@instapay", "beneficiaryName": "John Doe", }, "customer": { "id": "62f66472913640cc93f49d5477840633" }, "sessionContext": { "ip": "172.16.0.1", "languageCode": "en" }, "returnUrls": { "default": "https://yourwebsite.com/{someUsefulParams1}", "success": "https://yourwebsite.com/{someUsefulParams2}", "failure": "https://yourwebsite.com/{someUsefulParams3}" }, "notificationUrl": "https://yourwebsite.com/notify", "antifraudParams": { "antifraud_email": "rms@check.com", "antifraud_param_name": "param_value" } } ``` #### Request example **for the `orangecash` method**: ```javascript Authorization-Key: ***** Authorization-Password: ***** Content-Type: application/json { "order": { "id": "test-d43850a9-c909-4580-b589-a89c1748a1da", "amount": 123456, "currency": "EGP", "description": "some description" }, "method": "orangecash", "details": { "phone": "01212345678", "beneficiaryName": "John Doe", }, "customer": { "id": "62f66472913640cc93f49d5477840633" }, "sessionContext": { "ip": "172.16.0.1", "languageCode": "en" }, "returnUrls": { "default": "https://yourwebsite.com/{someUsefulParams1}", "success": "https://yourwebsite.com/{someUsefulParams2}", "failure": "https://yourwebsite.com/{someUsefulParams3}" }, "notificationUrl": "https://yourwebsite.com/notify", "antifraudParams": { "antifraud_email": "rms@check.com", "antifraud_param_name": "param_value" } } ``` #### Request example **for the `vodafonecash` method**: ```javascript Authorization-Key: ***** Authorization-Password: ***** Content-Type: application/json { "order": { "id": "test-d43850a9-c909-4580-b589-a89c1748a1da", "amount": 123456, "currency": "EGP", "description": "some description" }, "method": "vodafonecash", "details": { "phone": "01012345678", "beneficiaryName": "John Doe", }, "customer": { "id": "62f66472913640cc93f49d5477840633" }, "sessionContext": { "ip": "172.16.0.1", "languageCode": "en" }, "returnUrls": { "default": "https://yourwebsite.com/{someUsefulParams1}", "success": "https://yourwebsite.com/{someUsefulParams2}", "failure": "https://yourwebsite.com/{someUsefulParams3}" }, "notificationUrl": "https://yourwebsite.com/notify", "antifraudParams": { "antifraud_email": "rms@check.com", "antifraud_param_name": "param_value" } } ``` #### Request example **for the `mercadopago`method**: ```javascript Authorization-Key: ***** Authorization-Password: ***** Content-Type: application/json { "order": { "id": "test-d43850a9-c909-4580-b589-a89c1748a1da", "amount": 123456, "currency": "ARS", "description": "some description" }, "method": "mercadopago", "details": { "accountNumber": "0000168100000000000000", "beneficiaryName": "John Doe", }, "customer": { "id": "62f66472913640cc93f49d5477840633" }, "sessionContext": { "ip": "172.16.0.1", "languageCode": "en" }, "returnUrls": { "default": "https://yourwebsite.com/{someUsefulParams1}", "success": "https://yourwebsite.com/{someUsefulParams2}", "failure": "https://yourwebsite.com/{someUsefulParams3}" }, "notificationUrl": "https://yourwebsite.com/notify", "antifraudParams": { "antifraud_email": "rms@check.com", "antifraud_param_name": "param_value" } } ``` #### Request example **for the `lemoncash` method**: ```javascript Authorization-Key: ***** Authorization-Password: ***** Content-Type: application/json { "order": { "id": "test-d43850a9-c909-4580-b589-a89c1748a1da", "amount": 123456, "currency": "ARS", "description": "some description" }, "method": "lemoncash", "details": { "accountNumber": "0000168100000000000000", "beneficiaryName": "John Doe", }, "customer": { "id": "62f66472913640cc93f49d5477840633" }, "sessionContext": { "ip": "172.16.0.1", "languageCode": "en" }, "returnUrls": { "default": "https://yourwebsite.com/{someUsefulParams1}", "success": "https://yourwebsite.com/{someUsefulParams2}", "failure": "https://yourwebsite.com/{someUsefulParams3}" }, "notificationUrl": "https://yourwebsite.com/notify", "antifraudParams": { "antifraud_email": "rms@check.com", "antifraud_param_name": "param_value" } } ``` #### Request example **for the `payster` method:** ```json Authorization-Key: ***** Authorization-Password: ***** Content-Type: application/json { "order": { "id": "test-d43850a9-c909-4580-b589-a89c1748a1da", "amount": 123456, "currency": "AUD", "description": "some description" }, "method": "payster", "details": { "type": "email", "accountHolder": "John Doe", "email": "some.email@some.domain" }, "customer": { "id": "62f66472913640cc93f49d5477840633", "firstName": "Harry", "lastName": "Potter", "email": "customer@email.com", "phone": "357123456789" }, "sessionContext": { "ip": "172.16.0.1", "languageCode": "en" }, "returnUrls": { "default": "https://yourwebsite.com/{someUsefulParams1}", "success": "https://yourwebsite.com/{someUsefulParams2}", "failure": "https://yourwebsite.com/{someUsefulParams3}" }, "notificationUrl": "https://yourwebsite.com/notify", "antifraudParams": { "antifraud_email": "Camryn.Roob83@gmail.com", "antifraud_param_name": "param_value" } } ``` #### Request example **for the `pcr` method:**

Authorization-Key: *****
Authorization-Password: *****
Content-Type: application/json

{
    "order": {
        "id": "test-d43850a9-c909-4580-b589-a89c1748a1da",
        "amount": 123456,
        "currency": "TRY",
        "description": "some description"
    },
    "method": "pcr",
    "details": {
        "type": "iban",
        "accountNumber": "NL91ABNA0417164300",
        "beneficiaryName": "John Doe",
        "phoneNumber": "124567890"
    },
    "customer": {
        "firstName": "Harry",
        "lastName": "Potter",
        "email": "customer@email.com",
        "phone": "357123456789"
     },
    "sessionContext": {
        "ip": "172.16.0.1",
        "languageCode": "en"
    },
    "returnUrls": {
      "default": "https://yourwebsite.com/{someUsefulParams1}",
      "success": "https://yourwebsite.com/{someUsefulParams2}",
      "failure": "https://yourwebsite.com/{someUsefulParams3}"
    },
    "notificationUrl": "https://yourwebsite.com/notify",
    "antifraudParams": {
        "antifraud_email": "Camryn.Roob83@gmail.com",
        "antifraud_param_name": "param_value"
    }
}

#### Request example **for the `sepainstant`method:** ```json Authorization-Key: ***** Authorization-Password: ***** Content-Type: application/json { "order": { "id": "test-d43850a9-c909-4580-b589-a89c1748a1da", "amount": 1000, "currency": "EUR" }, "method": "sepainstant", "details": { "type": "bankAccount", "beneficiaryEmail": "test@test.com", "beneficiaryBirthdate": "23-08-1978", "beneficiaryCountryResidence": "FR", "beneficiaryFirstName": "John", "beneficiaryLastName": "Doe", "iban": "FR1420041010050500013M02606" }, "customer": { "firstName": "Harry", "lastName": "Potter", "email": "customer@email.com", "phone": "357123456789" }, "sessionContext": { "ip": "172.16.0.1", "languageCode": "en" }, "returnUrls": { "default": "https://yourwebsite.com/{someUsefulParams1}", "success": "https://yourwebsite.com/{someUsefulParams2}", "failure": "https://yourwebsite.com/{someUsefulParams3}" }, "notificationUrl": "https://yourwebsite.com/notify", "antifraudParams": { "antifraud_email": "customer@email.com", "antifraud_param_name": "param_value" } } ``` **Response parameters:** | Parameter | | R/O | Description | Example | | --------- | ------ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | `id` | string | R | Unique payout identifier. | 9073926b929f31c2abc9fad77ae3e8eb | | `orderId` | string | R | Unique Identifier of the order being paid in the merchant's system. | | | `method` | string | R | Payment method. | cards | | `status` | string | R | Payout status. | authorized | | `amount` | long | R | Total payout 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. | 10050 | #### **Response example:** ```json { "id": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "test-d43850a9-c909-4580-b589-a89c1748a1da", "method": "cards", "status": "pending", "amount": 10050 } ``` #### **Error types and codes:**

In case of	Error	Type	Title	Comment
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.
Merchant terminal not found when creating a session. Incorrect terminal password provided when creating a session.	422	invalidTerminalCredentials	Invalid terminal key or password.
Invalid Terminal Settings	422	invalidTerminalSettings	Terminal’s settings are invalid. Contact our support team.
The use of the mapi interface is not allowed for the payout transaction	422	interfaceNotAllowed	This interface is not allowed.
The operation amount specified is incorrect: the value passed is not a positive integer	422	invalidAmount	Invalid amount of the transaction.
Payout with the same order id value has already been registered	422	duplicatedOrderId	Duplicated order id.
The requested currency is not supported.	422	сurrencyNotSupported	This currency is not supported.
The requested payment method is not supported.	422	methodNotSupported	This payment method not supported.
Unforeseen errors on the service side. Prior to the creation of the session.	500	unexpectedError	Unexpected error. Contact our support team.
Temporary error: You might be able to do the operation successfully if you try again later.	503	temporaryMalfunction	Temporary malfunction. Please try again later.

### Get Payout Status Use this method to request the current payout status through the MAPI interface. **Entry parameters:** **Request URL:** `https://facade-api.main.gate-api.com/mapi/payout/v1/payouts/{payoutId}` **Request method:** GET **Request headers:**

Header	R/O	Value	Description
`Content-Type`	R	application/json	The original media type of the resource.
`Cache-Control`	R	no-cache	Mandates retrieving the response directly from the server, bypassing caches, to guarantee the latest status.
`AuthorizationKey`	R		Merchant terminal identifier.
`AuthorizationPassword`	R		Merchant terminal password.

Path parameters: | Parameter | Type | R/O | Description | | ---------- | ---- | ------ | ------------------------- | | `payoutId` | R | string | Unique payout identifier. | #### **Response body parameters:** | Parameter | Type | R/O | Description | Example | | ------------- | ------ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | `id` | string | R | Unique payout identifier. | 9073926b929f31c2abc9fad77ae3e8eb | | `orderId` | string | R | Unique identifier for the order within the merchant's system. | | | `method` | string | R | Payout method. | cards | | `status` | string | R | Payout status. | authorized | | `description` | string | O | Comment on the status. | "balanceExceeded" | | `amount` | long | R | Total payout 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. | 10050 | #### **Response example - Successful payout:** ```json { "id": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "test-d43850a9-c909-4580-b589-a89c1748a1da", "method": "cards", "status": "authorized", "amount": 10050 } ``` #### **Response example - Payout rejected:** ```json { "id": "9073926b929f31c2abc9fad77ae3e8eb", "orderId": "test-d43850a9-c909-4580-b589-a89c1748a1da", "method": "cards", "status": "rejected", "description": "balanceExceeded", "amount": 10050 } ``` #### **Error types and codes:** | **In case of** | **Error** | **Type** | **Title** | | ------------------------------------------------------------------------------------------------------------------ | --------- | -------------------------- | ------------------------------------------- | | No payout found with the specified ID. | 404 | payoutNotFound | There is no payout with the specified id. | | 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 mapi interface is not allowed for the payout transaction | 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. | ### MAPI failed request responses In the event of a request failure, the response will include a detailed description of the error. **Error description parameters:**

Name	Type	R/O	Description
`error.type`	string	R	Internal Error Code: Necessary when reaching out to technical support service.
`error.title`	string	R	Error Description: Details of the occurred error.

**Failed request response example:** ```json { "error": { "type":"invalidAmount", "title":"Invalid amount of the transaction." } } ``` Expected `error.type` values are described for all the API methods below. In cases errors were detected during input parameter validation, an additional invalid-params array is included in the response. Each element of this array describes the specific rules that were violated: ```json { "error": { "type": "validationError", "title": "Your request parameters didn't validate.", "invalid-params": [ { "name": "someKey", "reason": "keyHasExtraLength" } ] } } ``` The potential reasons for errors are detailed in the [Validation errors](#validation-errors) table below. Specifically, if the request body is not a correct JSON object, a response with the `malformedRequest` error type is returned. The reason value will include the line number where the first error occurred, indicated as 'XX' (the number of the line containing the first error): ```json { "error": { "type": "malformedRequest", "title": "Your request body didn't validate.", "invalid-params": [ { "name": "body", "reason": "bodyMalformedAtPosXXX" } ] } } ``` #### **Validation errors:**

Error	Description
`keyHasExtraLength`	Key exceeds maximum length limit.
`keyIsRequired`	Mandatory attribute `key` is missing.
`keyIsNotPermited`	Unexpected attribute `key` is provided.
`valueHasExtraLength`	Value exceeds maximum length limit.
`arrayHasExtraAttributes`	Array attribute contains extra elements beyond the expected count.
`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.
`valueHasWrongFormat`	Value format differs from the expected format.