International Credit Card (VISA/MASTER) Payment API

About 1485 wordsAbout 5 min

Warning

Before reading this API documentation, be sure to review the API Description Guide

Warning

The following regions are prohibited from using the service!!!

Prohibited Regions List

AD - Andorra
AE - United Arab Emirates
AF - Afghanistan
AG - Antigua and Barbuda
AI - Anguilla
AL - Albania
AM - Armenia
AO - Angola
AQ - Antarctica
AR - Argentina
AS - American Samoa
AW - Aruba
AX - Åland Islands
BA - Bosnia and Herzegovina
BB - Barbados
BD - Bangladesh
BF - Burkina Faso
BH - Bahrain
BI - Burundi
BJ - Benin
BL - Saint Barthélemy
BM - Bermuda
BN - Brunei
BQ - Bonaire, Sint Eustatius, and Saba
BS - Bahamas
BT - Bhutan
BV - Bouvet Island
BW - Botswana
BY - Belarus
BZ - Belize
CC - Cocos (Keeling) Islands
CD - Democratic Republic of the Congo
CF - Central African Republic
CG - Republic of the Congo
CI - Ivory Coast
CK - Cook Islands
CM - Cameroon
CO - Colombia
CU - Cuba
CV - Cape Verde
CW - Curaçao
CX - Christmas Island
CY - Cyprus
DJ - Djibouti
DM - Dominica
DO - Dominican Republic
DZ - Algeria
EC - Ecuador
EE - Estonia
EG - Egypt
EH - Western Sahara
ER - Eritrea
ET - Ethiopia
FJ - Fiji
FK - Falkland Islands
FM - Federated States of Micronesia
FO - Faroe Islands
GA - Gabon
GD - Grenada
GE - Georgia
GF - French Guiana
GG - Guernsey
GH - Ghana
GI - Gibraltar
GL - Greenland
GM - Gambia
GN - Guinea
GP - Guadeloupe
GQ - Equatorial Guinea
GS - South Georgia and the South Sandwich Islands
GT - Guatemala
GW - Guinea-Bissau
HK - Hong Kong
HM - Heard Island and McDonald Islands
HN - Honduras
HT - Haiti
ID - Indonesia
IL - Israel
IM - Isle of Man
IN - India
IO - British Indian Ocean Territory
IQ - Iraq
IR - Iran
JM - Jamaica
JO - Jordan
JP - Japan
KE - Kenya
KH - Cambodia
KI - Kiribati
KM - Comoros
KN - Saint Kitts and Nevis
KP - North Korea
KR - South Korea
KW - Kuwait
KY - Cayman Islands
KZ - Kazakhstan
LA - Laos
LB - Lebanon
LC - Saint Lucia
LI - Liechtenstein
LK - Sri Lanka
LR - Liberia
LS - Lesotho
LV - Latvia
LY - Libya
MD - Moldova
ME - Montenegro
MF - Saint Martin (French part)
MG - Madagascar
MH - Marshall Islands
MK - North Macedonia
ML - Mali
MM - Myanmar
MN - Mongolia
MP - Northern Mariana Islands
MQ - Martinique
MR - Mauritania
MS - Montserrat
MU - Mauritius
MV - Maldives
MW - Malawi
MY - Malaysia
MZ - Mozambique
NA - Namibia
NC - New Caledonia
NE - Niger
NF - Norfolk Island
NG - Nigeria
NI - Nicaragua
NP - Nepal
NR - Nauru
NU - Niue
OM - Oman
PA - Panama
PE - Peru
PF - French Polynesia
PG - Papua New Guinea
PH - Philippines
PK - Pakistan
PM - Saint Pierre and Miquelon
PN - Pitcairn Islands
PR - Puerto Rico
PS - Palestine
PW - Palau
RE - Réunion
RU - Russia
RW - Rwanda
SA - Saudi Arabia
SB - Solomon Islands
SC - Seychelles
SD - Sudan
SH - Saint Helena
SJ - Svalbard and Jan Mayen
SK - Slovakia
SL - Sierra Leone
SM - San Marino
SN - Senegal
SO - Somalia
SR - Suriname
SS - South Sudan
ST - São Tomé and Príncipe
SV - El Salvador
SX - Sint Maarten (Dutch part)
SY - Syria
SZ - Eswatini
TC - Turks and Caicos Islands
TD - Chad
TF - French Southern Territories
TG - Togo
TH - Thailand
TK - Tokelau
TL - East Timor
TM - Turkmenistan
TN - Tunisia
TO - Tonga
TR - Turkey
TT - Trinidad and Tobago
TV - Tuvalu
TW - Taiwan
TZ - Tanzania
UA - Ukraine
UG - Uganda
UM - United States Minor Outlying Islands
UY - Uruguay
UZ - Uzbekistan
VA - Vatican City
VC - Saint Vincent and the Grenadines
VE - Venezuela
VG - British Virgin Islands
VI - U.S. Virgin Islands
VN - Vietnam
VU - Vanuatu
WF - Wallis and Futuna
WS - Samoa
YE - Yemen
YT - Mayotte
ZA - South Africa
ZM - Zambia
ZW - Zimbabwe

Transaction Limits

Transaction Type	Limit (USD)
Collect Payment	0.99 - 1000

Collect API

1. Apply for Collect Payment

Brief Description:

Create a collect payment order.

URL:

USD: /usd/collect/apply Description: appId for USD, amount in USD, actual settlement in USD.

Parameters:

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (to be obtained in the backend, pass the appropriate ID based on URL currency)
orderId	Yes	String	Merchant order number (must be unique, length not exceeding 48 characters)
name	Yes	String	User name (recommended to use real name, format: firstName and lastName, separated by space)
phone	Yes	String	Real phone number (refer to Phone Number Format)
email	Yes	String	Real email address
amount	Yes	String	Transaction amount (accurate to two decimal places; do not add punctuation, e.g., “,”)
payType	Yes	String	BANK_TRANSFER
inBankCode	Yes	String	Payment Methods
clientIp	No	String	Client IP address
callBackUrl	Yes	String	URL to redirect after successful payment
callBackFailUrl	Yes	String	URL to redirect after failed payment
notifyUrl	No	String	Callback URL
subject	Yes	String	Payment remark
body	No	String	Remark details
partnerUserId	Yes	String	Unique user identifier (e.g., userId), used for risk control, must be valid. Format: digits, letters, or common symbols `-~!@#$%&*()`
sign	Yes	String	Signature

Request

{
    "appId": 1054,
    "orderId": "M233323000059",
    "amount": "300",
    "phone": "09230219312",
    "email": "23423@qq.com",
    "name": "test",
    "inBankCode": "USA",
    "payType": "BANK_TRANSFER",
    "partnerUserId": "149597870",
    "sign": "af0gAHkUOyYHu9owQp8NJ4mPEeUW4vuJcjdxqLIzrVw8AvpLSjD1DXupReSG/CyuSkFRyiIvCp5u703AuGGmfgD2gKDH3Ywau41bAbG2jnHJ8mtjiSJ5iWUzanyd4Kr7d1+rETbzUl7/BkW3t0X8UUFdqpxwG8DPUjAwUKfplWDHV7koG51Ozexd80DCsmW6eWdouAZ1uNXGLYmV3ftE3BmfNRtuv1C5bfTJWrTEIOxbF6g2uYOFZTlIgrQgd7/2PsAYwQQXNz8Q8CYl4OxqCv4pXJxaLWPbR5tqZu9og5kn32C9aHW/NlU1y39vzz+4ef81yPAqUV9oHlSMSPrMmw=="
}

response

{
    "status": "1",
    "error": "00000000",
    "msg": "",
    "data": {
        "orderId": "M233323000059",
        "orderNo": "6023071013539074",
        "payUrl": "",
        "sign": "YEoA8Y2JzQFGVzwJSqmemm1Kfv/bfyIfCqv2dp7RNzT5B72AQvdD+nt2nR4sL1HWscvmNHyVt5ovAi7MMhy3ziih/sMph+wPx4YjH3W1h5DyBvSlWvaKfKrK5ViomZ0pPYWydwRHnnRnicxToHK9S6qtSy7Q73O0hdz4hJ9p41Th3ycBl2Q9SeqSZYSY1ohcPDhdyRf2y0prb8rHgpBKzxZ5BKX/1bsE9OmsSEHAEYT8OGgko6aNe8XPAhr4G48cpWTftvnGQuzh0O65nuZRI/PF+Axt2zJCVbFHDDSREI9NlAT82ebDqhlVdxQzKE67D1nxgjb3dPmDUYHOBpmwxQ=="
    }
}

Response Data Parameter Description

Parameter Name	Type	Description
orderId	String	Merchant order number (must be unique)
orderNo	String	Platform order number
payUrl	String	Payment URL
sign	String	Signature

2. Collection Query

Brief Description:

Query collection order

URL:

USD: /usd/collect/query

Parameters:

Parameter Name	Required	Type	Description
appId	Yes	Long	Business ID (obtained from the backend, needs to be passed according to the currency type in the URL)
orderId	Yes	String	Merchant order number
orderNo	No	String	Platform order number (responds faster)
sign	Yes	String	Signature

Request Example

{
    "appId": 1054,
    "orderId": "M22222000028",
    "sign": "EmyJGm3ELzG4FsOd0Krs9ncbSjo4oTGuXWML+7djYla3+VAwd9wS17z38p/7U2ZAjroO04XrE7YXcB1o76Dtyipj3h3bJzs7FYma1QNkMUdt9hh7m8U6hMsMQX7vIWHtXNwz4pbTSC75+kQWXaCew7KoE6LXECdJU8AISgNgeki2TK9R0pCfshr0Z2SZBPeuT6OvIH5LdmqgdZhuqnffGU2qnXk4KMkO848e6/WALLBR+LE1wyKHfPnYVcuKSMVYxkvKyyIL5JIPEgW0o5bh4RCbaUn3NZtyYwrU1uQ3ZDFRThm9j6XAQP+LBlmq3nOePqBtp/VDVarRaV+7FbQg3A=="
}

response

{
    "status": "1",
    "error": "00000000",
    "msg": "",
    "data": {
        "orderId": "M22222000028",
        "orderNo": "6023042811314347",
        "amount": "50.00",
        "actualAmount": "0.00",
        "fee": "0.00",
        "status": 1,
        "sign": "fP433ygWVDLVGxYkVnIJj7riGq0U3vyVX+MbBAImxfGLZkZcEAHVEoVYuULZSmXAAXKRSyd67WlDNm+24pougM54ofAoH4HMtCL2tfCoBReFyz3z02AGKkrKE2xWhSpWoqfQoBvzwuN5iGMMu0s9Q1YvqiwJ8WDVIENnmiIyD8qDJN7caHTW2US14/faG+69AvnuIgJ/nu7/jogOlgEYdZdVYU7gcRDE+d47KjlFGswQkJ/h/uzV7cWtUqrtOO7ZnZ3/z33Xx8awokX36QoYcPSWAU0h+Ij9O9402HNhm1eTbYcLU0uI/z8xCAtyAI/tTyiFijpiNlxUKQj+zKsILw=="
    }
}

Response Data Parameter Description

Parameter Name	Type	Description
orderId	String	Merchant order number (must be unique)
orderNo	String	Platform order number
amount	String	Transaction amount
actualAmount	String	Amount received
fee	String	Handling fee
status	Integer	Status (0 - Not started, 1 - In progress, 2 - Success (final state), 3 - Failure (final state), -1 - Pending confirmation)
payTime	String	Payment success time (available when status=2) (local time), format: yyyy-MM-dd HH:mm:ss
errorMsg	String	Payment failure reason (available when status=3)
sign	String	Signature

3. Refund Application

Brief Description:

Initiate a refund operation for the original credit card transaction order. Pay attention to the status values returned synchronously. It is recommended to use the query interface for status checks.

URL:

USD: /usd/refund/apply

Parameters:

Parameter Name	Required	Type	Description
appId	Yes	Long	Business ID (obtained from the backend, needs to be passed according to the currency type in the URL)
orderId	Yes	String	Merchant refund application order number (new merchant order number, cannot use the original collection merchant order number)
orderNo	Yes	String	Platform order number (original collection platform order number returned)
sign	Yes	String	Signature

Response Data Parameter Description

Parameter Name	Type	Description
appId	String	Business ID
orderNo	String	Platform order number (original collection platform order number returned)
orderId	String	Merchant refund application order number
refundNo	String	Platform refund number for this refund
status	String	Refund status: 1 indicates refund application success, 0 indicates processing, 2 indicates failure. Initially, it returns processing; the status needs to be checked via the query interface later
errorMsg	String	Error message (may not always have a value)
sign	String	Signature

4. Refund Query

Brief Description:

Query the result of the refunded order.

URL:

USD: /usd/refund/refundQuery

Parameters:

Parameter Name	Required	Type	Description
appId	Yes	Long	Business ID (obtained from the backend, needs to be passed according to the currency type in the URL)
orderId	No	String	Merchant refund application order number
refundNo	No	String	Platform refund number (the platform order number returned when the refund was applied. If provided, prioritize checking this field)
sign	Yes	String	Signature

Response Data Parameter Description

Parameter Name	Type	Description
appId	String	Merchant order number (must be unique)
orderNo	String	Platform order number (original collection platform order number)
orderId	String	Merchant application order number
refundNo	String	Platform refund number
status	String	Refund status: 1 indicates refund application success, 0 indicates processing, 2 indicates failure. The refund result is based on this status
errorMsg	String	Error message (may not always have a value)
sign	String	Signature

Payment Methods

payType	inBankCode	Limit	Description
BANK_TRANSFER	CREDIT_CARD	(0.99-1000)	Only supports USD orders, credit cards (VISA, MasterCard)
EWALLET	APPLE_PAY	(0.99-1000)	Only supports USD orders, Apple Pay
EWALLET	GOOGLE_PAY	(0.99-1000)	Only supports USD orders, Google Pay

Test Card Numbers

Warning

For use in the test environment only

Simulate Successful Payment

Use the following test card number, enter any CVC (3-digit) and expiration date (future date) to simulate a successful payment:

Card Number 1: 4242424242424242

Simulate Payment Failure

Use the following test card numbers with invalid data to simulate payment failure:

Card Number 1: 4000000000009995
Invalid Month: 13
Invalid CVV: 99