API Document

# Callback Transaction Result

# Callback Interface Signature Verification

Purpose of Signature Verification

During API requests, there is a risk of data being tampered with by a middleman while being transmitted over the public network. To ensure the integrity and trustworthiness of the callback data, the platform supports and strongly recommends that merchants perform signature verification when receiving the callback.

Setup Method

Log in to the [Cashier Backend] → [Developer Center] → [Callback Address] → Add/Edit.

Signature Verification Steps

The signature verification logic is generally the same as the API request signature, with the key difference being that the data source is the received callback content.

1.Obtain the Signature

Retrieve the signature field from the HTTP request Header：

sign: {Platform-generated signature string}

2.Obtain the Callback Parameters

​ Store the JSON parameters from the callback Body in a Map (dictionary) structure in key-value form.

3.Add Public Parameters

​ Also retrieve the following fields from the Header and include them in the Map for signature verification:

  1. access_key
  • timestamp
  • nonce

4.Construct the String to Be Signed

​ Sort all the keys in the Map in ASCII order from smallest to largest, and concatenate them into the following format:

key1=value1&key2=value2&...&keyN=valueN

5.Perform Signature Calculation

  1. Use the secret_key bound to the merchant's backend to process the above string as follows:
    • Encrypt using the HMAC_SHA1 algorithm
    • Base64 encode the result to obtain the local sign value

6.Compare Signatures

Compare the locally generated sign with the sign provided in the Header by the platform:

  • ✅ If they match → Signature verification passes, and business logic can be processed
  • ❌ If they don't match → Reject processing and consider logging the event for troubleshooting

# Exchange Callback

When the payment order reaches the final status (such as success or failure), the platform will send the following callback data to the merchant's pre-set notifyUrl.

Callback Data Example

{
  "currencyType":"INR",
  "orderId":"OCURREXCH202505080800451746691245254HAMBIT-U0000000201298031",
  "tokenAmount":"1.193602291716400095",
  "currencyAmount":"100",
  "orderFee":"0.014084507042253522",
  "remark":"test",
  "chainType":"BSC",
  "externalOrderId":"20250508160039180270",
  "orderEntryAmount":"1.179517784674146573",
  "addressTo":"0xa8666442fA7583F783a169CC9F5449ec660295E8",
  "orderCompleteTime":1746691310000,
  "orderAmount":"100",
  "exchangeRate":"83.78",
  "notifyUrl":"https://tofficeapi.hambit.co/api/v1/hambit/hambit-api/test/testNotifySuccess",
  "tokenType":"USDT",
  "exSymbolType":602
}

Callback Parameter Description

Parameter Name Type Description
currencyType String Fiat currency type (e.g., BRL, INR)
orderId String Order ID
tokenAmount String Amount of tokens
currencyAmount String Amount of fiat currency
orderFee String Transaction fee
remark String Order remark
chainType String Blockchain type
externalOrderId String Merchant order ID
orderEntryAmount String Actual received amount
addressTo String Address
orderCompleteTime int Order completion time
orderAmount String Order amount
exchangeRate String Exchange rate
notifyUrl String Callback URL
tokenType String Token type
exSymbolType int Exchange type (601 for crypto to fiat, 602 for crypto to fiat)

Tips: Manual Callback Mechanism Description

Merchants can log in to the merchant backend at any time and manually trigger the order callback.

Precautions:

  • Do not manually trigger the callback when the order is not in a final state (e.g., not paid or in processing), as it may cause business logic issues.
  • In the manually triggered callback response data, the order status reflects the current actual status. Please process it according to the status on the business side.
  • If the order is not in the final state (e.g., in processing), the platform will still initiate a notification once the order status changes to the final state. Merchants should handle business redundancy and ensure idempotency to avoid duplicate entries or notification conflicts.
  • If the order is already in the final state, and the merchant manually triggers the callback (not recommended), the platform will still initiate the notification again. Merchants should handle business redundancy to ensure idempotency and avoid duplicate entries or notification conflicts.

# Callback Response

Description

  • All callbacks include a signature field. It is recommended that merchants validate the callback to ensure the integrity of the callback data.
  • After receiving and processing the callback data, merchants must respond to the gateway with the following JSON format:

Example Response (Success)

{
  "code": 200,
  "success": true
}

Callback Retries Mechanism (Important) 🔥

To ensure stable delivery and business consistency of the callback notifications, the platform has designed a retry strategy. If the merchant system fails to respond to the callback (e.g., network timeout, returns a non-200 status code, etc.), the system will retry according to the following rules:

Callback Retry Schedule (4 attempts total):

Attempt No. Interval (approx.) Description
1st Attempt About 2 minutes First retry after initial failure
2nd Attempt About 2 minutes Second retry after first failure
3rd Attempt About 11 minutes Third retry after second failure
4th Attempt About 2 minutes Final retry after third failure

Note: The intervals above represent internal scheduling intervals. The "callback time" recorded in the merchant's backend includes the merchant's processing/response time, so there may be a slight discrepancy (about 1 minute) between the displayed and actual push times.

Practical Reminders

  • When there is a large volume of orders online, callbacks may experience queue delays, so please ensure the server can handle high concurrency.
  • Each callback is an idempotent operation, and merchants should support idempotent checks.
  • After 4 failed retry attempts, the system will stop retrying automatically, and it is recommended to manually trigger the callback via the backend.

Callback Response Parameters

Param Type Required Description
code int ✅ Status code; 200 for success
success boolean ✅ Whether the response was successful

# Callback Notification URL Configuration

Two types of notification address configurations are supported:

  1. [Merchant Backend] Configure a Unified Callback Address
  • This can be configured in the "Merchant Backend" → "Developer Center."
  • Suitable for handling callbacks with common logic across most orders.

img

2.Order-level Manual Specification of Callback URL (notifyUrl)

  • The notifyUrl field can be passed when creating an order.
  • If the order specifies the notifyUrl parameter, the system will use that address as the only callback notification target.

Priority of Address Configuration

The notifyUrl in the order takes precedence over the unified callback address configured in the system.

Priority of Response Status Code

The platform uses the HTTP response status code (status_code) as the only criterion to determine whether the callback was successful.

Specific Rules:

  • ✅ As long as the merchant system returns HTTP 200, the platform will consider the callback as successful.
    • In this case, even if the returned content is not { "code": 200, "success": true }, it will be ignored.
  • ❌ If the response status_code ≠ 200 (e.g., 400/500) or there is no response, the callback will be considered failed, and the platform will automatically retry the push.

← 1. Fiat-to-cryptocurrency exchange →