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 | Explanation | 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 | |
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, details send webhook to merhcant only when order status as: PAY_FAIL, PAY_SUCCESS, FINISHED | |
message | string | fait payment failed cause | |
merchantOrderNo | string | merchant order ID | |
networkFee | string | crypto network fee | Count as USD |
rampFee | string | ramp fee | |
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,the sign method can refer here | |
fiatInUSD | string | fiat amount(count in USD) | Returned if status is FINISHED. |
rampFeeInUSD | string | service charge(count in USD) | Returned if status is FINISHED. |
cryptoNetworkFee | string | priced counted on purchased tokens | Returned if status is FINISHED. |
networkFeeInUSD | string | Network fee (priced in USD), calculated as cryptoNetworkFee and priced in USD | Returned if status is FINISHED. |
cryptoAmountInUSDT | string | The token received by user (priced in USDT) | Returned if status is FINISHED. |
rampFeeUnit | string | Unit of Ramp fee, such as USD, INR | |
newSignature | string | newSignature,reference here |
Note:
- For local payment in INR, there is no callback for the completion of fiat payment.
- 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.
Element | Data Type | Remarks |
---|---|---|
createTime | string | Order creation time, format YYYY-MM-DD, HH:MM:SS, e.g., 2021-11-25 10:00:00 |
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. |
rebateFiatAmount | string | Commission amount, valued in fiat currency. |
rebateUsdAmount | string | Commission 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
Element | Data Type | Remark |
---|---|---|
orderNo | string | Alchemy Pay Order ID |
address | string | ACH address for receiving user tokens |
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 number |
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, contains ramp fee |
appId | string | appID |
fiat | string | fiat currency |
txHash | string | Token transferred txHash |
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, details |
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 | Time of user receives payment |
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
{
"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
}
Updated 2 months ago