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 proceeds with the payment for the order, the merchant's website may or may not display the Apple Pay.
If the customer selects Apple Pay method on the merchant's website, there is no need to select the Apple Pay on the 9Pay payment gateway.
Steps 2 and 3: The merchant generates a payment link with the order information and a unique invoice_no. Then, the merchant's website redirects 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 completes the payment steps on the 9Pay payment gateway, if the transaction is successful, 9Pay will send IPN (Instant Payment Notification) transaction status information to the merchant's website as registered with 9Pay.
Step 7: The customer is redirected back to the merchant's website via 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 actively queries the transaction status to update the transaction result.
Not receiving IPN may be due to network issues, service unavailability, or other technical problems.
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 | OrderId of merchant, unique for each request |
| amount | Number | yes |
Amount needs to be paid Min: 10,000 VND Max: 100,000,000 VND Curency: VND |
| description | String(255) | yes | Description of order information |
| method | String | no | By default, redirect customers to 9Pay to select their payment method. If you pass "method = APPLE_PAY," then redirect to 9Pay to enter payment information. |
| 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 |
| bank_code | String | no | Pass the bank code if you want to go directly to the bank's card input form. |
| 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
You can use Apple Pay to process payment.
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 | APPLE_PAY |
| currency | String (10) | yes | Currency |
| created_at | Array | yes | Example: 1335939007 (UTC+0, length=10) |
| card_brand | String | yes | Bank name |
| status | Number | yes | |
| failure_reason | String | yes | Error description |
| card_info | Array | yes | Payment information data |
| card_info.card_name | String | yes | The name of the cardholder printed on the card |
| card_info.card_brand | String | yes | The issuing bank of the card |