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
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, 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:

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.

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

JSON

{
    "payTime": "2024-07-05 11:50:37",
    "txTime": "2024-07-05 11:53:06",
    "signature": "f9783922400fde4eweww9f1f07383bef09dbef8",
    "networkFee": "95.02338009",//count as fiat
    "rebateFiatAmount": "",
    "rawRampFee": "69.060000",
    "fiatInUSD": "10.77",//Exchange rate between payment fiat currency and USD
    "network": "TRX",
    "cryptoPrice": "95.02330000",//Crypto price count as fiat
    "payType": "CREDIT_CARD",
    "rampFee": "68.47027388",//User purchase fee count as fiat
    "appId": "XXXXXXXXXXXXXX",
    "fiat": "INR",
    "newSignature": "e98PkmrF1Lg9uiCaJdDAzOVifdkg6lyR2h9gNIT/Kps=",
    "txHash": "c65d12f672e8f1aewwwwe5f510e4bee71086a4071577e5ab35b",
    "email": "[email protected]",
    "rampFeeInUSD": "0.82",
    "amount": "900.00000000",//Fiat payment amount
    "orderNo": "125862236283185152",
    "address": "TKBSr2wessawfsBra9p7opSyRGfuXrrT",
    "cryptoNetworkFee": "1.17",//Token network fee,count as purchase token
    "networkFeeInUSD": "1.33",//Token network fee,count as USD
    "cryptoAmountInUSDT": "8.61466",//User token received amount count as USDT
    "rebateUsdAmount": "",
    "merchantOrderNo": "P202233454543423939810",
    "crypto": "USDT",
    "rampFeeUnit": "INR",
    "cryptoQuantity": "7.57",//User token received amount
    "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
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, 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

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