1. Introduction
Along with the rapid development of e-commerce, the online shopping demand of consumers is increasing. To meet this online payment demand, TrueMoney developed TrueMoney Pay online payment gateway, providing payment services through Vietnam Local ATMs Card, International Payment Cards (VISA, Master, JCB) and TrueMoney e-Wallet. Not only do we offer convenience in payment to consumers, we also offer the convenience of integrating, operating, controlling and paying for partners.
For payment via International Payment Cards (VISA, Master, JCB), after the integration, the website / application of the business can display the TrueMoney Pay button so that the customer can complete the payment in just a few simple steps:
- The user choose payment method of International Payment Cards (VISA, Master, JCB), then click the payment/checkout button.
- Customers are directed to the TrueMoney Pay Website and are required to enter the card information for authentication. Depending on the security requirements of the card issuing bank and the international card organization, customers may be required to add 3D-Secure security information (usually OTP sent to the customer’s phone number).
- Once the payment is completed, the customer will be directed back to the purchase page of the merchant along with the payment result. Merchant can check the payment result and make decision on how to move forward.
2. Biz Model
Step 1: End-user purchases on the Merchant’s Website / App and select payment via International Payment Cards (VISA, Master, JCB).
Step 2: End-user is redirected to the payment page of TrueMoney Pay and required to enter customer infomation
Step 3: End-user enter card infomation.
Step 4: Depending on the card issuing bank, End-user may be required to enter OTP authentication transactions.
Step 5: End-user receives a successful payment notification and is redirected to the Merchant purchase page.
3. Guide
Implementation Steps:
- End-user clicks Pay on the Merchant’s website/app to pay for the order.
- Merchant call web service (2) do-payment to get payment_url and trans_ref.
- Merchant redirects end-user to payment_url (which TrueMoney Pay returns from do-payment).
- TrueMoney Pay shows payment page and process transactions with end-user, then show result to end-user. TrueMoney Pay will redirect end-user to return_url and return transaction result to Merchant via return_url after the end of transaction.
- TrueMoney Pay returns transaction result to Merchant’s IPN_url.
- After 15 minutes, if Merchant haven’t got transaction result, Merchant can request transaction-details to TrueMoney Pay to recheck transaction result.
4. APIs Reference
Detailed Description
(*): Required parameters must have values. Other parameters can input null values.
(2) Request Do-payment
Address to receive Request Charging:
POST https://partner.truemoney.com.vn/paymentgw/v1/do-payment
Max request time out: 30 seconds
Parameter | Description |
---|---|
access_key* string(255) |
Representing the product of the merchant declared in the system of TrueMoney Pay. |
amount* Bigdecimal |
Payment amount. Payment amount must be an integer. |
order_id* String(50) |
Order ID is representing the transaction, must be unique in the day of transaction. Order ID does not exceed 50 characters, Vietnamese without diacritic (A-z, 0-9). |
order_info* String(100) |
Order description. Order info does not exceed 100 characters, Vietnamese without diacritic (A-z, 0-9, space). |
return_url String(255) |
The URL which will be redirected back after the payment is completed, merchant need to build to receive results from TrueMoney Pay. The request sent by the TrueMoney Pay System will be in the form of HTTP GET. If there is no data then it will take the value as the merchant’s settings in TrueMoney Pay portal. |
bank_code String(50) |
Bank code is defined by TrueMoney Pay (used in case of payment by Vietnamese domestic ATM card). View details in III. Supported Bank list. |
wallet_code* String(50) |
Wallet code is defined by TrueMoney Pay (used in case of payment by Wallet). View details in V. Supported Wallet list. |
payment_type* Int |
0: payment by Vietnamese domestic ATM card, 1: payment by International card (VISA, Mastercard, JCB) or 2: payment by wallet. |
customer_name String(255) |
Name of the payer. |
customer_email. String(50) |
Email of the payer.. |
customer_phone String(50) |
Phone number of the payer. |
language String(2) |
vi (Vietnamese), en (English). If Merchant does not require a language, then the default language is Vietnamese. |
signature* String(255) |
Signature, Merchant use signature to control security. Signature is a string access_key=$access_key&amount=$amount&order_id=$order_id&order_info=$order_info&return_url=$return_url which is hmac by SHA256 algorithm. |
(2′) Response Do-payment
Is a string of json, including the following values::
{"response_code":"[code]","response_message":"[message]", "data":{"payment_url":"[url]","trans_ref":"[Trading code]"},"signature":"[Signature]"}
In which
Parameter | Description |
---|---|
response_code | Transaction result code, mapping with Transaction result error code. |
response _message | Transaction result description. |
payment_url | Url to submit request (redirect). |
trans_ref | Code generated by TrueMoney Pay. The transaction code is used to commit the request, recheck and save it on the system |
signature* String(255) |
Signature, Merchant use signature to control security. Signature is a string response_code=$response_code&response_message=$response_message which is hmac by SHA256 algorithm. |
(3) Submit(redirect) request
Redirect request to the address of payment_url receive from (2′), TrueMoney Pay system displays filling out with Bank card information and doing transaction with end users..
(3′) Response to return_url
After end user does payment via bank card,TrueMoney wallet account TrueMoney Pay returns the transaction result to merchant at the address of declared return_url from (2).
Parameter | Description |
---|---|
access_key String(255) |
Representing the product of the merchant declared in the system of TrueMoney Pay |
order_id String(50) |
The order ID is unique, representing the transaction <50 characters |
trans_ref String(50) |
Transaction reference generated by TrueMoney Pay. Merchant need to save the transaction reference to merchant’s system. It is used to mapping transactio between TrueMoney and Merchant, search transaction result on Merchant portal, call API check transaction result and refund. |
payment_type Int |
0: payment by Vietnamese domestic ATM card, 1: payment by International card (VISA, Mastercard, JCB) or 2: payment by wallet. |
result_code String(10) |
Transaction result code, depend on payment type, mapping with Transaction result error code for payment by domestic cards, international cards (II.1) or Transaction result error code for payment by Wallet (IV.1). |
description String(255) |
Transaction result description. |
language String(2) |
vi (Vietnamese), en (English). |
wallet_id String(50) |
Code of the wallet that payment was made (returned in case of payment via TrueMoney Wallet). |
signature String(255) |
Signature, Merchant use signature to control security. Signature is a string access_key=$access_key&order_id=$order_id&trans_ref=$trans_ref&payment_type=$payment_type&result_code=$result_code which is hmac by SHA256 algorithm. |
(5) Send IPN (Instance Payment Notification)
After end user does payment via bank card,TrueMoney wallet account TrueMoney Pay returns the transaction result to merchant at the address of declared return_url from (2) with method POST.
TrueMoney can send IPN up to 3 times for a transaction.
Parameter | Description |
---|---|
access_key String(255) |
Representing the product of the merchant declared in the system of TrueMoney Pay. |
trans_ref String(50) |
Transaction reference generated by TrueMoney Pay. Merchant need to save the transaction reference to merchant’s system. It is used to mapping transactio between TrueMoney and Merchant, search transaction result on Merchant portal, call API check transaction result and refund. |
amount Bigdecimal |
Payment amount. |
order_id String(50) |
Order ID that merchant sent to TrueMoney Pay when request payment. |
order_info String(100) |
Order info that merchant sent to TrueMoney Pay when request payment. |
payment_type Int |
0: payment by Vietnamese domestic ATM card 1: payment by International card (VISA, Mastercard, JCB) or 2: payment by wallet |
bank_code String(50) |
Bank code is defined by TrueMoney Pay (used in case of payment by Vietnamese domestic ATM card). View details in III. Supported Bank list. |
wallet_code String(50) |
Wallet code is defined by TrueMoney Pay (used in case of payment by Wallet). View details in V. Supported Wallet list. |
payment_time String(50) |
Transaction completion time (format hh:mm:ss dd-mm-yyyy) |
result_code String(10) |
Transaction result code, depend on payment type, mapping with Transaction result error code for payment by domestic cards, international cards (II.1) or Transaction result error code for payment by Wallet (IV.1). |
description String(255) |
Transaction result description. |
language String(2) |
vi (Vietnamese), en (English). |
wallet_id String(50) |
Code of the wallet that payment was made (returned in case of payment via TrueMoney Wallet). |
signature | Signature, Merchant use signature to control security. Signature is a string access_key=$access_key &order_id=$order_id&trans_ref=$trans_ref&payment_type=$payment_type&result_code=$result_code which is hmac by SHA256 algorithm. |
(5′) Response IPN
After merchant get result from IPN, merchant need to return json below to TrueMoney Pay:
{"response_code":"[00]","response _message":"[Success]"}
In which
Parameter | Description |
---|---|
response_code | Merchant should send a response to TrueMoney Pay system to recognize the status of Merchant transaction records. Merchant need to send the error code for IPN which is defined by TrueMoney (depend on payment type, mapping with Transaction result error code for payment by domestic cards, international cards (II.2) or Transaction result error code for payment by Wallet (IV.2).). If Merchant returns 00 or 01, TrueMoney will stop sending IPN. If not, TrueMoney will send the IPN to Merchant for total of 3 times, every 5 minutes. |
response_message | IPN result description. |
(6) Request Transaction- Detail
POST https://partner.truemoney.com.vn/paymentgw/api/v1/transaction-detail
Confirm transaction is completed.
Parameter | Description |
---|---|
access_key* | Representing the product of the merchant declared in the system of TrueMoney Pay |
trans_ref* | Code generated by TrueMoney Pay. The transaction code is used to commit the request, recheck and save it on the system |
signature* | Signature, merchant can use signature to control security. Signature is a string: access_key=$access_key&trans_ref=$trans_ref which is hmac by SHA256 algorithm |
Is a string of json, including the following values:
{"response_code":"[code]","response_message":"[message]", "data":{"trans_ref":"[Trading code]","amount":"[Amount]","order_id":"[Order_ID]","order_info":"[Description]","payment_type":"[2]","bank_code":"[Bank code]","wallet_code":"[Code]","status":"[Status]","refund_status":"[Refund status]","request_time":"[Time start]","finish_time":"[Time finish]","result_code":"[Result code]","description":"[Detail]"},"signature":"[Signature]"}
In which
Parameter | Description |
---|---|
response_code | Check transaction result code, depend on payment type, mapping with Transaction result error code for payment by domestic cards, international cards (II.3) or Transaction result error code for payment by Wallet (IV.3). |
response_message | Check transaction result description. |
trans_ref | Transaction reference generated by TrueMoney Pay. Merchant need to save the transaction reference to merchant’s system. It is used to mapping transactio between TrueMoney and Merchant, search transaction result on Merchant portal, call API check transaction result and refund. |
amount | Payment amount. |
order_id | Order ID that merchant sent to TrueMoney Pay when request payment. |
order_info | Order info that merchant sent to TrueMoney Pay when request payment. |
payment_type | 0: payment by Vietnamese domestic ATM card 1: payment by International card (VISA, Mastercard, JCB) or 2: payment by wallet. |
bank_code | Bank code is defined by TrueMoney Pay (used in case of payment by Vietnamese domestic ATM card). View details in III. Supported Bank list. |
wallet_code | Wallet code is defined by TrueMoney Pay (used in case of payment by Wallet). View details in V. Supported Wallet list. |
status | init: initialize the transaction processing: processing transaction success: transaction successful fail: transaction fail timeout: transaction timeout. |
refund_status | Refund status:init: initialize the transaction processing: processing transaction success: transaction successful fail: transaction fail timeout: transaction timeout. |
request_time | Transaction start time (format hh:mm:ss dd-mm-yyyy). |
finish_time | Transaction completion time (format hh:mm:ss dd-mm-yyyy). |
result_code | Transaction result code, depend on payment type, mapping with Transaction result error code for payment by domestic cards, international cards (II.1) or Transaction result error code for payment by Wallet (IV.1). |
description | Transaction result description. |
signature | Signature, Merchant use signature to control security. Signature is a string: response_code=$response_code&response_message=$response_message which is hmac by SHA256 algorithm. |
ERROR CODE
Table 1. Transaction result error code
Error code | Error message |
---|---|
00 | Successful transaction. |
01 | Merchant is invalid (Invalid access key). |
02 | The sent data is not formatted correctly. |
03 | Bank is not supported. |
04 | Invalid signature. |
05 | Customer account has insufficient payment balance. |
06 | Invalid transaction amount (less than or beyond the transaction limit). |
07 | The transaction amount is smaller than the minimum limit of one payment. |
08 | The transaction amount exceeds the maximum limit of one payment. |
09 | Transactions amount exceed the daily/weekly/monthly maximum limit. |
10 | Customer entered the wrong OTP too many times. |
11 | Transactions exceed the maximum number of times that OTPs are omitted during the day for a service. |
12 | Customer cancels the transaction. |
13 | Transaction failed due to timeout. |
14 | Transaction error, please check with the bank. |
15 | Pending transaction result from Bank. |
16 | Error connecting to bank system. |
17 | The system is maintenance. |
18 | IP addresses are not allowed. |
19 | Transaction not found. |
24 | The number of transactions exceeds the maximum limit of days / weeks / months. |
25 | Bank rejects transaction. |
26 | The transaction is suspicious and being suspended for inspection. |
99 | Unknown error, please contact to investigate. |
Table 2. Merchant return error code when updating result after receive Instant Payment notification
Error code | Error message |
---|---|
00 | Record successful transaction results. |
01 | Request was previously processed. |
02 | Order not found. |
99 | Unknown error, please contact to investigate. |
Table 3. Check transaction error code
Error code | Error message |
---|---|
00 | Success. |
01 | Merchant is invalid (Invalid access key). |
02 | The sent data is not formatted correctly. |
04 | Invalid signature. |
17 | The system is maintenance. |
18 | IP addresses are not allowed. |
19 | Transaction not found. |
99 | Unknown error, please contact to investigate. |
5. Examples
6. Sandbox
API URL in Sandbox environment:
POST https://payment.truemoney.com.vn/sandbox/api/v1/do-payment
Check test transaction in Sandbox environment:
POST https://payment.truemoney.com.vn/sandbox/ui/v1/transaction-log
Account test success case, enough balance, eligible for payment:
- Account: 5358 2700 0000 0001
- Name of card holder: NGUYEN VAN A
- Expiration date: 09/2023
- CVV: 123
- OTP: 123456
Account not enough balance:
- Account: 5358 2700 0000 0002
- Name of card holder: NGUYEN VAN A
- Expiration date: 09/2023
- CVV: 123