# API Documentation (/docs) All endpoints share one base URL, issued to you per merchant, and exchange JSON over HTTPS with an `apikey` header. Amounts, currencies and payment methods use the same vocabulary throughout. If you have not called the API before, start with the Postman Guide and send a request against the sandbox. The general API workflow consists of the following: - [Postman Guide](/docs/getting-started): Set up the request headers and send your first call from Postman. - [Payment API](/docs/payment-api): Create a payment and send the customer to the payment page. - [Payment Statuses](/docs/payment-statuses-flow): What each payment status means, and the postbacks you receive. - [Payout API](/docs/payout-api): Send a payout to a beneficiary account. - [Status API](/docs/status-api): Look up the current status of a payment or a payout. - [Payout Sandbox](/docs/sandbox): Test credentials for trying out payouts. - [Balance API](/docs/balance-api): Check the available balance for a currency and method. # Balance API (/docs/balance-api) ### Balance API information [#balance-api-information] | Field | Data Description | | ------------------- | ---------------------------------------------------------------------------------------------- | | Request method | GET | | Balance Request URL | https\://\/api/v1/external/balance/status?currency=\{currency}\&method=\{method} | | Data format: | All data is sent and received in the JSON format. | | Content-Type: | application/json | | Headers: | ‘apikey’: \ | #### Balance API Request Fields [#balance-api-request-fields] Merchant must provide *currency* and *method*. | | | | --------------------- | --------------------------------------------- | | currency | Currency. Example: INR, BDT. | | method | Payment method. Example: BANK\_TRANSFER, UPI. | #### Balance API Response Fields [#balance-api-response-fields] | | | | -------------------- | ---------------------------------------------------------------------------------------------------------- | | balance | Total aggregated balance in currency units, not minor units, as a number: 100032 is 100,032, not 1,000.32. | #### Balance API Response Sample [#balance-api-response-sample] ```json { "balance": 100032 } ``` # CSV Report API (/docs/csv-report-api) Request a CSV report of your pay-ins and payouts, get notified when it is ready, and download it. ### CSV Report API information [#csv-report-api-information] | Field | Data Description | | ------------------ | ---------------------------------------------------------------------------------- | | Base URL | https\://\ — the same host you use for your other API calls | | Request Report URL | POST https\://\/api/v1/external/report/csv | | Report Status URL | GET https\://\/api/v1/external/report/\{id} | | Data format: | All data is sent and received in the JSON format. | | Content-Type: | application/json | | Headers: | ‘apikey’: \ | | Request dates | `from` and `to` are UTC, format `yyyy-MM-ddTHH:mm:ss` (e.g. `2025-08-01T00:00:00`) | ### How it works [#how-it-works] Reports are generated asynchronously. You do not wait for the file in the API response — you receive a report ID immediately and a notification to your webhook URL when the file is ready. | Step | Who | What happens | | ---- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | You | Send `POST /api/v1/external/report/csv` with the report type, period and your webhook URL. | | 2 | API | Validates the request and returns the report `id` with status `PENDING`. | | 3 | API | Generates the CSV file. Requests are processed one after another, so a report can take from a few seconds to several minutes depending on the period and the queue. | | 4 | API | Sends a `POST` notification to your webhook URL with status `READY` and the `reportUrl`, or `FAILED` if the report could not be generated. | | 5 | You | Download the CSV file from `reportUrl` (plain HTTPS GET, no API key needed). The link is valid for 72 hours. | | \* | You | At any time you can check the status and get the link with `GET /api/v1/external/report/{id}` — e.g. if your webhook was unavailable. | Report statuses: `PENDING` — report is queued or being generated; `READY` — file is available at `reportUrl`; `FAILED` — report could not be generated, please request a new one. ### Request a CSV Report [#request-a-csv-report] #### Request Report Fields [#request-report-fields] All fields are required. | Field | Type | Description | | ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | type | String | `PAYIN` — pay-ins (deposits) only. `PAYOUT` — payouts only. `TRANSACTION` — pay-ins and payouts in one file. | | from | String | Period start (inclusive), UTC, `yyyy-MM-ddTHH:mm:ss`. | | to | String | Period end (inclusive), UTC, `yyyy-MM-ddTHH:mm:ss`. Must not be before `from`. | | webhookURL | String | Absolute URL (http/https) where the readiness notification is sent. | Transactions are included by their creation date. #### Request Report Sample [#request-report-sample] ```bash curl -X POST "https://{url-provided}/api/v1/external/report/csv" \ -H "apikey: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "PAYIN", "from": "2025-08-01T00:00:00", "to": "2025-09-29T23:59:59", "webhookURL": "https://example.com/webhooks/csv-report" }' ``` #### Request Report Response Sample [#request-report-response-sample] ```json { "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b7a1c0e93", "type": "PAYIN", "from": "2025-08-01T00:00:00", "to": "2025-09-29T23:59:59", "status": "PENDING", "reportUrl": null, "createdDate": "2025-09-30T08:15:02.417+00:00" } ``` Store the `id` — it identifies the report in the webhook notification and in the status request. ### Get Report Status [#get-report-status] `GET https://{url-provided}/api/v1/external/report/{id}` The `apikey` header is required. You can only access reports created with your own API key. #### Report Status Request Sample [#report-status-request-sample] ```bash curl "https://{url-provided}/api/v1/external/report/3f6c2a9e-8b1d-4c7a-9e2f-5d4b7a1c0e93" \ -H "apikey: YOUR_API_KEY" ``` #### Report Status Response Sample [#report-status-response-sample] ```json { "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b7a1c0e93", "type": "PAYIN", "from": "2025-08-01T00:00:00", "to": "2025-09-29T23:59:59", "status": "READY", "reportUrl": "https://{storage-host}/csv-reports/...", "createdDate": "2025-09-30T08:15:02.417+00:00" } ``` #### Report Status Response Fields [#report-status-response-fields] | Field | Description | | ------------------------ | ---------------------------------------------- | | id | Report ID | | type | `PAYIN`, `PAYOUT` or `TRANSACTION` | | from | Period start as requested (UTC) | | to | Period end as requested (UTC) | | status | `PENDING`, `READY` or `FAILED` | | reportUrl | Download link, set only when status is `READY` | | createdDate | When the report was requested | ### Webhook Notification [#webhook-notification] When the report is finished, a `POST` request with a JSON body is sent to the `webhookURL` from your request. #### Webhook Headers [#webhook-headers] | Header | Value | | ------------ | ----------------------------------------------------------------------- | | Content-Type | application/json | | apikey | Your merchant API key — use it to verify the notification comes from us | #### Webhook Fields [#webhook-fields] | Field | Description | | ---------------------- | ------------------------------------------------ | | id | Report ID returned when the report was requested | | type | `PAYIN`, `PAYOUT` or `TRANSACTION` | | from | Period start (UTC) | | to | Period end (UTC) | | status | `READY` or `FAILED` | | reportUrl | Download link (only for `READY`) | | message | Error description (only for `FAILED`) | #### Webhook Sample — Report Ready [#webhook-sample--report-ready] ```json { "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b7a1c0e93", "type": "PAYIN", "from": "2025-08-01T00:00:00", "to": "2025-09-29T23:59:59", "status": "READY", "reportUrl": "https://{storage-host}/csv-reports/...", "message": null } ``` #### Webhook Sample — Report Failed [#webhook-sample--report-failed] ```json { "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b7a1c0e93", "type": "PAYIN", "from": "2025-08-01T00:00:00", "to": "2025-09-29T23:59:59", "status": "FAILED", "reportUrl": null, "message": "Report generation failed" } ``` Your webhook endpoint should respond with any 2xx status. The notification is sent once and is not retried — if your endpoint was unavailable, use `GET /api/v1/external/report/{id}` to get the status and the download link. ### Report File [#report-file] | Property | Value | | ------------ | ---------------------------------------------------------------------------------------------------- | | Format | CSV, UTF-8, comma separated, first row is the header, values containing commas are quoted | | Rows | One row per transaction whose creation date is within the requested period | | Sorting | By creation date, oldest first. In `TRANSACTION` reports pay-ins and payouts are mixed in date order | | Dates | UTC, format `yyyy-MM-dd HH:mm:ss` | | Amounts | Decimal with 2 digits and a dot separator, e.g. `1250.00` | | Empty period | The file contains only the header row | #### Report File Columns [#report-file-columns] | # | Column | Description | | -- | ------------------ | --------------------------------------------------------------------- | | 1 | Type | `PAYIN` or `PAYOUT` | | 2 | ID | Transaction ID | | 3 | Order ID | Your order ID sent when the transaction was created | | 4 | Status | Transaction status, e.g. `SUCCESS`, `PENDING`, `REJECTED`, `REVERSED` | | 5 | Method | Payment method, e.g. `BANK_TRANSFER` | | 6 | Currency | Transaction currency, e.g. `INR` | | 7 | Amount | Transaction amount | | 8 | Fee | Transaction fee | | 9 | Created Date (UTC) | When the transaction was created | | 10 | Updated Date (UTC) | When the transaction was last updated | #### Report File Sample [#report-file-sample] ```csv Type,ID,Order ID,Status,Method,Currency,Amount,Fee,Created Date (UTC),Updated Date (UTC) PAYIN,DP-1001,order-1001,SUCCESS,BANK_TRANSFER,INR,1250.00,31.25,2025-08-01 09:12:44,2025-08-01 09:14:02 PAYOUT,PO-2001,order-2001,SUCCESS,BANK_TRANSFER,INR,500.00,5.00,2025-08-01 10:03:10,2025-08-01 10:05:51 PAYIN,DP-1002,order-1002,REJECTED,BANK_TRANSFER,INR,300.00,0.00,2025-08-02 14:40:00,2025-08-02 14:41:12 PAYOUT,PO-2002,order-2002,REVERSED,BANK_TRANSFER,INR,500.00,-5.00,2025-08-03 08:20:31,2025-08-04 11:00:09 ``` #### Download Link [#download-link] * `reportUrl` is a private, pre-signed link to your file only. Open it with a plain HTTPS GET — no API key or other headers are needed. * The link is valid for 72 hours. Anyone who has the link can download the file during that time, so do not share it. * Files are kept for 3 days. After the link expires, request a new report for the same period. ### Errors [#errors] Errors are returned as JSON: ```json { "timestamp": "2025-09-30T08:15:02.417+00:00", "message": "from date must be before to date", "details": "MERCHANT_EXCEPTION" } ``` | HTTP status | message | Reason | | ----------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | 400 | `{type is required;}` | Missing field. Several missing or invalid fields are listed together, e.g. `{from is required;to is required;}` | | 400 | `{webhookURL must be a valid URL;}` | `webhookURL` is not an absolute http/https URL | | 400 | `from date must be before to date` | `from` is later than `to` | | 400 | An invalid parameter message | Unknown `type` value or wrong date format | | 400 | `Report not found` | Unknown report ID, or the report belongs to another merchant | | 400 | `Could not create report, please try again later` | Temporary issue — retry the request later | | 400 | `Error: The IP not whitelisted` | The request comes from an IP address that is not whitelisted for your account | | 403 | `No api key provided` / `Api key is incorrect` | Missing or wrong `apikey` header | # Error Messages (/docs/error-codes) The API reports failures as human-readable messages. There are no numeric or string error codes to branch on, so match on the message text. Every message the `/api/v6/external/payin` and `/api/v6/external/payout` endpoints can return is listed below, reproduced exactly as it is delivered. Some arrive wrapped in square brackets — `[ERROR: ...]` — some start with `Error:`, and some arrive bare. Every form is kept as it is sent, so a message copied out of your logs matches what is on this page. The messages are grouped by endpoint: payin only, payout only, and both. ## Reading the list [#reading-the-list] The messages carry the notation the API uses: * `{fieldName}` is the name of the field the message is about, written as the API writes it. * `X`, `N`, `{X}` and `` stand for a name or value the API fills in when it sends the message. ## Payin [#payin] | Message | | ------------------------------------------------------------------------------------------------------- | | `[ERROR: {amount} may not be null.]` | | `IP Address is empty or null` | | `Country value is empty` | | `Currency value is empty` | | `Callback url is empty` | | `Return url is empty` | | `Method could not be null` | | `[ERROR: There are no available Mids found for the Bank code {X} Please contact your Account Manager.]` | | `MID Setup Incomplete. Contact Customer Support` | | `Invalid Channel & MID Settings. Contact Support` | | `Current bank disabled for this mid` | ## Payout [#payout] | Message | | ------------------------------------------------------------------------------------- | | `[ERROR: Hash value is incorrect]` | | `[ERROR: {country} may not be be null or empty.]` | | `[ERROR: {amount} may not be null or empty.]` | | `[Error: {midId} parameter must be a valid midId]` | | `[ERROR: {ipAddress} may not be null or empty.]` | | `[ERROR: {currency} may not be null or empty.]` | | `[ERROR: {account} may not be be null or empty.]` | | `[ERROR: MidId or Payment method must be specified.]` | | `[ERROR: Suitable Mid not found]` | | `Payout was already created under the same transaction ID: X` | | `Payout has already been created under the same external transaction ID` | | `Error: Customer email is empty` | | `Error: Customer is blacklisted. Please contact our customer support.` | | `Current bank disabled for payouts` | | `Insufficient Payout Balance` | | `Min amount is X` | | `Max amount is X` | | `[ERROR: {data.name} must be 1-150 characters and may not be null or empty]` | | `[ERROR: {data.lastname} must be 1-150 characters and may not be null or empty]` | | `[ERROR: {data.accountnumber} must be 9-19 characters and may not be null or empty.]` | | `[ERROR: {data.accountname} must not be null or empty.]` | | `[ERROR: {data.bankname} must not be null or empty.]` | | `[ERROR: {data.bankaddress} must not be null or empty.]` | | `[ERROR: {data.ifsc} must be 11 characters and may not be null or empty.]` | | `[ERROR: {data.bankcode} must be 4 length and may not be null or empty.]` | | `[ERROR: {data.mobile} must be 8-15 length and may not be null or empty.]` | | `[ERROR: invalid {mobile} format.]` | | `[ERROR: invalid {ifsc} format.]` | | `[ERROR: {data.bsb} must be 6 characters and may not be null or empty.]` | ## Payin and Payout [#payin-and-payout] | Message | | ------------------------------------------------------------------------------------------------------------- | | `Error: The IP not whitelisted` | | `[Error: {X} parameter must be valid]. Please request a X from your account manager.` | | `Unexpected error occurred: . Please contact support team.` | | `Order ID is empty` | | `[ERROR: {orderId} must be 1-50 characters.]` | | `[ERROR: invalid {email} format.]` | | `Error: Fraud User Detected. Contact Support.` | | `[ERROR: Attempt blocked due to too many failed attempts from this user or IP. Please contact Administrator]` | | `[ERROR: {amount} must be a positive value.]` | | `[ERROR: No MID with given ID found, ID: N]` | | `[ERROR: Cascading for payment method X is missing. Please contact your Account Manager.]` | | `[ERROR: Cascading for country X is missing]` | | `[ERROR: No MID found for target country X]` | | `[ERROR: All mids are currently down for country X. Please contact our CS Team immediately]` | | `[ERROR: There are no available Mids found for the requested amount. Please contact your Account Manager.]` | | `Inconsistency between Mid Currency and requested Currency. Please contact Support` | | `Mid not found!` | | `Payment not supported` | # Postman Guide (/docs/getting-started) | Field | Data Description | | ------------------------- | ----------------------------------------------------- | | Request method | POST | | Additional Request header | ‘apikey’ \ | | Payment Request URL | https\://\/api/v6/external/payin | | Payout Request URL | https\://\/api/v6/external/payout | | Data format | All data is sent and received in the JSON format. | | Content-Type | application/json | | iFrame | The payment url for customers does not work in iframe | | Postman Headers | | --------------------------------------------------------------------------------------------------------------------- | | Postman Headers tab with the apikey and Content-Type request headers checked | # Payment API (/docs/payment-api) ### Default Payment Request Table [#default-payment-request-table] | Field Name | Data Description | Type | Min | Max | Example | Required | | ----------- | ----------------------------------------------------------------------------- | ---- | --- | --- | ------------------------------------------------------------ | -------- | | amount | Float data type. Accepted as a number or a numeric string, e.g. 500 or "500". | NU | 1 | – | 50000.00 | yes | | callbackUrl | Url where payment callback will be sent | URL | – | – | [https://example.com/callback](https://example.com/callback) | yes | | country | ISO 3166-1-alpha-2 | CH | 2 | 2 | PK | yes | | currency | Alphabetic currency code, e.g. INR | CH | 3 | 3 | PKR | yes | | email | Valid email format | AN | 6 | 120 | [name@email.com](mailto:name@email.com) | yes | | ip | Customer’s IP | IP | – | – | 192.0.2.1 | yes | | method | Methods supported, see the samples below. | CH | – | – | WALLETS | yes | | orderId | Merchant Order ID | AN | 1 | 50 | abc123456 | yes | | returnUrl | Url to redirect after payment | URL | – | – | [https://example.com/return](https://example.com/return) | yes | | traffic | Traffic type.
Options: FTD, TRUSTED | CH | 3 | 7 | TRUSTED | yes | ### Generic Payment Request Body & Response Samples [#generic-payment-request-body--response-samples] ```json { "amount": "5000", "country": "AR", "currency": "ARS", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "dni": "65476574" } } ``` ```json { "amount": "5000", "country": "AR", "currency": "ARS", "email": "email@test.com", "ip": "192.0.2.1", "method": "MERCADO_PAGO", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "dni": "65476574" } } ``` ```json { "amount": "20", "country": "AU", "currency": "AUD", "email": "email@test.com", "ip": "192.0.2.1", "method": "PAY_ID", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "accountNumber": "35465345543453", "lastName": "Doe", "mobileNumber": "0412123123", "name": "John" } } ``` ```json { "amount": "100", "country": "AZ", "currency": "AZN", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "bankCode": "UNIB", "lastName": "Doe", "name": "John" } } ``` ```json { "amount": "300", "country": "BD", "currency": "BDT", "email": "email@test.com", "ip": "192.0.2.1", "method": "BKASH", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "mobileNumber": "01888123456", "name": "John" } } ``` ```json { "amount": "300", "country": "BD", "currency": "BDT", "email": "email@test.com", "ip": "192.0.2.1", "method": "NAGAD", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "mobileNumber": "01888123456", "name": "John" } } ``` ```json { "amount": "300", "country": "BD", "currency": "BDT", "email": "email@test.com", "ip": "192.0.2.1", "method": "ROCKET", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "mobileNumber": "01888123456", "name": "John" } } ``` ```json { "amount": "10", "country": "BR", "currency": "BRL", "email": "email@test.com", "ip": "192.0.2.1", "method": "PIX", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "pixAccount": "12345678900" } } ``` ```json { "amount": "10000", "country": "ID", "currency": "IDR", "email": "email@test.com", "ip": "192.0.2.1", "method": "DANA", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "mobileNumber": "6281234567890", "name": "John" } } ``` ```json { "amount": "10000", "country": "ID", "currency": "IDR", "email": "email@test.com", "ip": "192.0.2.1", "method": "QR_CODE", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "mobileNumber": "6281234567890", "name": "John" } } ``` ```json { "amount": "10000", "country": "ID", "currency": "IDR", "email": "email@test.com", "ip": "192.0.2.1", "method": "VIRTUAL_ACCOUNT", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "mobileNumber": "6281234567890", "name": "John" } } ``` ```json { "amount": "500", "country": "IN", "currency": "INR", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "mobileNumber": "919876543210", "name": "John" } } ``` ```json { "amount": "500", "country": "IN", "currency": "INR", "email": "email@test.com", "ip": "192.0.2.1", "method": "PAY_TM", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "mobileNumber": "919876543210", "name": "John" } } ``` ```json { "amount": "500", "country": "IN", "currency": "INR", "email": "email@test.com", "ip": "192.0.2.1", "method": "UPI", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "mobileNumber": "919876543210", "name": "John", "pin": "user_1" } } ``` ```json { "amount": "1000", "country": "JP", "currency": "JPY", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "name": "John" } } ``` ```json { "amount": "1000", "country": "JP", "currency": "JPY", "email": "email@test.com", "ip": "192.0.2.1", "method": "KONBINI", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "name": "Taro", "lastName": "Yamada" } } ``` ```json { "amount": "1000", "country": "JP", "currency": "JPY", "email": "email@test.com", "ip": "192.0.2.1", "method": "PAYEASY", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "name": "Taro", "lastName": "Yamada" } } ``` ```json { "amount": "100", "country": "KE", "currency": "KES", "email": "email@test.com", "ip": "192.0.2.1", "method": "MOBILE_MONEY", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "name": "John" } } ``` ```json { "amount": "10000", "country": "KR", "currency": "KRW", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "accountNumber": "79823570294", "bankCode": "OSB", "lastName": "Doe", "mobileNumber": "01095786574", "name": "John" } } ``` ```json { "amount": "10000", "country": "KR", "currency": "KRW", "email": "email@test.com", "ip": "192.0.2.1", "method": "VIRTUAL_ACCOUNT", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "accountNumber": "79823570294", "bankCode": "OSB", "lastName": "Doe", "mobileNumber": "01095786574", "name": "John" } } ``` ```json { "amount": "10", "country": "MY", "currency": "MYR", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "mobileNumber": "601123456789", "name": "John" } } ``` ```json { "amount": "10", "country": "MY", "currency": "MYR", "email": "email@test.com", "ip": "192.0.2.1", "method": "QR_CODE", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "mobileNumber": "601123456789", "name": "John" } } ``` ```json { "amount": "100", "country": "NG", "currency": "NGN", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "name": "John" } } ``` ```json { "amount": "100", "country": "PH", "currency": "PHP", "email": "email@test.com", "ip": "192.0.2.1", "method": "GOTYME", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "mobileNumber": "09151037552" } } ``` ```json { "amount": "100", "country": "PH", "currency": "PHP", "email": "email@test.com", "ip": "192.0.2.1", "method": "GRABPAY", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "mobileNumber": "09151037552" } } ``` ```json { "amount": "100", "country": "PH", "currency": "PHP", "email": "email@test.com", "ip": "192.0.2.1", "method": "G_CASH", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "mobileNumber": "09151037552" } } ``` ```json { "amount": "100", "country": "PH", "currency": "PHP", "email": "email@test.com", "ip": "192.0.2.1", "method": "MAYA", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "mobileNumber": "09151037552" } } ``` ```json { "amount": "100", "country": "PH", "currency": "PHP", "email": "email@test.com", "ip": "192.0.2.1", "method": "QR_CODE", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "mobileNumber": "09151037552" } } ``` ```json { "amount": "1000", "country": "PK", "currency": "PKR", "email": "email@test.com", "ip": "192.0.2.1", "method": "EASY_PAISA", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "mobileNumber": "03123123123", "name": "John" } } ``` ```json { "amount": "1000", "country": "PK", "currency": "PKR", "email": "email@test.com", "ip": "192.0.2.1", "method": "JAZZ_CASH", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "mobileNumber": "03123123123", "name": "John" } } ``` ```json { "amount": "1000", "country": "PK", "currency": "PKR", "email": "email@test.com", "ip": "192.0.2.1", "method": "RAAST", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "mobileNumber": "03123123123" } } ``` ```json { "amount": "100", "country": "SG", "currency": "SGD", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "bankCode": "DBS", "lastName": "Doe", "name": "John" } } ``` ```json { "amount": "100", "country": "SG", "currency": "SGD", "email": "email@test.com", "ip": "192.0.2.1", "method": "PAYNOW", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "name": "John" } } ``` ```json { "amount": "100", "country": "TH", "currency": "THB", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "name": "John" } } ``` ```json { "amount": "100", "country": "TH", "currency": "THB", "email": "email@test.com", "ip": "192.0.2.1", "method": "PROMPT_PAY", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "lastName": "Doe", "accountNumber": "35465345543453", "name": "John" } } ``` ```json { "amount": "100", "country": "TR", "currency": "TRY", "email": "email@test.com", "ip": "192.0.2.1", "method": "VIP_HAVALE", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return", "map": { "dob": "01-01-1970", "lastName": "Doe", "mobileNumber": "905476476455", "name": "John", "tin": "12345678911" } } ``` ```json { "amount": "50000", "country": "VN", "currency": "VND", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return" } ``` ```json { "amount": "50000", "country": "VN", "currency": "VND", "email": "email@test.com", "ip": "192.0.2.1", "method": "MOMOPAY", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return" } ``` ```json { "amount": "50000", "country": "VN", "currency": "VND", "email": "email@test.com", "ip": "192.0.2.1", "method": "PHONE_CARD", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return" } ``` ```json { "amount": "50000", "country": "VN", "currency": "VND", "email": "email@test.com", "ip": "192.0.2.1", "method": "QR_CODE", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return" } ``` ```json { "amount": "50000", "country": "VN", "currency": "VND", "email": "email@test.com", "ip": "192.0.2.1", "method": "VIETTELPAY", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return" } ``` ```json { "amount": "50000", "country": "VN", "currency": "VND", "email": "email@test.com", "ip": "192.0.2.1", "method": "VIRTUAL_ACCOUNT", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return" } ``` ```json { "amount": "50000", "country": "VN", "currency": "VND", "email": "email@test.com", "ip": "192.0.2.1", "method": "ZALOPAY", "orderId": "abc123456", "traffic": "TRUSTED", "callbackUrl": "https://example.com/callback", "returnUrl": "https://example.com/return" } ``` **Generic Payment Response Sample** ```json { "paymentUrl": "https://example.com/payment", "status": "PENDING", "message": "Transaction is being processed", "id": "912z-1zs4-acvb-1bre3", "orderId": "abc123456" } ``` ```json { "status": "REJECTED", "message": "Transaction rejected by processor", "id": "912z-1zs4-acvb-1bre3", "orderId": "abc123456" } ``` ```json { "timestamp": "2023-12-01T15:22:01.069+00:00", "message": "{Order ID is empty;IP Address is empty;}", "details": "" } ``` ##### Additional Payment Data Fields: [#additional-payment-data-fields] The payment request “map” field contains possible additional parameters, which are provider dependent. If the parameters are missing, the required values will be asked (via web form) from the customer. The exception is **accountNumber**: for the methods that require it, a request without it is rejected. | Field Name | Data Description | Type | Min | Max | Example | Required | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | --- | --- | --------------------------------------------------------------------- | -------- | | accountNumber | Customer’s account identifier: a bank account number, an email or similar, depending on country and method (AUD / PAY\_ID takes either). Required for AUD / PAY\_ID, KRW / BANK\_TRANSFER, KRW / VIRTUAL\_ACCOUNT and THB / QR\_CODE; for these methods a request without it is rejected. | CH | 1 | – | 35465345543453 or [customer@example.com](mailto:customer@example.com) | yes | | address | Customer address | CH | 1 | – | Testshington Street | no | | bankCode | Customer bank code | CH | 1 | – | DBS | yes | | city | Customer city | CH | 1 | – | City | no | | dni | Customer’s national identity number (DNI) | CH | 1 | – | 65476574 | yes | | dob | Customer’s Date of Birth | AN | 10 | 10 | 1990-12-21 | no | | lastName | Customer last name | CH | 1 | – | Doe | yes | | midId | For technical flexibility purposes | NU | 1 | – | 123 | no | | mobileNumber | Customer mobile number | CH | 1 | – | 5467756764 | yes | | name | Customer first name | CH | 1 | – | John | yes | | pin | Merchant’s own customer identifier, e.g. a user ID | CH | 1 | – | user\_1 | no | | pixAccount | Customer’s PIX key | CH | 1 | – | 12345678900 | yes | | postalCode | Customer postal code | CH | 1 | – | 435645 | no | | state | Customer state | CH | 1 | – | ST | no | | tin | Tax Identification Number | NU | 9 | 11 | 12345678910 | no | ### Payment API Response Fields [#payment-api-response-fields] | **Description** | **Format** | **Explanation** | | --------------- | ---------- | --------------------------------------------- | | id | String | System Transaction ID | | message | String | Payment response message | | paymentUrl | String | The payment URL you need to serve to customer | | status | String | Transaction status | | orderId | String | Merchant Order ID | # Payment Statuses (/docs/payment-statuses-flow) | TX type | Event | Status | | -------- | --------- | ----------------------------------- | | Received | Immediate | **PENDING** | | Approved | Temporary | **SUCCESS** | | Failed | Temporary | **FAIL**  | | Failed | Final | **REJECTED, REVERSED** | ## Status Flow [#status-flow] | Immediate Response | Callback | Potential Callback | | ------------------ | -------- | --------------------- | | REJECTED | | | | PENDING | SUCCESS | REVERSED | ### Payment Postbacks [#payment-postbacks] Each postback is a general **HTTP POST** request. The final amount in the postback may differ from the initial payment amount; therefore, the merchant must verify and update the amount value when receiving the postback. Multiple payment requests with the same **orderId** are allowed. Each payment gets its own unique `id`. #### Payment Postback Table [#payment-postback-table] | **Title** | **Format** | **Explanation** | | --------- | ---------- | ---------------------------------- | | id | String | System Transaction ID | | orderId | String | Merchant Order ID | | status | String | Transaction status | | amount | double | Transaction amount | | currency | String | Alphabetic currency code, e.g. INR | | hash | String | Data signature for encryption | #### Postback Payload [#postback-payload] header name ‘apikey’, header value \ ```json { "id": "912z-1zs4-acvb-1bre3", "orderId": "merchtx12345", "status": "SUCCESS", "amount": 100.00, "currency": "PKR", "hash": "" } ``` ### Callback- & Return URLs [#callback---return-urls] | **Value** | **Description** | **Format** | **Provided by** | | ----------- | --------------------------------------- | ---------- | --------------- | | callbackUrl | Callback/postbacks are sent here | string | Merchant | | returnUrl | Customer is returned here after payment | string | Merchant | | paymentUrl | The payment page to serve the customer | string | PSP | ### Data Signature of Payload [#data-signature-of-payload] | **Encryption** **Variables** | **Values and explanations** | | ---------------------------- | ---------------------------------------------------------------------- | | apikey | \ | | Secret key | \ | | Encryption format | Concatenated and signed by using SHA-256 algorithm | | Parameter order | The order must be in exact order as per below sample | | Parameter example | secretKey=xxx\&amount=xx.xx\¤cy=xx\&id=xx\&orderId=xx\&status=xx | | Amount format | 2 digits after comma Ex: 100.999 -> 100.99, 100 -> 100.00 | | Result string | Will be signed using SHA-256 | # Payout API (/docs/payout-api) ### Payout Request Table [#payout-request-table] | Field Name | Data Description | Type | Min | Max | Example | Required | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | --- | --- | ------------------------------------------------------------ | --------------------- | | account | Beneficiary Account | CH | 1 | – | abc123 | yes | | amount | Float data type. Decimals are ignored: 100.99 is paid out as 100. Accepted as a number or a numeric string, e.g. 500 or "500". | NU | 1 | – | 50000.00 | yes | | currency | Alphabetic currency code, e.g. INR | CH | 3 | 3 | PKR | yes | | callbackUrl | Url where payment callback will be sent | URL | – | – | [https://example.com/callback](https://example.com/callback) | yes | | country | ISO 3166-1-alpha-2 | CH | 2 | 2 | PK | yes | | email | Customer’s email | AN | 6 | 120 | [name@email.com](mailto:name@email.com) | yes | | data | For additional parameters for payout | OBJ | – | – | data\{
"name":"John Doe"
} | yes | | hash | Payout payload signature.
Contact your account manager
to enable this parameter.
When enabled, a payout
without it is rejected. [More](/docs/payout-api#payout-request-hash-generation) | AN | 64 | 64 | F74723256…..E9EF2 | yes
(if enabled) | | method | Methods supported. | CH | – | – | BANK\_TRANSFER | yes | | orderId | Merchant Order ID | AN | 1 | 50 | abc123456 | yes | | ip | Customer’s IP | IP | – | – | 192.0.2.1 | yes | A payout request with an **orderId** that has already been used is rejected. ### Generic Payout Request Body & Response Sample [#generic-payout-request-body--response-sample] **Request Body for Payouts** ```json { "account": "5466547856436481364252", "amount": "10000", "country": "AR", "currency": "ARS", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": {} } ``` ```json { "account": "5466547856436481364252", "amount": "10000", "country": "AR", "currency": "ARS", "email": "email@test.com", "ip": "192.0.2.1", "method": "MERCADO_PAGO", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "cuit": "76576574758" } } ``` ```json { "account": "847536845", "amount": "20", "country": "AU", "currency": "AUD", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "bsb": "012002", "city": "Adelaide", "dob": "1970-12-30", "lastName": "Cash", "mobileNumber": "0456785678", "name": "Johny", "postalCode": "5000", "state": "SA", "street": "122 Grenfell St" } } ``` ```json { "account": "0412345678", "amount": "100", "country": "AU", "currency": "AUD", "email": "email@test.com", "ip": "192.0.2.1", "method": "PAY_ID", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash" } } ``` ```json { "account": "984793423", "amount": "100", "country": "AZ", "currency": "AZN", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash" } } ``` ```json { "account": "892375982", "amount": "500", "country": "BD", "currency": "BDT", "email": "email@test.com", "ip": "192.0.2.1", "method": "BKASH", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johnny Cash", "mobileNumber": "01888123456" } } ``` ```json { "account": "01345634562", "amount": "500", "country": "BD", "currency": "BDT", "email": "email@test.com", "ip": "192.0.2.1", "method": "NAGAD", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johnny Cash", "mobileNumber": "01888123456" } } ``` ```json { "account": "8173586239", "amount": "500", "country": "BD", "currency": "BDT", "email": "email@test.com", "ip": "192.0.2.1", "method": "ROCKET", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johnny Cash", "mobileNumber": "01888123456" } } ``` ```json { "account": "63640348252", "amount": "100", "country": "BR", "currency": "BRL", "email": "email@test.com", "ip": "192.0.2.1", "method": "PIX", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "GH", "currency": "GHS", "email": "email@test.com", "ip": "192.0.2.1", "method": "MOBILE_MONEY", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash" } } ``` ```json { "account": "8173586239", "amount": "50000", "country": "ID", "currency": "IDR", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash", "bankCode": "BCA" } } ``` ```json { "account": "922010014620362", "amount": "1000", "country": "IN", "currency": "INR", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash", "ifsc": "BSBN0001234", "pin": "user_1" } } ``` ```json { "account": "8173586239", "amount": "1000", "country": "JP", "currency": "JPY", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash", "bankBranch": "4153", "bankCode": "AOMB" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "KE", "currency": "KES", "email": "email@test.com", "ip": "192.0.2.1", "method": "MOBILE_MONEY", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash" } } ``` ```json { "account": "8173586239", "amount": "10000", "country": "KR", "currency": "KRW", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash", "bankCode": "BOKOR" } } ``` ```json { "account": "3021234567890", "amount": "10000", "country": "KR", "currency": "KRW", "email": "email@test.com", "ip": "192.0.2.1", "method": "VIRTUAL_ACCOUNT", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash", "bankCode": "KNMB" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "MY", "currency": "MYR", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash", "bankBranch": "BB", "bankCode": "BSBN" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "NG", "currency": "NGN", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "PH", "currency": "PHP", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash", "bankCode": "AOMB" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "PH", "currency": "PHP", "email": "email@test.com", "ip": "192.0.2.1", "method": "GOTYME", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "John Amigo" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "PH", "currency": "PHP", "email": "email@test.com", "ip": "192.0.2.1", "method": "GRABPAY", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "John Amigo" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "PH", "currency": "PHP", "email": "email@test.com", "ip": "192.0.2.1", "method": "G_CASH", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "PH", "currency": "PHP", "email": "email@test.com", "ip": "192.0.2.1", "method": "MAYA", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "PK", "currency": "PKR", "email": "email@test.com", "ip": "192.0.2.1", "method": "EASY_PAISA", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "mobileNumber": "9243134334" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "PK", "currency": "PKR", "email": "email@test.com", "ip": "192.0.2.1", "method": "JAZZ_CASH", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "mobileNumber": "9243134334" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "SG", "currency": "SGD", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash", "bankCode": "DBS" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "SG", "currency": "SGD", "email": "email@test.com", "ip": "192.0.2.1", "method": "PAYNOW", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash" } } ``` ```json { "account": "8173586239", "amount": "10000", "country": "TH", "currency": "THB", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash", "bankCode": "BCA" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "TR", "currency": "TRY", "email": "email@test.com", "ip": "192.0.2.1", "method": "VIP_HAVALE", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "dob": "01-01-1970", "accountName": "Johny Cash", "mobileNumber": "9012345678", "tin": "12345678911", "tinDate": "01-01-1970", "bankCode": "ISBKSI" } } ``` ```json { "account": "8173586239", "amount": "100", "country": "VN", "currency": "VND", "email": "email@test.com", "ip": "192.0.2.1", "method": "BANK_TRANSFER", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "Johny Cash", "bankBranch": "BB", "bankCode": "BSBN" } } ``` **Generic Payout Response Sample** ```json { "status": "PENDING", "message": "Transaction is being processed", "id": "912z-1zs4-acvb-1bre3", "orderId": "abc123456" } ``` ```json { "status": "REJECTED", "message": "Payout rejected", "id": "912z-1zs4-acvb-1bre3", "orderId": "abc123456" } ``` ```json { "timestamp": "2023-12-01T15:28:35.156+00:00", "message": "{[ERROR: {amount} must be positive value.];}", "details": "" } ``` ##### Payout Request Optional Data Field Table: [#payout-request-optional-data-field-table] The payout request “data” field contains possible additional parameters, which are provider dependent. If the parameters are missing, the required values will be asked (via web form) from the customer. | **Field Name** | **Data Description** | **Type** | Min | Max | Example | | -------------- | ------------------------------------------------------ | -------- | --- | --- | --------------- | | ifsc | Beneficiary ifsc number | CH | 11 | 11 | BSBN0001234 | | accountName | Beneficiary name | CH | 1 | – | Johny Cash | | bankCode | Beneficiary bank code | CH | 1 | – | BSBN0001111 | | bankName | Beneficiary bank | CH | 1 | – | BSBN Bank | | bankBranch | Beneficiary bank branch | CH | 1 | – | BB | | bankAddress | Beneficiary bank address | CH | 1 | – | BA | | bankCity | Beneficiary bank city | CH | 1 | – | Bank Area | | bankState | Beneficiary bank state | CH | 1 | – | Bank Province | | bsb | Australian beneficiary bank code | NU | 6 | 6 | 123456 | | dob | Customer’s Date of Birth | AN | 10 | 10 | 1990-12-21 | | name | Beneficiary first name | CH | 1 | – | Johny | | lastName | Beneficiary last name | CH | 1 | – | Cash | | street | Beneficiary street address | CH | 1 | – | 122 Grenfell St | | city | Beneficiary city | CH | 1 | – | Adelaide | | state | Beneficiary state | CH | 1 | – | SA | | postalCode | Beneficiary postal code | CH | 1 | – | 5000 | | mobileNumber | Beneficiary mobile number | CH | 1 | – | 5467756764 | | pin | Merchant’s own customer identifier, e.g. a user ID | CH | 1 | – | user\_1 | | cuit | Beneficiary CUIT (Argentine tax identification number) | CH | 1 | – | 76576574758 | | tin | Tax Identification Number | NU | 9 | 11 | 12345678910 | | tinDate | Tax Identification Number Date | AN | 10 | 10 | 2021-12-21 | ##### Payout API Response Fields [#payout-api-response-fields] | **Description** | **Format** | **Explanation** | | --------------- | ---------- | ------------------------ | | id | String | System Transaction ID | | message | String | Payment response message | | status | String | Transaction status | | orderId | String | Merchant Order ID | ### Payout Request Hash Generation [#payout-request-hash-generation] To ensure the integrity and security of payout requests, the hash value must be generated using the following steps: 1. **Concatenation of Parameters:**
– All parameters from the payload, including both inner and outer object parameters, must be concatenated into a single string.
– Parameters must be sorted alphabetically by their names.
– The callbackUrl and hash parameters should be **excluded** from the hash calculation.
– The format of the amount parameter value must be as follows: xx.xx. (Example, 100.00) 2. **Exclusion of Empty Parameters:**
– Parameters that have empty or null values must be **excluded** from the concatenated string. 3. **Appending the Secret Key:**
– A unique secret key, provided to the merchant, must be securely stored and never exposed to unauthorized parties.
– This secret key must be prepended to the beginning of the generated string.
– The final concatenated string must be hashed using the SHA-256 algorithm.
– The resulting hash value will then be compared to the hash value received in the payout request for validation. **Example:** ```json { "account": "abc123", "amount": "100", "country": "IN", "currency": "INR", "email": "email@test.com", "ip": "192.0.2.1", "midId": "123", "orderId": "abc123456", "callbackUrl": "https://example.com/callback", "data": { "accountName": "JohnyCash", "bankCity": "", "bankCode": "BSBN", "city": null, "ifsc": "BSBN0001234", "mobileNumber": "9123456789" } } ``` Step 1: Concatenate Parameters according to the rules. After sorting them alphabetically and excluding certain parameters, the resulting string is as follows: ```text account=abc123&accountName=JohnyCash&amount=100.00&bankCode=BSBN&country=IN¤cy=INR&email=email@test.com&ifsc=BSBN0001234&ip=192.0.2.1&midId=123&mobileNumber=9123456789&orderId=abc123456 ``` Step 2: Append the secret key: ```text mySecretUniqueKey&account=abc123&accountName=JohnyCash&amount=100.00&bankCode=BSBN&country=IN¤cy=INR&email=email@test.com&ifsc=BSBN0001234&ip=192.0.2.1&midId=123&mobileNumber=9123456789&orderId=abc123456 ``` Step 3: Hash the resulting string using SHA-256 algorithm: ```text AC5654FE3128E76AAF2EC79701DA170BFBC77F8AFBB8F9F060E629A62E1B6B0F ``` Step 4: Send it as a *hash* parameter value in a payout request. ### Payout Statuses [#payout-statuses] | **TX** **Type** | Event | **Status** | | --------------- | --------- | ----------------------------------- | | Received: | Temporary | **PENDING** | | Approved: | Final | **SUCCESS** | | Failed: | Final | **REJECTED**, **FAIL** | ### Payout Postbacks [#payout-postbacks] Each postback is a general **HTTP POST** request with a retry mechanism of maximum 5 attempts with a retry possibility every 3 minutes. We only consume one unique orderId per merchant. After that all transactions with the same ID will be rejected. #### Payout Postback Table [#payout-postback-table] | **Title** | **Format** | **Explanation** | | --------- | ---------- | ----------------------------- | | id | String | System Transaction ID | | orderId | String | Merchant Order ID | | status | String | Transaction status | | hash | String | Data signature for encryption | #### Payout Postback for Rejected payouts [#payout-postback-for-rejected-payouts] Opt-in to get payout ‘message’ in postbacks. It is possible to opt-in to get more detailed information about rejected payouts. Contact our tech support for assistance. These settings will be default for new apps after 9th September 2025. | **Title** | **Format** | **Explanation** | | --------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | message | String | **Missing some fields (could be one or many fields)**
\[Mid 4 rejected due to \{Error:\{mobile} is missing}]
\[Mid 4 rejected due to \{Error:\{accountname, bankcode, ifsc} is missing}]

**Balance**
\[Mid 4 rejected due to \{Insufficient Payout Balance}]
\[Mid 4 rejected due to \{Min amount is 100.0}]
\[Mid 4 rejected due to \{Max amount is 100.0}]

**Rejected by the bank**
\[Mid 4 rejected due to \{Rejected by the Bank}]

**Rejected by multiple MIDs**
“\[Mid 4 rejected due to \{Error:\{accountname} is missing}]
\[Mid 6 rejected due to \{Insufficient Payout Balance}]
\[Mid 9 rejected due to \{Rejected by the Bank}]” | #### Payout Postback Sample [#payout-postback-sample] header name ‘apikey’, header value \ ```json { "id": "912z-1zs4-acvb-1bre3", "orderId": "merchtx12345", "status": "SUCCESS", "hash": "", "message": "" } ``` #### Data Signature of Payout [#data-signature-of-payout] | **Encryption** **Variables** | **Values and explanations** | | ---------------------------- | ---------------------------------------------------- | | apikey | \ | | Secret key | \ | | Encryption format | Concatenated and signed by using SHA-256 algorithm | | Parameter order | The order must be in exact order as per below sample | | Parameter example | secretKey=xxx\&id=xx\&orderId=xx\&status=xx | | Result string | Will be signed using SHA-256 | # Payout Sandbox (/docs/sandbox) #### Payout Test Credentials [#payout-test-credentials] | | | | ------------ | ------------------------- | | API Endpoint | (/api/v6/external/payout) | | Use “email” Parameter | Response | Final status with postback | | --------------------------------------------- | -------- | -------------------------- | | [rejected@test.com](mailto:rejected@test.com) | REJECTED | n/a | | [success@test.com](mailto:success@test.com) | PENDING | SUCCESS | | [fail@test.com](mailto:fail@test.com) | PENDING | FAIL | # Status API (/docs/status-api) Get the current status and core details of a payment or a payout via the Status API. | Field | Data Description | | -------------------------- | --------------------------------------------------------- | | Request method | POST | | Payment Status Request URL | https\://\/api/v3/external/payment/status | | Payout Status Request URL | https\://\/api/v3/external/payout/status | | Data format: | All data is sent and received in the JSON format. | | Content-Type: | application/json | | Accept: | application/json | | Headers: | ‘apikey’: \ (required) | Both endpoints accept the same request body and return the same response body. #### Status API Request Fields [#status-api-request-fields] Provide *id* or *orderId*. | Field | Type | Description | | -------------------- | ------ | ---------------------------------------------------------- | | id | String | Transaction identifier. | | orderId | String | Merchant/order identifier associated with the transaction. | #### Status API Response Fields [#status-api-response-fields] | Field | Type | Description | | ---------------------- | ------- | ----------------------------------------------------------------------------------------- | | status | String | Current transaction status. | | id | String | Transaction identifier. | | orderId | String | Merchant/order identifier. | | amount | Decimal | Transaction amount. | | currency | String | Transaction currency, e.g. INR, BDT, PKR. | | createdAt | Date | Transaction creation timestamp. | | paidAt | Date | Timestamp when the transaction was paid. May be null when not applicable or not yet paid. | | fee | Decimal | Transaction fee. | | method | String | Payment/payout method. | **Payment Status Request Sample** ```bash curl -X POST "https://{url-provided}/api/v3/external/payment/status" \ -H "apikey: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "id": "txn_123456", "orderId": "order_987654" }' ``` **Payment Status Response Sample** ```json { "status": "SUCCESS", "id": "txn_123456", "orderId": "order_987654", "amount": 125.50, "currency": "INR", "createdAt": "2026-09-04T15:30:00Z", "paidAt": "2026-09-04T15:31:12Z", "fee": 2.50, "method": "UPI" } ``` **Payout Status Request Sample** ```bash curl -X POST "https://{url-provided}/api/v3/external/payout/status" \ -H "apikey: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "id": "payout_123456", "orderId": "order_987654" }' ``` **Payout Status Response Sample** ```json { "status": "SUCCESS", "id": "payout_123456", "orderId": "order_987654", "amount": 500.00, "currency": "INR", "createdAt": "2026-09-04T16:10:00Z", "paidAt": "2026-09-04T16:12:45Z", "fee": 4.00, "method": "BANK_TRANSFER" } ```