> ## 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. # Credit Card Payments (VISA/MASTER CARD) > [!WARNING] > > **Before reading this API documentation, be sure to review the [**API Description Guide**](https://doc.haipay.net/docs/en/guide/api_description_guide.md)** > [!TIP] > > * **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.** > [!CAUTION] > > 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 > [!TIP] > > 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.). > [!TIP] > > **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 > **Unsupported 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 ## 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** 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** **1. Server calls collection application API** 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`. **2. Get payUrl and redirect** The API response contains a `payUrl` field. Merchant redirects the user's browser to this URL. **3. 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)** ```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. **JS Embedded Mode** 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** 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); }); ``` **Apple Pay / Google Pay (Deprecated Soon)** > [!WARNING] > > 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); }); ``` **Credit Card (Deprecated Soon)** > [!WARNING] > > 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](https://doc.haipay.net/docs/en/guide/frequently_asked_question.md#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 | | 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": "299.99", "phone": "02012345678", "email": "robert.taylor@gmail.com", "name": "Robert Taylor", "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](#haipaycdn)) | | 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](https://doc.haipay.net/docs/en/guide/frequently_asked_question.md#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": "299.99", "phone": "02012345678", "email": "robert.taylor@gmail.com", "name": "Robert Taylor", "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](#haipaycdn)) | | 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": "299.99", "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 > [!WARNING] > > **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](https://doc.haipay.net/docs/en/api/version2/CommonApi.md) * [HaiPay API Description and Common Rules](https://doc.haipay.net/docs/en/guide/api_description_guide.md) * [PCI Payment Interface](https://doc.haipay.net/docs/en/api/version2/creditcard-pci) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.