Overview
This Document includes APIs for both Payment Gateway and Payment Processor. If you are a merchant,please use the Payment Gateway API for integration If you are an acquirer,please used the Payment Processor API for integration.
1.Payment Gateway
Abstract
The chapter describes the API of online service which is based on HTTPS protocol.The API is organized around Payment Gateway. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication.
Target audience: Experienced payment developer.
Key Benefits:
Fast setup & integration.
Very secure.
PCIDSS requirements and compliances are handled by JS SDK.
Base
Apply To Service Provider For The Required Parameters
Please apply to the payment process service provider for the required parameters before API integration. The online service system includes a developing and production environment. Obviously, developers should develop on the "develop" environment during the development and test.
Required Parameter List:
| Parameter | Description |
|---|---|
| Domain | The online service system includes a developing and production environment. Obviously, developers should develop on the "develop" environment during the development and test. |
| login email | usernameIt is used for Login API. |
| Password | passwordIt is used for Login API. |
| Store ID | {store_id}It is used for URL |
| APP-ID | It is used for Webhook |
| secret_key | It is used for Webhook |
Communication
HTTPS porctocol is used in Payment Gateway Server.
The requests are required to send same header items as below:
| Parameter | Type | Usage | Description |
|---|---|---|---|
| Content-Type | String | M | Constant. Value example: “application/json; charset=UTF-8” |
| X-USER-DEVICE-ID | String | O | If the payment is made on the POS device, this field should be POS Device SN. If the payment is made on the website, this field should be fingerprint |
| X-USER-ACCESS-TOKEN | String | M | Access token, could be null while doing Login. Value example: “q8s4qg53s8g99grszad9wusds72z9n6” |
| X-CLIENT-IP | String | M | 1.The client ID must be the IP address of the consumer. 2.It is client ip and the field must be required for pre-create api. Pre-create and called JS SDK should be from the same client ip. |
| X-APP-ID | String | O | The appid is provided by Payment Process Service Provider when applying for merchants Value Example:HxEAHKIAAAF5IKE0RZ3MBeHt4WEUKWbBzyPa_WQLseDAcqdDtZ-QAPP-ID |
Time Format
| Parameter | example |
|---|---|
| date_time | 2025-08-12T07:03:01+00:00 |
| created_at | 2025-05-16T07:53:48.649Z |
| update_at | 2025-05-16T07:53:48.649Z |
| complete_at | 2025-05-16T07:53:48.649Z |
| acquirer_txn_date_time | 2025-08-12T07:03:01+00:00 |
| gateway_clearance_at | 2025-05-16T07:53:48.649Z |
| acquirer_clearance_at | 2025-05-16T07:53:48.649Z |
Login/Authentication
Description
The Login command request like this:
curl --location --request POST 'https://{Domain}/gateway/v3/login' \
--header 'Content-Type: application/json' \
--data-raw '{
"username":"abcdtest@test.com",
"password":"123456"
}'
The Login command response like this:
{
"access_token": "i2ctfruzrda0efqlu47dnu2zwha97o6",
//* The access_token value is very important and needs to be saved
}
The API is used to logging in online service with a valid username and password. An access token will be returned it is mandatory to save it for future use. Any new HTTPS requests should contain the access token in Https headers, or 401 error occurs.
1.The login email, password and the Store ID are provided by payment process service provider when applying for merchants.
2.Validity of Access Token: Default permanent validity. If doing Login to get new access token, the new access token will be valid, the old access token will be invalid.
POST https://{Domain}/gateway/v3/login
Parameters Description
| Parameter | Type | Usage | Description |
|---|---|---|---|
| Requeset Parameters | |||
| username | String | M | ID / E-mail that applied from vendor. |
| password | String | M | Password |
| Response Parameters | |||
| access_token | String | M | Access token returned from server. The filed is need |
Payment API
The Payment Gateway API's description and demo as below.
If you need to used this API for payment, Please provide PCIDSS certificate to Your Payment Process Service Provider.
The API is used for payment directly.
POST https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions
Parameters Description
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| uuid | String | M | Transaction UUID. It is the unique identifier of the transaction. And new transaction should be requested with a new UUID. |
| transaction_type | String | M | Transaction type(“sale“). Referring to Appendix |
| payment_method | String | M | Payment method(“credit_card“). Referring to Appendix |
| amount | String | M | Transaction amount |
| currency | String | M | Transaction currency. Example: “HKD“ |
| order_num | String | O | The order number |
| order_info | String | O | The order info |
| success_url | String | O | It is required for 3DS transaction. After input the message PIN code, redirect the validate result page |
| fail_url | String | O | It is required for 3DS transaction. After input the message PIN code, redirect the validate result page |
| credit_card | JSON | M | Credit card info. |
| txn_exp_at | String | O | The expiration time of the order. and this parameter is optional. If it is not used, the default expiration time for order is 15 minutes. If “txn_exp_at“ is used, the value format is RFC3339 and it should be an absolute time of 15 minutes less than the create time. Eg: "txn_exp_at":"2021-09-28T14:41:00+08:00", |
| notify_url | String | O | WebHook notify url. The “notify_url” is required if use WebHook. |
| pay_redirect_url | String | M | Pay redirect url, is a required parameter to call the JS SDK. |
| Param(credit_card) | |||
| card_reader_mode | String | M | Card reader mode. Referring to Appendix |
| card_exp_date | String | M | Card expired date: YYMM |
| card_fallback | boolean | O | Whether it is fallback |
| card_number | String | M | Card number |
| card_sn | String | O | Card SN. If card_reader_mode is contact or contactless, must include this field. |
| card_track1 | String | O | Track 1 magnetic data |
| card_track2 | String | O | Track 2 magnetic data. If card_reader_mode is swipe, contact, or contactless, must include this field. |
| card_track3 | String | O | Track 3 magnetic data |
| card_holder_name | String | O | Cardholder name |
| is_msd_card | boolean | O | Whether it is an MSD card |
| cvv | String | O | CVV |
| icc_request | String | O | EMV ICC request data. If card_reader_mode is contact or contactless, must include this field. |
| pin | String | O | |
| Param(billing_address) | O | AVS | |
| zip_code | String | O | Zip Code |
| address | String | O | Address |
| city | String | O | City |
| state | String | O | Address State |
| country_code | String | O | Country Code:ISO_3166 Alpha 3 |
| Param(3DS) | |||
| enable | boolean | O | Enable 3ds. true or false |
| location_token | String | O | Submit Location Info. Value Example:2391003628694407168 |
| Response Parameters | |||
| uuid | String | M | Transaction UUID |
| transaction_type | String | M | Transaction type(“sale“). Referring to Appendix |
| payment_method | String | M | Payment method(“credit_card“). Referring to Appendix |
| amount | String | M | Transaction amount |
| currency | String | M | Transaction currency. Example: “HKD“ |
| transaction_state | String | M | Transaction state. Referring to Appendix Field value - Description success - Transaction success pending - Pending，waiting for processing failed - Transaction failed |
| error_code | String | O | Error code. If transaction state is “failed“ |
| error_desc | String | O | Error description. If transaction state is “failed“ |
| date_time | String | M | Transaction date time. |
| merchant_id | String | O | Merchant ID |
| terminal_id | String | O | Terminal ID |
| rrn | String | M | Reference number |
| brn | String | M | Bill reference number |
| acquirer_type | String | O | Acquirer type. Referring to Appendix |
| redirect_url | String | O | redirect url |
| credit_card | JSON | O | Credit card info |
| pay_redirect_url | String | M | Pay redirect url, is a required parameter to call the JS SDK. |
| Param(credit_card) | |||
| card_reader_mode | String | O | Card reader mode. Referring to Appendix |
| card_exp_date | String | O | Card expired date |
| card_fallback | boolean | O | Whether it is fallback |
| card_number | String | O | Card number |
| card_sn | String | O | Card SN |
| card_holder_name | String | O | Cardholder name |
| icc_request | String | O | EMV ICC request data |
| icc_response | String | O | EMV ICC response data(TLV string) |
| trace_no | String | O | Trace number |
| batch_no | String | O | Batch number |
| invoice_no | String | O | Invoice number if existed |
| auth_code | String | O | Auth code |
| response_code | String | O | Response code |
| Param(3DS) | |||
| enrolled | String | O | enrolled |
Payment By Credit Card With Manual (Sale & Pre Auth)
The payment by credit card with manual command request like this:
curl --location --request POST 'https://{Domain}/gateway/v3/stores/8527/payment/transactions' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction": {
"amount": "2.0",
"currency": "HKD",
"payment_method": "credit_card",
"transaction_type": "sale", //If the transaction type is Pre Auth, this value must be "pre_auth" （Eg: "transaction_type": "pre_auth"）
"allow_over_completion":true, //If the transaction is Pre Auth, this value will controll allow pre_auth_complete amount above pre_auth amount or not.（Optional, defaults to false if not provided)
"uuid": "fde16844-5db4-4e62-b5ce-f848814b5d4b",
"credit_card": {
"card_exp_date": "2412",
"card_number": "4384375620640049",
"cvv": "880",
"card_reader_mode": "manual"
},
"location_token":"2391003628694407168",
"notify_url":"https://www.baidu.com",
"billing_address":{
"zip_code":"12345",
"address": "simple address",
"city": "city name",
"state": "address state",
"country_code": "JP"
}
}
}'
The payment by credit card with manual command response like this:
{
"transaction": {
"amount": "2.0",
"merchant_id": "987654321",
"transaction_type": "sale",
"uuid": "2d852f27-c5a4-4f64-9ab7-5c5e42493589",
"rrn": "2370549374775197696",
"acquirer_name": "fake",
//* If transaction success，
"transaction_state": "success",
//* If transaction failed，"error_desc"、"transaction_state" and "error_code" are required.
"error_desc": "Internal Error 3",
"transaction_state": "failed",
"error_code": "199997",
//* If transaction pending,wait for processing
"transaction_state": "pending",
"credit_card": {
"response_code": "00",
"card_number": "451461******4854",
"card_reader_mode": "manual",
"card_exp_date": "0925",
"auth_code": "2370549374775197699"
},
"date_time": "2025-08-12T07:03:01+00:00",
"total_amount": "2.0",
"dcc_amount": "0",
"transaction_state": "success",
"currency": "HKD",
"payment_method": "credit_card",
"brn": "2370549374607450112",
"acquirer_type": "visa"
}
}
It is used for manual input card number and card info. to complete the payment transaction.
Pre Auth Complete
The command request like this:
curl --location --request POST 'https://{domain}/gateway/v3/stores/{store_id}/payment/pre_auth_complete' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction": {
"transaction_type": "pre_auth_complete",
"origin_brn": "4369097544467220480",
"amount": "0.1",
"currency": "HKD",
"oms_transaction_id": "1",
"uuid": "d5b89650-f6a0-45b0-b136-aa674cfd31fe"
}
}'
The command response like this:
{
"transaction": {
"amount": "0.1",
"origin_rrn": "4369097544836317185",
"merchant_id": "3333",
"transaction_type": "pre_auth_complete",
"uuid": "d5b89650-f6a0-45b0-b136-aa674cfd31fe",
"consumer_identify": "4560550000014514",
"rrn": "4369099096359698433",
"acquirer_name": "fake",
"credit_card": {
"response_code": "00",
"card_number": "456055******4514",
"origin_auth_code": "4369097544836317186",
"card_reader_mode": "manual",
"card_exp_date": "3212",
"trace_num": "016335",
"batch_num": "000001",
"auth_code": "4369099096359698434"
},
"origin_brn": "4369097544467220480",
"date_time": "2025-08-01T02:29:59+00:00",
"total_amount": "0.1",
"invoice_num": "000002",
"transaction_state": "success",
"currency": "HKD",
"payment_method": "credit_card",
"terminal_id": "12345678",
"brn": "4369099096175151105",
"acquirer_type": "visa"
}
}
API: POST https://{domain}/gateway/v3/stores/{store_id}/payment/pre_auth_complete
Payment By Credit Card With 3DS
The payment by credit card with 3DS command request like this:
curl --location --request POST 'https://{Domain}/gateway/v3/stores/8527/payment/transactions' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction": {
"amount": "2.0",
"currency": "HKD",
"payment_method": "credit_card",
"transaction_type": "sale",
"uuid": "fde16844-5db4-4e62-b5ce-f848814b5d4b",
"credit_card": {
"card_exp_date": "2412",
"card_number": "4384375620640049",
"cvv": "880",
"card_reader_mode": "manual"
},
"location_token":"2391003628694407168",
"notify_url":"https://www.baidu.com",
"3ds":{
"enable":true
},
"success_url":"https://baidu.com/payment-results?status=success",
"fail_url":"https://baidu.com/payment-results?status=failed",
"billing_address":{
"zip_code":"12345",
"address": "simple address",
"city": "city name",
"state": "address state",
"country_code": "JP"
}
}
}'
The payment by credit card with 3DS command response like this:
{
"transaction": {
"amount": "2.0",
"merchant_id": "987654321",
"transaction_type": "sale",
"uuid": "fde16844-5db4-4e62-b5ce-f848814b5d4b",
"rrn": "2370549374775197696",
"acquirer_name": "fake",
//* If transaction success
"transaction_state": "success",
//* If transaction failed，"error_desc"、"transaction_state" and "error_code" are required.
"error_desc": "Internal Error 3",
"transaction_state": "failed",
"error_code": "199997",
//* If transaction pending, wait for processing
"transaction_state": "pending",
"pay_redirect_url":"https:xxxxxxxxxxxx",
"credit_card": {
"response_code": "00",
"card_number": "451461******4854",
"card_reader_mode": "manual",
"card_exp_date": "0925",
"auth_code": "2370549374775197699"
},
"date_time": "2025-08-12T07:03:01+00:00",
"total_amount": "2.0",
"dcc_amount": "0",
"transaction_state": "success",
"currency": "HKD",
"payment_method": "credit_card",
"brn": "2370549374607450112",
"acquirer_type": "visa"
}
}
It's used for 3DS payment.
3DS Data Flow
Payment By Credit Card Token
The command request like this:
curl --location --request POST 'https://{Domain}/gateway/v3/stores/8527/payment/transactions' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction": {
"amount": "2.0",
"credit_card_token": {
"token":"a61aab03-8c78-415b-97f7-8b338fce5af5"
},
"currency": "HKD",
"payment_method": "credit_card_token",
"transaction_type": "sale",
"uuid": "4e242071-d0d9-4f77-bb4e-7450b73936a2"
}
}'
The payment by credit card with manual command response like this:
{
"transaction":{
"uuid":"4e242071-d0d9-4f77-bb4e-7450b73936a2",
"brn":"2307924901681446912",
"total_amount":"2",
"amount":"2",
"currency":"HKD",
"dcc_amount":"0",
"transaction_type":"sale",
"payment_method":"credit_card_token",
"transaction_state":"success",
"date_time":"2025-08-12T07:03:01+00:00",
"merchant_id":"987654321",
"rrn":"2307926358497427457",
"acquirer_type":"mastercard",
"credit_card":{
"card_reader_mode":"credit_card_token",
"card_exp_date":"3010",
"card_fallback":false,
"card_number":"2223520000010014",
"card_holder_name":"abc",
"auth_code":"2307926358497427458",
"response_code":"00"
}
}
}
Integration Guide
Bind Credit Card, please refer to ##Bind Credit Card.
Payment with credit card token
Payment By QR code
The request command of merchant present QR code is like this:
curl --location --request POST 'https://{Domain}/gateway/v3/stores/8527/payment/transactions' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction": {
"uuid": "7ea751b4-3fd5-4b5b-8d76-7b4a7a6ebd29",
"currency": "HKD",
"transaction_type": "sale",
"amount": "0.10",
///It is used merchant present QR code of Octopus .
"payment_method": "octopus_business",
"octopus_business": {
"merchant_presented_qr_code": {
}
}
///It is used merchant present QR code of Alipay
"payment_method": "alipay",
"alipay": {
"merchant_presented_qr_code": {
}
}
}
}'
The response command like this:
{
"transaction":{
"uuid":"7ea751b4-3fd5-4b5b-8d76-7b4a7a6ebd29",
"brn":"2489479077614850049",
"total_amount":"0.1",
"amount":"0.1",
"currency":"HKD",
"transaction_type":"sale",
//It is used merchant present QR code of Octopus .
"payment_method":"octopus_business",
"transaction_state":"pending",
"merchant_id":"54513D80A95",
"octopus_business":{
"merchant_presented_qr_code":{
"payinfo":"octopus://qrpayment?token=OEM060254071931111392540261109774904120B" // Used this field to display the QR code
}
}
///It is used merchant present QR code of Alipay
"payment_method":"alipay",
"transaction_state":"pending",
"alipay":{
"merchant_presented_qr_code":{
"payinfo":"https://qr.alipay.com/xax077074quskcu7crke3068"
}
}
}
}
The request command of consumer present QR code is like this:
curl --location --request POST 'https://{Domain}/gateway/v3/stores/8527/payment/transactions' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction": {
"amount": "100.00",
"currency": "HKD",
"payment_method": "consumer_presented_qr_code",
"consumer_presented_qr_code": {
"code_type": "qrcode",
"content": "280000000000000000"
},
"currency": "HKD",
"transaction_type": "sale",
"uuid": "6de8757b-03c5-4c23-8d9d-83a46bf8bb9e"
}
}'
The command response is like this:
{
"transaction": {
"amount": "100",
"merchant_id": "3333",
"transaction_type": "sale",
"uuid": "6de8757b-03c5-4c23-8d9d-83a46bf8bb9e",
"rrn": "2387628088319016961",
"date_time": "2025-08-12T07:03:01+00:00",
"total_amount": "100",
//* If transaction success
"transaction_state": "success",
//* If transaction failed，"error_desc"、"transaction_state" and "error_code" are required.
"error_desc": "Internal Error 3",
"transaction_state": "failed",
"error_code": "199997",
//* If transaction pending, wait for processing
"transaction_state": "pending",
"currency": "HKD",
"payment_method": "consumer_presented_qr_code",
"brn": "2387628088151250944",
"acquirer_type": "alipay" //* The types of QR codes
}
}
It is used for Payment by merchant or consumer present QR codes. WeChat pay, Alipay, UnionPay QR-Code , Octopus App are supported so far.
Parameters Description
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| transaction_type | String | M | Transaction type(“sale“). Referring to Appendix |
| payment_method | String | M | "consumer_presented_qr_code": Payment by consumer present QR code "alipay": Payment by Alipay wallet. "wechat_pay":Payment By WechatPay wallet. |
| consumer_present_qr_code | JSON | It's required for payment by consumer present QR code. | |
| code_type | String | O | Code Type. Example: “qrcode“ |
| content | String | O | QR code |
| merchant_presented_qr_code | JSON | O | It is required for payment by merchant presented QR code |
| payinfo | String | O | It is used for merchant presented QR code |
| return_url | String | O | URL to go after the wallet in web |
Payment By In App And In Web
The command request like this:
curl --location --request POST '<https://{Domain}/gateway/v3/stores/8527/payment/transactions'> \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction": {
"uuid": "f4b46344-ec59-402a-8a1c-3cb2c473bee4",
"transaction_type": "sale",
"payment_method": "alipay",// Payment method，"alipay" or "wechat"
"amount": "0.10",
"currency": "HKD",
///If used in_app of Alipay wallet.
"alipay": {
"in_app": {
"subject":"XXXXXXXXXXXXXX",
"app_env": "system=android^version=3.0.1.2",
"payment_inst": "ALIPAYHK"
}
}
///If used in_web of Alipay wallet.
"alipay": {
"in_web": {
"subject":"XXXXXXXXXXXXXX",
"return_url": "<https://dev-main.wonderpayment.io/return_url",>
"payment_inst": "ALIPAYHK" //
}
}
///If used in_app of WechatPay wallet.
"wechat_pay": {
"in_app": {
"app_id": "XXXXX"
}
}
///If used in_web of WechatPay wallet.
"wechat_pay": {
"in_web": {
}
}
///If used in_app of Octopus wallet.
"octopus_business": {
"in_app": {
}
}
///If used in_web of Octopus wallet.
"octopus_business": {
"in_web": {
"return_url":"......" //URL to go after the octopus payment
}
}
///If used in_app of FPS.
"fps": {
"in_app": {
}
}
///If used in_web of FPS.
"fps": {
"in_web": {
}
}
}
}'
The command response like this:
{
"transaction": {
"amount": "0.1",
"total_amount": "0.1",
"transaction_state": "pending",
"currency": "HKD",
"transaction_type": "sale",
"uuid": "d4bcfeff-77fd-4ec5-b931-33a3c4a9d17c",
"brn": "2374754957359343616",
//* Payment by in_web of Alipay wallet
"payment_method": "alipay",
"acquirer_type": "alipay",
"alipay": {
"in_web": {
"payinfo": XXXXXXXXXXXXXX
}
}
//* Payment by in_app of Wechatpay wallet
"payment_method": "wechat_pay",
"acquirer_type": "wechat",
"wechat_pay": {
"in_app": {
"payinfo": "{"detail":{},"prepay_id":"wx291724557359510d194ce8bc98bc860000","timeStamp":"1661765095","nonceStr":"nwDZ47EXJqmDtFPxt87YVm6yBSdX2Xfy","package":"prepay_id=wx291724557359510d154ce8bc98bc860000","signType":"RSA","paySign":"LhJ11SbZLRWdP2u4+6OotseXolDxtotsetD5MZioavLnsQiX4PaLMoWYN58dw9hIfa56NJRAWFTYNf2t38u93yIFdQpi7MRJjN4KrQLNW6Brh+AvSBR6ScaZqGsVB+c0xl7OMDRDgT/njUs1yOngkIxXHt4QOpVuySorFyzbKIVnlRAUsikXRM3CO9gl38nMDOQw0p2hA5pAPioYWw/gWHUliaWOsdo0tVVX4RrJ2tbEPv9xiOxpZo/M1VutHqNqRDzfhJci2GXbondDVLg6crG9Q4uKrQWOkxO6weleKByiNnoy+Be+UG0WXSYDdJukI5FqHDQ58Rit+ZGtJlCdBQ==","partnerid":"4668344432"}"
}
}
//* Payment by in_web of Octopus Business wallet
"payment_method": "octopus_business",
"acquirer_type": "octopus_business",
"octopus_business": {
"in_web": {
"payinfo": "https://app.octopus.com.hk/qrpayment?token=OEM060254071928212611839511121934904732F"
}
}
//* Payment by in_app of Octopus Business wallet
"payment_method": "octopus_business",
"acquirer_type": "octopus_business",
"octopus_business": {
"in_app": {
"payinfo": "octopus://qrpayment?token=OEM0602540719282126390612151705649046098"
}
}
//* Payment by in_app of FPS
"payment_method": "fps",
"acquirer_type": "fps",
"fps": {
"in_web": {
"payinfo": "XXXXXXX"
}
}
//* Payment by in_web of FPS
"payment_method": "fps",
"acquirer_type": "fps",
"fps": {
"in_web": {
"payinfo": "XXXXXXXXX"
}
}
}
}
Online payment by Alipay, Wechat wallet or Octopus Wallet . This chapter contains 2 different modes, which are in-app and in-web.
in-app means the application call the wallet to complete payment. The precondition is the device shall install the acquirer application. For example: Call Alipay wallet.
in-webmeans the web client call the wallet to complete payment.
POST <https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions>
Parameters Description
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| in_app | JSON | O | In-app request |
| in_web | JSON | O | In-web request |
| Parameter(in-app) | |||
| payment_inst | String | O | Alipay institution. “ALIPAYHK“ or “ALIPAYCN“ |
| app_id | String | O | Your WechatPay APP ID |
| open_id | String | O | WeChat open ID |
| app_env | String | O | App environment |
| subject | String | O | Product details, not mandatory, max 256 bytes, only use for alipay(in-app and in-web). |
| Parameter(in-web) | |||
| return_url | String | O | URL to go after the Alipay payment |
| payment_inst | String | O | Alipay institution. “ALIPAYHK“ or “ALIPAYCN“ |
| Response Parameters | Type | Usage | Description |
| Parameter | |||
| in_app | JSON | O | Alipay in-app acquirer response |
| in_web | JSON | O | Alipay in-web acquirer response |
| payinfo | String | O | It is used for call wallet. |
Payment By WeChat Official Account
The command request like this:
curl --location --request POST '<https://{Domain}/gateway/v3/stores/8527/payment/transactions'> \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction": {
"uuid": "f4b46344-ec59-402a-8a1c-3cb2c473bee4",
"transaction_type": "sale",
"payment_method": "wechat_pay",
"amount": "0.10",
"currency": "HKD",
"wechat_pay": {
"official_account": {
"code": "xxxxxxxxxxxx"
}
}
}
}
'
The command response like this:
{
"transaction":{
"uuid":"f4b46344-ec59-402a-8a1c-3cb2c473bee4",
"brn":"3183621624289052672",
"total_amount":"0.1",
"amount":"0.1",
"currency":"HKD",
"transaction_type":"sale",
"payment_method":"wechat_pay",
"transaction_state":"pending",
"merchant_id":"532291249",
"acquirer_name":"wechatpay",
"acquirer_type":"wechat",
"wechat_pay":{
"official_account":{ // Obtain the required parameters for initiating an Official Account payment through the transaction API, and then use the front-end JS method provided by WeChat Pay to trigger the Official Account payment.
"time_stamp":"1683355440",
"nonce_str":"kRJ4HwkSJhVIHP0rMn04IMhTYIuObDLw",
"package":"prepay_id=wx06144400241307545acf70c254a1ea0000",
"sign_type":"RSA",
"pay_sign":"nVU9/juwnSYmR7UvG8LpYWh88oJNgEQ93mbbg+pIaZ1WR6Ud0DPFIdpCWd0X8ZuP7njIEKunOR4pHF69qwP+8RCRXOARWVClAfi76KTkGS+pA7R4Qqt5lOshMWrjy4grDlBqXRqmsyVaGxHCtjwAEApDcv0UZ40CHPNIWtZU/T2nfw6BbPpMHCdNCCDjfqk9xEPryeujvPNqmGFlhX42e+e08hogc76u0w7xLbA/D7ubtIodzyl4WnFZZEAQ8QM2cSNCau4zEPuOzVUrNc74O0bo0H+AgoDu9mi63aO10nflN0ZvD663+mTF0OncXMcgHvb7zD5F1tSxGH13Q8xXhA=="
}
}
}
}
Integration Guide
1.The front-end application guide the user to enter the authorization page to approve authorization and get code. （Please Noted：Only need to get the code）Refer to the documentation of Wechat Pay: 网页授权|微信开放文档
2.Call the payment API to make a transaction with code, the api response the parameters necessary to call the official account payment.
POST https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions
3.The front-end application uses the JS method provided by Wechat Pay to call up the official account payment. Refer to the documentation of Wechat Pay: 微信支付-开发者文档
4.Query Transaction status also can by BRN or UUID through the Query API.
Parameters Description
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| official_account | M | Wechat Official Acoount is request | |
| code | String | M | When accessing a third-party web page in the wechat client, the front-end application needs to guide the user to enter the authorization page to approve authorization and get code |
| time_stamp | String | M | The front-end JS method provided by wechat payment adjusts the necessary parameters of the official account payment. Refer to the documentation of Wechat Pay |
| nonce_str | String | M | The front-end JS method provided by wechat payment adjusts the necessary parameters of the official account payment. Refer to the documentation of Wechat Pay |
| package | String | M | The front-end JS method provided by wechat payment adjusts the necessary parameters of the official account payment. Refer to the documentation of Wechat Pay |
| sign_type | String | M | The front-end JS method provided by wechat payment adjusts the necessary parameters of the official account payment. Refer to the documentation of Wechat Pay |
Payment With Exchange Rate
The command request like this:
curl --location --request POST 'https://{Domain}/gateway/v3/stores/8527/payment/transactions' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction": {
"amount": "650",
"currency": "HKD",
"credit_card": { //This field is required if payment with credit card
"card_exp_date": "2412",
"card_number": "4427808001112223337",
"cvv": "880",
"card_reader_mode": "manual"
},
"cryptocurrency": { // This field is required if payment with the crypto currency.
"merchant_presented_qr_code":{
}
},
"payment_method": "credit_card",
"dcc_currency": "USD", // If it's crypto currency, for example: "dcc_currency":"BTC"
"dcc_rate": "0.133",
"dcc_amount": "86.45",
"transaction_type": "sale",
"uuid": "87ba1f15-6341-4453-a6df-d431229c44da"
}
}
'
The command response like this:
{
"transaction": {
"amount": "650",
"merchant_id": "010601994000005",
"transaction_type": "sale",
"uuid": "87ba1f15-6341-4453-a6df-d431229c44da",
"rrn": "210809001259",
"credit_card": {
"response_code": "00",
"card_number": "442780*********3337",
"extra": {
"cup_trace_no": "001259",
"cup_rrn": ""
},
"card_reader_mode": "manual",
"card_exp_date": "2412",
"trace_num": "001259",
"batch_num": "000019",
"auth_code": "036434"
},
"date_time": "2022-04-18T17:46:16+08:00",
"total_amount": "650",
"dcc_amount": "0",
"transaction_state": "success",
"currency": "HKD",
"payment_method": "credit_card",
"terminal_id": "81720400",
"brn": "2628626961194305536",
"acquirer_type": "visa"
}
}
It's used for payment with exchange rate.
POST <https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions>
Data Flow
Parameters Description
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| dcc_currency | String | M | Exchange Currency or crypto currency |
| dcc_rate | String | M | Exchange rate |
| dcc_amount | String | M | Exchange Amount |
| credit_card | JSON | This field is mandatory for credit card transaction | |
| cryptocurrency | JSON | This field is mandatory for crypto currency |
Payment with Google Pay
The command request like this:
curl --location 'https://{Domain}/gateway/v3/payment/transactions' \
--header 'content-type: application/json;charset=UTF-8' \
--header 'x-client-secret: K3dPAOMAAADRr2ogr8E9pDLz1gnukQyFeTnfpYy1eChtguZqkrc-2Ry8qYNOH_tYnllckZ34R8414YrASyLA_D8fVWRx78Mt1U7ADAupvMpr3pyfs96yywX5aAhEbqXr7HoqQdV5YA' \
--data '{
"transaction": {
"amount": "0.2",
"currency": "HKD",
"transaction_type": "sale",
"payment_method": "google_pay",
"uuid": "3b6ce3f9-15e3-4c75-b49f-141528a4fdbe",
"google_pay": {
"tag": "12345678901234567890",
"token": {
"apiVersion": 2,
"apiVersionMinor": 0,
"paymentMethodData": {
"description": "Mastercard •••• 0089",
"info": {
"assuranceDetails": {
"accountVerified": true,
"cardHolderAuthenticated": false
},
"cardDetails": "0089",
"cardNetwork": "MASTERCARD"
},
"tokenizationData": {
"token": "{\"signature\":\"MEQCIE3W5XNWphlRfig7Z6vo0V6p+8GCMtTVJjD3X6rB8no8AiAEki/w6cjbXqQfyp9e2QtI5tNICPxCJpJkrFaVg5CdbQ\\u003d\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEv3RjcMrO8a/VfAWXq8K3uOo6d4jbkWMGFVXOTwFvuk58sfMXy2L6Dg4awpjA8/JsNhZ98zFKvIYzqVS+DtxXIw\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1699670395909\\\"}\",\"signatures\":[\"MEUCIQDLP9KtLg+6cXFJbuqeR7s3PEd1GTHtZFypm7FJ4egoTwIgFZheJOybkAlKjXaBmkP1SbHJ1ohFK3dizxc0fdLnr1I\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"zyKqBuNV3JgZn8qfOJ5y7mff+H3kQFIq8BAGHQmSF7SQZjeTUi88fr7i26bOvonrVtV/U/MKaYgWX1LOxI8AXg+0HDjZh3RIFjhrUV/co6CbP/vB6lmIgg62qZX28sdjO+CbtxuNh3BadY3p6rJ0nM8a0/dTOWBvRfrBZL/dSR4k7hJ+IUQK7eOwroTrF3o+8PNsotbYb1Oi+ki3egfmgZl8GirGACPkZJ3HWTnEPN4pW1rCEzqxQm3/9OKFiwsK65ASccqvWI1BJdGhyAAJQTG2Ihe8MgoC/wDRbgHjrKg1IEkZG6yZdK0WVGQSYCyZdcDJVMFILq9v4YQp+zmEGptjhulgWxdCfMiXoa884/sWEHrPbQXMxCvsHcDIb7suAGvaM4FUYzSfRNR+oXvWi3MGLUX4Ped/xC2A8jdAcpijZlmP03AuQfcuf/o\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BLgvkkUw6qNRiG7lFJ875g1uE3FIvX6yO4EaIlxIH0R+zFqo5TSjDtSfSpYDgjhQ8R/e/hCTYajpjSasVx6Iu0A\\\\u003d\\\",\\\"tag\\\":\\\"bdr/Z3QBwzJMNuatD3gSDfPik//mvbsk4wHdJAJY5G0\\\\u003d\\\"}\"}",
"type": "DIRECT"
},
"type": "CARD"
}
}
}
}
}'
The command response like this:
{
"transaction":{
"date_time":"2023-11-07T07:32:19+00:00",
"uuid":"dc2d0c34-33aa-41e0-8d24-941e844afccd",
"brn":"3451834970182524929",
"total_amount":"0.2",
"amount":"0.2",
"currency":"HKD",
"transaction_type":"sale",
"payment_method":"google_pay",
"transaction_state":"success",
"merchant_id":"777777666666",
"terminal_id":"12345678",
"rrn":"331127840777",
"acquirer_type":"mastercard",
"credit_card":{
"card_reader_mode":"google_pay",
"card_exp_date":"2512",
"card_number":"555555******4444",
"trace_num":"001188",
"batch_num":"000001",
"auth_code":"467555",
"response_code":"00"
},
}
}
The store’s config must include Google Pay. Make sure to use a browser that supports Google Pay, and if you are not logged in, it will automatically redirect you to log in.
In this part, we just talk about API in system(frontend and backend), for further details about Google Pay guides, please visit: Google Pay Guide
Google Pay Flow
Parameters Description
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| token | JSON | google return card details,api version,token |
Payment Transactions
This API is use for make payment transactions
API: POST https://{Domain}/gateway/payment/transactions
Payment By Payment Token
The command request like this:
curl --location --request POST 'https://{Domain}/gateway/v3/stores/8527/payment/transactions' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--header 'Content-Type: application/json' \
--data-raw '{
"transaction": {
"uuid": "28a9365d-13a7-479e-b0a7-69824c335f86",
"transaction_type": "sale",
"payment_method": "payment_token",
"amount": "2.00",
"currency": "HKD",
"payment_token": "5bae4bb3-0714-438f-b7d7-327d67e998cc"
}
}'
The command response like this:
{
"transaction": {
"date_time": "2024-03-29T06:54:53+00:00",
"uuid": "ec078cec-5510-45c9-97ff-ecc73909e97c",
"brn": "3659085542525521921",
"total_amount": "2",
"amount": "2",
"currency": "HKD",
"transaction_type": "sale",
"payment_method": "payment_token",
"transaction_state": "success",
"merchant_id": "3333",
"rrn": "c4a707e5-3f3f-4064-9660-1b1dbd470bb3",
"acquirer_type": "visa",
"credit_card": {
"card_reader_mode": "credit_card_token",
"card_exp_date": "3312",
"card_number": "424242******4242",
"auth_code": "f85d6a99-2ed2-4dec-9ffd-fb5e451c83ae",
"response_code": "00"
}
}
}
Integration Guide
Bind Payment, please refer to Bind Payment.
Payment with payment token
This API is use for make payment transactions
API: POST https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions
Payment By Octopus
The command request like this:
curl --location --request POST '<https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions> \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction":{
"amount":"0.4",
"currency":"HKD",
"payment_method":"octopus",
"sn":"PAX-A930-1170013867",
"tips_amount":"0.00",
"transaction_type":"sale",
"uuid":"c6e1f77b-a307-4ceb-8299-4a970f1d64fd"
//If used in_app of octopus,
"octopus":{
"in_app":{
}
}
//If used in_web of octopus,
"octopus":{
"in_web":{
"return_url":"https://{Domain}/js/v1/iframe/success.html"
}
}
//If used merchant_presented_qr_code of octopus,
"octopus":{
"merchant_presented_qr_code":{
}
}
}
}'
The command response like this:
{
"transaction": {
"uuid": "87493cca-ba4d-43d2-bda3-5e5606ff30ca",
"brn": "3658915394762074113",
"sn": "PAX-A930-1170013867",
"total_amount": "0.1",
"amount": "0.1",
"currency": "HKD",
"transaction_type": "sale",
"payment_method": "octopus",
"transaction_state": "pending",
"acquirer_gateway_id": "196800",
"merchant_id": "196801",
"acquirer_name": "octopus",
"acquirer_type": "octopus",
"billing_address": {},
//Payment by in_web of Octopus,
"octopus": {
"in_web": {
"payinfo": "https://web-test.online.octopus.com.hk/oos/payment/?token=uh3ne63"
},
"token": "uh3ne63",
"landing_url": "https://web-test.online.octopus.com.hk/oos/payment/?token=uh3ne63",
"octopus_uri": "octopus://payment?token=uh3ne63"
}
//Payment by in_app of Octopus,
"octopus": {
"in_app": {
"payinfo": "octopus://payment?token=u1u1tja"
},
"token": "u1u1tja",
"landing_url": "https://web-test.online.octopus.com.hk/oos/payment/?token=u1u1tja",
"octopus_uri": "octopus://payment?token=u1u1tja"
}
//Payment by merchant_presented_qr_code of Octopus,
"octopus": {
"merchant_presented_qr_code": {
"payinfo": "octopus://payment?token=ttnx84n"
},
"token": "ttnx84n",
"landing_url": "https://web-test.online.octopus.com.hk/oos/payment/?token=ttnx84n",
"octopus_uri": "octopus://payment?token=ttnx84n"
}
}
}
Transactions via 'in app', 'in web' and 'merchant presented qr code'.
This API is use for make payment transactions
API:POST https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions
Payment By Samsung Pay
The command request like this:
curl --location --request POST '<https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions> \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction": {
"amount": "0.2",
"currency": "HKD",
"transaction_type": "sale",
"payment_method": "samsung_pay",
"uuid": "484c598d-6bff-4212-bbf8-4758639bb881",
"samsung_pay": {
"tag": "740371407f134c888cf186",
"token": {
"method": "3DS",
"recurring_payment": false,
"card_brand": "AX",
"card_last4digits": "2009",
"3DS": {
"type": "S",
"version": "100",
"data": "eyJhbGciOiJSU0ExXzUiLCJraWQiOiJRN3Y2OTJwcHl5SkxqR2RxbWJZN2FJeDd2eUp0MTlHZWtnaW9HS2JydExjPSIsInR5cCI6IkpPU0UiLCJjaGFubmVsU2VjdXJpdHlDb250ZXh0IjoiUlNBX1BLSSIsImVuYyI6IkExMjhHQ00ifQ.arVKZdGaHBeLYrPJJH6Lcm8V2g5hj4upDEbPbOc_bOC6jnCQxZPXZQTb_CEqGG-BYLPT6UuM_4jBDc1fV89w1nhH5xwLp3w-HmrgDvzk4q_ANiJaG5KNNabjkek4gY3m9iVnVqT8JLNJONzo0Eb2SSKtFb1BhWBJBkhb92fgZKdR27L_Oq5C8m0E3KfrVcFSu3LYyjmroR6eBkq_YCgY34sD3KKd78ua8fNLe0Gcf_PAKc4eMKqCh4nQqTI1dmMlpvs_4UrhL5UmvwFyXCaPo0WAU-x-eNEM4Gt10hryu1fTE5pL13ir_-bsqoNuf-gJIxhLkZobV93ce2L-6oWtnA.e7TloH1KifuATq_i.Mc8SpRwIxP2B7OAJZ6CUf3G4Do6XC3fd8_TZO01FYk_zauenz3WDu7W8stIENyZF_TJS024eg0DEVXjB4Ts61VfftCpZOnvIMCn6Hmy5CwhiFerrd7ywIIPwaJbFmNxg1Rto5zF2gwGiI0YQmhMPCoKv9BhiV9FozwYHeeE8CA2DHdB8gKLSfRCxyYHWTBxNElWjnnSXwH8OTkVw4tYtN5fHPsjQGiIWmb-szQGwYKLPBeTHDA.gHPyrt6ozY04l7I92CUB3g"
}
}
}
}
}'
The command response like this:
{
"transaction": {
"amount": "0.2",
"merchant_id": "123456789012",
"transaction_type": "sale",
"uuid": "484c598d-6bff-4212-bbf8-4758639bb881",
"rrn": "7826ae4d-9b13-4794-8dd1-ad4762088d2c",
"acquirer_name": "fake3ds",
"credit_card": {
"response_code": "00",
"card_number": "370382*****4652",
"card_reader_mode": "samsung_pay",
"card_exp_date": "1130",
"auth_code": "a80c6acf-9349-4aad-ab72-3cdf6390c2d5"
},
"date_time": "2024-06-17T07:15:24+00:00",
"total_amount": "0.2",
"transaction_state": "success",
"currency": "HKD",
"payment_method": "samsung_pay",
"brn": "3775070310609461248",
"acquirer_type": "amex"
}
}
The store’s config must include Samsung Pay. You can log in or use a QR code to make transactions.
Samsung Pay Flow
Parameter Description
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| token | JSON | O | transaction details from Samsung Pay |
| tag | String | O | service id confined in Samsuang developer website |
This API is use for make payment transactions
API:POST https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions
Payment By Pay Me
The command request like this:
### consumer_presented_qr_code
POST https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions
Content-Type: application/json
X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t
{
"transaction": {
"amount": "3000",
"currency": "HKD",
"payment_method": "consumer_presented_qr_code",
"consumer_presented_qr_code": {
"code_type": "qrcode",
"content": "801234567890123456"
},
"transaction_type": "sale",
"uuid": "f4b46344-ec59-402a-8a1c-3cb2c473bee4"
}
}
### merchant_presented_qr_code
POST https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions
Content-Type: application/json
X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t
{
"transaction": {
"amount": "2.81",
"currency": "HKD",
"payment_method": "payme",
"payme": {
"merchant_presented_qr_code": {}
},
"transaction_type": "sale",
"uuid": "f4b46344-ec59-402a-8a1c-3cb2c473bee4"
}
}
### In_Web
POST https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions
Content-Type: application/json
X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t
{
"transaction": {
"amount": "2.81",
"currency": "HKD",
"payment_method": "payme",
"payme": {
"in_web": {
"return_url": "http://example.com/return_url"
}
},
"transaction_type": "sale",
"uuid": "f4b46344-ec59-402a-8a1c-3cb2c473bee4"
}
}
### In_App
POST https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions
Content-Type: application/json
X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t
{
"transaction": {
"amount": "2.81",
"currency": "HKD",
"payment_method": "payme",
"payme": {
"in_app": {
"return_url": "http://example.com/return_url"
}
},
"transaction_type": "sale",
"uuid": "f4b46344-ec59-402a-8a1c-3cb2c473bee4"
}
}
The command response like this:
### consumer_presented_qr_code
{
"transaction": {
"date_time": "2024-07-18T03:14:36+00:00",
"uuid": "89c4885b-68c2-45ca-9a09-d16f23a95e2d",
"brn": "3819763994181251073",
"total_amount": "3000",
"amount": "3000",
"currency": "HKD",
"transaction_type": "sale",
"payment_method": "consumer_presented_qr_code",
"transaction_state": "success",
"merchant_id": "3b3d8614-1062-4d99-b308-1941554e0531",
"rrn": "ad8e203b-f6b9-45c6-8dc7-63f3d6ffbd39",
"acquirer_name": "payme",
"acquirer_type": "payme"
}
}
### merchant_presented_qr_code
{
"transaction": {
"uuid": "35706d44-a169-4efc-92fa-c2f2038c1c21",
"brn": "3819764028725540865",
"total_amount": "2.81",
"amount": "2.81",
"currency": "HKD",
"transaction_type": "sale",
"payment_method": "payme",
"transaction_state": "pending",
"merchant_id": "3b3d8614-1062-4d99-b308-1941554e0531",
"rrn": "c02a1ab5-869f-4af5-a075-49ae4b162b09",
"acquirer_name": "payme",
"acquirer_type": "payme",
"payme": {
"merchant_presented_qr_code": {
"payinfo": "https://mobsandboxprod.paymebiz.hsbc.com.hk/bdfb3804-682a-4ffd-b160-a170ddd9d6db"
}
}
}
}
### In_Web
{
"transaction": {
"uuid": "a2dbdd11-db26-45be-92b4-bb807bbec0fa",
"brn": "3819764038691205120",
"sn": "xxx",
"total_amount": "2.81",
"amount": "2.81",
"currency": "HKD",
"transaction_type": "sale",
"payment_method": "payme",
"transaction_state": "pending",
"merchant_id": "3b3d8614-1062-4d99-b308-1941554e0531",
"rrn": "80482840-a61d-44f3-bf1f-73d282d4adb5",
"acquirer_name": "payme",
"acquirer_type": "payme",
"payme": {
"in_web": {
"payinfo": "https://mobsandboxprod.paymebiz.hsbc.com.hk/249fcbb9-c686-4f0a-b3ca-22be78440faf?appSuccessCallback=http://example.com/return_url"
}
}
}
}
### In_App
{
"transaction": {
"uuid": "523db7c3-01df-458c-96b9-dbff3e1ce9ec",
"brn": "3819764052230418433",
"total_amount": "2.81",
"amount": "2.81",
"currency": "HKD",
"transaction_type": "sale",
"payment_method": "payme",
"transaction_state": "pending",
"merchant_id": "3b3d8614-1062-4d99-b308-1941554e0531",
"rrn": "4328baa0-66df-4680-94a8-5efa480eb61b",
"acquirer_name": "payme",
"acquirer_type": "payme",
"payme": {
"in_app": {
"payinfo": "https://mobsandboxprod.paymebiz.hsbc.com.hk/1582f4d2-d924-4d83-bbdf-ec7b4bdd6817?appSuccessCallback=http://example.com/return_url"
}
}
}
}
A payment method from HSBC, same as Alipay and WeChat pay, support in_app, in_web,consumer_presented_qr_code, and merchant_presented_qr_code four entry types.
Pay Me has UI design requirement please refer to:Pay Me Parameters Description
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| transaction_type | String | M | Transaction type(“sale“). Referring to Appendix |
| payment_method | String | M | "payme":Payment via payme. |
| consumer_present_qr_code | JSON | It's required for payment by consumer present QR code. | |
| code_type | String | O | Code Type. Example: “qrcode“ |
| content | String | O | QR code |
| merchant_presented_qr_code | JSON | O | It is required for payment by merchant presented QR code |
| payinfo | String | O | It is used for merchant presented QR code |
| return_url | String | O | URL to go after the wallet in web |
API:POST https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions
Payment By JkoPay
The command request like this:
POST https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions
Content-Type: application/json
X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t
{
"transaction": {
"amount": "1",
"currency": "HKD",
"payment_method": "jkopay",
"tips_amount": "0.00",
"transaction_type": "sale",
"jkopay": {
"in_web":{
"return_url":"https://www.baidu.com"
}
},
"oms_transaction_id":"1"
}
}
The command response like this:
{
"transaction": {
"uuid": "53d7b628-a801-4f2f-9c55-0bc156b91ac5",
"brn": "3891114659738040320",
"total_amount": "1",
"amount": "1",
"currency": "HKD",
"transaction_type": "sale",
"payment_method": "jkopay",
"transaction_state": "pending",
"acquirer_name": "jkopay",
"acquirer_type": "jkopay",
"jkopay": {
"in_web": {
"payinfo": "https://uat-onlinepay.jkopay.app/web/paymentRouter?j=OL%231%3AENT%23Y0hFcWFBRDFNWVpBbCtRMElVcStydz09%3AS%233aaaa1f8-585b-11ef-94d5-005056b665e9%3AA%231.00%3ACUR%23HKD%3ASRC%23REDIRECT_MWEB%3AUNRDM%230%3AFX%231%3ATA%235%3ATCUR%23TWD%3AFXR%234.98%3AUR%231%3AD%23D&s=1018dd52e3715d56077cb54601ecc67753a3e0520eed70281a0403bbae1835a1"
}
}
}
}
Only support consumer presented QR code (offline) and in_web (online).
Parameters Description
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| oms_transaction_id | String | O | Get from OMS system |
API:POST https://{Domain}/gateway/v3/stores/{store_id}/payment/transactions
***Parameters Description***
| Request Parameters | Type | Usage | Description |
| --- | --- | --- | --- |
| crypto_coin | String | O | Details about crypto currecy,payment address,amount and Qrcode |
| crypto_currency | String | O | Type of crypto currencies |
| paymentAddresses | String | O | crypto wallet address use for transfer crypto currencies |
| network | String | O | crypto network like eth, tron, solana and etc.. |
| symbol | String | O | Which currecy do you use like eth, usdt, usdc and etc... |
| address | String | O | target wallet address |
This API is use for make payment transactions
API: `POST https://{Domain}/gateway/payment/transactions`
>The command request like this:
```SHELL
curl --location --request POST 'https://{Domain}/gateway/v3/stores/8527/payment/transactions' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction":{
"amount":"30",
"currency":"HKD",
"payment_method":"crypto_coin",
"sn":"PAX-A930-1170013867",
"tips_amount":"0.00",
"transaction_type":"sale",
"uuid":"{{$guid}}"
}
}
```
>The command response like this:
```shell
{
"transaction": {
"uuid": "994214b6-1637-4920-a7ce-20a5dc91488d",
"brn": "3612981193621917696",
"sn": "PAX-A930-1170013867",
"total_amount": "30",
"amount": "30",
"currency": "HKD",
"transaction_type": "sale",
"payment_method": "crypto_coin",
"transaction_state": "pending",
"rrn": "1f4daa73-5a66-40d0-bd49-aa904cf23171",
"acquirer_name": "cyphalab",
"acquirer_type": "crypto_coin",
"billing_address": {},
"crypto_coin": {
"total_amount": "0",
"qr": "https://stage-pay.cyphalab.com/1f4daa73-5a66-40d0-bd49-aa904cf23171",
"cyphalab": {
"paymentAddresses": [
{
"network": "ETH",
"symbol": "ETH",
"address": "0x074CC2D32Ce5fEd0FA6024554489b51e8a9D8707",
"amount": "0.001229"
},
{
"network": "ETH",
"symbol": "USDT",
"address": "0x074CC2D32Ce5fEd0FA6024554489b51e8a9D8707",
"amount": "3.76"
},
{
"network": "TRON",
"symbol": "TRX",
"address": "TMKfGN1rBQQQsWfRm7pfemU6yRUVujQQ1a",
"amount": "27.251"
},
{
"network": "TRON",
"symbol": "USDT",
"address": "TMKfGN1rBQQQsWfRm7pfemU6yRUVujQQ1a",
"amount": "3.76"
}
]
}
}
}
}
```
Other API
Refund
The command request like this:
curl --location --request POST 'https://{Domain}/gateway/v3/stores/8527/payment/refund'
--header 'Content-Type: application/json'
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t'
--data-raw '{
"transaction": {
"amount": "20.00",
"currency": "HKD",
"origin_brn": "2387798364612726784",
"transaction_type": "refund",
"uuid": "186edff9-c889-4aa7-9490-7bbf48f1ab73"
}
}'
The command response like this:
{
"transaction": {
"amount": "20",
"merchant_id": "3333",
"transaction_type": "refund",
"uuid": "186edff9-c889-4aa7-9490-7bbf48f1ab73",
"rrn": "2387799043922198529",
"acquirer_name": "fake",
"credit_card": {
"response_code": "00",
"card_number": "222352******0014",
"card_reader_mode": "swipe",
"card_exp_date": "2512",
"auth_code": "2387799043922198530"
},
"date_time": "2025-08-12T07:03:01+00:00",
"total_amount": "20",
"dcc_amount": "0",
"transaction_state": "success",
"currency": "HKD",
"payment_method": "credit_card",
"brn": "2387799043771207680",
"acquirer_type": "mastercard"
}
}
The API is used for refund transactions. Full and partial amount refund are supported.
POST https://{Domain}/gateway/v3/stores/{store_id}/payment/refund
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| uuid | String | M | Transaction UUID |
| transaction_type | String | M | Transaction type(“refund“). Referring to Appendix |
| payment_method | String | O | Payment method. Referring to Appendix |
| amount | String | M | Refund amount |
| currency | String | M | Currency |
| origin_brn | String | M | Original transaction BRN |
Void
The command request like this:
curl --location --request POST '<https://{Domain}/gateway/v3/stores/{store_id}/payment/void'> \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction": {
"currency": "HKD",
"origin_brn": "2387657838852839424", //*Original transaction BRN
"transaction_type": "void",
"uuid": "dd32d92d-9c55-4b79-9437-66e23f3bbe5f" //*And new transaction should be requested with a new UUID.
}
}
The command response like this:
{
"transaction": {
"amount": "20",
"merchant_id": "3333",
"transaction_type": "void",
"uuid": "dd32d92d-9c55-4b79-9437-66e23f3bbe5f",
"rrn": "2387658514018336769",
"acquirer_name": "fake",
"credit_card": {
"response_code": "00",
"card_number": "222352******0014",
"card_reader_mode": "swipe",
"card_exp_date": "2512",
"auth_code": "2387658514018336770"
},
"date_time": "2025-08-12T07:03:01+00:00",
"total_amount": "20",
"transaction_state": "success",
"currency": "HKD",
"payment_method": "credit_card",
"brn": "2387658513867347969",
"acquirer_type": "mastercard"
}
}
The API is used for void transactions.
Note
- Only unsettled transactions can be voided.
- It is a full amount void transaction.
POST https://{domain}/gateway/v3/stores/{store_id}/payment/void
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| uuid | String | M | Transaction UUID. It is the unique identifier of the transaction. And new transaction should be requested with a new UUID. |
| transaction_type | String | M | Transaction type ("void"). |
| payment_method | String | M | Payment method like Visa/Mastercard/JCB |
| currency | String | M | Currency |
| origin_brn | String | M | Original transaction BRN |
Query Transaction Status
Query A Transaction Status by BRN or UUID
The Query a transaction by UUID command request like this:
curl --location -g --request GET 'https://{Domain}/gateway/v3/stores/8527/query/transactions/8ec9cd52-a1ab-41cb-be85-89b933fff6f3' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw ''
The Query a transaction by UUID command response like this:
{
"transaction": {
"uuid": "8ec9cd52-a1ab-41cb-be85-89b933fff6f3",
"brn": "2351687111989594113",
"total_amount": "2.1",
"amount": "2.1",
"currency": "HKD",
"dcc_amount": "0",
"transaction_type": "sale",
"payment_method": "credit_card_token",
"transaction_state": "success",
"date_time": "2025-08-12T07:03:01+00:00",
"merchant_id": "987654321",
"rrn": "2351689413873893376",
"acquirer_type": "visa",
"credit_card": {
"card_reader_mode": "credit_card_token",
"card_exp_date": "202412",
"card_number": "438437******0049",
"card_holder_name": "ABCDEFGHTID",
"auth_code": "2351689413873893379",
"response_code": "00"
},
"pay_redirect_url": "https://stg-payment.gateway.co/gateway/v3/payment/precreate/link?X-CLIENT-SECRET=HxEAHKIAAAFQRl2-5avfQbSMbpc_ZGKtBCCgVWXSiX3o_6qSqGsho15Xow1FuLgqddLq2ra9u5pWfpAu6X6wQ8yXZWUpf_I-nvH7CG5fDMHQHW1Lac1w500cNOP9EwSCyIg4Se4",
}
}
The Query a transaction by BRN command request like this:
curl --location -g --request GET 'https://{Domain}/gateway/v3/stores/8527/query/transactions/2351687111989594113' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw ''
The Query a transaction by BRN command response like this:
{
"transaction": {
"uuid": "8ec9cd52-a1ab-41cb-be85-89b933fff6f3",
"brn": "2351687111989594113",
"total_amount": "2.1",
"amount": "2.1",
"currency": "HKD",
"dcc_amount": "0",
"transaction_type": "sale",
"payment_method": "credit_card_token",
"transaction_state": "success",
"date_time": "2025-08-12T07:03:01+00:00",
"merchant_id": "987654321",
"rrn": "2351689413873893376",
"acquirer_type": "visa",
"credit_card": {
"card_reader_mode": "credit_card_token",
"card_exp_date": "202412",
"card_number": "438437******0049",
"card_holder_name": "ABCDEFGHTID",
"auth_code": "2351689413873893379",
"response_code": "00"
},
"pay_redirect_url": "https://stg-payment.gateway.co/gateway/v3/payment/precreate/link?X-CLIENT-SECRET=HxEAHKIAAAFQRl2-5avfQbSMbpc_ZGKtBCCgVWXSiX3o_6qSqGsho15Xow1FuLgqddLq2ra9u5pWfpAu6X6wQ8yXZWUpf_I-nvH7CG5fDMHQHW1Lac1w500cNOP9EwSCyIg4Se4",
}
}
The API is used for querying transaction status.
GET https://{Domain}/gateway/v3/stores/{store_id}/query/transactions/{parameter} //* The parameter is brn or uuid of the original pre-create transaction
Parameter Description
| Response Parameters | Type | Usage | Description |
|---|---|---|---|
| uuid | String | M | Transaction UUID, the original pre-create |
| transaction_type | String | M | Transaction type. |
| payment_method | String | M | Payment method. Referring to Appendix |
| amount | String | M | Transaction amount |
| currency | String | M | Transaction currency. Example: “HKD“ |
| transaction_state | String | M | Transaction state. Referring to Appendix Field value - Description success - Transaction success pending - Pending，waiting for processing failed - Transaction failed |
| error_code | String | O | Error code. If transaction state is “failed“ |
| error_desc | String | O | Error description. If transaction state is “failed“ |
| date_time | String | M | Transaction date & time. |
| merchant_id | String | O | Merchant ID |
| terminal_id | String | O | Terminal ID |
| rrn | String | O | Refund Reference number |
| brn | String | M | Bill reference number |
| acquirer_name | String | O | Acquirer name, Bank name. |
| acquirer_type | String | O | Acquirer type. |
| is_voided | boolean | O | Whether it is voided |
| voided_time | String | O | Voided at |
| refunded_times | int | O | Refund time |
| refunded_amount | String | O | Total refunded amount |
| Param(credit_card) | JSON | O | Credit card info |
| card_reader_mode | String | O | Card reader mode. Referring to Appendix |
| card_exp_date | String | O | Card expired date |
| card_fallback | boolean | O | Whether it is fallback |
| card_number | String | O | Card number |
| card_holder_name | String | O | Cardholder name |
| trace_no | String | O | Trace number |
| batch_no | String | O | Batch number |
| invoice_no | String | O | Invoice number if existed |
| auth_code | String | O | Auth code |
| response_code | String | O | Response code |
Bind Credit Card
The command to bind the card is like this:
curl --location --request POST 'https://{Domain}/gateway/v3/payment/credit_card_bind' \
--header 'Content-Type: application/json' \
--data-raw '{
"transaction": {
"uuid": "243a977f-6481-444f-bff3-650d57d76415",
"credit_card": {
"card_exp_date": "3010",
"card_number": "2223520043560014",
"card_holder_name": "abc",
"cvv": "123"
},
"billing_address":{
"zip_code":"12345",
"address": "simple address",
"city": "city name",
"state": "address state",
"country_code": "JP"
}
}
}'
The command response like this:
{
"transaction":{
"uuid":"243a977f-6481-444f-bff3-650d57d76415",
"transaction_state":"success",
"date_time":"2025-08-12T07:03:01+00:00",
"credit_card_token":{
"token":"13a17d49-a62a-46d1-8996-8ffaa07cef29",
"card_number":"2223520000010014",
"acquirer_type":"mastercard"
}
}
}
The Api is used for Bind credit card to get the credit card token. The credit card token can be used to payment.
POST https://{Domain}/gateway/v3/payment/credit_card_bind
Parameters Description
| Parameters | Type | Usage | Description |
|---|---|---|---|
| uuid | String | M | Transaction UUID |
| Param(credit_card) | M | ||
| card_exp_date | String | M | Card expired date |
| card_number | String | M | Card number |
| card_holder_name | String | M | Cardholder name |
| cvv | String | M | CVV |
| Param(billing_address) | M | AVS | |
| zip_code | String | M | Zip Code |
| address | String | M | Address |
| city | String | M | City |
| state | String | M | Address State |
| country_code | String | M | Country Code, ALPHA-2 |
| credit_card_token | JSON | M | The information of credit card token |
| token | String | M | Token after credit card binding |
Exchange Rate
Query foreign exchange rates command request like this:
curl --location --request POST 'https://{Domain}/gateway/v3/stores/8527/query/dccrate' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction": {
"amount": "509",
"credit_card": {
"card_exp_date": "2412",
"card_number": "4111111111111111",
"cvv": "880",
"card_reader_mode": "manual"
},
"currency": "HKD",
"payment_method": "credit_card",
"transaction_type": "rate_lookup",
"uuid": "39be5ef1-b9b1-4601-983e-745619427698"
}
}'
The command response like this:
{
"transaction": {
"amount": "509",
"dcc_rate": [
{
"dcc_currency": "USD",
"dcc_rate": "0.133",
"dcc_amount": "67.69"
}
],
"merchant_id": "010601994000005",
"transaction_type": "rate_lookup",
"uuid": "39be5ef1-b9b1-4601-983e-745619427698",
"credit_card": {
"response_code": "YY",
"card_number": "411111******1111",
"card_reader_mode": "manual",
"card_exp_date": "2412",
"trace_num": "001215",
"batch_num": "000019"
},
"date_time": "2025-08-12T07:03:01+00:00",
"total_amount": "509",
"transaction_state": "success",
"currency": "HKD",
"payment_method": "credit_card",
"terminal_id": "81720400",
"brn": "2628444511520442368",
"acquirer_type": "visa"
}
}
Query crypto coin command request like this:
curl --location --request POST 'https://{Domain}/gateway/v3/stores/8527/query/dccrate' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"transaction": {
"amount": "89",
"cryptocurrency": {
},
"currency": "USD",
"payment_method": "cryptocurrency",
"transaction_type": "rate_lookup",
"uuid": "9eb6617c-807a-4ac7-9f93-a7518773e82a"
}
}'
The command response like this:
{
"transaction": {
"amount": "89",
"dcc_rate": [
{
"dcc_currency": "BTC",
"dcc_rate": "0.000000000001",
"dcc_amount": "0.000000000001"
},
{
"dcc_currency": "ETH",
"dcc_rate": "0.000000000001",
"dcc_amount": "0.000000000001"
}
],
"merchant_id": "BTC_000000001",
"transaction_type": "rate_lookup",
"uuid": "9eb6617c-807a-4ac7-9f93-a7518773e82a",
"date_time": "2025-08-12T07:03:01+00:00",
"total_amount": "89",
"transaction_state": "success",
"currency": "USD",
"payment_method": "cryptocurrency",
"brn": "2628536646806554625",
"acquirer_type": "cryptocurrency"
}
}
The Exchange Rate API allows merchant to retrieve foreign exchange rates or crypto coin.
Query Exchange Rate Data Flow
POST <https://{Domain}/gateway/v3/stores/{store_id}/query/dccrate>
Parameters Description
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| uuid | String | M | Transaction UUID |
| transaction_type | String | M | Transaction type(“rate_lookup“). Referring to Appendix |
| payment_method | String | M | Payment method.“credit_card”,"cryptocurrency" |
| amount | String | M | Transaction Amount |
| currency | String | M | Currency |
| Response Parameters | |||
| dcc_rate | JSON | M | The information of rate |
| dcc_currency | String | M | DCC Currency |
| dcc_rate | String | M | DCC Rate |
| dcc_amount | String | M | DCC Amount |
Integration Octopus Business
1.Enable the Octopus Payment Method Of The Store（Only once)
If the merchant want to enable the payment method of Octopus Business, they must apply to create an Octopus Partner Link by merchant App (eg: Wonder APP, Softpos app.It should be a To B app) call the Octopus Business App first. After the Octopus Partner link is create successfully, upload the information response by Octopus Business app to the Gateway API, Gateway will auto enable the store‘s Octopus Business payment method. Create Octopus Partner Linkage and upload the merchant information to Payment Gateway.
Data Flow
The Request command of Step 1 is like this:
curl --location --request POST 'https://{Domain}/gateway/v3/stores/8527/payment/request_linkage' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
"return_url":"paymentapp://result?" //*Client App‘s uri，Octopus merchant business app will returns to this uri after request linkage.
}'
The response is like this:
{
"transaction":{
"transaction_state":"success",
"octopus_business":{
"payinfo":"bizoctopus://requestlinkage?token=OEM06025448125741222816654904C073" //Used this parameter to call the Octopus Merchant APP
}
}
}
Parameters Description
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| return_url | String | M | URL to go after the Octopus app |
| status | String | M | The status is returned by the Octopus Business App |
| mertAccRef | String | M | The status is returned by the Octopus Business App |
| payinfo | String | M | It is used for call octopus app |
| terminal_id | String | M | The devices sn |
Step 1: Request Linkage
The API is used Request for Octopus Partner Linkage: POST <https://{Domain}/gateway/v3/stores/{store_id}/payment/request_linkage>
Step 2:Call Octopus business APP By Open URI（with "payinfo"）to create Partner linkage
- If used the payment SDK, Please refer to "The demo Call the Octopus Business APP of step 2"
The JAVA demo Call the Octopus Business APP of step 2
public enum LinkageStatus {
LINKAGE_ACCEPT,
LINKAGE_EXISTS,
LINKAGE_REJECT;
}
public void onOctopusLinkage() {
payment.linkageOctopus(STORE_ID, new AidlLinkageListener.Stub() {
String[] approvedArr = {LinkageStatus.LINKAGE_EXISTS.name(), LinkageStatus.LINKAGE_ACCEPT.name()};
@Override
public void onCommuSuccess(String status) throws RemoteException {
Log.e(TAG, "onCommuSuccess: " + status);
if(Arrays.asList(approvedArr).contains(status)){ // arr.asList.contains
Log.i(TAG, "onCommuSuccess: setIsLinkaged(true)");
}
}
@Override
public void onFail(int errorCode, String errDesc) throws RemoteException {
Log.w("testapi", "onFail->" + errorCode + ", errDesc->" + errDesc);
}
@Override
public void onCancel() throws RemoteException {
Log.w("testapi", "onCancel");
}
});
}
Step 3: Upload the data returned by Octopus Business App to Server
The Request command of Step 3 is like this:
curl --location --request POST 'https://{Domain}/gateway/v3/stores/8527/redirect/request_linkage' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw '{
{
"isOffline":false,
"mertAccRef":"54513D80A15", //The value is returned by the Octopus Business App
"status":"LINKAGE_ACCEPT", //The status is returned by the Octopus Business App
"terminal_id":"9aaf509fcf79281c"
}
'
The command response like this:
{
"transaction":{
"transaction_state":"success",
"octopus_business":{
"payinfo":"bizoctopus://requestlinkage?token=OEM06025448125741222816654904C073"
}
}
}
API: POST <https://{Domain}/gateway/v3/stores/{store_id}/redirect/request_linkage >
2. Payment with Octopus APP
It supports 2 payment entry type: Merchant Pesented QR code and in web. Refund is not supported.
Payment by Octopus App please refer to “Payment By QR code” and "Payment By In web " on the part of Sale Directly
Get the APPID for the payment by Wechat offical account
The Request command is like this:
curl --location --request GET 'https://{Domain}/gateway/v3/stores/8527/payment/official_account_appid' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw ' '
The command response like this:
{
"transaction": {
"transaction_state": "success",
"app_id": "wx72596b4dc********8"
}
}
This API is used by get the appid for the payment by wechat offical account
API: GET <https://{Domain}/gateway/v3/stores/{store_id}/payment/official_account_appid>
List transactions and fees
The Request command is like this:
curl --location --request GET 'https://{Domain}/gateway/v3/query/merchant_account/list_transaction_and_fee?limit=5' \
--header 'Content-Type: application/json' \
--header 'X-USER-ACCESS-TOKEN: t6er5fevg75ea91oe3rmmytndzsda4t' \
--data-raw ' '
The command response like this:
{
"transaction": {
"data": [
{
"id": "3622915728996319233",
"created_at": "2024-03-04T08:03:25.082Z",
"updated_at": "2024-03-04T08:06:09.535Z",
"deleted_at": null,
"store_id": "537343",
"partner_uuid": "ae459fbc-3876-4427-8e22-36045504e93d",
"detail_id": "3622915728996319233",
"dcc_amount": "1.25",
"dcc_currency": "USDT",
"installment": 0,
"total_amount": "10",
"amount": "10",
"currency": "HKD",
"acquirer_id": "350",
"merchant_account_id": "19221",
"terminal_id": "0",
"request_payment_method": "crypto_coin",
"payment_method": "crypto_coin",
"payment_entry_type": "",
"payment_type": "sale",
"customer_payment_method": "",
"org_txn_id": "0",
"acquirer_rrn": "38a37d08-b7ce-4508-bc62-5ab6bf31f349",
"acquirer_auth_code": "3622915728996319233",
"acquirer_recon_id": "",
"oms_transaction_id": 75856146,
"order_num": "202403040306092420187712",
"complete_at": "2024-03-04T08:06:03Z",
"acquirer_txn_date_time": null,
"status": "success",
"error_code": "",
"void_at": null,
"refund_times": 0,
"refund_at": null,
"adjust_times": 0,
"adjust_at": null,
"capture_at": null,
"is_offline": false,
"gateway_settlement_at": null,
"acquirer_settlement_at": null,
"payment_from_name": "",
"payment_from_ip": "42.3.16.133",
"payment_from_device_id": "PAX-A930-1170013867",
"gateway_batch_num": 410,
"acquirer_batch_num": 0,
"mid_batch_num": 0,
"tid_batch_num": 0,
"tid_trace_num": 0,
"invoice_num": 0,
"consumer_identify": "",
"cashier_id": "",
"gateway_clearance_at": "2024-03-07T00:00:00Z",
"acquirer_clearance_at": "2024-03-06T00:00:00Z",
"day_end_id": "0",
"increment_pre_auth_times": 0,
"increment_pre_auth_at": null,
"p_business_id": "62fe527c-4f52-45f5-a01f-b25d910433c6",
"hold_status ": "",
"tipsAmount": "0",
"orgTxnDayEndId": "0",
"txn_id": "3622915728996319233",
"rule_id": "0",
"fee_amount": "0",
"fee_currency": "HKD",
"fee_amount_before_exchange": "0",
"report_id": "0",
"tran_amount": "10",
"tran_currency": "HKD",
"rate": "0",
"order_reference_number": "000572"
},
{
"id": "3618664273124798464",
"created_at": "2024-03-01T09:39:58.565Z",
"updated_at": "2024-03-01T09:44:56.018Z",
"deleted_at": null,
"store_id": "537343",
"partner_uuid": "76ef845c-456c-407c-8122-f02fc3ec9e12",
"detail_id": "3618664273124798464",
"dcc_amount": "1.25",
"dcc_currency": "USDT",
"installment": 0,
"total_amount": "10",
"amount": "10",
"currency": "HKD",
"acquirer_id": "350",
"merchant_account_id": "19221",
"terminal_id": "0",
"request_payment_method": "crypto_coin",
"payment_method": "crypto_coin",
"payment_entry_type": "",
"payment_type": "sale",
"customer_payment_method": "",
"org_txn_id": "0",
"acquirer_rrn": "8b93060d-e44a-4aba-9121-c59aaac6c65f",
"acquirer_auth_code": "3618664273124798464",
"acquirer_recon_id": "",
"oms_transaction_id": 75855469,
"order_num": "202403010444554077813642",
"complete_at": "2024-03-01T09:44:47Z",
"acquirer_txn_date_time": null,
"status": "success",
"error_code": "",
"void_at": null,
"refund_times": 0,
"refund_at": null,
"adjust_times": 0,
"adjust_at": null,
"capture_at": null,
"is_offline": false,
"gateway_settlement_at": null,
"acquirer_settlement_at": null,
"payment_from_name": "",
"payment_from_ip": "42.118.76.169",
"payment_from_device_id": "PAX-A930-1170013867",
"gateway_batch_num": 410,
"acquirer_batch_num": 0,
"mid_batch_num": 0,
"tid_batch_num": 0,
"tid_trace_num": 0,
"invoice_num": 0,
"consumer_identify": "",
"cashier_id": "",
"gateway_clearance_at": "2024-03-06T00:00:00Z",
"acquirer_clearance_at": "2024-03-05T00:00:00Z",
"day_end_id": "3618384048604332033",
"increment_pre_auth_times": 0,
"increment_pre_auth_at": null,
"p_business_id": "62fe527c-4f52-45f5-a01f-b25d910433c6",
"hold_status ": "",
"tipsAmount": "0",
"orgTxnDayEndId": "0",
"txn_id": "3618664273124798464",
"rule_id": "0",
"fee_amount": "0",
"fee_currency": "HKD",
"fee_amount_before_exchange": "0",
"report_id": "0",
"tran_amount": "10",
"tran_currency": "HKD",
"rate": "0",
"order_reference_number": "000569"
},
{
"id": "3615638973239533569",
"created_at": "2024-02-28T07:34:36.64Z",
"updated_at": "2024-02-28T07:36:39.94Z",
"deleted_at": null,
"store_id": "537343",
"partner_uuid": "948e1bd3-6d53-4f0d-94e6-4fb9d2659a98",
"detail_id": "3615638973239533569",
"dcc_amount": "1.25",
"dcc_currency": "USDT",
"installment": 0,
"total_amount": "10",
"amount": "10",
"currency": "HKD",
"acquirer_id": "350",
"merchant_account_id": "19221",
"terminal_id": "0",
"request_payment_method": "crypto_coin",
"payment_method": "crypto_coin",
"payment_entry_type": "",
"payment_type": "sale",
"customer_payment_method": "",
"org_txn_id": "0",
"acquirer_rrn": "bd5bc95f-0ca3-4cb9-be18-a4179d714e33",
"acquirer_auth_code": "3615638973239533569",
"acquirer_recon_id": "",
"oms_transaction_id": 1,
"order_num": "",
"complete_at": "2024-02-28T07:36:37Z",
"acquirer_txn_date_time": null,
"status": "success",
"error_code": "",
"void_at": null,
"refund_times": 0,
"refund_at": null,
"adjust_times": 0,
"adjust_at": null,
"capture_at": null,
"is_offline": false,
"gateway_settlement_at": null,
"acquirer_settlement_at": null,
"payment_from_name": "",
"payment_from_ip": "42.118.76.169",
"payment_from_device_id": "PAX-A930-1170013867",
"gateway_batch_num": 410,
"acquirer_batch_num": 0,
"mid_batch_num": 0,
"tid_batch_num": 0,
"tid_trace_num": 0,
"invoice_num": 0,
"consumer_identify": "",
"cashier_id": "",
"gateway_clearance_at": "2024-03-04T00:00:00Z",
"acquirer_clearance_at": "2024-03-01T00:00:00Z",
"day_end_id": "3615484986750152704",
"increment_pre_auth_times": 0,
"increment_pre_auth_at": null,
"p_business_id": "62fe527c-4f52-45f5-a01f-b25d910433c6",
"hold_status ": "",
"tipsAmount": "0",
"orgTxnDayEndId": "0",
"txn_id": "3615638973239533569",
"rule_id": "0",
"fee_amount": "0",
"fee_currency": "HKD",
"fee_amount_before_exchange": "0",
"report_id": "0",
"tran_amount": "10",
"tran_currency": "HKD",
"rate": "0",
"order_reference_number": ""
},
{
"id": "3613989250581663745",
"created_at": "2024-02-27T04:15:45.528Z",
"updated_at": "2024-02-27T04:21:48.388Z",
"deleted_at": null,
"store_id": "537343",
"partner_uuid": "2a16adb0-f369-4fa3-8894-8e584b305033",
"detail_id": "3613989250581663745",
"dcc_amount": "3.76",
"dcc_currency": "USDT",
"installment": 0,
"total_amount": "30",
"amount": "30",
"currency": "HKD",
"acquirer_id": "350",
"merchant_account_id": "19221",
"terminal_id": "0",
"request_payment_method": "crypto_coin",
"payment_method": "crypto_coin",
"payment_entry_type": "",
"payment_type": "sale",
"customer_payment_method": "",
"org_txn_id": "0",
"acquirer_rrn": "b73ae65e-d645-4fbb-9dc9-3a15c895190b",
"acquirer_auth_code": "3613989250581663745",
"acquirer_recon_id": "",
"oms_transaction_id": 1,
"order_num": "",
"complete_at": "2024-02-27T04:21:03Z",
"acquirer_txn_date_time": null,
"status": "success",
"error_code": "",
"void_at": null,
"refund_times": 0,
"refund_at": null,
"adjust_times": 0,
"adjust_at": null,
"capture_at": null,
"is_offline": false,
"gateway_settlement_at": null,
"acquirer_settlement_at": null,
"payment_from_name": "",
"payment_from_ip": "42.118.76.169",
"payment_from_device_id": "PAX-A930-1170013867",
"gateway_batch_num": 410,
"acquirer_batch_num": 0,
"mid_batch_num": 0,
"tid_batch_num": 0,
"tid_trace_num": 0,
"invoice_num": 0,
"consumer_identify": "",
"cashier_id": "",
"gateway_clearance_at": "2024-03-01T00:00:00Z",
"acquirer_clearance_at": "2024-02-29T00:00:00Z",
"day_end_id": "3612585821950986241",
"increment_pre_auth_times": 0,
"increment_pre_auth_at": null,
"p_business_id": "62fe527c-4f52-45f5-a01f-b25d910433c6",
"hold_status ": "",
"tipsAmount": "0",
"orgTxnDayEndId": "0",
"txn_id": "3613989250581663745",
"rule_id": "0",
"fee_amount": "0",
"fee_currency": "HKD",
"fee_amount_before_exchange": "0",
"report_id": "0",
"tran_amount": "30",
"tran_currency": "HKD",
"rate": "0",
"order_reference_number": ""
},
{
"id": "3612794875642122240",
"created_at": "2024-02-26T08:29:15.234Z",
"updated_at": "2024-02-26T11:00:00.191Z",
"deleted_at": null,
"store_id": "537343",
"partner_uuid": "9dc4de20-6632-4fba-93f0-e54e4b12cded",
"detail_id": "3612794875642122240",
"dcc_amount": "0",
"dcc_currency": "",
"installment": 0,
"total_amount": "5.11",
"amount": "5.11",
"currency": "HKD",
"acquirer_id": "313",
"merchant_account_id": "835",
"terminal_id": "0",
"request_payment_method": "credit_card",
"payment_method": "visa",
"payment_entry_type": "manual",
"payment_type": "sale",
"customer_payment_method": "",
"org_txn_id": "0",
"acquirer_rrn": "3612794876246097921",
"acquirer_auth_code": "3612794876246097922",
"acquirer_recon_id": "3612794876246097921",
"oms_transaction_id": 75854303,
"order_num": "202402260329157099595825",
"complete_at": "2024-02-26T08:29:15.249Z",
"acquirer_txn_date_time": "2025-08-12T07:03:01+00:00",
"status": "success",
"error_code": "",
"void_at": null,
"refund_times": 0,
"refund_at": null,
"adjust_times": 0,
"adjust_at": null,
"capture_at": "2024-02-26T11:00:00.187Z",
"is_offline": false,
"gateway_settlement_at": null,
"acquirer_settlement_at": "2024-02-26T11:00:00.187Z",
"payment_from_name": "",
"payment_from_ip": "42.116.144.50",
"payment_from_device_id": "PAX-A930-1170013867",
"gateway_batch_num": 410,
"acquirer_batch_num": 1,
"mid_batch_num": 0,
"tid_batch_num": 0,
"tid_trace_num": 0,
"invoice_num": 0,
"consumer_identify": "4012010000010026",
"cashier_id": "",
"gateway_clearance_at": "2024-02-29T00:00:00Z",
"acquirer_clearance_at": "2024-02-27T00:00:00Z",
"day_end_id": "3612585821950986241",
"increment_pre_auth_times": 0,
"increment_pre_auth_at": null,
"p_business_id": "62fe527c-4f52-45f5-a01f-b25d910433c6",
"hold_status ": "",
"tipsAmount": "0",
"orgTxnDayEndId": "0",
"txn_id": "3612794875642122240",
"rule_id": "3511294005923031040",
"fee_amount": "0.18",
"fee_currency": "HKD",
"fee_amount_before_exchange": "0.18",
"report_id": "0",
"tran_amount": "5.11",
"tran_currency": "HKD",
"rate": "1",
"order_reference_number": "000283"
}
],
"transaction_state": "success"
}
}
This api is used to get last few transactions and fees.
API:GET <https://{Domain}/gateway/v3/query/merchant_account/list_transaction_and_fee?limit=5>
Bind Payment Token
The Api is used for getting payment token. The payment token can be used to payment.
POST https://{{domain}}/gateway/v3/stores/{store_id}/payment/payment_token_bind
The command request like this:
curl --location --request POST '{{domain}}/gateway/v3/stores/268/payment/payment_token_bind' \
--header 'X-PLATFORM-ID: PLATFORM-ID' \
--header 'X-PLATFORM-KEY: PLATFORM-KEY' \
--header 'Content-Type: application/json' \
--data '{
"transaction": {
"uuid": "1b731290-a753-45ec-a304-a9d765319da0",
"payment_method": "credit_card",
"success_url": "https://example.com/success_url",
"fail_url": "https://example.com/fail_url",
"merchant_initiated_transactions_type": "unscheduled_cof",
"3ds": {
"enable": true
},
"credit_card": {
"card_reader_mode": "manual",
"card_exp_date": "1233",
"card_number": "6250947000000014",
"cvv": "123",
"credit_token_bind_expire": 1716708172 //expire time timestamp
},
"billing_address": {
"zip_code":"12345",
"address": "simple address",
"city": "city name",
"state": "address state",
"country_code": "JP"
}
}
}'
The command response like this:
{
"transaction": {
"uuid": "{{uuid}}",
"transaction_type": "sale",
"payment_method": "payment_token",
"amount": "2.00",
"currency": "HKD",
"payment_token": {
"token": "074a89a5-af56-4ca9-a946-b4ec691d27d6",
"payment_entry_type": "mit"
}
}
}
Bind Payment Token Flow
Merchant_initiated_transactions_type Description
| Parameters | Type | Usage | Description |
|---|---|---|---|
| partial_split_shipment | String | M | This is typically applied when merchants are unable to deliver all items at once. For instance, if some items purchased by consumers are temporarily out of stock, merchants may send the available items first and charge accordingly. They then wait until the remaining items are in stock before proceeding with delivery and charging. |
| delayed_charges | String | M | This is typically applied in scenarios where certain services may incur additional charges, such as car rentals, hotel reservations, and the like. Consumers pay the base fee when using the service. If additional charges arise (such as excess mileage, room cleaning fees, etc.), the merchant will initiate a post-service charge, known as a "MIT," after the service concludes. |
| no_show | String | M | In industries such as hotels, flights, restaurant reservations, medical appointments, etc., if a customer fails to use the service at the scheduled time without canceling in advance, the merchant may impose a certain "no-show fee" or "unused fee" to compensate for the losses incurred due to the customer's absence. |
| recurring_payment | String | M | Recurring payment refers to regular, periodic automatic deductions commonly seen in subscription-based services such as online streaming services (like Netflix, Spotify), gym memberships, magazine subscriptions, etc. |
| unscheduled_cof | String | M | Unscheduled COF (Card-On-File)This is typically applied in ongoing business relationships between consumers and merchants, where consumers provide and store payment card information with merchants, allowing merchants to make irregular deductions from their accounts in terms of price or time. For example, cab-hailing services deducting payments after the service ends. |
| unscheduled_cof_subsequent | String | M | This refers to subsequent transactions for Unscheduled Card-on-File (COF), meaning after the initial Unscheduled COF transaction is completed, merchants proceed with subsequent deductions without consumers needing to input card information again. |
Payment_entry_type Description
| Parameters | Type | Usage | Description |
|---|---|---|---|
| mit | String | M | merchant initial transaction |
| cit | String | M | consumer initial transaction |
Payment Token Inquiry
The command request like this:
curl --location --request '{{domain}}/gateway/v3/stores/268/query/payment_token_bind/{{uuid}}' \
--header 'X-PLATFORM-ID: PLATFORM-ID' \
--header 'X-PLATFORM-KEY: PLATFORM-KEY'
The command response like this:
{
"transaction": {
"date_time": "2024-03-21T10:02:43+00:00",
"uuid": "9eca34e9-4f32-4e21-9273-e7b391764535",
"transaction_state": "success", //or fail/pending
"token": "1bcc5c2a-e003-4b56-ba88-f70fef4d7614",
"credit_card_token": {
"card_number": "625094******0014",
"acquirer_type": "cup",
"credit_token_bind_expire": 1711620163
}
}
}
This API is used for inquiry payment token bind status.
GET https://{{domain}}/gateway/v3/stores/{store_id}/query/payment_token_bind/{{uuid}}
Transaction List Inquiry
The command request like this:
curl --location 'http://{Domain}/gateway/v3/query/merchant_account/{Store_ID}/list_transaction_and_fee?limit=50&transaction_start_time=2025-07-06%2016%3A00%3A00&transaction_end_time=2025-07-07%2016%3A00%3A00&last_id=2479332628487014400' \
--header 'X-USER-ACCESS-TOKEN: rcife0mycab2l98k02w7w277m5uwhj4' \
--header 'User-Agent: apifox/1.0.0 (https://www.apifox.cn)' \
--header 'X-PLATFORM-ID: 2862134663244156932' \
--header 'X-PLATFORM-KEY: testplatformkey123'
The command response like this:
{
"transaction": {
"data": {
"items": [
{
"id": "4257809597076692992", // transactionid
"created_at": "2025-05-16T07:53:48.559Z", // transaction created time
"updated_at": "2025-05-16T07:53:48.649Z",
"deleted_at": null,
"store_id": "539956", // store id
"partner_uuid": "8511c225-a79b-4c1d-a4a9-a83659308b94",
"detail_id": "4257809597076692992",
"dcc_amount": "0", // dcc amount
"dcc_currency": "",// dcc curency
"installment": 0,
"total_amount": "1",
"amount": "1", // transaction amount
"currency": "HKD", // transaction currency
"acquirer_id": "346",
"merchant_account_id": "19425",
"terminal_id": "0",
"request_payment_method": "payment_token",
"payment_method": "visa",
"payment_entry_type": "cit",
"payment_type": "pre_auth",
"customer_payment_method": "",
"org_txn_id": "0",
"acquirer_rrn": "ec172ae6-d852-4736-9927-ee1d184d4dc2",
"acquirer_auth_code": "3c33b670-2894-4012-b019-ee24a131085f",
"acquirer_recon_id": "ec172ae6-d852-4736-9927-ee1d184d4dc2",
"oms_transaction_id": 76125324,
"order_num": "202505161553448255547584",
"complete_at": "2025-05-16T07:53:48.567Z",
"acquirer_txn_date_time": "2025-08-12T07:03:01+00:00",
"status": "success",
"error_code": "",
"void_at": null,
"refund_times": 0,
"refund_at": null,
"adjust_times": 0,
"adjust_at": null,
"capture_at": null,
"is_offline": false,
"gateway_settlement_at": null,
"acquirer_settlement_at": null,
"payment_from_name": "",
"payment_from_ip": "222.240.44.99",
"payment_from_device_id": "6BA5DD98-E390-4341-A85C-BFB4544C9754",
"gateway_batch_num": 6533151,
"acquirer_batch_num": 1,
"mid_batch_num": 0,
"tid_batch_num": 0,
"tid_trace_num": 0,
"invoice_num": 8150,
"consumer_identify": "4242420000014242", // card number
"cashier_id": "",
"gateway_clearance_at": "2025-05-21T00:00:00Z",
"acquirer_clearance_at": "2025-05-19T00:00:00Z",
"day_end_id": "0",
"increment_pre_auth_times": 0,
"increment_pre_auth_at": null,
"p_business_id": "b3660410-c1fa-4f22-bf20-2f034ea9e2af",
"hold_status ": "",
"tipsAmount": "0", // tips amount
"orgTxnDayEndId": "0",
"txn_id": "4257809597076692992",
"rule_id": "3511294005923031119",
"fee_amount": "0.01",
"fee_currency": "HKD",
"fee_amount_before_exchange": "0.01",
"report_id": "0",
"tran_amount": "1",
"tran_currency": "HKD",
"rate": "1",
"order_reference_number": "Testing-202505160753441694",
"superior_txn_id": "0",
"transaction_category": ""
}
],
"last_id": "4333390172918908928"
},
"transaction_state": "success"
}
}
This API is used for inquiry transaction details. For this API, you can inquire about the transactions you made before, and you can customize the start time and end time to search for a specific time of the transaction, and use the limit to search for the latest few transactions. Using the Last (transaction) ID, you can search for a specific transaction. Time Zone is UTC+0
GET https://{Domain}/gateway/v3/query/merchant_account/{Store_ID}/list_transaction_and_fee?limit=50&transaction_start_time={Start Time}&transaction_end_time={End Time}&last_id={Last ID}
Parameters Description
| Parameters | Type | Usage | Description |
|---|---|---|---|
| id | String | M | Transcation ID |
| created_at | String | M | Transaction created time |
| store_id | String | M | Your store ID |
| amount | String | M | Transaction amount |
| currency | String | M | Transaction currency |
| consumer_identify | String | M | Card number |
| limit | String | M | limit the number of transactions(1-100),if above 100 will treat as 100 |
| Start Time | String | M | Transaction time range, please use UTC+0 timezone |
| End Time | String | M | Transaction time range, please use UTC+0 timezone |
| Last ID | String | M | The ID of the last record in the previous query result. For the first query, pass 0 (or omit it). For subsequent queries, pass the last_id from the previous response to continue querying from where the last query ended. |
PGP Keys
To transfer sensitive data to Wonder, you must encrypt it using our public PGP (Pretty Good Privacy) key. Refer to OpenPGP for information about how to get started with PGP keys.
Wonder recommends that token and data migrations use this encryption method.
Wonder Public GPG Key:
ID: 8C761A27BB267ECCC4E017AB8982824EA918E364
Type: ESA
Size: 4096 bits
User ID: XXXXX <XXXXX@XXX.COM>
Expires: 2034-08-09
WebHook
If the notify url is:https://www.baidu.com The WebHook command like this:
curl --location --request POST 'https://www.baidu.com' \
--header 'X-SIGNATURE: hmac_sha256(request body, secret_key) ' \
--header 'X-APP-ID: appid ' \
--data-raw '{
"transaction": {
"uuid": "8ec9cd52-a1ab-41cb-be85-89b933fff6f3",
"brn": "2351687111989594113",
"total_amount": "2.1",
"amount": "2.1",
"currency": "HKD",
"dcc_amount": "0",
"transaction_type": "sale",
"payment_method": "credit_card_token",
"transaction_state": "success",
"date_time": "2025-08-12T07:03:01+00:00",
"merchant_id": "987654321",
"rrn": "2351689413873893376",
"acquirer_type": "visa",
"credit_card": {
"card_reader_mode": "credit_card_token",
"card_exp_date": "202412",
"card_number": "438437******0049",
"card_holder_name": "ABCDEFGHTID",
"auth_code": "2351689413873893379",
"response_code": "00"
},
"pay_redirect_url": "https://stg-payment.gateway.co/gateway/v3/payment/precreate/link?X-CLIENT-SECRET=HxEAHKIAAAFQRl2-5avfQbSMbpc_ZGKtBCCgVWXSiX3o_6qSqGsho15Xow1FuLgqddLq2ra9u5pWfpAu6X6wQ8yXZWUpf_I-nvH7CG5fDMHQHW1Lac1w500cNOP9EwSCyIg4Se4",
}
}'
The WebHook command response like this:
Response Headers:
HTTP/1.1 200 OK
WebHook is a callback function. If the pre-create order has a “notity_url” parameter, Payment Gateway server will automatically return the transaction result to the notify url after the transaction is completed. When the third party received the WebHook, it needs to return a response with HTTP status code =200 OK.
- The secret_key is provided by payment process service provider when applying for merchants.
- The appid is provided by payment process service provider when applying for merchants
- X-SIGNATURE: hmac_sha256(request body, secret_key)
Parameter Description:
Refer to the parameter description of Query a transaction by BRN or UUID.
2.Payment Processor
Introduction
This document provides information about the payment processor API. To begin integration, you need to generate a CSR file (used to create the JSON Web Token) and submit it to us. We will then provide you with essential information, including your certificate and organization ID, which are required before you can start using the API.
Generate the csr file
Use the PEM format. Reference the command below:
openssl req -new -newkey rsa:4096 -nodes -keyout private_key.key -out certificate.csr
Keep your private_key.key secure and provide the certificate.csr to us
API Endpoint & Authentication
Endpoints
All requests to the Bindo API are sent via HTTP to one of our API endpoint URLs
- Sandbox API endpoint: {Please contact your payment processor for details}
- Production API Endpoint: {Please contact your payment processor for details}
HTTP Headers
The following headers are required for every API request that uses the HTTP Signature authentication method.
| Field | Type | Usage | Description |
|---|---|---|---|
| organization-id | Required | Your organization ID registered in Bindo | |
| Date | Required | The date in RFC1123 format: Thu, 18 Jul 2019 00:18:03 GMT |
|
| Content-Type | Required | application/json | |
| Host | Required | The endpoint for the transaction. | |
| Authorization | Required | Bearer :JWT Generated A JSON Web Token |
Authentication
The available authentication method is JSON Web Token(JWT). Please generate the JSON Web Token according to the steps below.
Generate A JSON Web Token
- Generate the Token Header
The header contains the following metadata
| Name | Description |
|---|---|
| alg | Algorithm used to sign the token header. |
| kid | The ID of the key used to digitally sign the JWT. |
| organization-id | Your organization ID registered in Bindo |
import base64
data = b'{"organization-id":"organization","alg":"RS256","kid":"7078633285250177041499"}'
encoded = base64.urlsafe_b64encode(data)
stripped = encoded.decode('ascii').strip('=')
print(stripped)
- Generate the Message Body
Encode the message body (payload) using URL safe Base64 encryption. At a minimum, the body should include these fields:
| Name | Description |
|---|---|
| digest | A base64 encoded SHA-256 has of the claim set |
| digestAlgorithm | Algorithm used to sign the JWT |
| iat | Time the JWT was issued. |
Follow these steps to generate the hash:
- Generate the SHA-256 hash of the JSON payload (body of the message).
- Encode the hashed string to Base64.
- Add the message body hash to the digest header fields.
- Add the hash algorithm used to the digestAlgorithm header fields.
import base64
data = b'{"digest":"eyJkaWdlc3QiOiJSQk52bzFXelo0b1JScTBXOStoa25wVDdUOElmNTM2REVNQmc5aHlxLzRvPSIsImRp2VzdEFsZ29yaXRobSI6IlNIQS0yNTYiLCJpYXQiOiIyMDI0LTA0LTA1VDE2OjI1OjE4LjI1OVoifQ","digestAlgorithm":"SHA-256","iat":1756699583}'
encode = base64.urlsafe_b64encode(data)
stripped = encode.decode('ascii').strip('=')
print(stripped)
- Generate a Token Signature
You can now build the JSON token signature. The token signature is made up of the JWT header and claim set hashes in the following format, and encrypted with the private key. [Token Header].[Claim Set] Follow these steps to generate the signature:
- Concatenate the header and claim set hash strings with a period (.) separating the hashes: [Token Header].[Claim Set].
- Generate an encoded version of the text file using your private key.
Base64 encode the signature output.
Generate a JSON Web Token
You can now build the JWT. The JWT is made up of the token header Base64 encoded hash, the payload Base64 encoded hash, and the JWT signature in the following format: [Token Header].[Payload].[Signature]
To generate the JWT, concatenate the header, payload, and signature strings with a period (.) separating the hashes: [[Token Header].[Payload].[Signature].
Example: JSON Web Token
eyJhbGciOiJSUzI1NiIsImtpZCI6IjcwNzg2MzMyODUyNTAxNzcwNDE0OTkiLCJvcmdhbml6YXRpb24taWQiOiJtZXJjaGFudC1pZCIsInR5cCI6IkpXVCJ9.eyJkaWdlc3QiOiJleUprYVdkbGMzUWlPaUpTUWs1MmJ6RlhlbG8wYjFKU2NUQlhPU3RvYTI1d1ZEZFVPRWxtTlRNMlJFVk5RbWM1YUhseEx6UnZQU0lzSW1ScDJWemRFRnNaMjl5YVhSb2JTSTZJbE5JUVMweU5UWWlMQ0pwWVhRaU9pSXlNREkwTFRBMExUQTFWREUyT2pJMU9qRTRMakkxT1ZvaWZRIiwiZGlnZXN0QWxnb3JpdGhtIjoiU0hBLTI1NiIsImlhdCI6MTc1NjY5OTcyOH0.hbb9sKHrrRVViZ4HPqSlCykyCR7D0DgsHQqKdhxTAQNqJeZR2bUNtztuitMdsNjOyjdtFwW7OFu3pWjTcij9BRSgBYimT9Y6YZ_IUU9L9gD4ryhOaaRVkAzj-qu8l8XWLDL3kxtAkaadDJmC7DIPBSBkOKwaqqEiTwlGfisCLlZn4bkoHkzrwV0r9IKy3WhMvEKCCD4hXLQDzLNHZfJG1wYHgi3A6GKlpujSWSCTrz-FwC8Qgv0hVmNUGn12pp9eqAyTIgwq1DMJzo3jQS4H_WbuqWRUV0Yz0TBehVVGriNy3AVEv8ja2YXeK-9bnuka5nheMv65U7DnFKQGJRUQ371AgLhtP5r8k6ip_ar9shKSfOIc8gbYhspD6Uha3zhya8JIwjoXuHsxi2uFMQUJKkOCCA-911PZqLKg4lcWNDjtJ0eS8x8Em1aDCEh4HKVyJP7tX5u-kYSO9LUVMCHUEvMjZRtEOyD4w6VgN_l7s_yiEf0z8OXQhTvEN2OLMc0cAeyMY2h9M32PCBbQ5kSrdsikhmJ2grJL44jiFAyLet8Jct6h38HTr5KAwisoKMIzb9IsCgkg2v9MKEdWSrPsNFi_G7rIJr6-jCLyf_lZ44cU4tRe0cI91YlAiR73kcKC85uYCKrXLQk3tv-RlA5y_Qq0fKM0AqqSnkEtdQ3pcNg
Payments API
Encrypt "credit_card" into "secure_data".
Original "credit_card" Object Structure
"credit_card": {
"cvv": "123",
"card_exp_date": "3010",
"card_fallback":false,
"card_number": "5555555555554444",
"card_reader_mode": "contact",
"card_track2": "5555555555554444D19121010000023700000",
"icc_request":"9F26087FE8B0EF60A64D9F9F2701809F101307010103A0A000010A0100000000008E2720819F37043BF58F559F360200799505808008E0009A032204079C01009F02060000000001005F2A02034482021C009F1A0203449F3303E0F8C89F34031E03009F3501229F1E0830383231343331378408A0000003330101029F090200209F4104000000019B0268009F080200205F340100500F556E696F6E506179204372656469749F420201565F28020156",
"pin": ""
},
| Param(credit_card) | Type | Usage | Description |
|---|---|---|---|
| card_reader_mode | String | M | Card reader mode manual swipe contact contactless |
| card_exp_date | String | M | Card expired date：YYMM |
| card_fallback | boolean | O | Whether it is fallback ture or false |
| card_number | String | M | Card number |
| card_track1 | String | O | Track 1 magnetic data |
| card_track2 | String | O | Track 2 magnetic data. If card_reader_mode is swipe, contact, or contactless, must include this field. |
| card_track3 | String | O | Track 3 magnetic data |
| card_holder_name | String | O | Card holder name |
| cvv | String | O | CVV |
| icc_request | String | O | EMV ICC request data. If card_reader_mode is contact or contactless, must include this field. |
| pin | String | O |
Encrypt
In the payment processor API, credit card information must be encrypted to protect card data security. Use "secure_data" instead of "credit_card" in the request payload.
To encrypt, combine the "credit_card" JSON object with a timestamp as the original data, then encrypt this combination to generate the "secure_data" JSON object.
Public Key Certificate:
Contact your payment processor to get the public key certificate files for both staging (stg) and production (prod) environments.
Follow these steps to encrypt your data and obtain secure data:
- Extract the public key from the certificate file
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwEokyU6GLUbNWiHatu64
+XgHeLyAXowRav6Ijs6IxlyjtdWF4y/VvgcPgwcLcekZlJHgmGMPcqvmKe74McS1
mLu4KTcBckrwksfnVpbk8iA/lnjn7JCUmn30Yu3ghOI7Pyg23h3As7hut9LytddZ
AxSUqq+rGCZXqvAVcogeQ1fJSk6LS2z3wCkVqrts2agrw6eoMXrDj7f6O0WVfTva
Dwui39VBYJpT7b9aYShmHSNxxhMDsOb4mGJsFnA6sKU7hh4NLuP6cL0mqQK6BkSr
icgM7MxhZqfbKIi/hghRlw8SJhO8uKrSdiSClw+OBVb0YkiCz0OYc0o4avbLVcyg
OwIDAQAB
-----END PUBLIC KEY-----
2.1 Extract the public key byte array from the PEM file
eg:hex string
30820122300d06092a864886f70d01010105000382010f003082010a0282010100c04a24c94e862d46cd5a21dab6eeb8f9780778bc805e8c116afe888ece88c65ca3b5d585e32fd5be070f83070b71e9199491e098630f72abe629eef831c4b598bbb8293701724af092c7e75696e4f2203f9678e7ec90949a7df462ede084e23b3f2836de1dc0b3b86eb7d2f2b5d759031494aaafab182657aaf01572881e4357c94a4e8b4b6cf7c02915aabb6cd9a82bc3a7a8317ac38fb7fa3b45957d3bda0f0ba2dfd541609a53edbf5a6128661d2371c61303b0e6f898626c16703ab0a53b861e0d2ee3fa70bd26a902ba0644ab89c80ceccc6166a7db2888bf860851970f122613bcb8aad2762482970f8e0556f4624882cf4398734a386af6cb55cca03b0203010001
2.2 Calculate the SHA-256 hash and encode it as Base64
eg：
"pub_key_hash" : "UJfxs5BRZQlaAtlLbS1mtKS57L0mVF01hbtbSLKRwMk="
3.Generate a random 32-byte AES key
eg：hex string:
0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
4.Generate a random 16-byte nonce. The additionalData should be null.
eg：
"nonce" : "AAAAAAAAAAAAAAAAAAAAAA=="
5.Obtain a timestamp
eg：timestamp=1738994658
6.The original data for encryption consists of the data to be encrypted combined with the timestamp
eg：
{
"credit_card" : {
"card_exp_date" : "2912",
"card_fallback" : false,
"card_number" : "3567721195148481",
"card_reader_mode" : "manual",
"is_msd_card" : false,
"pin" : ""
}
}1738994658
Note: Be careful with invisible characters. Convert the data bytes into a hexadecimal string.
eg： hex str:
7b226372656469745f63617264223a7b0a20202020202020202020202022636172645f6578705f64617465223a2232393132222c0a20202020202020202020202022636172645f66616c6c6261636b223a66616c73652c0a20202020202020202020202022636172645f6e756d626572223a2233353637373231313935313438343831222c0a20202020202020202020202022636172645f7265616465725f6d6f6465223a226d616e75616c222c0a2020202020202020202020202269735f6d73645f63617264223a66616c73652c0a2020202020202020202020202270696e223a22220a20202020202020207d7d31373338393934363538
7.Encrypt both the credit card data and timestamp using AES-GCM, then convert the encrypted result to base64：
eg: "data"=
"g9BbjUVM4056XCiSHNTsnFMjfR2U1ywji+wkEBeiG0YRfmWOlN87K74puYliTuuILZRSZE3JcHs4zjmichaQegzf7dXhcfojdzPu4J04DuXjnMq2bgz6cHN7HXk2EElCxFTCEl7jC0Nf/ZLUPrq+QY2ItuFLcUKnrixWepNVTgpHlBUAqSGGERhjrGecxgyc4IXpfE8sWCDUqdjTSPkzP55FN6HB2Z9eq1thIsgcJ9l6oW+dRKQ7+IhYxhXzEeY+GhDHw9LzCCRksSe/tQfJGiaOW+SmKEKrh/3mTznNjj1YEF76uqSXvDkXzIHmSwWvNCmA98NU+Tfq5n+VhULFi7hJg/gnX2FSng=="
8.Encrypt the AES-256 key using the public key: Use RSA-OAEP encryption and then encode with base64
eg
"enc_key"："Kvt5sWuT96rQNUM28VO4E40EvNCKV+BPa3R8YHluClyxbccn4hWJ+RTwZH6u+8n7ejZSpWSaRPzRrthDooLbkHk+p8hmQEwq333zwqX5OrtfDY7UiKci2GTYd8WaOzM08p9KE6kp2skfcwh9n6Kk/nlNIwM+4xxzwvHaHpBTETrjD7arf7q8xca9+qyKDtbWsvLei/lVk5Gf4RKN6+LvWi415h30KPytL/+z4ntKDoZX2ZzmwnPNatAyIX+Z2gQUwbBiUzhkw1XrxEfpSye7whwlOcp/yZPFCIQHs2Mb+gx8P3ZiRqinUNJmf52RIVSY4H9aUQr9FH8x+I/KAnjqsA=="
9.Construct the final encrypted secure_data object
"secure_data":{
"data" : "g9BbjUVM4056XCiSHNTsnFMjfR2U1ywji+wkEBeiG0YRfmWOlN87K74puYliTuuILZRSZE3JcHs4zjmichaQegzf7dXhcfojdzPu4J04DuXjnMq2bgz6cHN7HXk2EElCxFTCEl7jC0Nf/ZLUPrq+QY2ItuFLcUKnrixWepNVTgpHlBUAqSGGERhjrGecxgyc4IXpfE8sWCDUqdjTSPkzP55FN6HB2Z9eq1thIsgcJ9l6oW+dRKQ7+IhYxhXzEeY+GhDHw9LzCCRksSe/tQfJGiaOW+SmKEKrh/3mTznNjj1YEF76uqSXvDkXzIHmSwWvNCmA98NU+Tfq5n+VhULFi7hJg/gnX2FSng==",
"enc_key" : "Kvt5sWuT96rQNUM28VO4E40EvNCKV+BPa3R8YHluClyxbccn4hWJ+RTwZH6u+8n7ejZSpWSaRPzRrthDooLbkHk+p8hmQEwq333zwqX5OrtfDY7UiKci2GTYd8WaOzM08p9KE6kp2skfcwh9n6Kk/nlNIwM+4xxzwvHaHpBTETrjD7arf7q8xca9+qyKDtbWsvLei/lVk5Gf4RKN6+LvWi415h30KPytL/+z4ntKDoZX2ZzmwnPNatAyIX+Z2gQUwbBiUzhkw1XrxEfpSye7whwlOcp/yZPFCIQHs2Mb+gx8P3ZiRqinUNJmf52RIVSY4H9aUQr9FH8x+I/KAnjqsA==",
"pub_key_hash" : "UJfxs5BRZQlaAtlLbS1mtKS57L0mVF01hbtbSLKRwMk=",
"timestamp":"1738994658",
"nonce":"AAAAAAAAAAAAAAAAAAAAAA=="
}
10.The complete payload format for the request is as follows:
curl --location --request POST 'https://{Domain}/gateway/v1/payment/transactions' \
--header 'Content-Type: application/json' \
--header 'organization-id: xxxxxxxxxxxxxx' \
--header 'authorization: xxxxxxx'\
--data-raw '{
"transaction": {
"amount": "2.0",
"currency": "HKD",
"payment_method": "credit_card",
"transaction_type": "sale", //If it is purchase, the value must be “sale”; If it is pre auth, the value must be "pre_auth"）
"uuid": "fde16844-5db4-4e62-b5ce-f848814b5d4b",
"secure_data": {
"data":"g9BbjUVM4056XCiSHNTsnFMjfR2U1ywji+wkEBeiG0YRfmWOlN87K74puYliTuuILZRSZE3JcHs4zjmichaQegzf7dXhcfojdzPu4J04DuXjnMq2bgz6cHN7HXk2EElCxFTCEl7jC0Nf/ZLUPrq+QY2ItuFLcUKnrixWepNVTgpHlBUAqSGGERhjrGecxgyc4IXpfE8sWCDUqdjTSPkzP55FN6HB2Z9eq1thIsgcJ9l6oW+dRKQ7+IhYxhXzEeY+GhDHw9LzCCRksSe/tQfJGiaOW+SmKEKrh/3mTznNjj1YEF76uqSXvDkXzIHmSwWvNCmA98NU+Tfq5n+VhULFi7hJg/gnX2FSng==",
"enc_key": "Kvt5sWuT96rQNUM28VO4E40EvNCKV+BPa3R8YHluClyxbccn4hWJ+RTwZH6u+8n7ejZSpWSaRPzRrthDooLbkHk+p8hmQEwq333zwqX5OrtfDY7UiKci2GTYd8WaOzM08p9KE6kp2skfcwh9n6Kk/nlNIwM+4xxzwvHaHpBTETrjD7arf7q8xca9+qyKDtbWsvLei/lVk5Gf4RKN6+LvWi415h30KPytL/+z4ntKDoZX2ZzmwnPNatAyIX+Z2gQUwbBiUzhkw1XrxEfpSye7whwlOcp/yZPFCIQHs2Mb+gx8P3ZiRqinUNJmf52RIVSY4H9aUQr9FH8x+I/KAnjqsA==",
"pub_key_hash": "UJfxs5BRZQlaAtlLbS1mtKS57L0mVF01hbtbSLKRwMk="
"timestamp":"1738994658",
"nonce":"AAAAAAAAAAAAAAAAAAAAAA=="
},
"notify_url":"https://www.baidu.com", //Webhook notify url
"merchant_id":"999999", //Mandatory field,
"client_transaction_id":"xxxxxxx", //Optional fields，Customer's transaction ID
"notify_url":"https://www.baidu.com",
"billing_address":{
"zip_code":"12345",
"address": "simple address",
"city": "city name",
"state": "address state",
"country_code": "JP"
}
}
}'
Payment API Request Payload Demo
Parameter Description
| Request Parameters | Type | Usage | Description |
|---|---|---|---|
| uuid | String | M | Transaction UUID. It is the unique identifier of the transaction. And new transaction should be requested with a new UUID. |
| transaction_type | String | M | Transaction type(“sale“, “void”, ”refund”). |
| payment_method | String | M | Payment method(“credit_card“). Referring to Appendix |
| amount | String | M | Transaction amount |
| currency | String | M | Transaction currency. Example: “SGD“ |
Param(3ds) |
|||
| enable | boolean | O | Enable 3ds.true or false |
| success_url | String | O | It is required for 3DS transaction. After inputting the message OTP code, redirect to the validate result page |
| fail_url | String | O | It is required for 3DS transaction. After inputting the message OTP code, redirect the validation result page |
| secure_data | JSON | M | Encrypted card information data. Encrypt "credit_card" into "secure_data". |
| notify_url | String | O | WebHook notify url. The “notify_url” is required if using WebHook. |
| pay_redirect_url | String | M | Pay redirect url. |
| merchant_id | String | M | The unique ID assigned to the merchant by the organization. |
Param(payment_token) |
|||
| token | String | M | Credit Card Token It's required for bind credit card and recurring payment |
| payment_entry_type | String | M | Recurring transaction type: cit or mit. It’s required for recurring transaction, |
| Param(billing_address) | O | AVS | |
| String | O | ||
| zip_code | String | O | Zip Code |
| address | String | O | Address |
| city | String | O | City |
| state | String | O | Address State |
| country_code | String | O | Country Code |
| phone | String | O | Phone Number |
| String | O |
Purchase and Pre Auth（Non-3DS）
The command request like this:
curl --location --request POST 'https://{Domain}/gateway/v1/payment/transactions' \
--header 'Content-Type: application/json' \
--header 'organization-id: xxxxxxxxxxxxxx' \
--header 'authorization: xxxxxxx'\
--data-raw '{
"transaction": {
"amount": "2.0",
"currency": "HKD",
"payment_method": "credit_card",
"transaction_type": "sale", //If it is purchase, the value must be “sale”; If it is pre auth, the value must be "pre_auth"）
"uuid": "fde16844-5db4-4e62-b5ce-f848814b5d4b",
"secure_data": {
"data":"g9BbjUVM4056XCiSHNTsnFMjfR2U1ywji+wkEBeiG0YRfmWOlN87K74puYliTuuILZRSZE3JcHs4zjmichaQegzf7dXhcfojdzPu4J04DuXjnMq2bgz6cHN7HXk2EElCxFTCEl7jC0Nf/ZLUPrq+QY2ItuFLcUKnrixWepNVTgpHlBUAqSGGERhjrGecxgyc4IXpfE8sWCDUqdjTSPkzP55FN6HB2Z9eq1thIsgcJ9l6oW+dRKQ7+IhYxhXzEeY+GhDHw9LzCCRksSe/tQfJGiaOW+SmKEKrh/3mTznNjj1YEF76uqSXvDkXzIHmSwWvNCmA98NU+Tfq5n+VhULFi7hJg/gnX2FSng==",
"enc_key": "Kvt5sWuT96rQNUM28VO4E40EvNCKV+BPa3R8YHluClyxbccn4hWJ+RTwZH6u+8n7ejZSpWSaRPzRrthDooLbkHk+p8hmQEwq333zwqX5OrtfDY7UiKci2GTYd8WaOzM08p9KE6kp2skfcwh9n6Kk/nlNIwM+4xxzwvHaHpBTETrjD7arf7q8xca9+qyKDtbWsvLei/lVk5Gf4RKN6+LvWi415h30KPytL/+z4ntKDoZX2ZzmwnPNatAyIX+Z2gQUwbBiUzhkw1XrxEfpSye7whwlOcp/yZPFCIQHs2Mb+gx8P3ZiRqinUNJmf52RIVSY4H9aUQr9FH8x+I/KAnjqsA==",
"pub_key_hash": "UJfxs5BRZQlaAtlLbS1mtKS57L0mVF01hbtbSLKRwMk="
"timestamp":"1738994658",
"nonce":"AAAAAAAAAAAAAAAAAAAAAA=="
},
"merchant_id":"999999", //Mandatory field,
"client_transaction_id":"xxxxxxx", //Optional fields，Customer's transaction ID
"notify_url":"https://www.baidu.com",
"billing_address":{
"zip_code":"12345",
"address": "simple address",
"city": "city name",
"state": "address state",
"country_code": "JP"
}
}
}'
The command response like this:
{
"transaction": {
"amount": "2.0",
"merchant_id": "999999",
"transaction_id":"xxxxxxxxxxxxxxxx", //Our system's unique transaction index ID, used as org_transaction_id in void/refund/pre-auth-complete operations "client_transaction_id":"xxxxxxxxx", //Customer's transaction ID
"mid":"123456789012345",
"tid":"xxxxxxxx",
"transaction_type": "sale",
"uuid": "2d852f27-c5a4-4f64-9ab7-5c5e42493589",
"rrn": "2370549374775197696",
"transaction_state": "success",
"credit_card": {
"response_code": "00",
"card_number": "451461******4854",
"card_reader_mode": "manual",
"card_exp_date": "0925",
"auth_code": "2370549374775197699"
},
"date_time": "2025-08-12T07:03:01+00:00",
"total_amount": "2.0",
"currency": "HKD",
"payment_method": "visa",
}
}
Purchase and Pre Auth（with 3DS）—Additional technical integration with 3DS SERVER vendor is required
curl --location --request POST 'https://{Domain}/gateway/v1/payment/transactions' \
--header 'Content-Type: application/json' \
--header 'organization-id: xxxxxxxxxxxxxx' \
--header 'authorization: xxxxxxx'\
--data-raw '{
"transaction": {
"amount": "2.0",
"currency": "HKD",
"payment_method": "credit_card",
"transaction_type": "sale",
"uuid": "fde16844-5db4-4e62-b5ce-f848814b5d4b",
"secure_data": {
"data":"g9BbjUVM4056XCiSHNTsnFMjfR2U1ywji+wkEBeiG0YRfmWOlN87K74puYliTuuILZRSZE3JcHs4zjmichaQegzf7dXhcfojdzPu4J04DuXjnMq2bgz6cHN7HXk2EElCxFTCEl7jC0Nf/ZLUPrq+QY2ItuFLcUKnrixWepNVTgpHlBUAqSGGERhjrGecxgyc4IXpfE8sWCDUqdjTSPkzP55FN6HB2Z9eq1thIsgcJ9l6oW+dRKQ7+IhYxhXzEeY+GhDHw9LzCCRksSe/tQfJGiaOW+SmKEKrh/3mTznNjj1YEF76uqSXvDkXzIHmSwWvNCmA98NU+Tfq5n+VhULFi7hJg/gnX2FSng==",
"enc_key": "Kvt5sWuT96rQNUM28VO4E40EvNCKV+BPa3R8YHluClyxbccn4hWJ+RTwZH6u+8n7ejZSpWSaRPzRrthDooLbkHk+p8hmQEwq333zwqX5OrtfDY7UiKci2GTYd8WaOzM08p9KE6kp2skfcwh9n6Kk/nlNIwM+4xxzwvHaHpBTETrjD7arf7q8xca9+qyKDtbWsvLei/lVk5Gf4RKN6+LvWi415h30KPytL/+z4ntKDoZX2ZzmwnPNatAyIX+Z2gQUwbBiUzhkw1XrxEfpSye7whwlOcp/yZPFCIQHs2Mb+gx8P3ZiRqinUNJmf52RIVSY4H9aUQr9FH8x+I/KAnjqsA==",
"pub_key_hash": "UJfxs5BRZQlaAtlLbS1mtKS57L0mVF01hbtbSLKRwMk="
"timestamp":"1738994658",
"nonce":"AAAAAAAAAAAAAAAAAAAAAA=="
},
"authentication":{ //This field must exist when 3ds transaction
"eci":"xx",
"xid":"xxxxxxxxxx",
"cavv":"xxxxxxxxxxxx", //Cardholder authentication verification value
"threeDSversion":"2.2.0", //3DS version
"directoryResponse":"C",
"authenticationResponse":"Y",
"threeDSTransactionId":"xxxxxxxxxx" //3DS server id
},
"merchant_id":"999999",
"client_transaction_id":"xxxxxxx",
"notify_url":"https://www.baidu.com",
"billing_address":{
"zip_code":"12345",
"address": "simple address",
"city": "city name",
"state": "address state",
"country_code": "JP"
}
}
}'
Purchase and Pre Auth (with 3DS) — No additional technical integration required with the 3DS SERVER vendor
curl --location --request POST 'https://{Domain}/gateway/v1/payment/transactions' \
--header 'Content-Type: application/json' \
--header 'organization-id: xxxxxxxxxxxxxx' \
--header 'authorization: xxxxxxx'\
--data-raw '{
"transaction": {
"amount": "2.0",
"currency": "HKD",
"payment_method": "credit_card",
"transaction_type": "sale",
"uuid": "fde16844-5db4-4e62-b5ce-f848814b5d4b",
"secure_data": {
"data":"g9BbjUVM4056XCiSHNTsnFMjfR2U1ywji+wkEBeiG0YRfmWOlN87K74puYliTuuILZRSZE3JcHs4zjmichaQegzf7dXhcfojdzPu4J04DuXjnMq2bgz6cHN7HXk2EElCxFTCEl7jC0Nf/ZLUPrq+QY2ItuFLcUKnrixWepNVTgpHlBUAqSGGERhjrGecxgyc4IXpfE8sWCDUqdjTSPkzP55FN6HB2Z9eq1thIsgcJ9l6oW+dRKQ7+IhYxhXzEeY+GhDHw9LzCCRksSe/tQfJGiaOW+SmKEKrh/3mTznNjj1YEF76uqSXvDkXzIHmSwWvNCmA98NU+Tfq5n+VhULFi7hJg/gnX2FSng==",
"enc_key": "Kvt5sWuT96rQNUM28VO4E40EvNCKV+BPa3R8YHluClyxbccn4hWJ+RTwZH6u+8n7ejZSpWSaRPzRrthDooLbkHk+p8hmQEwq333zwqX5OrtfDY7UiKci2GTYd8WaOzM08p9KE6kp2skfcwh9n6Kk/nlNIwM+4xxzwvHaHpBTETrjD7arf7q8xca9+qyKDtbWsvLei/lVk5Gf4RKN6+LvWi415h30KPytL/+z4ntKDoZX2ZzmwnPNatAyIX+Z2gQUwbBiUzhkw1XrxEfpSye7whwlOcp/yZPFCIQHs2Mb+gx8P3ZiRqinUNJmf52RIVSY4H9aUQr9FH8x+I/KAnjqsA==",
"pub_key_hash": "UJfxs5BRZQlaAtlLbS1mtKS57L0mVF01hbtbSLKRwMk="
"timestamp":"1738994658",
"nonce":"AAAAAAAAAAAAAAAAAAAAAA=="
},
"3ds":{
"enable":true
},
"success_url":"https://baidu.com/payment-results?status=success",
"fail_url":"https://baidu.com/payment-results?status=failed",
"notify_url":"https://www.baidu.com", //Webhook notify url
"merchant_id":"999999",
"client_transaction_id":"xxxxxxx",
"notify_url":"https://www.baidu.com",
"billing_address":{
"zip_code":"12345",
"address": "simple address",
"city": "city name",
"state": "address state",
"country_code": "JP"
}
}
}'
Pre Auth Complete API
curl --location --request POST 'https://{Domain}/gateway/v1/payment/pre_auth_complete' \
--header 'Content-Type: application/json' \
--header 'organization-id: xxxxxxxxxxxxxx' \
--header 'authorization: xxxxxxx'\
--data-raw '{
"transaction": {
"transaction_type": "pre_auth_complete",
"origin_transaction_id": "4369097544467220480", //origin pre auth transaction id
"amount": "0.1", // The pre_auth_complete amount cannot exceed the pre_auth amount
"currency": "HKD",
"uuid": "d5b89650-f6a0-45b0-b136-aa674cfd31fe". //*And new transaction should be requested with a new UUID
}
}'
Void API
This API can void same-day unsettled sale transactions and can also void pre-auth transactions. Full and partial amount void are supported.
curl --location --request POST 'https://{Domain}/gateway/v1/payment/void' \
--header 'Content-Type: application/json' \
--header 'organization-id: xxxxxxxxxxxxxx' \
--header 'authorization: xxxxxxx'\
raw '{
"transaction": {
"amount":"100", //If the “amount” field exists, it will be voided according to the amount. If there is no "amount" field, the full amount will be voided by default.
"currency": "HKD",
"origin_transaction_id": "2387657838852839424", //*Original transaction transaction id
"transaction_type": "void",
"uuid": "dd32d92d-9c55-4b79-9437-66e23f3bbe5f" //*And new transaction should be requested with a new UUID.
}
}
Refund API
The API is used for refund transactions. Full and partial amount refund are supported.
curl --location --request POST 'https://{Domain}/gateway/v1/payment/refund' \
--header 'Content-Type: application/json' \
--header 'organization-id: xxxxxxxxxxxxxx' \
--header 'authorization: xxxxxxx'\
--data-raw '{
"transaction": {
"amount": "20.00",
"currency": "HKD",
"origin_transaction_id": "2387657838852839424", //*Original transaction transaction id
"transaction_type": "refund",
"uuid": "dd32d92d-9c55-4b79-9437-66e23f3bbe5f" //*And new transaction should be requested with a new UUID.
}
}
Increase the pre auth amount
This API is used to increase the amount of pre-auth
curl --location --request POST 'https://{Domain}/gateway/v1/payment/increment_pre_auth' \
--header 'Content-Type: application/json' \
--header 'organization-id: xxxxxxxxxxxxxx' \
--header 'authorization: xxxxxxx'\
--data-raw '{
"transaction": {
"amount": "20.00", //the original pre auth amount increase of 20.00HKD
"currency": "HKD",
"origin_transaction_id": "2387657838852839424", //*Original pre auth transaction id
"transaction_type": "increment_pre_auth",
"uuid": "dd32d92d-9c55-4b79-9437-66e23f3bbe5f" //*And new transaction should be requested with a new UUID.
}
}
Query API
curl --location --request GET 'https://{Domain}/gateway/v1/query/transactions/{transaction_id or uuid}' \
--header 'Content-Type: application/json' \
--header 'organization-id: xxxxxxxxxxxxxx' \
--header 'authorization: xxxxxxx'
Response
{
"transaction": {
"amount": "2.0",
"merchant_id": "999999",
"transaction_id":"xxxxxxxxxxxxxxxx",
"client_transaction_id":"xxxxxxxxx",
"mid":"123456789012345",
"tid":"xxxxxxxx",
"transaction_type": "sale",
"uuid": "2d852f27-c5a4-4f64-9ab7-5c5e42493589",
"rrn": "2370549374775197696",
"transaction_state": "success",
"credit_card": {
"response_code": "00",
"card_number": "451461******4854",
"card_reader_mode": "manual",
"card_exp_date": "0925",
"auth_code": "2370549374775197699"
},
"date_time": "2025-08-12T07:03:01+00:00",
"total_amount": "2.0",
"currency": "HKD",
"payment_method": "visa",
}
}
Webhook API
WebHook is a callback function. If the pre-create order has a "notify_url" parameter, the Payment Processor server will automatically return the transaction result to this URL after the transaction is completed. When the third party receives the WebHook, it must return a response with HTTP status code =200 OK.
- The secret_key is provided by the payment process service provider when applying for merchants.
- The appid is provided by the payment process service provider when applying for merchants.
- X-SIGNATURE: hmac_sha256(request body, secret_key)
Parameter Description:
Refer to the parameter description of "Query a transaction by Transaction id or UUID."
Recurring Payment
Flow Diagram
This is the API for recurring payments. Below is the flow diagram.
Step 1: Initiate the token API to obtain the tokenized information of the card number.
Step 2: Use the token to initiate a CIT transaction.
Step 3: Use the token to initiate an MIT transaction.
*Note: Please be aware that the client must initiate the CIT (Customer-Initiated Transaction) before initiating the MIT (Merchant-Initiated Transaction).
*
Parameters Description of “mit_type”
| Parameters | Type | Usage | Description |
|---|---|---|---|
| partial_split_shipment | String | M | This is typically applied when merchants are unable to deliver all items at once. For instance, if some items purchased by consumers are temporarily out of stock, merchants may send the available items first and charge accordingly. They then wait until the remaining items are in stock before proceeding with delivery and charging. |
| delayed_charges | String | M | This is typically applied in scenarios where certain services may incur additional charges, such as car rentals, hotel reservations, and the like. Consumers pay the base fee when using the service. If additional charges arise (such as excess mileage, room cleaning fees, etc.), the merchant will initiate a post-service charge, known as a "MIT," after the service concludes. |
| no_show | String | M | In industries such as hotels, flights, restaurant reservations, medical appointments, etc., if a customer fails to use the service at the scheduled time without canceling in advance, the merchant may impose a certain "no-show fee" or "unused fee" to compensate for the losses incurred due to the customer's absence. |
| recurring_payment | String | M | Recurring payment refers to regular, periodic automatic deductions commonly seen in subscription-based services such as online streaming services (like Netflix, Spotify), gym memberships, magazine subscriptions, etc. |
| unscheduled_cof | String | M | Unscheduled COF (Card-On-File)This is typically applied in ongoing business relationships between consumers and merchants, where consumers provide and store payment card information with merchants, allowing merchants to make irregular deductions from their accounts in terms of price or time. For example, cab-hailing services deducting payments after the service ends. |
| unscheduled_cof_subsequent | String | M | This refers to subsequent transactions for Unscheduled Card-on-File (COF), meaning after the initial Unscheduled COF transaction is completed, merchants proceed with subsequent deductions without consumers needing to input card information again. |
Token API
original “cridt_card” data:
"credit_card": {
"cvv": "123",
"card_exp_date": "1233",
"card_number": "2223520000010014",
"credit_token_bind_expire": 1716708172 //token expire timestamp
},
Please encrypt "cridt_card" into ""secure_data"
curl --location --request POST 'https://{Domain}/gateway/v1/payment/tokens' \
--header 'Content-Type: application/json' \
--header 'organization-id: xxxxxxxxxxxxxx' \
--header 'authorization: xxxxxxx'\
--data-raw '{
"transaction": {
"uuid": "243a977f-6481-444f-bff3-650d57d76415", //UUID is also used in token query API
"payment_method": "credit_card",
"merchant_id":"87654321",
"is_authentication":true, //If set to true, cardholder authentication is required. If set to false, cardholder authentication is not required.
"mit_type": "recurring_payment", //Reference Parameters Description of “mit_type”
"secure_data": {
"data": "x7FXnMA+lKpfSJZ+Qg8aKymSQpTnXOa92Ny6eIdjdue0AxyjndPmp5gLBLzVX3e/lGMFavxeSyK/U0AQrejhi4u1MtiSkfCL4VCPln6KkdRsFS5Ok7fzbhS1OWxcUPa6ZUng80iHFfR+3R9bcR5tpDRV5GpqYjoczgfYr8+Phoa51OcwETt26bsrF6xZ6Ea9T9e/RgZBV2JbcGbRDyCSEQEr048=",
"enc_key": "mEhI7kFRXfaddGw7Cz8Ht2MsPAMGM7M61jnx4VhqVHOw1Q57KT3IA9iJsTQ6tWGRQ0DN0WjJqrFUZ8GYDne0MbpJs3b8kNgbhW9hGi8mCXtfpsCLgBttm6XhII145BG8ozmq0m0G5aO/knr63lSBKQOuZOhyuC69gSYU20L1qqAtu62syy27ngKUtlC5LHSWfwzFVfHflpIP6Kc94+rlh3+Riel3imKxaPddA+czN8BypDr6w2K4BwmrSy0+38wreUrdVM7CvzUnEZdhOagbs4iZRX+ZOhl+RoU7PIzK141c4M8lIfAYTfIgHy9+UrHGrjRV+IEDkrO0vfBpnoVB/w==",
"pub_key_hash": "UJfxs5BRZQlaAtlLbS1mtKS57L0mVF01hbtbSLKRwMk=",
"timestamp":"1759026720",
"nonce":"6ZQou5d86jYlmntj"
},
"notify_url":"https://www.baidu.com",
"billing_address": {
"zip_code":"12345",
"address": "simple address",
"city": "city name",
"state": "address state",
"country_code": "JP"
}
}
}
Response Body
{
"transaction":{
"uuid":"243a977f-6481-444f-bff3-650d57d76415",
//***When "is_authentication"=true, the following fields will appear ***//
"pay_redirect_url":"xxxxxxxx",
"transaction_state":"pending",
///***When "is_authentication"=false, the following fields will appear***//
"transaction_state":"success",
"credit_card_token":{
"token":"13a17d49-a62a-46d1-8996-8ffaa07cef29"
"payment_method":"mastercard",
"credit_token_bind_expire": 1711620163
}
}
}
The token API enables secure storage of payment details by creating an encrypted token that contains the shopper's payment information. When cardholders wish to make a recurring payment, you simply submit this token to process the payment.
Query API of the Token
curl --location --request
GET 'https://{Domain}/gateway/v1/query/tokens/{{uuid}}' \
--header 'Content-Type: application/json' \
--header 'organization-id: xxxxxxxxxxxxxx' \
--header 'authorization: xxxxxxx'\
Response body
{
"transaction":{
"uuid":"243a977f-6481-444f-bff3-650d57d76415",
"mit_type": "unscheduled_cof",
"transaction_state":"success",
"credit_card_token":{
"token":"13a17d49-a62a-46d1-8996-8ffaa07cef29"
"payment_method":"mastercard"
}
}
}
This API is used to query token results.
CIT transaction
This API is used to initialize CIT (Customer-Initiated Transaction) transactions
curl --location --request POST 'https://{Domain}/gateway/v1/payment/transactions' \
--header 'Content-Type: application/json' \
--header 'organization-id: xxxxxxxxxxxxxx' \
--header 'authorization: xxxxxxx'\
--data-raw '{
"transaction": {
"uuid": "b04207b1-e037-4bc7-92aa-cff192bfaf83",
"transaction_type": "sale",
"payment_method": "payment_token",
"merchant_id":"87654321",
"amount": "2",
"currency": "HKG",
"payment_token": {
"token": "baef9051-2eaa-4bdc-9dab-57d2cc19740a",
"payment_entry_type": "cit"
},
//***If a CIT transaction requires 3DS authentication, the following 3DS-related parameters must be included**//
"3ds":{
"enable":true
},
"success_url":"https://baidu.com/payment-results?status=success",
"fail_url":"https://baidu.com/payment-results?status=failed",
"notify_url":"https://www.baidu.com"
}
'
Response body
{
"transaction": {
"transaction_id": "4454933579968821248",
"amount": "2",
"mid": "123456789000005",
"merchant_id": "87654321",
"transaction_type": "sale",
"uuid": "bd2939e9-692a-4926-956c-a6676dacb530",
"rrn": "4454933580103024640",
"credit_card": {
"response_code": "00",
"card_number": "356600******0007",
"card_reader_mode": "cit",
"card_exp_date": "2512",
"auth_code": "4454933580103024643"
},
"date_time": "2025-09-29T07:38:53+00:00",
"total_amount": "7",
"transaction_state": "success",
"currency": "HKD",
"payment_method": "jcb"
}
}
MIT Transaction
This API is used to initialize MIT (Merchant-Initiated Transaction) transactions
curl --location --request POST 'https://{Domain}/gateway/v1/payment/transactions' \
--header 'Content-Type: application/json' \
--header 'organization-id: xxxxxxxxxxxxxx' \
--header 'authorization: xxxxxxx'\
--data-raw '{
"transaction": {
"amount": "30",
"currency": "HKD",
"payment_method": "payment_token",
"transaction_type": "sale",
"uuid": "8d804cf7-637a-4107-a657-b003007c85c0",
"merchant_id":"87654321",
"payment_token": {
"token": "6189e254-37d4-40ac-ae2b-6c7ba4f76814",
"payment_entry_type": "mit"
}
}
}
Response body：
{
"transaction": {
"transaction_id": "4454935774445451265",
"amount": "30",
"mid": "123456789000005",
"merchant_id": "87654321",
"transaction_type": "sale",
"uuid": "8d804cf7-637a-4107-a657-b003007c85c0",
"rrn": "4454935774562877441",
"credit_card": {
"response_code": "00",
"card_number": "356600******0007",
"card_reader_mode": "mit",
"card_exp_date": "2512",
"auth_code": "4454935774562877442"
},
"date_time": "2025-09-29T07:41:04+00:00",
"total_amount": "30",
"transaction_state": "success",
"currency": "HKD",
"payment_method": "jcb"
}
}
Onboarding API
Introduction
This document is about how to quickly complete the onboarding and update of the Merchant ID and MID through the API.
Parameter Description
| Parameter name | Optional/Mandatory | Format | Max Length | Support update | Special Comment |
|---|---|---|---|---|---|
| organization_id | Mandatory | Numeric | 15 | No | Assigned by us |
| merchant_legal_name | Mandatory | Alpha-Numeric | 50 | No | Merchant name on BR |
| merchant_dba_name | Mandatory | Alpha-Numeric | Yes | Doing business as name | |
| merchant_address | Mandatory | Alpha-Numeric | 50 | Yes | Merchant location |
| merchant_city | Mandatory | Alpha | 10 | Yes | Merchant location |
| merchant_state | Mandatory | Alpha | 2 | Yes | Merchant location |
| merchant_country | Mandatory | Alpha | 3 | Yes | Merchant location |
| merchant_id | Mandatory | Numeric | 10 | No | The unique ID assigned to the merchant by the organization. |
| mid | Mandatory | Numeric | 15 | No | MID is the unique identifier of a merchant during the transaction processing |
| mid_type | Mandatory | Alpha | 10 | No | online offline |
| mid_payment_method | Mandatory | Alpha | 10 | No | visa mastercard jcb unionpay discover |
| mid_mcc_code | Mandatory | Numeric | 4 | Yes | Merchant category code |
| Status | Mandatory in response body | - | success failed pending |
||
| record_id | Mandatory in the response body of the apply api. | No | The unique identifier in the our system, it can be used for update, disable and query api |
Onboarding the merchant id and MID
Customers can submit application materials through the API to enable payment functionality for the relevant Merchant ID and MID .
Url： POST '<https://{domain}/gateway/v1/onboarding/apply'>
request body '{
"uuid":"b4807c11-2f12-450f-9cc6-7741ba386598",
"merchant_legal_name": "legal name updated",
"merchant_dba_name": "dba name updated",
"merchant_address": "address",
"merchant_city": "hongkong",
"merchant_state": "state",
"merchant_country": "HKG",
"merchant_id": "888888",
"mid": "123456789012345",
"mid_type":"online",
"mid_payment_method": "visa",
"mid_mcc_code": "5499"
}
response body
'{
"uuid":"b4807c11-2f12-450f-9cc6-7741ba386598",
"status":"success",
"record_id":"123xxxxxxxxxx",
"merchant_legal_name": "legal name",
"merchant_dba_name": "dba name",
"merchant_address": "address",
"merchant_city": "hongkong",
"merchant_state": "state",
"merchant_country_code": "HKG",
"merchant_id": "888888",
"mid": "123456789012345",
"mid_type":"online",
"mid_payment_method": "visa",
"mid_mcc_code": "5499"
}
'
Update the merchant id and MID
Customers can use this API to update the information related to the MID they have applied for, such as DBA Name, MCC, etc.
In the request body, the “merchant id” and “mid” of the information to be updated must be exist.
Url： POST '<https://{domain}/gateway/v1/onboarding/update'>
request body '{
"uuid":"b4807c11-2f12-450f-9cc6-7741ba386598",
"record_id":"123xxxxxxxxxx",
"merchant_id": "888888", //Mandatory fields
"mid": "123456789012345", //Mandatory fields
"merchant_legal_name": "legal name updated",
"merchant_dba_name": "dba name updated",
"merchant_address": "address updated",
"merchant_city": "hongkong",
"merchant_state": "state",
"mid_mcc_code": "5499"
}
response body
'{
"uuid":"b4807c11-2f12-450f-9cc6-7741ba386598",
"status":"success",
"record_id":"123xxxxxxxxxx",
"merchant_legal_name": "legal name updated",
"merchant_dba_name": "dba name updated",
"merchant_address": "address updated",
"merchant_city": "hongkong",
"merchant_state": "state",
"merchant_country_code": "HKG",
"merchant_id": "888888",
"mid": "123456789012345",
"payment_method": "visa",
"mid_mcc_code": "5499"
}
'
Disabled the merchant id and MID
Customers can disable the payment function of the MID through this API.
In the request body, the “merchant id” and “mid” of the information to be disabled must be exist.
Url： POST '<https://{domain}/gateway/v1/onboarding/disable'>
request body '{
"uuid":"b4807c11-2f12-450f-9cc6-7741ba386598",
"record_id":"123xxxxxxxxxx"
"merchant_id": "888888", //Mandatory fields
"mid": "123456789012345" //Mandatory fields
}
response body
'{
"uuid":"b4807c11-2f12-450f-9cc6-7741ba386598",
"status":"disabled",
"record_id":"123xxxxxxxxxx"
"merchant_id": "888888",
"mid": "123456789012345"
}
'
Query the merchant id and MID information
Customers can query the information of the MID with the “record_id” through this API
In the request body, the “merchant id” and “mid” of the information to be query must be exist.
Url： GET '<https://{domain}/gateway/v1/onboarding/query/{record_id}>'
response body
'{
"uuid":"b4807c11-2f12-450f-9cc6-7741ba386598",
"status":"success",
"record_id":"123xxxxxxxxxx",
"merchant_legal_name": "legal name",
"merchant_dba_name": "dba name",
"merchant_address": "address",
"merchant_city": "hongkong",
"merchant_state": "state",
"merchant_country_code": "HKG",
"merchant_id": "888888",
"mid": "123456789012345",
"mid_type":"online",
"mid_payment_method": "visa",
"mid_mcc_code": "5499"
}
'
3.Google Pay™ Developer Document
Branding
1. Google Pay Trade Marks
If you provide Google Pay as a payment method to your customers, you must use the official Google Pay logo and button assets in compliance with Google Pay Android brand guidelines and Google Pay web brand guidelines, without modifications to the Google Pay asset colors, proportions, or appearance.
Implementation Paths
1. Android Merchant
For Android merchants, please refer to Google Pay Android developer documentation, Google Pay Android integration checklist and Google Pay Android brand guidelines.
2. Web Merchant
For Web merchants, please refer to Google Pay Web developer documentation, Google Pay Web integration checklist and Google Pay Web Brand Guidelines.
3. Payment Link
Most merchants will use the Wonder App to generate payment links that integrate with Google Pay. They will use Bindo’s merchant ID for payments.
- **Adhere to Google policies: all merchants are required to follow the Google Pay and Wallet API's Acceptable Use Policy and accept the terms defined in the Google Pay API Terms of Service.
4. Payment SDK
Some merchants use the Bindo API to integrate the Google Pay payment method. They need to register for Google Pay and select Bindo Labs Limited as their service provider. Or Bindo uses the backend website to add a merchant to the list.
- **Adhere to Google policies: all merchants are required to follow the Google Pay and Wallet API's Acceptable Use Policy and accept the terms defined in the Google Pay API Terms of Service.
<1>. Add The SDK To The Project
In your Project/build.gradle add the following lines:
dependencyResolutionManagement {
repositories {
mavenCentral()
maven {
url 'https://XXXXXXX.com'
}
}
}
In your Project/app/build.gradle add the following lines:
dependencies {
implementation 'com.wonder.payment.sdk:wonderpayment-android:v1.x.x'
}
If code obfuscation is enabled in your project, please add the following configuration in your proguard-rules.pro configuration file
-keep class com.wonder.payment.sdk.** { *;}
-keep class com.google.gson.reflect.TypeToken { *; }
-keep class * extends com.google.gson.reflect.TypeToken
<2>. Initiate The SDK
Initiate The SDK
WonderPayment.initConfig(
PaymentConfig(
appId = "f3615c8b-e402-48ac-bcd9-5af7a473ebdc",
customerId = "87d8f5a5-e745-456d-938e-065bb77cedc7",
environment = PaymentEnv.STAGING,
locale = Locale.US,
fromScheme = "paydemo",
wechatAppId = "wx5ac0eb5676b32e80",
googleConfig = GoogleConfig(
countryCode = "HK",
currencyCode = "HKD",
merchantId = "BRC2DN4H8T7I76EZ",
merchantName = "Jek Limited"
),
)
)
To initiate the SDK, customer needs know:
Set Up the Payment Configurations. Retrieve
appIDas a first step when initiating the SDK when you onboard on Wonder, in order to get access to our Payment Gateway configurations. For specific methods such as Apple Pay, Google Pay, Wechat Pay, you will be required to apply directly with the schemes in order to obtain the unique identifier, for the activation of those methods.To set up a method for future payments, you must generate a
customerIDfor Tokenisation process.
PSP Mode
private fun buildPaymentString(businessId: String, cardList: List<CardType>): String {
return """
{
"environment": "${if (WonderPayment.paymentConfig.environment == PaymentEnv.STAGING) "TEST" else "PRODUCTION"}",
"apiVersion": 2,
"apiVersionMinor": 0,
"allowedPaymentMethods": [
{
"type": "CARD",
"tokenizationSpecification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "bindo",
"gatewayMerchantId": "$businessId"
}
},
"parameters": {
"allowedCardNetworks": ${
cardList.filter { it != CardType.CUP && it != CardType.DINERS }
.map { "\"${it.type.uppercase()}\"" }
},
"allowedAuthMethods": ["PAN_ONLY","CRYPTOGRAM_3DS"]
}
}
],
"merchantInfo": {
"merchantId": "${merchantId()}",
"merchantName": "${WonderPayment.paymentConfig.googleConfig?.merchantName}"
},
"transactionInfo": {
"countryCode": "${WonderPayment.paymentConfig.googleConfig?.countryCode}",
"currencyCode": "${WonderPayment.paymentConfig.googleConfig?.currencyCode}"
}
}
"""
}
For PSP Mode
Usually called direct mode
<3>. PaymentConfig class
| Variable | Type | Required | Description |
|---|---|---|---|
| appId | String | Y | The APP ID generated from new API credential on Wonder Dashboard |
| customerId | String | N | This field is needed if customer would like to access to tokenisation feature, check out tokenisation feature here. User can create the customerId by calling the Create Customer API.Refer to : https://developer-stage.wonder.today/openapi/customer |
| environment | enum | Y | The environment of the payment SDK. Available options are:.staging, .alpha, .production |
| locale | String | N | Localised language that the app is opened in. Available options:.zh_CN .zh_HK .en_US |
| fromScheme | String | Y | Used to redirect back to the customer’s app after app-to-app call payment is completed. |
| wechatAppId | String | N | The appId applied on WeChat pay, the merchant need to give it to our side for WeChat Pay configuration. |
| googleConfig | GoogleConfig | N | Refer to the below configs if customer wants to enable Google Pay payment. |
| GoogleConfig.countryCode | String | Y | ISO 3166-1 alpha-2 country code where the transaction is processed. |
| GoogleConfig.currencyCode | String | Y | The ISO 4217 alphabetic currency code. |
| GoogleConfig.merchantId | String | Y | A Google merchant identifier issued after registration with the Google Pay & Wallet Console. |
| GoogleConfig.merchantName | String | Y | Merchant name encoded as UTF-8. Merchant name is rendered in the payment sheet. |
Implementation Details
1.Pan Only
{
"parameters": {
"allowedCardNetworks": ${cardList.filter { it != CardType.CUP && it != CardType.DINERS }.map { "\"${it.type.uppercase()}\"" }
},
"allowedAuthMethods": ["PAN_ONLY","CRYPTOGRAM_3DS"]
}
}
We provide 3DS on Google Pay PAN_ONLY transactions. When Google Pay returns PAN_ONLY payload, referring to the merchant 3DS amount setting, will determine whether the transaction will initiate 3DS verification or not.
2. Gateway and Gateway ID
"tokenizationSpecification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "bindo",
"gatewayMerchantId": "$businessId"
}
}
As a supported payment service provider with the Google Pay API, our integration lets you, as a merchant to use the Google Pay API's gateway integration type, where we handle all of the decryption on your behalf.
When you integrate with the Google Pay API as a merchant, ensure to set the following values in the TokenizationSpecification object:
• *gateway: Set this value to the gateway ID value you set during technical onboarding with Google.
• **gatewayMerchantID: Set this value to a unique identifier that you've set for a merchant in your system.
Here's an API configuration example to show merchants, if your gateway value is set to Google and your gatewayMerchantID value is found in your merchant's account with you:*
- •
gateway: Set this value to the gateway ID value you set during technical onboarding with Google. - •
gatewayMerchantID: Set this value to a unique identifier that you've set for a merchant in your system.
3. Authorization Methods
Our integration with Google Pay supports two types of card credentials:
1.*PAN_ONLY*: physical card details stored in Google Pay™.
- **3DS required: yes, standard 3DS flow applies.
- **Supported countries: All countries.
2.*CRYPTOGRAM_3DS*: T*okenized virtual card stored on device.*
- **3DS required: no, authentication is performed by Google Pay™.
- **Supported country: All countries.
4. Allowed Card Networks
We support VISA, Mastercard, Discover, and JCB card networks with the Google Pay API. You can define these values in the allowedCardNetworks property and find the appropriate values in Google Pay's web developer documentation and Google Pay's Android developer documentation.
5. Billing Address(Not Mandatory)
"allowedPaymentMethods": [
{
"type": "CARD",
"allowedPaymentMethods": [
{
"type": "CARD",
"tokenizationSpecification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "bindo",
"gatewayMerchantId": "$businessId"
}
},
"parameters": {
"allowedCardNetworks": ${
cardList.filter { it != CardType.CUP && it != CardType.DINERS }
.map { "\"${it.type.uppercase()}\"" }
},
"parameters": {
"billingAddressRequired": true,
"billingAddressParameters": {
"phoneNumberRequired": true,
"format": "MIN"
},
"allowedAuthMethods": ["PAN_ONLY","CRYPTOGRAM_3DS"]
}
}
],
]
The billing address is an optional field, which the merchant can use to request that the customer fill in their billing address. Please refer to this for more information.
6. Handle The Google Pay Payload
curl --location 'https://{Domain}/gateway/v3/payment/precreate/transactions' \
--header 'authority: {Domain}' \
--header 'accept: application/json, text/plain, */*' \
--header 'accept-language: zh-CN,zh;q=0.9,en-US;q=0.8,en;q=0.7,zh-TW;q=0.6,mt;q=0.5' \
--header 'content-type: application/json;charset=UTF-8' \
--header 'origin: http://127.0.0.1:8848' \
--header 'referer: http://127.0.0.1:8848/' \
--header 'sec-ch-ua: "Chromium";v="118", "Google Chrome";v="118", "Not=A?Brand";v="99"' \
--header 'sec-ch-ua-mobile: ?0' \
--header 'sec-ch-ua-platform: "macOS"' \
--header 'sec-fetch-dest: empty' \
--header 'sec-fetch-mode: cors' \
--header 'sec-fetch-site: cross-site' \
--header 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36' \
--header 'x-client-secret: K3dPAOMAAADRr2ogr8E9pDLz1gnukQyFeTnfpYy1eChtguZqkrc-2Ry8qYNOH_tYnllckZ34R8414YrASyLA_D8fVWRx78Mt1U7ADAupvMpr3pyfs96yywX5aAhEbqXr7HoqQdV5YA' \
--data '{
"transaction": {
"amount": "0.2",
"currency": "HKD",
"transaction_type": "sale",
"payment_method": "google_pay",
"uuid": "3b6ce3f9-15e3-4c75-b49f-141528a4fdbe",
"google_pay":{
"token": {
"apiVersion": 2,
"apiVersionMinor": 0,
"paymentMethodData": {
"description": "Mastercard •••• 0089",
"info": {
"assuranceDetails": {
"accountVerified": true,
"cardHolderAuthenticated": false
},
"cardDetails": "0089",
"cardNetwork": "MASTERCARD"
},
"tokenizationData": {
"token": "{\"signature\":\"MEQCIE3W5XNWphlRfig7Z6vo0V6p+8GCMtTVJjD3X6rB8no8AiAEki/w6cjbXqQfyp9e2QtI5tNICPxCJpJkrFaVg5CdbQ\\u003d\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEv3RjcMrO8a/VfAWXq8K3uOo6d4jbkWMGFVXOTwFvuk58sfMXy2L6Dg4awpjA8/JsNhZ98zFKvIYzqVS+DtxXIw\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1699670395909\\\"}\",\"signatures\":[\"MEUCIQDLP9KtLg+6cXFJbuqeR7s3PEd1GTHtZFypm7FJ4egoTwIgFZheJOybkAlKjXaBmkP1SbHJ1ohFK3dizxc0fdLnr1I\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"zyKqBuNV3JgZn8qfOJ5y7mff+H3kQFIq8BAGHQmSF7SQZjeTUi88fr7i26bOvonrVtV/U/MKaYgWX1LOxI8AXg+0HDjZh3RIFjhrUV/co6CbP/vB6lmIgg62qZX28sdjO+CbtxuNh3BadY3p6rJ0nM8a0/dTOWBvRfrBZL/dSR4k7hJ+IUQK7eOwroTrF3o+8PNsotbYb1Oi+ki3egfmgZl8GirGACPkZJ3HWTnEPN4pW1rCEzqxQm3/9OKFiwsK65ASccqvWI1BJdGhyAAJQTG2Ihe8MgoC/wDRbgHjrKg1IEkZG6yZdK0WVGQSYCyZdcDJVMFILq9v4YQp+zmEGptjhulgWxdCfMiXoa884/sWEHrPbQXMxCvsHcDIb7suAGvaM4FUYzSfRNR+oXvWi3MGLUX4Ped/xC2A8jdAcpijZlmP03AuQfcuf/o\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BLgvkkUw6qNRiG7lFJ875g1uE3FIvX6yO4EaIlxIH0R+zFqo5TSjDtSfSpYDgjhQ8R/e/hCTYajpjSasVx6Iu0A\\\\u003d\\\",\\\"tag\\\":\\\"bdr/Z3QBwzJMNuatD3gSDfPik//mvbsk4wHdJAJY5G0\\\\u003d\\\"}\"}",
"type": "PAYMENT_GATEWAY"
},
"type": "CARD"
}
}
}
}
}'
When a customer pays with Google Pay, it generates encrypted data which contains the payment data. The encrypted data can be extracted from the google_pay.token.paymentMethodData.tokenizationData.token property of the PaymentData response object.
- Confirm Protocol Version is ECv2 or not. If not ECv2, return directly, no further action will be taken.
- Verify intermediateSigningKey.signedKey.keyExpiration expired or not, if the key expired, no further action will be taken.
- Validate the signature of intermediateSigningKey.signedKey. If the validation fails, return immediately without any further processing.
- Use intermediateSigningKey.signedKey.keyValue to verify signedMessage. If the verification fails, return immediately without any further processing.
- Use the private key and signedMessage.ephemeralPublicKey to derive the symmetric encryption key and MAC key. If the verification of signedMessage.encryptedMessage or signedMessage.tag fails, return immediately without any further processing.
- Use the symmetric encryption key to decrypt signedMessage.encryptedMessage. If decryption fails, return immediately without any further processing. If decryption succeeds, check whether messageExpiration has expired. If it has expired, return immediately without any further processing. If it has not expired, return the successfully decrypted data and end the process.
Encrypted data handle demo
func GooglePayDecrypt(merchantId string, googleRootPublicKey, privateKey string, resp *GooglePayEncryptResult) (*GooglePayDecryptResult, error) {
token := resp.PaymentMethodData.TokenizationData.Token
if token.ProtocolVersion != ProtocolVersionECv2 {
return nil, errors.New("google pay decrypt only support protocol version ECv2.")
}
keyExpiration, err := strconv.ParseInt(token.IntermediateSigningKey.SignedKey.KeyExpiration, 10, 64)
if err != nil {
return nil, errors.New("intermediate signing key expiration format error.")
}
if time.Now().UnixMilli() > keyExpiration {
return nil, errors.New("signed key expiration .")
}
if err := GooglePayVerifyIntermediateSigningKeySignatures(googleRootPublicKey, token); err != nil {
return nil, errors.New(fmt.Sprintf("GooglePay Verify Intermediate SigningKey Signature error: %s", err.Error()))
}
if err := GooglePayVerifySignedMessage(merchantId, token); err != nil {
return nil, errors.New(fmt.Sprintf("GooglePay Verify Signed Message error: %s", err.Error()))
}
eciesPrivateKey, err := ConvertToEciesPrivateKey(privateKey)
if err != nil {
return nil, errors.New(fmt.Sprintf("GooglePay Parse EcdsaKey error: %s", err.Error()))
}
ephemeralPublicKeyBytes, err := base64.StdEncoding.DecodeString(token.SignedMessage.EphemeralPublicKey)
if err != nil {
return nil, errors.New(fmt.Sprintf("GooglePay Parse Ephemeral Public Key error: %s", err.Error()))
}
symmetricEncryptionKey, macKey, err := GetSymmetricEncryptionKeyAndMacKey(eciesPrivateKey, ephemeralPublicKeyBytes)
if err != nil {
return nil, err
}
encryptedMessageBytes, err := base64.StdEncoding.DecodeString(token.SignedMessage.EncryptedMessage)
if err != nil {
return nil, errors.New(fmt.Sprintf("GooglePay Parse Encrypted Message error: %s", err.Error()))
}
tagBytes, err := base64.StdEncoding.DecodeString(token.SignedMessage.Tag)
if err != nil {
return nil, errors.New(fmt.Sprintf("GooglePay Parse Tag error: %s", err.Error()))
}
if !CheckMAC(encryptedMessageBytes, tagBytes, macKey) {
return nil, errors.New("CheckMAC error")
}
decryptBytes, err := AES128CTRDecrypt(symmetricEncryptionKey, encryptedMessageBytes)
if err != nil {
return nil, err
}
decryptRet := &GooglePayDecryptResult{}
err = json.Unmarshal(decryptBytes, decryptRet)
if err != nil {
return nil, err
}
messageExpiration, err := strconv.ParseInt(decryptRet.MessageExpiration, 10, 64)
if err != nil {
return nil, errors.New("message expiration format error.")
}
if time.Now().UnixMilli() > messageExpiration {
return nil, errors.New("message expiration .")
}
return decryptRet, nil
}
Encrypted data handle demo
Decrypt Data
{
"gatewayMerchantId": "googletest",
"messageExpiration": "1757708839555",
"messageId": "AH2Ejtes1D2jTXiLOYJjMTF_cvHr1MyGrb-LTrBMFCN__NjMIcXzPP-a8ky4FZR4NJtsBwyttR79Nr4NvYo3PEUzgmMeYFRHSrXefvxc6yAndt_zu1y64tM",
"paymentMethod": "CARD",
"paymentMethodDetails": {
"expirationYear": 2027,
"expirationMonth": 10,
"pan": "5360812150551589",
"authMethod": "CRYPTOGRAM_3DS",
"cryptogram": "AD/IwCRrntMyBUvuGuTOGgADFA==",
"eciIndicator": "02",
"assuranceDetails": {
"cardHolderAuthenticated": true,
"accountVerified": true
}
}
}
Decrypt Data
Appendix
Test Card Numbers
Payment Service Provider helps merchants confirm that their integration is successful with a suite of test cards. This will allow merchants to perform test transactions before going live. Those cards numbers will simulate fake payments in your test environment.
| Test Card Number | CARD SCHEME | AMOUNT | ISSUER RESPONSE CODE |
|---|---|---|---|
| 4111 1111 1111 1111 | Visa | Any | This card will always make payment succeed regardless of amount |
| 5555 5555 5555 4444 | Master Card | Any | This card will always make payment succeed regardless of amount |
| 3743 4009 5639 074 | Amex | Any | This card will always make payment succeed regardless of amount |
| 3566 1111 1111 1113 | JCB | Any | This card will always make payment succeed regardless of amount |
| 6250 9470 0000 0014 | China UnionPay | Any | This card will always make payment succeed regardless of amount |
3DS Test Card Numbers
| Match Type | Payment Method | Card Numbers |
|---|---|---|
| Frictionless | Visa | 4440000042200011, 4440000042200012, 4440000042200014, 4532580769309444 |
| Frictionless | Mastercard | 5123456789012345, 5123456789012346, 5123456789012347, 5537250990816011 |
| Frictionless | CUP | 6282900000000001, 6282900000000002, 6282900000000003, 6290389843107635 |
| Frictionless | JCB | 3566000000000001, 3566000000000002, 3566000000000003, 3528903821182419 |
| Frictionless | Discover | 6011000000000001, 6011000000000002, 6011000000000003, 6011883188179082 |
| Frictionless | Amex | 378282000000001, 378282000000002, 378282000000003, 374176349288429 |
| Challenge | Visa | 4440000009900010, 4440000009900011, 4440000009900012, 4556592205794346 |
| Challenge | Mastercard | 5123450000000008, 5123450000000009, 5123450000000010, 5301343343646807 |
| Challenge | CUP | 6211111111111111, 6211111111111112, 6211111111111113, 6220185812368496 |
| Challenge | JCB | 3566000000000007, 3566000000000008, 3566000000000009, 3551002170315397 |
| Challenge | Discover | 6011000000000007, 6011000000000008, 6011000000000009, 6011333861199759 |
| Challenge | Amex | 378282000000007, 378282000000008, 378282000000009, 375451138084787 |
| Failed | Visa | 4440000042200022, 4440000042200023, 4440000042200024, 4929279885499335 |
| Failed | Mastercard | 5500005555555556, 5500005555555557, 5500005555555558, 5304954783585409 |
| Failed | CUP | 6282900000000004, 6282900000000005, 6282900000000006, 6263449802590909 |
| Failed | JCB | 3566000000000004, 3566000000000005, 3566000000000006, 3540289411430986 |
| Failed | Discover | 6011000000000004, 6011000000000005, 6011000000000006, 6011783546569364 |
| Failed | Amex | 378282000000004, 378282000000005, 378282000000006, 375979278069549 |
transaction_type
| Field value | Description |
|---|---|
| sale | Sale |
| refund | Refund |
| void | Void |
| tips | Tips Adjust |
| pre_auth | Pre Authentication |
| pre_auth_complete | Pre Authrntication Complete |
| increment_pre_auth | Pre Authentication Increasement |
payment_method
| Field value | Description |
|---|---|
| credit_card | By credit card |
| fps | HKFPS:Merchant Present QR code |
| tap_go | By Tap&go wallet |
| wechat_pay | Wechat Pay |
| alipay | Alipay |
| octopus_business | Octopus |
transaction_state
| Field value | Description |
|---|---|
| success | Transaction Succeed |
| pending | Transaction Pending, waiting for processing |
| failed | Transaction Failed |
acquire_type
| Field value | Description |
|---|---|
| visa | VISA |
| mastercard | MasterCard |
| cup | CUP |
| amex | AMEX |
| jcb | JCB |
| discover | Discover |
Error Code And Error mssage
| Error Code | Error Message | Solutions |
|---|---|---|
| "100000" | Success | |
| "100001" | Parameters Error | Request parameter error, please check the payment type or value, and then try again. |
| "100003" | Merchant Account Is Disable. Please Contact Your Payment Process Service Provider | Please contact your payment processing service provider |
| "100005" | Processing Rule Required. Please Contact Your Payment Process Service Provider | Please contact your payment processing service provider |
| "100007" | Terminal TID is Busy. Please Try Again Later | Please try again |
| "100011" | Risk Flagged. Please Contact Your Payment Process Service Provider | 1.Please Check whether the IP address of Pre-create and called JS SDK are the same. 2.Please contact your payment processing service provider |
| "100013" | No Record | |
| "100015" | Transaction Amount Exceeded | Please check the amount of payment or duplicate payment. |
| "100016" | The Currency Is Not Matched | Please check the value of currency. |
| "110010" | Time-Out Payment Failed | Please reprocess the pre-create orders and pay again. |
| "100024" | Order Closing | |
| "110001" | Fraud Card Detected and Rejected. | Please try again with other cards |
| "110003" | Rejected By Issuer | Transaction rejected by issuer, please try again with other cards. |
| "110004" | Insufficient Funds. Please Make Sure The Card Has Sufficient Amount or To Process The Payment With Other Cards | Please try again with other cards |
| "110007" | Bank Key Not Active | Please contact your payment processing service provider |