The instructions below show how you can process accordingly for each platform type and how API Configurations operate.
A. Process flow
B. Explanation
Step 1: The customer makes a payment for the order on the merchant's website.
When the customer completes the payment for the order, the merchant's website interface may or may not display the 9Pay e-wallet option.
If the customer selects the 9Pay e-wallet option on the merchant's website, there is no need to choose the 9Pay e-wallet option on the 9Pay Payment Gateway.
Steps 2 and 3: The merchant generates a payment link with unique order information and invoice_no. Subsequently, the merchant's website will redirect the customer to the created payment URL.
Steps 4 and 5: The customer enters payment information and verifies the payment.
Step 6: After the customer successfully completes the payment steps on the 9Pay Payment Gateway, if the transaction is successful, 9Pay will return an IPN (Instant Payment Notification) containing transaction status information to the merchant's website, based on the IPN registered with 9Pay.
Step 7: The customer is redirected back to the merchant's website using the return_url provided by the merchant in Step 2.
Step 8: The merchant displays the transaction result to the customer.
Step 9: Approximately 20 minutes after creating the payment URL, if no IPN is received, the merchant proactively queries the transaction status to update the transaction result.
Not receiving IPN can occur due to network issues, service unavailability, or other reasons.
C. API configuration
1. Create a payment URL
On the merchant's website, after the customer adds products/services to the shopping cart, the merchant's system will generate a payment URL. Then, it will redirect the customer to the payment page.
You only need to build the Merchant signature without constructing the entire header.
| Language | Reference link |
| PHP | https://gitlab.com/9pay-sample/sample-php |
| JAVA | https://gitlab.com/9pay-sample/sample-java |
| NodeJS | https://gitlab.com/9pay-sample/sample-javascript |
Required parameters
| Attribute | Type | Required | Description | |||
| invoice_no | String (30) | yes | Order Id of merchant, unique for each request | |||
| amount | Number | yes | Payment amount: Minimum: 4,000 VND Maximum: 100,000,000 VND Currency: VND |
|||
| description | String(255) | yes | Description of order information | |||
| method | String | no | y default, redirect the customer to 9Pay to choose the payment method. If you pass the method = WALLET, then redirect to 9Pay to scan the wallet QR code. | |||
| return_url | String | yes | A merchant's URL. This URL is used to redirect from 9Pay page to merchant's page after customer's payment | |||
| currency | String (10) | no | Currency. Default is VND. Support as USD, EUR, GBP, CNY, JPY | |||
| time | Int (10) | yes | Example : 1335939007 (UTC+0, length=10) | |||
| merchantKey | String | yes | The merchant identification string provided by 9Pay | |||
| lang | String | no | The language displayed on transaction screens for customers. (vi and en). Default is vi | |||
| profile_id | Int | no | Retrieve from the "Profile" list. In the case of wanting to update payment information for each profile. | |||
| is_customer_pay_fee | Int | no |
Determine the entity responsible for transaction fees. 0: Merchant bears the transaction fees., 1: Customers bear the transaction fees. Default is 0 |
2. Payment
Contact 9Pay to receive the download link for the 9Pay electronic wallet test app.
3. Processing payment result
Pay attention to duplicate handling when receiving results for a transaction using both methods.
Return
After the payment process is completed, the customer is redirected to the return_url provided by the merchant when creating the payment URL.
The merchant uses this result to display a notification of the successful/failed transaction to the customer (contained within the query string when returning to the merchant's link).
IPN - Instant Payment Notification
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 |
| version | String | IPN version |
The value in the result after decoding:
| Attribute | Type | Required | Description | |||
| payment_no | Number | yes | 9Pay's transaction id | |||
| invoice_no | String | yes | Orderid of merchant, unique for each request | |||
| amount | Number | yes | Payment amount | |||
| description | String (255) | yes | Order's information | |||
| method | String | yes | WALLET | |||
| currency | String (10) | yes | Currency | |||
| created_at | Array | yes | Example: 1335939007 (UTC+0, length=10) | |||
| card_brand | String | yes | 9PAY | |||
| status | Number | yes | Transaction status | |||
| failure_reason | String | yes | Error description | |||
| card_info | Array | yes | Payment information data | |||
| card_info.card_brand | String | yes | 9PAY | |||
| card_info.card_number | String | yes | The phone number registered for the 9Pay wallet |
4. See also