Acquiring Payment Create Resource

This resource describes the data structure of the payment order creation result in the acquiring business scenario, including core order information, status, associated merchant/ticket details, and next-step operation guidance. It is mainly used for returning payment order creation results to merchants or internal systems.

Example JSON

{
  "tradeNo": "PAY2025081500001",
  "merchantTradeNo": "MCH2025081500001",
  "amount": 399.50,
  "currency": "USD",
  "orderStatus": "READY",
  "orderType": "PAYMENT",
  "createTime": "1750000000000",
  "completeTime": null,
  "chargeToken": "ch_tok_64b8e321a7c8231f9d0e",
  "actions": {
    "redirectToPay": "https://payment-gateway.interlace.money/pay/123456789",
    "redirectTo3DS": "https://payment-3ds.interlace.money/pay/123456789"
  },
  "merchant": {
    "subMerchantId": "1000000123"
  },
  "ticket": {
    "ticketNo": "TKT2025081500001",
    "expirationTime": "2025-08-20T23:59:59",
    "barcode": "69825417369245813267",
    "format": "Code128",
    "currency": "USD",
    "amount": 399.50
  },
  "description": "Purchase of wireless headphones (Model: WH-1000XM5)"
}

Acquiring Payment Result Properties

tradeNo string required Order number - System-generated global unique identifier for the acquiring payment order, used for internal order query, reconciliation, and status tracking (e.g., "PAY2025081500001").

merchantTradeNo string required Merchant order number - Unique order identifier provided by the merchant, consistent with the value passed in when creating the order. It is used to associate merchant-side and system-side orders (e.g., "MCH2025081500001").

amount BigDecimal required Order amount - The monetary value of the payment order, supporting 6 decimal places (consistent with the precision of common currencies) (e.g., 399.50, 100.000101).

currency string required Order currency - Currency code of the order amount, following the ISO 4217 standard. Common values include "USD" (US Dollar), "EUR" (Euro) (e.g., "USD").

orderStatus OrderStatusEnum required Order status - Current processing status of the payment order, corresponding to the system’s standard status enumeration. For detailed descriptions of each status, see the OrderStatusEnum Resource. Common values: PENDING (order created), READY (waiting for payment), PAID (paid successfully), FAILED (order failed).

orderType OrderTypeEnum required Order type - Classification of the payment order, corresponding to the system’s transaction type enumeration. For detailed descriptions of each type, see the OrderTypeEnum Resource. Common values: PAYMENT (normal payment order), REFUND (refund order).

createTime Long required Order creation time - Timestamp when the order was created (in milliseconds since the Unix epoch), used to calculate order validity and track operation time (e.g., 1750000000000 corresponds to "2025-08-15 12:00:00").

completeTime Long optional Order completion time - Timestamp when the order was completed (paid/refunded/failed) (in milliseconds since the Unix epoch). It is null when the order is in an incomplete state (e.g., PENDING, READY) (e.g., 1750000120000 corresponds to "2025-08-15 12:02:00").

chargeToken string optional Payment token - Unique token associated with the payment method (e.g., credit card, e-wallet) used for the order. It is used for subsequent payment authorization, capture, or refund operations (e.g., "ch_tok_64b8e321a7c8231f9d0e").

actions PaymentAction optional Next action - Guidance for the next step of the payment process (only returned when the order requires additional operations). For detailed structure, see the PaymentAction Resource.

merchant Merchant optional Merchant information - Details of the merchant that initiated the payment order. For detailed structure, see the Merchant Resource. It is used to confirm the order’s merchant attribution and support merchant-level reconciliation.

ticket PaymentTicket optional Payment ticket information - Electronic ticket generated for the payment order (e.g., order receipt, redemption voucher). For detailed structure, see the PaymentTicket Resource. It is null when no ticket is required for the order.

description string optional Merchant-provided information - Custom description of the order provided by the merchant (e.g., product name, order purpose). The system returns this field as-is without modification (e.g., "Purchase of wireless headphones (Model: WH-1000XM5)").

Acquiring Refund Response Resource

This resource describes the data structure of the refund order response in the acquiring business scenario. It is returned by the system after a merchant initiates a refund request (e.g., via the refund API), and contains core information about the refund order—such as order numbers, refund amount, status, and associated merchant details—to confirm the refund application result to the merchant.

Example JSON

{
  "tradeNo": "REF2025081400001",
  "merchantTradeNo": "MER_REF2025081400001",
  "amount": 199.99,
  "currency": "USD",
  "orderStatus": "REFUNDED",
  "orderType": "REFUND",
  "createTime": "1750002000000",
  "completeTime": "1750002120000",
  "merchant": {
    "subMerchantId": "SUB_MERCH_001",
    "merchantNo": "M000000123"
  }
}

Acquiring Refund Response Properties

tradeNo string required Acquiring system refund order number - Global unique identifier for the refund order generated by the acquiring system. Used for internal refund order query, reconciliation, and status tracking (e.g., "REF2025081400001", with the prefix "REF" to distinguish from payment orders).

merchantTradeNo string required Merchant-generated refund order number - Unique refund identifier provided by the merchant, used for idempotency verification (the system will return the same result for repeated requests with the same merchantTradeNo to avoid duplicate refunds). Must be unique in the merchant’s system (e.g., "MER_REF2025081400001").

amount BigDecimal required Refund amount - The monetary value of the refund, supporting up to 6 decimal places (to accommodate currencies with small denominations). The amount cannot exceed the original payment order amount (e.g., 199.99, 50.123456).

currency string required Order currency - Currency code of the refund amount, following the ISO 4217 standard and consistent with the original payment order’s currency (e.g., "USD" for US Dollar, "CNY" for Chinese Yuan, "EUR" for Euro).

orderStatus OrderStatusEnum required Refund order status - Current processing status of the refund order, corresponding to the system’s standard transaction status enumeration. For detailed descriptions of each status, see the OrderStatusEnum Resource. Common values:

• REFUNDING: Refund in progress (intermediate status, e.g., waiting for the payment gateway to confirm)
• REFUNDED: Refund completed successfully (final status)
• FAILED: Refund failed (final status, e.g., gateway error, insufficient funds in the merchant account)

orderType OrderTypeEnum required Order type - Fixed as REFUND for refund orders, used to distinguish from normal payment orders (PAYMENT). For detailed descriptions of the enumeration, see the OrderTypeEnum Resource.

createTime Long required Refund order creation time - Timestamp when the refund order was generated (in milliseconds since the Unix epoch), used to record the refund initiation time (e.g., 1750002000000 corresponds to "2025-08-14 12:20:00").

completeTime Long optional Refund order completion time - Timestamp when the refund order reached a final status (e.g., REFUNDED or FAILED) (in milliseconds since the Unix epoch). Returned as null if the refund is still in progress (e.g., REFUNDING) (e.g., 1750002120000 corresponds to "2025-08-14 12:22:00").

merchant Merchant optional Merchant information - Details of the merchant (or sub-merchant) associated with the refund order. For the full structure, see the Merchant Resource.

Acquiring Payment Query Resource

This resource describes the data structure of the payment order query result in the acquiring business scenario. It is used to return comprehensive information about a specific payment order to merchants or internal systems, including core order details, status, associated merchant/card/customer information, and billing address.

Example JSON

{
  "tradeNo": "PAY2025081500001",
  "merchantTradeNo": "MCH2025081500001",
  "amount": 399.50,
  "currency": "USD",
  "country": "US",
  "orderStatus": "PAID",
  "orderType": "PAYMENT",
  "createTime": "1750000000000",
  "completeTime":"1750000000000",
  "merchant": {
    "subMerchantId": "SUB_MERCH_001"
  },
  "card": {
    "firstName": "John",
    "lastName": "Doe",
    "pan": "4111****1111"
  },
  "customer": {
    "merchantCustomerId": "CUST_0001",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+1-123-456-7890",
    "email": "[email protected]"
  },
  "billAddress": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "postalCode": "10001"
  },
  "paymentMethod": "CARD"
}

Acquiring Payment Query Properties

tradeNo string required Order number - System-generated global unique identifier for the acquiring payment order, used to uniquely locate the order during queries (e.g., "PAY2025081500001").

merchantTradeNo string required Merchant order number - Unique order identifier provided by the merchant when creating the order, used to associate the merchant’s internal order with the system order (e.g., "MCH2025081500001").

amount BigDecimal required Order amount - The monetary value of the payment order, supporting 2 decimal places (consistent with common currency precision) (e.g., 399.50, 100.00).

currency string required Order currency - Currency code of the order amount, following the ISO 4217 standard. Common values: "USD" (US Dollar), "EUR" (Euro) (e.g., "USD").

country string optional Order country - Country/region associated with the order (usually the merchant’s business country or the customer’s country), following the ISO 3166-1 alpha-2 standard (e.g., "US" for United States).

orderStatus OrdeStatusEnum required Order status - Current processing status of the payment order, corresponding to the system’s standard status enumeration. For detailed descriptions of each status, see the OrderStatusEnum Resource. Common values: PENDING (order created), READY (waiting for payment), PAID (paid successfully), FAILED (order failed).

orderType OrderTypeEnum required Order type - Classification of the payment order, corresponding to the system’s transaction type enumeration. For detailed descriptions of each type, see the OrderTypeEnum Resource. Common values: PAYMENT (normal payment order), REFUND (refund order).

createTime Long required Order creation time - Timestamp when the order was created (in milliseconds since the Unix epoch), used to calculate order validity and track operation time (e.g., 1750000000000 corresponds to "2025-08-15 12:00:00").

completeTime Long optional Order completion time - Timestamp when the order was completed (paid/refunded/failed) (in milliseconds since the Unix epoch). It is null when the order is in an incomplete state (e.g., PENDING, READY) (e.g., 1750000120000 corresponds to "2025-08-15 12:02:00").

merchant Merchant optional Merchant information - Details of the sub-merchant associated with the order. For the full structure, see the Merchant Resource.

card Card optional Card information - Payment card details used for the order (masked to ensure security). For the full structure, see the Card Resource. Returned as null if the payment method is non-card (e.g., PIX, OXXO).

customer Customer optional Customer information - Details of the customer who initiated the payment. For the full structure, see the Customer Resource.

billAddress BillAddress optional Billing address information - The billing address associated with the payment method (e.g., card billing address). For the full structure, see the BillAddress Resource.

paymentMethod string optional Payment method - Type of payment method used for the order, with a maximum length of 100 characters. Valid values: CARD (credit/debit card), CRYPTO_CARD (crypto card), PIX (Brazilian instant payment), OXXO (Mexican convenience store payment) (e.g., "CARD").

Acquiring Order Webhook Data Resource

This resource defines the data structure of the webhook notification sent when an acquiring order’s status changes. It is used to synchronize real-time order status updates to merchants, enabling timely business processing (e.g., order fulfillment, refund handling).

Example JSON (Webhook Payload)

{
  "tradeNo": "PAY2025081500001",
  "merchantTradeNo": "MCH2025081500001",
  "currency": "USD",
  "amount": 399.50,
  "orderStatus": "PAID",
  "orderType": "PAYMENT",
  "createTime": "1750000000000",
  "completeTime": "1750000150000",
  "paymentMethodId": "100003",
  "merchantCustomerId": "CUST_0001",
  "subMerchantId": "987654321098",
  "description": "Purchase of wireless headphones (Model: WH-1000XM5)",
  "errorCode": "151001",
  "errorMsg": "Param Error"
}

Webhook Data Properties

tradeNo string required Order number - System-generated global unique identifier for the acquiring order, consistent with the tradeNo in the Acquiring Payment Create Result Resource (e.g., "PAY2025081500001").

merchantTradeNo string required Merchant order number - Unique order identifier provided by the merchant, used to associate the webhook notification with the merchant’s internal order (e.g., "MCH2025081500001").

currency string required Order currency - Currency code of the order amount, following the ISO 4217 standard (e.g., "USD", "CNY") (consistent with the order’s creation information).

amount BigDecimal required Order amount - The monetary value of the order, supporting 2 decimal places (consistent with the order’s creation amount) (e.g., 399.50).

orderStatus OrderStatusEnum required Updated order status - The latest status of the order that triggers the webhook. For detailed descriptions of each status, see the OrderStatusEnum Resource. Common trigger statuses: PAID (payment success), FAILED (order failure), REFUNDED (refund completion), CLOSED (order closure).

orderType OrderTypeEnum required Order type - Classification of the order (consistent with the order’s creation type). For detailed descriptions, see the OrderTypeEnum Resource. Valid values: PAYMENT (normal payment order), REFUND (refund order).

createTime Long required Order creation time - Timestamp when the order was created (in milliseconds since the Unix epoch), consistent with the order’s creation record (e.g., 1750000000000 corresponds to "2025-08-15 12:00:00").

completeTime Long optional Order completion time - Timestamp when the order reached a final status (e.g., PAID, FAILED, REFUNDED) (in milliseconds since the Unix epoch). Returned as null if the order is still in an intermediate status (e.g., CANCELED, REFUNDING) (e.g., 1750000150000 corresponds to "2025-08-15 12:02:30").

paymentMethodId Long optional Payment method ID - System-generated unique identifier for the payment method used by the order (e.g., ID of a credit card or e-wallet). Returned as null if the payment method is not associated with an ID (e.g., OXXO).

merchantCustomerId string optional Merchant-side customer ID - Unique identifier of the customer in the merchant’s system (consistent with the customer information provided when creating the order) (e.g., "CUST_0001").

subMerchantId Long optional Sub-merchant ID - Unique identifier of the sub-merchant in the system (for scenarios involving sub-merchants). Returned as null if the order belongs to a primary merchant (e.g., 987654321098).

description string optional Merchant-provided information - Custom description passed by the merchant when creating the order, returned as-is in the webhook (e.g., "Purchase of wireless headphones (Model: WH-1000XM5)").

errorCode string optional Error code - Error identifier returned if the order status is FAILED or REFUNDED due to an error. Returned as null for successful statuses (e.g., "PAYMENT_GATEWAY_ERROR", "INSUFFICIENT_FUNDS").

errorMsg string optional Error message - Human-readable description of the error corresponding to errorCode. Returned as null for successful statuses (e.g., "Payment gateway connection timed out", "Customer’s account has insufficient funds").

Webhook Notification Notes

1. Trigger Conditions: The webhook is only sent when the order status changes (e.g., initial status READY → PAID, READY → FAILED). No notification is sent for repeated status updates (e.g., multiple PAID status pushes for the same order).
2. Idempotency: Merchants should use tradeNo to ensure idempotent processing of webhook notifications (avoid duplicate business operations caused by repeated webhook pushes).
3. Signature Verification: The system will sign the webhook payload using a pre-configured secret key. Merchants must verify the signature before processing the notification to prevent malicious requests (see Webhook Signature Verification Guide for details).

Acquiring Dispute Webhook Data Resource

This resource defines the data structure of webhook notifications for acquiring dispute cases. When a dispute is initiated (e.g., by a cardholder or issuing bank), updated (e.g., status change to "Representation"), or resolved (e.g., status change to "CB Dispute Win" or "CB Dispute loss"), the system sends this webhook to the merchant’s pre-configured endpoint. It synchronizes real-time dispute information to enable merchants to timely respond to disputes (e.g., submit evidence) and track case progress.

Example JSON (Webhook Payload)

{
  "disputeCaseId": 123456789012,
  "disputeType": "FIRST_CHARGEBACK",
  "disputeStatus": "NOTICE",
  "tradeNo": "PAY2025081000001",
  "disputeCurrency": "USD",
  "disputeAmount": 299.50,
  "reasonCode": "4837",
  "reasonInfo": "Transaction not authorized by cardholder",
  "dueDate": "2025-09-10",
  "createTime": 1750005600000,
  "description": "Cardholder claims the transaction was not initiated by them; merchant needs to submit proof of authorization by 2025-09-10"
}

Acquiring Dispute Webhook Data Properties

disputeCaseId Long required Dispute case ID - System-generated unique identifier for the dispute case, used to uniquely locate and track the dispute (e.g., 123456789012).

disputeType DisputeOrderTypeEnum required Dispute type - Classification of the dispute, determined by the DisputeOrderTypeEnum enumeration. For detailed descriptions of the enumeration, see the DisputeOrderTypeEnum Resource.

disputeStatus DisputeOrderStatusEnum required Dispute status - Current progress of the dispute case, determined by the DisputeOrderStatusEnum enumeration. It indicates the merchant’s required actions (if any). For detailed descriptions of the enumeration, see the DisputeOrderStatusEnum Resource.

tradeNo string required Associated QBit order number - The original acquiring payment order number linked to the dispute. It is consistent with the tradeNo in the Acquiring Payment Create Result Resource and used to associate the dispute with the original transaction (e.g., "PAY2025081000001").

disputeCurrency string required Dispute currency - Currency code of the dispute amount, following the ISO 4217 standard and consistent with the original payment order’s currency (e.g., "USD", "EUR").

disputeAmount BigDecimal required Dispute amount - The monetary value of the dispute, which can be the full or partial amount of the original payment order (e.g., 299.50 for a full dispute, 100.00 for a partial dispute).

reasonCode string required Reason code - Standardized code provided by the issuing bank to explain the dispute reason, following industry standards (e.g., Visa/Mastercard reason codes). Example values:

• 4837: Transaction not authorized by cardholder
• 4512: Service not received
• 4863: Goods not as described

reasonInfo string required Reason information - Human-readable description of the dispute reason, corresponding to reasonCode (e.g., "Transaction not authorized by cardholder", "Service not received by the cardholder").

dueDate string required Dispute due date - Deadline for the merchant to submit evidence to respond to the dispute, following the YYYY-MM-DD format. Merchants must submit evidence before this date; otherwise, the dispute may be ruled in favor of the cardholder (e.g., "2025-09-10").

createTime Long required Dispute creation time - Timestamp when the dispute case was created (in milliseconds since the Unix epoch), used to record the dispute initiation time (e.g., 1750005600000 corresponds to "2025-08-14 13:20:00").

description string optional Dispute remarks - Supplementary information about the dispute, such as additional details from the issuing bank or system reminders for the merchant (e.g., "Cardholder claims the transaction was not initiated by them; merchant needs to submit proof of authorization by 2025-09-10").

Webhook Notification Key Notes

1. Trigger Scenarios: The webhook is sent in the following cases:

   • A new dispute is initiated (disputeStatus: NOTICE).
   • The dispute status is updated (e.g., NOTICE → REPRESENTATION, ISSUER_PENDING → CB_DISPUTE_WIN).
   • The dispute due date is adjusted (rare, but triggers a notification if it occurs).

2. Evidence Submission: When disputeStatus is NOTICE, merchants must submit supporting evidence (e.g., order confirmation, delivery proof, cardholder authorization records) via the designated portal before dueDate. Failure to submit evidence may result in an automatic "CB_DISPUTE_LOSS" ruling.

3. Idempotency Handling: Merchants should use disputeCaseId to ensure idempotent processing of webhook notifications (avoid duplicate evidence submissions or status updates caused by repeated webhook pushes).

4. Signature Verification: The system signs the webhook payload using a pre-configured secret key. Merchants must verify the signature before processing the notification to prevent malicious requests (see the Webhook Signature Verification Guide for details).

Associated Sub-Resources

The Acquiring Payment Resource relies on the following sub-resources to complete data expression. Click the links to view detailed descriptions:

PaymentAction Resource

Describes the next-step operation required to complete the payment.

redirectToPay string optional URL to redirect to payment page

redirectTo3DS string optional URL to redirect to 3DS page (e.g., "https://payment-gateway.interlace.com/pay/123456789").

Merchant Resource

Describes the merchant information associated with the order.

subMerchantId string required Sub-merchant ID - Unique identifier of the sub-merchant in the acquiring system, used to distinguish sub-merchants under the same parent merchant (e.g., "12414000011").

PaymentTicket Resource

Describes the electronic ticket information associated with the order.

ticketNo string required Ticket number - Unique identifier for the payment ticket (e.g., "TKT2025081500001").

expirationTime Date required Ticket expiration time - Valid end time of the ticket, following the ISO 8601 standard (e.g., "2025-08-20T23:59:59").

barcode string optional Ticket barcode - Barcode string for ticket verification, used for scanning redemption (e.g., "69825417369245813267").

format string optional Ticket format -(e.g., "Code 128","QR CODE" )

currency string required Ticket currency - Currency code of the ticket amount, consistent with the order’s currency (e.g., "USD").

amount BigDecimal required Ticket amount - Monetary value represented by the ticket, consistent with the order’s amount (e.g., 399.50).

Card Resource

Describes masked payment card information used for the order (ensures compliance with data security standards like PCI DSS).

firstName string optional Cardholder’s first name - Consistent with the name printed on the payment card (e.g., "John").

lastName string optional Cardholder’s last name - Consistent with the name printed on the payment card (e.g., "Doe").

pan string optional Masked card number - The primary account number (PAN) of the payment card, with middle digits masked for security (e.g., "41111111", "5555554444").

Customer Resource

Describes customer information associated with the payment order.

merchantCustomerId string optional Merchant-side customer ID - Unique identifier of the customer in the merchant’s system, used to associate the merchant’s customer data with the payment order (e.g., "CUST_0001").

firstName string optional Customer’s first name - Used for identity verification and order attribution (e.g., "John").

lastName string optional Customer’s last name - Used for identity verification and order attribution (e.g., "Doe").

phoneNumber string optional Customer’s phone number - Used for payment verification (e.g., SMS OTP) and order contact (e.g., "+1-123-456-7890", "+86-13800138000").

email string optional Customer’s email address - Used for sending order confirmations, receipts, and payment notifications (e.g., "[email protected]").

BillAddress Resource

Describes the billing address associated with the payment method (e.g., card billing address, used for address verification).

addressLine1 string optional Address line 1 - Primary street address, including house number and street name (e.g., "123 Main Street").

addressLine2 string optional Address line 2 - Supplementary address information (e.g., apartment number, suite number), returned as null if not provided (e.g., "Apt 4B").

city string optional City - City where the billing address is located (e.g., "New York", "Shanghai").

state string optional State/province - Sub-national administrative unit of the address (e.g., "NY" for New York, "CA" for California.

country string optional Country abbreviation - Country/region of the billing address, following the ISO 3166-1 alpha-2 standard (e.g., "US").

postalCode string optional Postal code - Postal/ZIP code of the billing address (e.g., "10001", "200000").

Associated Enums

The following enums are used to define the orderStatus and orderType fields of the Acquiring Payment Create Resource. Click the links to view the full enumeration details:

OrderStatusEnum Resource

Defines all possible processing statuses of payment orders.

OrderTypeEnum Resource

Defines all possible types of payment transactions.

DisputeOrderTypeEnum Resource

Defines all valid types of acquiring dispute cases.

DisputeOrderStatusEnum Resource

Defines all valid statuses of acquiring dispute cases, including action triggers for merchants.