Payout API description
Payout interaction diagram
Payout interaction diagram description:
1) User initiates a payout operation in Partner’s service using a Payment method
2) Partner’s service sends a payout request towards a specific System URL
3) The System accepts the request after checking required request parameters and request signature validity.
4) The System returns a response either with a message stating that a request is either correct and was accepted, or with an error message if the request did not meet the System requirements for processing.
5) The System performs further request processing and sends the data to Payment method.
6) Payment method’s service performs further payout request processing.
7) Payment method informs the System about the payout result.
8) The System notifies Partner’s service about payout operation result
Getting started with the system
Terms and conditions
System (hereinafter also referred to as the "Payout System") is a payment gateway that provides an API for conducting mass payout operations.
Partner (hereinafter also referred to as the "Merchant") is an Organization using the System API.
Transfer sender - a person making a transfer to the account (bank card account, mobile phone account, e-wallet, etc.) of the recipient through the payment gateway.
Transfer recipient – the person to whose account (bank card account, mobile phone account, e-wallet account, etc.) the transfer is to be received.
SecretKey - Partner's secret key, a fixed character string.
Transaction final status - fixed final state of the transaction (success/failure).
General Description
The protocol (API) is designed to organize information exchange between the Partner and the System. The API allows the Partner to perform a number of basic operations, such as: making mass payments to bank and mobile phone accounts, request and receive information about the current state of transactions, request a registry of operations, etc.
Protocol details
Information interaction is carried out via HTTP protocol with SSL/TLS add-on.
Authentication and authorization is carried out with Partner’s provided IP-address. Each request to the System uses external system identifier assigned to the Partner (Service_ID) and the secret key (secretKey). Each request to and from the System is signed with a control signature using the request parameters and the secret key. The external system identifier and the secret key are generated upon request to the technical support and sent to the Partner.
List of requests
| Request direction | Request method | Description | URL |
|---|---|---|---|
| Main requests: | |||
| Partner –> Payout system | Payout method. Payout request, POST | Used by Partner for payout transaction initialization. | /partner/{Service_ID}/payout |
| Payout System –> Partner | Payout notification (callback), POST | Used by the System to notify the Partner about the transaction and its status. | URL provided by the Partner |
| Additional requests: | |||
| Partner –> Payout system | Check method. Transaction status request, POST | Used by Partner to receive payout transaction status. | /partner/{Service_ID}/check |
| Partner –> Payout system | Balance method. Partner balance request, POST | Used by Partner to receive current account balance information. | /partner/{Service_ID}/balance |
| Partner –> Payout system | balance_statement method, POST | Used by Partner to receive account balance operation detail. | /partner/{Service_ID}/balance_statement |
| Partner –> Payout system | Payout_reestr method Payout transaction registry request, GET | Used by Partner to receive payout transaction registry | /payout_reestr |
| Partner –> Payout system–> Partner | Notify method. Callback resend request, POST | Used by Partner to resend callback with current transaction status. | /partner/{Service_ID}/notify |
At the beginning of the work with system Merchant gets credentials to access to Web Portal on the URL:
Test environment: https://int.gwp.digital
Production environment: https://gwp.digital
Payout method (Payout operation request)
This method is designed to carry out a payout operation to specific transfer requisites.
URL: https://[int.]gwp.digital/partner/{Service_ID}/payout
Http method: POST
Content-Type: application/x-www-form-urlencoded
Response format: XML
Request parameters:
| Parameter name | Type | Description | Required |
|---|---|---|---|
| id | string | Transaction ID within Partner’s system | Yes |
| dt | date and time | Date and time of request. Format: YYYY-MM-DD HH:MM:SS | Yes |
| amount | decimal | Payout amount (has to be an integer for payouts in IDR), with dot as a decimal point delimiter | Yes |
| currency | string | Transaction currency | Yes |
| phone | string | User’s phone number. Format: 622851280 (phone value is not validated, it is possible to pass a static value) | Yes |
| client | string | Crediting account (bank account) | Yes |
| destination | string | Payout destination identifier (see List of available destinations section) | Yes |
| receiver_fio | string | User’s first name and last name | Yes |
| payout_currency | string | Actual payout currency. Used when payout currency is different from {currency} parameter. | No |
| receiver_bic | string | Receiver bank code. (see. List of available values - depends on country). | No |
| hash | string | Request control signature: MD5-hash (id+ dt + amount + phone + client + destination + secret_key), where «+» - concatenation sign, secret_key – Partner’s account secret key. | Yes |
Additional parameters. Required for some destinations, for more details see the list of payment destinations.
| Parameter name | Type | Description |
|---|---|---|
| payer_fio | string | Payment sender’s name |
| payer_last_name | string | Payment sender’s last name |
| payer_first_name | string | Payment sender’s first name |
| payer_middle_name | string |