# Transfer / Payout
The merchant business system initiates a transfer application through the Transfer API, and the payment gateway will pass the request data to the corresponding upstream API.
# Transfer API
api
Request API: /api/transferOrder
Request method: POST
Request type: application/json or application/x-www-form-urlencoded
# Request parameters
| Field Name | Variable Name | Required | Type | Example Value | Description |
|---|---|---|---|---|---|
| Merchant No | mchNo | Yes | String(30) | M1621873433953 | Merchant Number |
| App ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | App ID |
| Merchant Order No | mchOrderNo | Yes | String(30) | 20160427210604000490 | Payment order number generated by the merchant |
| Entry Type | entryType | Yes | String(20) | PIX_XX | Payment channel |
| Transfer Amount | amount | Yes | int | 100 | Transfer amount, in cents |
| Country | country | Yes | String(2) | US | Country two-character code |
| Currency Code | currency | Yes | String(3) | USD | Three-digit currency code |
| Fee Bearer | feeBear | Yes | String(32) | merchant | Fee bearer merchant-merchant bear beneficiary-payee bear |
| *Payment Account Number | accountNo | Yes | String(64) | o6BcIwvTvIqf1zZZohc61biryWik | Payee Account Id |
| *Account type | accountType | No | String(32) | account | Payee account type |
| *Payee Name | accountFullName | No | String(64) | Sky Wong | Full Name |
| *First Name | accountFirstName | No | String(64) | Sky | First Name |
| *Middle Name | accountMiddleName | No | String(64) | sw | Middle Name |
| *Last Name | accountLastName | No | String(64) | Wong | Last Name |
| *Document ID | documentId | No | String(64) | 12345678 | Payment document ID |
| *Document Issuance Date | docIssueDate | No | String(10) | 20230101 | Issuance date (yyyyMMdd) |
| *Birth Date | birthDate | No | String(10) | 20230101 | Birth date (yyyyMMdd) |
| *Mobile phone number | phone | No | String(20) | 764346789 | Mobile phone number |
| * City | city | No | String(32) | London | City |
| *Postcode | postcode | No | String(16) | E4 7FH | Postcode |
| *Detailed address | address | No | String(128) | Epping Forest District | Detailed address |
| *The beneficiary's bank ID | bankCode | No | String(64) | ACEH | The bank ID |
| *Name of the beneficiary's account bank | bankName | No | String(64) | Bank Name | Bank name |
| *Bank Branch | bankBranch | No | String(64) | Bank Name on where | Bank Branch Name |
| No | String(128) | enjoy@enjoypayment.com | Payee email | ||
| Client IP | clientIp | No | String(32) | 210.73.10.148 | Client IPV4 address |
| Payment remark information | transferDesc | No | String(128) | Test payment | Payment remark information |
| Asynchronous notification address | notifyUrl | No | String(128) | https://merchant.com/testNotify/y01 | The URL will be called back after the payment is completed. The callback will only be initiated when the value is passed |
| Extended parameters | extraParam | No | String(512) | 134586944573118714 | Merchant extended parameters, which will be returned unchanged during callback |
| Request Time | reqTime | Yes | long | 1622016572190 | Request API time, 13-digit timestamp |
| API Version | version | Yes | String(3) | 1.0 | API version number, fixed: 1.0 |
| Signature | sign | Yes | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Signature value, see signature algorithm for details |
| Signature type | signType | Yes | String(32) | MD5 | Signature type, currently only supports MD5 mode |
Attention
Parameters marked with * are optional and required according to different payment methods, please refer to"Payment support list"
# Request Example Data
{
"entryType":"PIX",
"amount":1,
"accountName":"",
"mchOrderNo":"mho1629106169045",
"sign":"3EB5A3B81E92DB41677E235363E7DDE3",
"transferDesc":"Test Payment",
"reqTime":"1629106169",
"version":"1.0",
"appId":"60cc3ba74ee0e6685f57eb1e",
"accountNo":"a6BcIwtTvIqv1zZZohc61biryWok",
"clientIp":"192.166.1.132",
"signType":"MD5",
"currency":"USD",
"mchNo":"M1623997351"
}
# Return Parameters
| Field Name | Variable Name | Required | Type | Example Value | Description |
|---|---|---|---|---|---|
| Return State | code | Yes | int | 0 | 0 - processing successful, others - processing error, see error code for details |
| Return Message | msg | No | String(128) | Signature failure | Specific error reasons, such as: signature failure, parameter format verification error |
| Signature | sign | No | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | Sign the data in data, if data is empty, it will not be returned |
| Return Data | data | No | String(512) | {} | Return order data, json format data |
# Parameter Data Format
| Field Name | Variable Name | Required | Type | Example Value | Description |
|---|---|---|---|---|---|
| Payment Order No | transferId | Yes | String(30) | T202108161731281310004 | Return payment order number |
| Merchant Order No | mchOrderNo | Yes | String(30) | mho1624007315478 | Returns the payment order number passed in by the merchant |
| Currency Code | currency | Yes | String(3) | USD | Three-digit currency code |
| Transfer Amount | amount | Yes | String(long) | 100 | Payment amount, in cents |
| Arrival Amount | arrivalAmount | Yes | String(long) | 100 | Arrival amount, in cents |
| Fee Bearer | feeBear | Yes | String(32) | merchant | Fee bearer merchant-merchant bear beneficiary-payee bear |
| Transfer State | state | Yes | int | 2 | Payment status 0-Order generated 1-Payment in progress 2-Payment successful 3-Payment failed 4-Payment closed |
| Channel Error Code | errCode | No | String | PAYMENT_AUTH_CODE_INVALID | Error code returned by the upstream channel |
| Channel Error Message | errMsg | No | String | Business Failed | Failed |
# Return Example Data
{
"code": 0,
"data": {
"accountNo": "1",
"amount": "11",
"channelOrderNo": "20210816110070001506260000372216",
"mchOrderNo": "1629106288",
"state": 2,
"transferId": "T202108161731281310004"
},
"msg": "SUCCESS",
"sign": "195BF6F112386F7FC8EA2AA7EECA1D33"
}