A. Process flow
B. Explantion
Step 1: The customer confirms the receiving account.
Steps 2, 3, 4: The merchant requests verification of the receiving account and submits a money transfer request if the receiving account is valid.
Steps 5, 6: After the bank confirms the successful transfer, 9Pay will send back IPN transaction status information to the merchant as per the IPN registration with 9Pay.
Step 7: The customer updates the transaction status and notifies the customer.
C. API configuration
The header will be built according to the Integration Rules for the APIs
1. Check the receiving account
The API provides merchants with an option to check receiving account information.
| POST | /disbursement/check-account |
Request
| Attribute | Type | Required | Description |
| request_id | String (30) | yes | Request ID, unique for each request |
| bank_code | String | yes | Bank codes list |
| account_no | String | yes | The receiving bank account number |
| account_type | String | yes |
0: Bank account number 1: Bank card number |
Example request:
|
{ "request_id": "1996359677", "bank_code": "BIDV", "account_no": "0888523111", "account_type": "1" } |
Reponse
| Attribute | Type | Required | Description |
| status | Number | no | Transaction status code |
| error_code | String | yes | Error code of disbursement |
| message | String | yes | Error discription |
| request_id | String | yes | Same as the original request |
| bank_code | String | yes | Same as the original request |
| account_no | String | yes | Same as the original request |
| account_name | String | yes | The name of the recipient's bank account |
| account_type | String | yes | Same as the original request |
Example reponse:
|
{ "status": 6, "error_code": "1004", "message": "Invalid bank account", "request_id": "1996359677", "bank_code": "9PAY", "account_no": "08885231111", "account_name": null, "account_type": "1" } |
2. Get current Merchant balance
The balance API allows Merchant to check the Disbursement fund in 9Paysystem
| GET | /disbursement/balance |
Reponse
| Attribute | Type | Required | Description |
| status | Number | yes | Transaction status code |
| error_code | Number | yes | Error code of disbursement |
| message | String | yes | Error discription |
| data | String | yes | Disbursement balance |
Example reponse:
|
{ "status": 5, "error_code": "000", "message": "success", "data": 9867767 } |
3. Money transfer request
Allowing partners to request 9Pay to transfer a specific amount of money into a 9Pay wallet or the customer's card/bank account
| POST | /disbursement/create |
Request
| Attribute | Type | Required | Description |
| request_id | String (30) | yes | Request ID, unique for each request |
| amount | Number | yes |
A specific amount Currency: VND Min: 2,000 VND Max: 2,000,000,000 VND
|
| description | String (150) | yes | Description |
| bank_code | String | yes | Bank codes list |
| account_no | String (20) | yes | The receiving bank account number |
| account_name | String (50) | yes | The receiving bank account name |
| account_type | String | yes |
0: Bank account number 1: Bank card number |
Example request:
|
{ "request_id": "Y3Y728959039", "amount": "1021120", "description": "Test chi ho", "bank_code": "9PAY", "account_name": "NGUYEN VAN A", "account_no": "0888523111", "account_type": "0" } |
Reponse
| Attribute | Type | Required | Description |
| status | Number | yes | Transaction status code |
| error_code | String | yes | Error code of disbursement |
| created_at | Datetime | no | Transaction creation time (UTC+0) |
| message | String | yes | Error description |
| payment_no | Number | no |
9Pay's transaction ID |
| amount | Number | no | Same as the original amount in the request |
| description | String | no | Description |
| bank_code | String | no | Bank codes list |
| account_name | String | no | The receiving bank account name |
| account_no | Number | no | The receiving bank account number |
Example reponse:
|
{ "status": 2, "error_code": "000", "message": "success", "payment_no": 42584867066915, "description": "Test chi hO", "amount": "1000000", "bank_code": "BIDV", "account_name": "NGUYEN VAN A", "account_no": "1023020330000", "created_at": "2023-08-25T08:51:20.000000Z" } |
4. Processing payment result
After a successful payment transaction, 9Pay will send a POST request (x-www-form-data) to the merchant's registered IPN_url address.
Data reponse
| Attribute | Type | Required | Description |
| result | String | yes | Transaction information |
| checksum | String | yes | The checksum code generated using the partner's result and checksum key |
The value in the result after decoding:
| Attribute | Type | Required | Description |
| status | Number | yes | Transaction status code |
| error_code | Number | yes | Error code of disbursement |
| failure_reason | String | no | Error description |
| message | String | yes | Detailing errors according to error_code |
| method | String | yes | DISBURSEMENT |
| payment_no | Number | yes |
9Pay's transaction id |
| amount | Number | yes | Same as the original amount in the request |
| description | String | yes | Description |
| bank_code | String | yes | Bank codes list |
| account_name | String | yes | The receiving bank account name |
| account_no | Number | yes | The receiving bank account number |
| created_at | Datetime | yes | Transaction creation time (UTC+0) |
5. Test card/account information for disbursement
| No | Case | Type | Account number/Card number | Bank code | Account name |
| 1 | Sucess | Account | 1023020330000 | BIDV, VCB | NGUYEN VAN A |
| 2 | Fail | Account | 2034030440000 | BIDV, VCB | NGUYEN VAN A |
| 3 | Sucess | Account | 66668888 | CTG, VCB | GOOGLE COMPANY |
| 4 | Fail | ATM card | 6868686868 | CTG, VCB | GOOGLE COMPANY |
| 5 | Sucess | ATM card | 9704060129837294 | CTG, VCB | NGUYEN VAN NAPAS |
| 6 | Fail | ATM card | 9704000000000018 | ACB, ABB | NGUYEN VAN A |
| 7 | Sucess | Wallet | 0888523111 | 9PAY | Nguyen Thanh Tung |
6. Error code of disbursement
| Error code | Description | Actions |
|
431 |
The balance in the Merchant account is not enough to make the transaction | Please contact 9Pay to top up the proxy account balance for further payments |
|
1001 |
Account not found |
Please check and try again with another bank or refer to the supported bank_code list |
|
1002 |
Invalid verify information |
Please verify your account information before retrying |
|
1004 |
Invalid bank account |
Please verify your account information before retrying |
|
1005 |
Service has not been activated. Please contact 9Pay via hotline 1900 88 68 32 (8h - 18h from Monday to Friday) for support. |
Please contact 9Pay for more details |
|
1006 |
Bank information not found | Please check and try again with another bank or refer to the supported bank_code list |
|
1007 |
Payment allowed limit has been exceeded (from 1 VND to 2,000,000,000 VND) | Please make the payment again with an amount within the allowed payment limit |
|
1008 |
Invalid account name |
Please double check if the receiver account's info is correct before retrying |
| 318 | Invalid data in request | The request contains invalid data. Please check the request data again. |
| 702 | Transaction has been completed | The transaction already exists. Please generate a different request ID. |