> ## Documentation Index > Fetch the complete documentation index at: https://doc.haipay.net/llms.txt > Use this file to discover all available pages before exploring further. # International Credit Card (VISA/MASTER) **Before reading this API documentation, be sure to review the [**API Description Guide**](/docs/en/guide/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.** 1. PCI Compliance: Direct violation of PCI DSS requirements 2. Security Risks: WebView and iframe may not provide sufficient security isolation 3. Man-in-the-Middle Attacks: Malicious applications may intercept or tamper with payment data 4. 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](https://support.apple.com/en-us/102896) and [Google Pay devices](https://developers.google.com/pay/issuers/overview/supported-devices#compatibility_requirements). * You must use **HTTPS** and [supported browsers](#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](https://support.apple.com/en-us/102626#:~:text=iPhone%20or%20.iPad,on%20all%20devices.). **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 Notes** For 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 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 ## 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 | 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** Merchant server sends a [Collection Application](#1-collection-application) request to HaiPay, passing required parameters such as transaction amount, payment method, callback URLs, and optional `cancelUrl`. The API response contains a `payUrl` field. Merchant redirects the user's browser to this URL. 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)** ```javascript theme={null} // 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: 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. **Script** `https://cashier.haipay.top/js/composite-component_1.0.0.min.js` **Parameters** | 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. ```javascript theme={null}
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. **Script** `https://cashier.haipay.top/js/applePayGooglePay_1.0.0.min.js` **Parameters** | 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) ```javascript theme={null}
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. **Script** `https://cashier.haipay.top/js/creditCard_1.0.0.min.js` **Parameters** | 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) ```javascript theme={null}
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](/docs/en/guide/frequently_asked_question#phone_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) | | inBankCode | Yes | String | [Payment method code](#inBankCode) | | 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** ```json theme={null} { "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** ```json theme={null} { "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](#haipaysdk)) | | sign | String | Signature | ### **2. Collection Application [MIT Mode](#mit)** **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](/docs/en/guide/frequently_asked_question#en_faq_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) | | inBankCode | Yes | String | [Payment method code](#inBankCode) | | 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** ```json theme={null} { "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** ```json theme={null} { "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](#haipaysdk)) | | 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** ```json theme={null} { "appId": 1054, "orderId": "M22222000028", "sign": "EmyJGm3ELzG4FsOd0Krs9ncbSjo4oTGuXWML+7djYla3+VAwd9wS17z38p/7U2ZAjroO04XrE7YXcB1o76Dtyipj3h3bJzs7FYma1QNkMUdt9hh7m8U6hMsMQX7vIWHtXNwz4pbTSC75+kQWXaCew7KoE6LXECdJU8AISgNgeki2TK9R0pCfshr0Z2SZBPeuT6OvIH5LdmqgdZhuqnffGU2qnXk4KMkO848e6/WALLBR+LE1wyKHfPnYVcuKSMVYxkvKyyIL5JIPEgW0o5bh4RCbaUn3NZtyYwrU1uQ3ZDFRThm9j6XAQP+LBlmq3nOePqBtp/VDVarRaV+7FbQg3A==" } ``` **Response Example** ```json theme={null} { "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 1. **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. 2. **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. 3. **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. #### MIT Flow Diagram ```mermaid theme={null} flowchart TD A["User: order on merchant platform"] --> B{"Transaction Type Judgment"} N["Payment Callback"] O["Merchant: Provides service/ships goods
 "] P["Merchant: Notifies user of payment failure
 "] subgraph S2 ["Scenario 2: Subsequent Transactions"] direction TB I["Subsequent Transaction"] --> J["Merchant: Sends transaction request and token to Haipay
 "] J --> K{"Haipay: Verifies token"} K -->|Valid| L["Haipay: Executes automatic deduction
 "] L --> N K -->|Invalid/Failed| M["Payment Failed"] M --> P end subgraph S1 ["Scenario 1: First Transaction"] direction TB C["First Transaction"] --> D["Haipay: Provides payment link"] D --> E["User: Confirms payment"] E --> F["Payment Success"] F --> G["Haipay: Generates secure token
(binds user and merchant)
 "] G --> N N --> O end B --> C B --> I ``` ## Related Topics * [Common API](/docs/en/api/version2/CommonApi) * [HaiPay API Description and Common Rules](/docs/en/guide/api_description_guide) * [PCI Payment Interface](/docs/en/api/version2/creditcard-pci)