Acquiring Callback Documentation (Webhook Notification)

Overview

After a payment transaction is completed (whether successful or failed), the system will send an HTTP POST request to the notify_url provided by the merchant system to notify the transaction status.

The merchant must verify and process the notification, and return HTTP 200 to indicate successful receipt.

If a non-200 status is returned or a timeout occurs, the system will automatically enter the exponential backoff retry mechanism.

The request body fields for the Webhook callback are as follows:

Request Body Field Structure

{
  "data": {
    "id": "pi_xxxx",
    "amount": 10000,
    "currency": "USD",
    "merchant_id": "acct_123456",
    "merchant_order_id": "order_id_123456",
    "result": {
      "result_code": "SUCCEEDED"
    },
    "metadata": {
      "shop": "happy",
      "domain": "example.com"
    }
  }
}

Field Descriptions

data Object Fields

Field Name	Type	Required	Description
id	string	Yes	Platform payment order number
amount	integer	Yes	Payment amount, in cents
currency	string	Yes	Payment currency (ISO 4217 standard 3-letter code, e.g. USD)
merchant_id	string	Yes	Merchant number, assigned by the platform
merchant_order_id	string	Yes	Original merchant order number
result	object	Yes	Payment result object, contains status code and info
metadata	object	No	Custom passthrough fields, returned as-is to merchant (e.g. shop name, domain, etc.)

result Sub-object Fields

Field Name	Type	Required	Description
result_code	string	Yes	Payment result status
result_message	string	No	Error description, provided only on failure, e.g.: card_declined, insufficient_funds, etc.

result_code Value Description

result_code	Meaning	Description/Handling Suggestion
SUCCEEDED	Payment Succeeded	Transaction succeeded, merchant can fulfill the order
FAILED	Payment Failed	Transaction failed, merchant should mark order as failed, do not fulfill or settle

Example Values Reference

Payment Success Example

{
    "data": {
        "id": "pi_xxxx",
        "amount": 10000,
        "result": {
            "result_code": "SUCCEEDED"
        },
        "currency": "USD",
        "metadata": {
            "shop": "happy",
            "domain": "example.com"
        },
        "merchant_id": "acct_123456",
        "merchant_order_id": "order_id_123456"
    }
}

Payment Failure Example

{
    "data": {
        "id": "pi_xxxx",
        "amount": 10000,
        "result": {
            "result_code": "FAILED",
            "result_message": "insufficient_funds"
        },
        "currency": "USD",
        "metadata": {
            "shop": "happy",
            "domain": "example.com"
        },
        "merchant_id": "acct_123456",
        "merchant_order_id": "order_id_123456"
    }
}