Table of content
Use cases
1. Retrieve accepted payment sources
- Purpose: To determine which type of payment method (domestic, international source issued in Vietnam, or international source issued abroad) is accepted by the merchant.
- Scenario: A customer scans a VNPAY QR code and wants to choose a valid payment source.
- System action: The system calls
/check-source-moneywith customer and merchant details. - Outcome: VNPAY returns the list of accepted payment sources.
- Benefit: The customer selects the correct account or card for payment.
2. Retrieve billing information
- Purpose: To verify bill details before payment.
- Scenario: A customer scans a VNPAY QR code in NCB’s mobile app.
- System action: The system calls
/get-infor-qr-vnpaywith the QR data, voucher code (if any), payment amount, payment source - Outcome: VNPAY returns the status of QR data (if the QR code is already paid or data has been changed), promotion value, merchant type
- Benefit: The customer validates the bill before confirming payment.
3. Notify successful payment
- Purpose: To synchronize transaction status with VNPAY.
- Scenario: After the customer completes payment, NCB records the transaction internally.
- System action: NCB calls
/qr-vnpay-paywith payment details. - Outcome: VNPAY validates the payment transaction such as QR data, voucher and then notifies the biller of successful payment so that the biller can process the order. After the order is processed, VNPAY can respond the process status (resCode field) to NCB in which if the order fails, this may trigger a call to void the transaction. The list of resCode is as belows:
Error code
| Error code | Void (Y/N) | Error description |
| 00 | N | Success |
| 01 | Y | Invalid input data |
| 02 | Y | IP address is not allowed to access |
| 03 | Y | Partner code is not configured in VNPAY system |
| 04 | Y | Invalid phone number |
| 06 | Y | Invalid PayDate |
| 07 | Y | Merchant does not exist |
| 08 | N | Suspicious transaction, customer’s funds are on hold |
| 11 | Y | Merchant is not activated or has been locked |
| 12 | Y | Invalid signature |
| 13 | Y | Transaction has already been paid |
| 14 | Y | Invalid or blocked transaction for this merchant |
| 15 | Y | Original transaction not found |
| 16 | Y | Invalid payment amount |
| 17 | Y | Transaction expired |
| 18 | Y | Invalid responsecode |
| 19 | Y | Payment account is locked |
| 20 | Y | Phone number is locked |
| 21 | Y | Terminal code does not exist |
| 23 | Y | Duplicate transaction: Invoice number has already been paid or traceTransfer is duplicated |
| 24 | Y | Terminal code is not activated or has been locked |
| 25 | Y | Master merchant code does not exist |
| 26 | Y | Master merchant code is not activated or has been locked |
| 29 | Y | QR code has expired |
| 30 | Y | QR code data has been modified |
| 31 | Y | Multiple QR code payments are not from the same merchant |
| 76 | Y | Bank or wallet is not accepted for payment at this merchant or terminal |
| 89 | Y | Master merchant is locked or does not support payment |
| 96 | Y | Merchant under maintenance |
| 99 | Y | System error |
- Benefit: Ensures accurate settlement and transparency between NCB, VNPAY, and the biller.
4. Void failed transaction
- Purpose: To handle transaction failures and prevent invalid reconciliation.
- Scenario: A payment attempt fails due to insufficient funds, expired QR, or system error.
- System action: NCB calls
/void-qr-vnpaywith the failed transaction reference. - Outcome: VNPAY voids the transaction and ensures it is excluded from settlement.
- Benefit: Provides proper reconciliation and reduces disputes.
