Interface Description

When users buy or sell coins, we will push order information to merchants based on the results of the transactions.

Retry Mechanism: By default, webhooks are sent only once. If needed, please contact us to configure webhook retries with the following intervals: 5 minutes, 15 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours. Retrying will stop once we receive an HTTP 200 response with a success message.Currently, webhook retries are only supported for OnRamp.

📘

We recommend using the webhook in conjunction with the Order Query API.

Interface Explanation

Request Method: POST

Request Address: The callbackUrl provided by the merchant when placing an order.

Header Parameter

ElementData TypeRemarks
timestampstringtimestamp (used for signature verification) reference here

On Ramp Webhook

Body Parameter List

ElementData TypeExplanationRemarks
appIdstringpartner unique ID, once a merchant has been on-boarded with Alchemy Pay, the merchant will be provided with the credentials with appId and appSecret
orderNostringAlchemy Pay Order ID
emailstringend user's email
merchantUidstringUser’s UUID from merchant side
cryptostringcrypto type
cryptoPricestringcrypto price
cryptoQuantitystringcrypto amount
payTypestringfiat payment method
fiatstringfiat type
amountstringfiat amount
payTimestringfiat payment time
networkstringcrypto network
addressstringcrypto address
txTimestringcrypto received time
txHashstringcrypto hash
statusstringOrder status, details
send webhook to merhcant only when order status as: PAY_FAIL, PAY_SUCCESS, FINISHED
messagestringfait payment failed cause
merchantOrderNostringmerchant order ID
networkFeestringcrypto network feeCount as USD
rampFeestringramp fee
signaturestringcallback signature, the generated signature string is: getMersign(appId,appSecret, appId+orderNo+crypto+network+address)
#getMersign is the sign function for Initiate API,the sign method can refer here
fiatInUSDstringfiat amount(count in USD)Returned if status is FINISHED.
rampFeeInUSDstringservice charge(count in USD)Returned if status is FINISHED.
cryptoNetworkFeestringpriced counted on purchased tokensReturned if status is FINISHED.
networkFeeInUSDstringNetwork fee (priced in USD), calculated as cryptoNetworkFee and priced in USDReturned if status is FINISHED.
cryptoAmountInUSDTstringThe token received by user (priced in USDT)Returned if status is FINISHED.
rampFeeUnitstringUnit of Ramp fee, such as USD, INR
newSignaturestringnewSignature,reference here

📘

Note:

  1. For local payment in INR, there is no callback for the completion of fiat payment.
  2. Failed payment notifications will include two additional fields: returnCode (error code for failure) and returnMsg (failure reason), without the "message" parameter.

The following parameters are not sent by default and will only be sent if the merchant commission rebate feature is enabled.

ElementData TypeRemarks
createTimestringOrder creation time, format YYYY-MM-DD, HH:MM:SS, e.g., 2021-11-25 10:00:00
tokenAddressstringContract address of the token returned when purchasing coins; leave blank if it is a native chain coin
alpha2stringISO 3166-1 two-letter country code, such as US/JP, etc.
rebateFiatAmountstringCommission amount, valued in fiat currency.
rebateUsdAmountstringCommission amount, valued in USD.

On Ramp Payload Sample

{
    "payTime": "2024-07-05 11:50:37",
    "txTime": "2024-07-05 11:53:06",
    "signature": "f9783922400fde4eweww9f1f07383bef09dbef8",
    "networkFee": "95.02338009",
    "rebateFiatAmount": "",
    "rawRampFee": "69.060000",
    "fiatInUSD": "10.77",
    "network": "TRX",
    "cryptoPrice": "95.02330000",
    "payType": "CREDIT_CARD",
    "rampFee": "68.47027388",
    "appId": "XXXXXXXXXXXXXX",
    "fiat": "INR",
    "newSignature": "e98PkmrF1Lg9uiCaJdDAzOVifdkg6lyR2h9gNIT/Kps=",
    "txHash": "c65d12f672e8f1aewwwwe5f510e4bee71086a4071577e5ab35b",
    "email": "[email protected]",
    "rampFeeInUSD": "0.82",
    "amount": "900.00000000",
    "orderNo": "125862236283185152",
    "address": "TKBSr2wessawfsBra9p7opSyRGfuXrrT",
    "cryptoNetworkFee": "1.17",
    "networkFeeInUSD": "1.33",
    "cryptoAmountInUSDT": "8.61466",
    "rebateUsdAmount": "",
    "merchantOrderNo": "P202233454543423939810",
    "crypto": "USDT",
    "rampFeeUnit": "INR",
    "cryptoQuantity": "7.57",
    "status": "FINISHED"
}

Off Ramp Webhook

Body Parameter List

ElementData TypeRemark
orderNostringAlchemy Pay Order ID
addressstringACH address for receiving user tokens
payTimestringThe time when ACH starts to transfer fiat to the user's account
completeTimestringThe time when this order receives the cryptos
merchantOrderNostringMerchant order number
cryptostringCrypto name
networkstringNetwork of crypto
cryptoPricestringCrypto price in fiat type
cryptoAmountstringOrder's crypto amount
fiatAmountstringThe fiat amount user will receive, contains ramp fee
appIdstringappID
fiatstringfiat currency
txHashstringToken transferred txHash
emailstringUser's email
signaturestringcallback signature, the generated signature string is: getMersign(appId,appSecret, appId+orderNo+crypto+network+address)
#getMersign is the sign function for Initiate API
statusstringOrder Status, details
orderAddressstringUrl to the order detail page
cryptoacturalAmountstringThe actual received crypto amount
rampfeestringRamp fee, based on fiat type
receiptTimestringTime of user receives payment
paymentTypestringcard: transfer to the user's card
account: transfer to the user's account
newSignaturestringnewSignature,reference here

📘

Note: Different statuses may have empty values and fields.

Off Ramp Payload Sample

{
  "orderNo": "1080106145537236992", 
  "address": "dev03dc84dbfeb74853aa91154efa9b7a13", // wallet address user need to transfer
  "payTime": "2023-02-28 20:44:46", // transfer fiat start time
  "completeTime": "2023-02-28 20:41:08", // block confirm time
  "merchantOrderNo": "kvhl6zvvrg", 
  "crypto": "USDT",
  "network": "TRX", 
  "cryptoPrice": "1.0000000000", // fiat
  "cryptoAmount": "100.0000000000",
  "fiatAmount": "100.0000000000", //fiat amount contains ramp fee
  "appId": "ahzxh0klegv1fzol",
  "fiat": "USD", 
  "txHash": "sdasdasdasdasdasdsad",
  "email": "[email protected]", 
  "signature": "9aa9b34e950061f1bb1e9ccd6fadcedab8e354f6",
  "status": "4",  // 1:create order success  2:user trnasfered token  3:start to pay fiat to user  4:payment success 5:payment fail 6:refund success 7:order expired
  "orderAddress": "https://ramp-dev.alchemytech.cc/#/sellOrder?sellOrderId\u003d1080106145537236992", // order detail page
  "cryptoActualAmount": "100.0000000000", // 
  "rampFee": "1.7500000000", // fiat
  "receiptTime": "2023-02-28 20:45:22", //transfer fiat success time
  "paymentType": "10001", //  10001 banktransfer
  "name": "asdfsfsd", // account name
  "newSignature": "sfsw32sfwfs",
  "account": "******4567", // account number
  "card": "", // card No 
  "failReason": "" // failReason
}