Integration Access Guide
Request and Response
The API request of the merchant system is submitted to the OTT Pay API server through HTTPS POST method.
The merchant system sends request to the OTT Pay API server, and the OTT Pay API server returns a response after processing the request. Both the request and the response are in JSON format, and the encoding format is UTF-8.
The response result is represented by JSON data format. The status attribute in the response indicates whether it is a successful result, and the result attribute indicates the actual returned data. For example:
{
"status": "SUCCESS",
"result": {
"token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJPTjAwMDAwMTgyMTQiLCJhdWRpZW5jZSI6bnVsbCwicm9sZSI6bnVsbCwiY3JlYXRlZCI6MTY3NzU5NDY2MzM5NywidXNlcnR5cGUiOiJDVVNUT01FUiIsImV4cCI6MTY3NzU5NTU2MywidXNlcmlkIjoxNH0.YHOw2N8oUP3vn_L-euzuUiShDfQbowAjrWjeVef0wn4jgHA4k5zsgcZ6euRUk-R-Xtn2OkYB7R8geGBjQQYnMw",
"expired": 1677595563672
}
}
Unsuccessful responses will contain error and message in result, for example:
{
"status": "ERROR",
"result": {
"code": 10003,
"message": "User does not exist"
}
}
Error Codes and Corresponding Messages: [API response error code](#api-response error code)
Authorization method
The OTT Pay API server is accessed using JWT token authorization. The merchant system needs to call Authorization API first to obtain a token, which will be included in the request header for each subsequent API call Contains authorization information:
Authorization: Bearer <token>
Example:
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJPTjAwMDAwMTgyMTQiLCJhdWRpZW5jZSI6bnVsbCwicm9sZSI6bnVsbCwiY3JlYXRlZCI6MTY3NzU5NDY2MzM5NywidXNlcnR5cGUiOiJDVVNUT01FUiIsImV4cCI6MTY3NzU5NTU2MywidXNlcmlkIjoxNH0.YHOw2N8oUP3vn_L-euzuUiShDfQbowAjrWjeVef0wn4jgHA4k5zsgcZ6euRUk-R-Xtn2OkYB7R8geGBjQQYnMw
@
API server URL
Production environment
https://ecom-api.ottpay.com/
Sandbox environment
https://sandbox-api.ottpay.com/
Test cards
All test local card transactions in the sandbox environment must use test cards. The following test cards are provided for testing payment transactions.
Brands | Card Number | Card Type | Expiry Date | CVV2 | Avs Address |
---|---|---|---|---|---|
Visa | 4000020000000000 | Credit | 03/2030 | 737 | Any address |
Visa | 4400000000000008 | Debit | 03/2030 | 737 | Any address |
Mastercard | 2222400010000008 | Credit | 03/2030 | 737 | Any address |
Mastercard | 2222400060000007 | Debit | 03/2030 | 737 | Any address |
American Express | 374101012180018 | Credit | 03/2030 | 7373 | 275 Notre-Dame St. East, Montreal, Quebec H2Y 1C6, Canada |
Discover | 6011601160116611 | Credit | 03/2030 | 737 | Any address |
JCB | 3569990010095841 | Credit | 03/2030 | 737 | Any address |
China UnionPay | 6243030000000001 | Credit | 12/2029 | 737 | Any address |
Diners | 36006666333344 | Credit | 03/2030 | 737 | Any address |
Payment Results
When the merchant system calls Payment API, it needs to perform subsequent payment actions according to the returned response results and payment scenarios. Some payment scenarios Payment results cannot be obtained immediately. After the OTT Pay API server receives the payment result from the payment channel, it will send the payment result to the specified callback URL (the callback URL needs to be specified in the request parameter of Payment API, please refer to the specific API description). Of course, the merchant system can also actively query through Payment Status Query API.
API Response error code
code | message | description |
---|---|---|
10001 | Transaction processing | Chinese Wallet Payment user is processing the payment, not applicable for local card transaction. |
10002 | Password is incorrect | Authorization failed OR The entered pre-authorization code is invalid. Apply on POS refund transactions only. |
10003 | API Authorization failed | The merchant appId and appKey pair you provided cannot be found |
10005 | Invalid parameter | Parameter format incorrect |
10006 | Parameter error | Input Parameter incorrect, Apply on EMV POS only, not applicable for local card transaction. |
10200 | Gateway error | OTT gateway’s error response. |
20001 | Payment paid | The transaction you have submitted has already been processed. Apply on Chinese Wallet Payment transactions only, not applicable for local card transaction. |
20002 | Payment number duplicated | The payment transaction you have submitted is duplicated. Apply on Chinese Wallet Payment transactions only, not applicable for local card transaction. |
20003 | This is not a pre-authorized payment | The payment request use a non-pre-authorized payment Id to complete a pre-authorized payment |
20004 | Database error | Transaction data induced database error. |
20005 | No permission for the merchant | 1) The entered pre-authorization code is invalid, or 2) The merchant account you provided cannot be found, or 3) The merchant account you provided is disabled, or 4) Your merchant account is not configured for the transaction you attempted. |
20006 | QR code expired, please refresh, and try again | The Chinese Wallet Payment auth code is expired. Apply on Chinese Wallet Payment transactions only, not applicable for local card transaction. |
20007 | Insufficient balance | 1) Card balance is insufficient to cover the payment, or 2) not enough funds for refund |
20008 | Unsupported card | The card type was not recognized, or The card was removed too quickly and the approval process was interrupted POS terminal was unable to encrypt the message and process the transaction |
20009 | Payment closed | The refund or void request on a payment that has already closed. |
20014 | Refund amount greater than the amount paid | The requested Refund amount exceeds the original/remaining transaction amount. |
20019 | Original payment not exist | Original transaction/payment ID you provided cannot be found |
20020 | Original payment has been finished | The Original payment has already been captured |
20021 | Original payment does not support revocation | Refund a non-captured transaction |
20030 | Payment failed | Your request has been declined due to no financial impact - original transaction already declined |
20031 | No channel supported | Chinese Wallet Payment transaction uses unsupported payment channel, not applicable for local card transaction. |
20034 | Other case | Any other errors that not include in the list |
20041 | The payment cannot be refunded | The payment has been fully refunded, it cannot be refunded any more. |
50001 | Failure | Payment Failed |
50002 | Timeout | Your request has been declined due to a timeout OR The authorization message is approved. The error occurs if: 1) the transaction was declined by the card afterwards, or 2) timeout on the terminal. As a result, the transaction is reversed. |
50003 | System error | No response received for the sent request |
90000 | Unauthorized | The entered access token is invalid |