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 TypeRemarks
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:PAY_FAIL、PAY_SUCCESS、FINISHED

Selling crypto status:Paying:request paying success, Pay Success:pay success
messagestringfait payment failed cause
merchantOrderNostringmerchant order ID
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 need to be configured for the push notification to be sent. If you have any requirements, please feel free to contact us.

ElementData TypeRemarks
createTimestringOrder creation time, format YYYY-MM-DD, HH:MM:SS, e.g., 2021-11-25 10:00:00
rampFeeUnitstringUnit of Ramp fee, such as USD, ETH
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.

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
addressstringOrder's crypto recipient address
payTimestringThe time when ACH starts to transfer fiat to the user's account
completeTimestringThe time when this order receives the cryptos
merchantOrderNostringMerchant order No
cryptostringCrypto name
networkstringNetwork of crypto
cryptoPricestringCrypto price in fiat type
cryptoAmountstringOrder's crypto amount
fiatAmountstringThe fiat amount user will receive, excluding the ramp fee
appIdstringappID
fiatstringfiat typr
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
orderAddressstringUrl to the order detail page
cryptoacturalAmountstringThe actual received crypto amount
rampfeestringRamp fee, based on fiat type
receiptTimestringFiat arrived time
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 user will receive
  "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
}