International Credit Card (VISA/MASTER)

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

For credit card transactions, consumers maintain the right to initiate a dispute within 180 days of the charge date. When a dispute is filed, a dispute fee of $20 will be assessed per transaction.
Upon receiving a dispute notification, you have two options for response
- First: you may accept the dispute by submitting a response to the issuing bank affirming that you do not contest the refunded amount.
- Second, you may counter the dispute by completing a guided submission process that prompts you to provide relevant evidence and supporting documentation for your case.
Should you elect to counter a dispute, an additional dispute countered fee of $20 will be applied. In the event that the issuing bank does not accept your counter materials and rules in favor of the consumer, both the dispute countered fee will be deducted and the consumer’s payment will be refunded to them.
Regarding fee refunds, Haipay will return the dispute countered fee if you successfully win the dispute. However, unless explicitly stated otherwise in your Haipay contract, the initial dispute fee is non-refundable under all circumstances.

PCI Compliance: Direct violation of PCI DSS requirements
Security Risks: WebView and iframe may not provide sufficient security isolation
Man-in-the-Middle Attacks: Malicious applications may intercept or tamper with payment data
Phishing Risks: Cannot ensure users are entering sensitive information in a trusted environment

Device Environment Requirements

If you cannot see the wallet you want on the payment page, your device or browser may not meet the following Apple Pay or Google Pay requirements.

You must have at least one card in your wallet.
You must use compatible Apple Pay devices and Google Pay devices.
You must use HTTPS and supported browsers to test the wallet you are testing.
Allow applicable browsers to access your wallet.
- Chrome: Settings > Autofill and passwords > Payment methods > Allow sites to check if you have saved payment methods
- Safari: Settings > Advanced > Allow websites to check for Apple Pay and Apple Card
Do not use Chrome incognito window or Safari private window.
Confirm you are operating in supported Apple Pay and Google Pay regions.
For Apple Pay, confirm your device supports biometric authentication.

Desktop Browsers

Chrome 38+
Safari 10.1+
Firefox 29+
Edge 15+
Opera 25+

Mobile Browsers

iOS Safari 9+ and other browsers and web views using the system-provided WebKit engine
Android Chrome 38+
Samsung Browser 7.1+

Other NotesFor browsers not explicitly supported, we limit support as follows:

Requires browser support for TLS 1.2
Requires a sufficiently modern browser to support Promises in JavaScript
We respond to error reports but do not actively test other browsers

Regional Restrictions

Unsupported Regions List

AD - AndorraAE - United Arab EmiratesAF - AfghanistanAG - Antigua and BarbudaAI - AnguillaAL - AlbaniaAM - ArmeniaAO - AngolaAQ - AntarcticaAR - ArgentinaAS - American SamoaAW - ArubaAX - Åland IslandsBA - Bosnia and HerzegovinaBB - BarbadosBD - BangladeshBF - Burkina FasoBH - BahrainBI - BurundiBJ - BeninBL - Saint BarthélemyBM - BermudaBN - BruneiBQ - Bonaire, Sint Eustatius, and SabaBS - BahamasBT - BhutanBV - Bouvet IslandBW - BotswanaBY - BelarusBZ - BelizeCC - Cocos (Keeling) IslandsCD - Democratic Republic of the CongoCF - Central African RepublicCG - Republic of the CongoCI - Ivory CoastCK - Cook IslandsCM - CameroonCO - ColombiaCU - CubaCV - Cape VerdeCW - CuraçaoCX - Christmas IslandCY - CyprusDJ - DjiboutiDM - DominicaDO - Dominican RepublicDZ - AlgeriaEC - EcuadorEE - EstoniaEG - EgyptEH - Western SaharaER - EritreaET - EthiopiaFJ - FijiFK - Falkland IslandsFM - Federated States of MicronesiaFO - Faroe IslandsGA - GabonGD - GrenadaGE - GeorgiaGF - French GuianaGG - GuernseyGH - GhanaGI - GibraltarGL - GreenlandGM - GambiaGN - GuineaGP - GuadeloupeGQ - Equatorial GuineaGS - South Georgia and the South Sandwich IslandsGT - GuatemalaGW - Guinea-BissauHK - Hong KongHM - Heard Island and McDonald IslandsHN - HondurasHT - HaitiID - IndonesiaIL - IsraelIM - Isle of ManIN - IndiaIO - British Indian Ocean TerritoryIQ - IraqIR - IranJM - JamaicaJO - JordanJP - JapanKE - KenyaKH - CambodiaKI - KiribatiKM - ComorosKN - Saint Kitts and NevisKP - North KoreaKR - South KoreaKW - KuwaitKY - Cayman IslandsKZ - KazakhstanLA - LaosLB - LebanonLC - Saint LuciaLI - LiechtensteinLK - Sri LankaLR - LiberiaLS - LesothoLV - LatviaLY - LibyaMD - MoldovaME - MontenegroMF - Saint Martin (French part)MG - MadagascarMH - Marshall IslandsMK - North MacedoniaML - MaliMM - MyanmarMN - MongoliaMP - Northern Mariana IslandsMQ - MartiniqueMR - MauritaniaMS - MontserratMU - MauritiusMV - MaldivesMW - MalawiMY - MalaysiaMZ - MozambiqueNA - NamibiaNC - New CaledoniaNE - NigerNF - Norfolk IslandNG - NigeriaNI - NicaraguaNP - NepalNR - NauruNU - NiueOM - OmanPA - PanamaPE - PeruPF - French PolynesiaPG - Papua New GuineaPH - PhilippinesPK - PakistanPM - Saint Pierre and MiquelonPN - Pitcairn IslandsPR - Puerto RicoPS - PalestinePW - PalauRE - RéunionRU - RussiaRW - RwandaSA - Saudi ArabiaSB - Solomon IslandsSC - SeychellesSD - SudanSH - Saint HelenaSJ - Svalbard and Jan MayenSK - SlovakiaSL - Sierra LeoneSM - San MarinoSN - SenegalSO - SomaliaSR - SurinameSS - South SudanST - São Tomé and PríncipeSV - El SalvadorSX - Sint Maarten (Dutch part)SY - SyriaSZ - EswatiniTC - Turks and Caicos IslandsTD - ChadTF - French Southern TerritoriesTG - TogoTH - ThailandTK - TokelauTL - East TimorTM - TurkmenistanTN - TunisiaTO - TongaTR - TurkeyTT - Trinidad and TobagoTV - TuvaluTW - TaiwanTZ - TanzaniaUA - UkraineUG - UgandaUM - United States Minor Outlying IslandsUY - UruguayUZ - UzbekistanVA - Vatican CityVC - Saint Vincent and the GrenadinesVE - VenezuelaVG - British Virgin IslandsVI - U.S. Virgin IslandsVN - VietnamVU - VanuatuWF - Wallis and FutunaWS - SamoaYE - YemenYT - MayotteZA - South AfricaZM - ZambiaZW - Zimbabwe

Integration Modes

Credit card payment offers two integration modes, the key difference being who hosts the payment page:

Comparison	PayUrl Redirect Mode	JS Embedded Mode
Payment Page	Redirects to HaiPay-hosted payment page	Embeds payment components in merchant’s own page
Frontend Effort	Almost zero, only handle redirect	Need to import JS script and listen to events
UI Control	Low, page style controlled by HaiPay	High, customizable theme, layout and interaction
Key Response Field	Use `payUrl` from response	Use `clientToken` from response
Use Case	Quick integration, no customization needed	Custom checkout, immersive payment experience

PayUrl Redirect Mode
JS Embedded Mode

The simplest integration method. After the merchant server calls the collection application API, use the returned payUrl to redirect the user to HaiPay’s hosted payment page, where the user completes credit card information entry and payment authorization.Integration Process

Server calls collection application API

Merchant server sends a Collection Application request to HaiPay, passing required parameters such as transaction amount, payment method, callback URLs, and optional cancelUrl.

Get payUrl and redirect

The API response contains a payUrl field. Merchant redirects the user’s browser to this URL.

User completes payment

User completes credit card information entry and payment authorization on HaiPay’s hosted page. After payment, HaiPay redirects the user back to the merchant’s callBackUrl; if provided, the payment page displays a Back button that redirects the user to cancelUrl when clicked; HaiPay also sends an async notification to notifyUrl.

Example Code (Frontend redirect after server obtains payUrl)

// Assume your server has called the collection application API and returned payUrl to the frontend
const payUrl = response.data.payUrl;

// Redirect in current window
window.location.href = payUrl;

// Or open in a new window
// window.open(payUrl, '_blank');

Recommendations

Ideal for the fastest payment integration with minimal frontend changes.
No strong customization requirements for the payment page UI.
In mobile H5 scenarios, the redirect experience typically meets requirements.

By importing HaiPay JS scripts, payment components are embedded directly in the merchant’s page. The merchant server calls the collection application API to obtain a clientToken, and the frontend uses this token to initialize the component. Users can complete payment on the current page without redirection.The JS provides the following component types. Choose based on your checkout design requirements:

Custom Combined Mode
Apple Pay / Google Pay (Deprecated Soon)
Credit Card (Deprecated Soon)

Displays Google Pay, Apple Pay, and Credit Card in a single container. Supports switching between one-time payment and subscription payment via the mode parameter. Ideal for merchants who need unified management of multiple payment scenarios.Scripthttps://cashier.haipay.top/js/composite-component_1.0.0.min.jsParameters

Parameter	Required	Description
`sandbox`	Yes	`true` for test environment, `false` for production
`clientToken`	Yes	Client token returned from collection application API
`mode`	Yes	Payment scenario: `payment` (one-time payment) or `subscription` (subscription payment)
`showPayButton`	No	Whether to display the credit card submit button. Default: `false` (hidden)
`themeMode`	No	Theme mode, options: `light` / `dark`, default `light`
`paymentMethodConfig`	No	Payment method combination, default `["GOOGLE_PAY","APPLE_PAY","CREDIT_CARD"]`
`applePayButtonType`	No	Apple Pay button text, options: `buy`, `subscribe`, etc.
`googlePayButtonType`	No	Google Pay button text, options: `buy`, `subscribe`, etc.
`cardPosition`	No	Credit card placement position, default `bottom`, options: `bottom`, `top`

Events

ready — Component rendered successfully, ready for interaction
error — Initialization failed or payment error occurred
confirm — Form submission result (success/failure)
paymentStatus — Payment result notification, failure will return error message (if not listened, the component will handle result display automatically)
paymentMethodType — Currently selected payment method

Recommendations

Recommended as the first choice for new checkout pages — cleaner structure, lower development cost.
To enable only specific payment methods, simply pass the desired combination.

<script src="https://cashier.haipay.top/js/composite-component_1.0.0.min.js"></script>

<div>
  <div id="paymentId"></div>
</div>

const elements = haiPay.create({
  mode: 'payment',
  sandbox: true,
  clientToken: 'your-client-token',
  themeMode: 'light',
  paymentMethodConfig: ['GOOGLE_PAY', 'APPLE_PAY', 'CREDIT_CARD']
});

elements.mount('#paymentId');

elements.on('ready', (event) => {
  console.log('rendered successfully:', event);
});

elements.on('error', (event) => {
  console.error('Payment error:', event);
});

elements.on('paymentMethodType', (event) => {
  console.log('payment method type', event);
});

elements.submitCardPayment();

elements.on('confirm', (event) => {
  console.log('confirm:', event);
});

elements.on('paymentStatus', (event, message) => {
  console.log('payment status:', event, message);
});

This component will be deprecated soon. Please use “Custom Combined Mode” instead.

Suitable for scenarios where you already have a wallet payment entry and want to quickly trigger Apple Pay / Google Pay authorization.Scripthttps://cashier.haipay.top/js/applePayGooglePay_1.0.0.min.jsParameters

Parameter	Required	Description
`sandbox`	Yes	`true` for test environment, `false` for production
`clientToken`	Yes	Client token returned from collection application API
`buttonType`	No	Button text type, options: `plain`, `buy` (default), `check-out`, `subscribe`, etc.
`buttonTheme`	No	Button theme, options: `black` (default), `white`
`buttonHeight`	No	Button height (px), default `50`

Events

ready — Button rendered successfully, ready for interaction
error — Initialization failed or payment error occurred
paymentStatus — Payment result notification (if not listened, the component will handle result display automatically)

<script src="https://cashier.haipay.top/js/applePayGooglePay_1.0.0.min.js"></script>

<div>
  <div id="applePay-googlePay"></div>
</div>

const elements = applePayGooglePay.create('applePayGooglePay', {
  sandbox: true,
  clientToken: 'your-client-token',
  buttonType: 'buy',
  buttonTheme: 'black',
  buttonHeight: 50
});

elements.mount('#applePay-googlePay');

elements.on('ready', (data) => {
  console.log('Button rendered successfully:', data);
});

elements.on('error', (data) => {
  console.error('Payment error:', data);
});

elements.on('paymentStatus', (data) => {
  console.log('payment status:', data);
});

This component will be deprecated soon. Please use “Custom Combined Mode” instead.

Suitable for scenarios that require directly displaying a credit card payment form with merchant-controlled submission timing.Scripthttps://cashier.haipay.top/js/creditCard_1.0.0.min.jsParameters

Parameter	Required	Description
`sandbox`	Yes	`true` for test environment, `false` for production
`clientToken`	Yes	Client token returned from collection application API
`cardTheme`	No	Form theme, options: `black`, `white` (default)

Events

ready — Credit card form rendered successfully, ready for interaction
confirm — Form submission result (success/failure)
paymentStatus — Payment result notification (if not listened, the component will handle result display automatically)

<script src="https://cashier.haipay.top/js/creditCard_1.0.0.min.js"></script>

<div>
  <div id="creditCardId"></div>
</div>

const elements = creditCard.create('card', {
  sandbox: true,
  clientToken: 'your-client-token',
  cardTheme: 'white'
});

elements.mount('#creditCardId');

elements.on('ready', (data) => {
  console.log('Card rendered successfully:', data);
});

elements.on('error', (data) => {
  console.error('Payment error:', data);
});

elements.submit();

elements.on('confirm', (data) => {
  console.log('confirm:', data);
});

elements.on('paymentStatus', (data) => {
  console.log('payment status:', data);
});

Common Errors

Error Message	Error Cause	Solution
Missing required parameters: env, orderNo	Missing required initialization parameters	Check if `clientToken` and other parameters are correctly passed
Unsupported region: CN	Production environment does not support China region	Verify merchant configuration and target market

Transaction Limits

Transaction Type	Limit (USD)
Collection	0.99-1000

Collection API

1. Collection Application

Brief Description:

Create a collection order

URL: USD: /usd/collect/apply Note: appId for USD, amount in USD, settlement in USD Parameters:

Parameter Name	Required	Type	Description
appId	Yes	Long	Business ID (obtained from backend, must pass corresponding business ID based on currency in URL)
orderId	Yes	String	Merchant order number (must be unique, length not exceeding 48)
name	No	String	User name, recommended to use real name, format: firstName and lastName separated by space, example: John Doe
phone	Yes	String	Real phone number (format reference Phone Number Format)
email	No	String	Real email address
amount	Yes	String	Transaction amount (accurate to two decimal places; do not add punctuation, e.g., ”,“)
payType	Yes	String	Payment method type
inBankCode	Yes	String	Payment method code
clientIp	No	String	Client IP address
callBackUrl	Yes	String	URL to redirect after successful payment
callBackFailUrl	Yes	String	URL to redirect after failed payment
cancelUrl	No	String	If provided, the payment page displays a Back button that redirects the user to this URL when clicked.
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 real and valid, otherwise it will affect transactions. Format requirements: digits, uppercase and lowercase letters or common symbols -~!@#$%&*()_.
paymentMethods	No	String	Supported payment method list, separated by English commas, e.g., CREDIT_CARD,GOOGLE_PAY,APPLE_PAY
sign	Yes	String	Signature

Request Example

{
  "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 Example

{
  "status": "1",
  "error": "00000000",
  "msg": "",
  "data": {
    "orderId": "M233323000059",
    "orderNo": "6023071013539074",
    "payUrl": "",
    "clientToken": "",
    "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 link
bankCode	String	Payment Method Code
clientToken	String	Client token used in JavaScript Web SDK (see HaiPaySDK.js)
sign	String	Signature

2. Collection Application MIT Mode

Brief Description:

Create MIT mode collection order

URL: USD: /usd/mit/apply Note: appId for USD, amount in USD, settlement in USD Parameters:

Parameter Name	Required	Type	Description
appId	Yes	Long	Business ID (obtained from backend, must pass corresponding business ID based on currency in URL)
orderId	Yes	String	Merchant order number (must be unique, length not exceeding 48)
name	No	String	User name, recommended to use real name, format: firstName and lastName separated by space, example: John Doe
phone	No	String	Real phone number (format reference Phone Number Format)
email	No	String	Real email address
amount	Yes	String	Transaction amount (accurate to two decimal places; do not add punctuation, e.g., ”,“)
payType	Yes	String	Payment method type
inBankCode	Yes	String	Payment method code
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 real and valid, otherwise it will affect transactions. Format requirements: digits, uppercase and lowercase letters or common symbols -~!@#$%&*()_.
tokenID	No	String	Payment token, not required for first transaction, required for subsequent active deductions, obtained through callback
loadingType	No	Integer	0 (default) – Display the current/normal payment result view; 1 – Show a loading spinner with no order information.
cancelUrl	No	String	If provided, the payment page displays a Back button that redirects the user to this URL when clicked.
paymentMethods	No	String	Supported payment method list, separated by English commas, e.g., CREDIT_CARD,GOOGLE_PAY,APPLE_PAY
sign	Yes	String	Signature

Request Example

{
  "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 Example

{
  "status": "1",
  "error": "00000000",
  "msg": "",
  "data": {
    "orderId": "M233323000059",
    "orderNo": "6023071013539074",
    "payUrl": "",
    "clientToken": "",
    "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 link
clientToken	String	Client token used in JavaScript Web SDK (see HaiPaySDK.js)
sign	String	Signature

3. 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 backend, must pass corresponding business ID based on currency in URL)
orderId	Yes	String	Merchant order number
orderNo	No	String	Platform order number (faster response)
sign	Yes	String	Signature

Request Example

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

Response Example

{
  "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), 3 - Failure (final), -1 - Pending confirmation)
payTime	String	Payment success time (present when status=2) (local time), format: yyyy-MM-dd HH:mm:ss
errorMsg	String	Payment failure reason (present when status=3)
sign	String	Signature

4. Refund Application

Brief Description:

Initiate a refund operation for the original credit card transaction order. Please 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 backend, must pass corresponding business ID based on currency in URL)
orderId	Yes	String	Merchant refund application order number (new merchant order number, cannot use original collection merchant order number)
orderNo	Yes	String	Platform order number (original collection platform order number returned)
refundAmount	No	String	Optional, will issue full refund if not provided
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 returns processing, status needs to be checked via query interface later
errorMsg	String	Error message (may not always have a value)
sign	String	Signature

5. 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 backend, must pass corresponding business ID based on currency in URL)
orderId	No	String	Merchant refund application order number
refundNo	No	String	Platform refund number (platform order number returned when 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. Refund result is based on this status
errorMsg	String	Error message (may not always have a value)
refundAmount	String	Refund amount
sign	String	Signature

6. Payment Methods

Currency	Payment Type (payType)	Payment Code (inBankCode)	Limits	Status	Description
USD	BANK_TRANSFER	CREDIT_CARD	0.99-1000	Available	VISA
USD	BANK_TRANSFER	CREDIT_CARD	0.99-1000	Available	MasterCard
USD	BANK_TRANSFER	CREDIT_CARD	0.99-1000	Available	JCB
USD	EWALLET	GOOGLE_PAY	0.99-1000	Available	Google Pay
USD	EWALLET	APPLE_PAY	0.99-1000	Available	Apple Pay

7. Test Card Numbers

For use in test environment only

Simulate Successful Payment

Use the following test card numbers, enter any CVC (3-digit number) and expiration date (future date) to simulate 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

8. MIT (Merchant Initiated Transaction) Mode Description

MIT (Merchant Initiated Transaction) Refers to transactions that merchants can initiate without the user being present after the user completes a one-time payment authorization. This mode is widely used in business scenarios such as subscription payments, installment payments, membership renewals, delayed deductions, etc.

Basic Process

User Authorization
- User enters payment information during the first payment and completes necessary identity verification.
- Merchant saves the user’s payment credentials for subsequent deduction requests.
Merchant-Initiated Deduction
- Merchant directly uses saved payment credentials to initiate deduction requests based on agreed cycles or conditions.
- Since the transaction is an offline scenario (off-session), meaning the user is not involved in the transaction, the system will complete processing based on user authorization and compliance requirements.
Authentication Requirements
- In most cases, transactions will complete directly.
- If the issuing bank or risk control system requires re-verification, the transaction may enter a pending user confirmation state, requiring user supplementary verification to complete.

Mode Features

Enhanced Experience: Users don’t need to manually enter payment information each time.
Compliant and Secure: Meets international payment regulations and Strong Customer Authentication (SCA) requirements.
Wide Application: Suitable for subscription billing, auto-renewal, installment deductions, delayed settlement, etc.

Quick start

Merchant Guide

Common Payment

Global Payment

Unified API

End To End Testing

Appendix

Merchant FAQ

International Credit Card (VISA/MASTER)

Device Environment Requirements

Regional Restrictions

Integration Modes

Transaction Limits

Collection API

1. Collection Application

2. Collection Application MIT Mode

3. Collection Query

4. Refund Application

5. Refund Query

6. Payment Methods

7. Test Card Numbers

Simulate Successful Payment

Simulate Payment Failure

8. MIT (Merchant Initiated Transaction) Mode Description

Basic Process

Mode Features

MIT Flow Diagram

​Device Environment Requirements

​Regional Restrictions

​Integration Modes

​Transaction Limits

​Collection API

​1. Collection Application

​2. Collection Application MIT Mode

​3. Collection Query

​4. Refund Application

​5. Refund Query

​6. Payment Methods

​7. Test Card Numbers

​Simulate Successful Payment

​Simulate Payment Failure

​8. MIT (Merchant Initiated Transaction) Mode Description

​Basic Process

​Mode Features

​MIT Flow Diagram

​Related Topics

Device Environment Requirements

Regional Restrictions

Integration Modes

Transaction Limits

Collection API

1. Collection Application

2. Collection Application MIT Mode

3. Collection Query

4. Refund Application

5. Refund Query

6. Payment Methods

7. Test Card Numbers

Simulate Successful Payment

Simulate Payment Failure

8. MIT (Merchant Initiated Transaction) Mode Description

Basic Process

Mode Features

MIT Flow Diagram

Related Topics