Webhook

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

Element	Data Type	Remarks
timestamp	string	timestamp (used for signature verification) reference here

On Ramp Webhook

Body Parameter List

Element	Data Type	Remarks
appId	string	partner unique ID, once a merchant has been on-boarded with Alchemy Pay, the merchant will be provided with the credentials with appId and appSecret
orderNo	string	Alchemy Pay Order ID
email	string	end user's email
merchantUid	string	User’s UUID from merchant side
crypto	string	crypto type
cryptoPrice	string	crypto price
cryptoQuantity	string	crypto amount
payType	string	fiat payment method
fiat	string	fiat type
amount	string	fiat amount
payTime	string	fiat payment time
network	string	crypto network
address	string	crypto address
txTime	string	crypto received time
txHash	string	crypto hash
status	string	Order status：PAY_FAIL、PAY_SUCCESS、FINISHED Selling crypto status：Paying：request paying success, Pay Success：pay success
message	string	fait payment failed cause
merchantOrderNo	string	merchant order ID
newSignature	string	newSignature,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.

Element	Data Type	Remarks
createTime	string	Order creation time, format YYYY-MM-DD, HH:MM:SS, e.g., 2021-11-25 10:00:00
rampFeeUnit	string	Unit of Ramp fee, such as USD, ETH
tokenAddress	string	Contract address of the token returned when purchasing coins; leave blank if it is a native chain coin
alpha2	string	ISO 3166-1 two-letter country code, such as US/JP, etc.

On Ramp Payload Sample

JSON

{
    "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

Element	Data Type	Remark
orderNo	string	Alchemy Pay Order ID
address	string	Order's crypto recipient address
payTime	string	The time when ACH starts to transfer fiat to the user's account
completeTime	string	The time when this order receives the cryptos
merchantOrderNo	string	Merchant order No
crypto	string	Crypto name
network	string	Network of crypto
cryptoPrice	string	Crypto price in fiat type
cryptoAmount	string	Order's crypto amount
fiatAmount	string	The fiat amount user will receive, excluding the ramp fee
appId	string	appID
fiat	string	fiat typr
txHash	string	Token transferred txHash
email	string	User's email
signature	string	callback signature, the generated signature string is: getMersign(appId,appSecret, appId+orderNo+crypto+network+address) #getMersign is the sign function for Initiate API
status	string	Order Status
orderAddress	string	Url to the order detail page
cryptoacturalAmount	string	The actual received crypto amount
rampfee	string	Ramp fee, based on fiat type
receiptTime	string	Fiat arrived time
paymentType	string	card: transfer to the user's card account: transfer to the user's account
newSignature	string	newSignature,reference here

📘

Note: Different statuses may have empty values and fields.

Off Ramp Payload Sample

js

{
  "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
}