Notifications
Notifications (a.k.a "Callbacks", "IPN") are used in 0xpay to alert users about events happenning to their merchants. Whenever something happens to your merchant, 0xpay will try to send a webhook to the Notifications URL that you've previously specified in merchant settings.
We guarantee that webhooks will come in described order, according to their tx status change.
For example: we won't send you a "Done" status webhook until you respond with success HTTP status to a "Pending" webhook that was sent earlier.
In case your URL responds with a non-success HTTP status – the notification will be retried 10 times, with initial delay of 10 minutes, each new retry triggered 15 minutes later, up to a maximum of 60 minutes. In total, we are going to try and notify you for 8 hours.
Number of Retries | Timeout |
---|---|
Retry #1 | 10 min |
Retry #2 | 25 min |
Retry #3 | 40 min |
Retry #4 | 55 min |
Retry #5-10 | 60 min |
Check out notification examples on the next page.
First of all, replenishment transaction can have two statuses:
- Pending – incoming transaction is already in mempool.⌛
- Done – incoming transaction is confirmed and added to your merchant's balance✅
Webhook request body:
Field | Type | Description |
---|---|---|
id | string* | Identifier |
kind | "Replenish" | |
hash | string | blockchain transaction hash, if no hash means it's an internal (look at "internal" field) |
internal | boolean* | 0xpay transaction – from 0xpay account to 0xpay address. No blockchain transaction |
block | number | block number where the transaction was mined, usually present only on "Done" status |
ticker | string* | |
blockchain | string* | |
from | string[]* | List of sender addresses |
to | string* | destination address |
amount | string* | amount in decimal format, look at the example |
fee | string | |
meta | string | |
status | string* | "Pending", "Done" |
First of all, withdrawals can be in two statuses:
- Pending – withdrawal is in the mempool, transaction hash was assigned.⏳
- Done – withdrawal was included to the block and has at least 1 confirmation.✅
- 😡 Failed
We guarantee that webhooks will be sent in order, according to their respective status.
For example: we won't send you a "Done" status webhook until you respond with success HTTP status to the "Pending" webhook
Webhook request body:
Field | Type | Description |
---|---|---|
id | string* | Identifier |
kind | "Withdraw" | |
hash | string | blockchain transaction hash, if no hash means it's an internal (look at "internal" field) |
internal | boolean* | 0xpay transaction – from 0xpay account to 0xpay address. No blockchain transaction |
block | number | block number where the transaction was mined, usually present only on "Done" status |
ticker | string* | |
blockchain | string* | |
from | string[]* | List of sender addresses |
to | string* | destination address |
amount | string* | amount in decimal format, look at the example |
fee | string | |
meta | string | |
localId | string | |
status | string* | "Pending", "Done", "Failed" |
time | number* | timestamp when withdrawal was created in ms |
Statuses
- Exchanged - your swap is filled and balances are exchanged⏳
- 😡 Failed – can fire before exchanged status or after exchanged status (order not filled, withdraw is not successful and etc. In that case you should check you account in web application)
- Done – withdrawal was mined✅
Webhook request body:
Field | Type | Description |
---|---|---|
kind | "CryptoExchangeWithdraw" | |
id | string* | Identifier |
ticker | string* | |
amount | string* | amount in decimal format |
fee | string* | |
meta | string | |
localId | string | |
status | string* | "Done" | "Exchanged" | "Failed" |
time | number* | timestamp when withdrawal was created in ms |
exchangeFee | string* | exchange fee used |
spendTicker | string* | ticker that was withdrawn from balance (exchanged) |
spendAmount | string* | amount that was withdrawn from balance (exchanged) |
price | string* | price value, example: 23000 for BTC -> USDT pair |
pricePair | string*[2] | pair that used in exchange |
blockchain | string* | destination blockchain |
hash | string | blockchain transaction hash. Appear only on done status |
internal | boolean | 0xpay transaction – from 0xpay account to 0xpay address. No blockchain transaction |
to | string* | destination address |
exchanged | boolean | balances were swapped and exchanged succeeded |
First of all, invoices can be in two statuses:
- Pending – client entered his email and goes to "Enter card" form, email is available here⏳
- Done – invoice was paid✅
- ⏱ Expired – invoice expired. Expire time is invoice created date + 72 hours
Webhook request body:
Field | Type | Description |
---|---|---|
id | string* | Identifier |
kind | string* | "CryptoInvoice" |
ticker | string* | |
amount | string | amount specified when invoice was created or entered by user |
paidAmount | string | The field is optional and exists only when the status of the invoice is "Done". Look at the "status" field. This field can differ from amount field in specific bank cases so it should be used as source of true. |
fee | string | optional and exists only when status is "Done" |
meta | string | |
description | string | Invoice description |
status | string* | "Expired", "Pending", "Done" |
time | number* | timestamp when withdrawal was created in ms |
blockchain | string* | |
address | string* | Invoice receive address |
price | string | if baseAmount was specified.baseAmount to the amount conversion price |
paidPrice | string | if baseAmount was specified.baseAmount to the amount conversion price at the moment when the invoice paid. Can differ from price |
First of all, invoices can be in three statuses:
- Pending – client entered his email and goes to "Enter card" form, email is available here⏳
- Done – invoice was payed✅
- 😡 Failed – invoice failed
Webhook request body:
Field | Type | Description |
---|---|---|
id | string* | Identifier |
kind | string* | "Invoice" |
ticker | string* | "UAH" |
amount | string | amount specified when invoice was created or entered by user |
paidAmount | string | The field is optional and exists only when the status of the invoice is "Done". Look at the "status" field. This field can differ from amount field in specific bank cases so it should be used as source of true. |
fee | string | optional and exists only when status is "Done" |
meta | string | |
description | string | Invoice description |
status | string* | "Failed", "Pending", "Done" |
time | number* | timestamp when withdrawal was created in ms |
First of all, withdrawals can be in two statuses:
- 😡 Failed – withdrawal was failed
- Done – withdrawal was sent✅
Webhook request body:
Field | Type | Description |
---|---|---|
id | string* | Identifier |
kind | "Withdraw" | |
ticker | string* | "UAH" |
to | string* | destination card number |
amount | string* | amount in decimal format, look at the example |
fee | string | |
meta | string | |
localId | string | |
status | string* | "Failed", "Done" |
time | number* | timestamp when withdrawal was created in ms |
Fiat batch withdrawals are split into single withdraws, so some of them may fail.
Fail withdraws will be refunded to your balance, but you should pay attention to paidAmount, amount and failedAmount fileds in body.
You should use paid amount field which represents success withdrawal amount
First of all, batch withdraw can be in single status:
- Done – withdrawal was sent✅
Webhook request body:
Field | Type | Description |
---|---|---|
kind | "WithdrawBatch" | |
id | string* | Identifier |
ticker | string* | "UAH" |
amount | string* | amount in decimal format, look at the example |
paidAmount | string* | This field can differ from amount field in specific bank cases so it should be used as source of true. |
failedAmount | string* | withdraw amount that not sent on bank side |
fee | string | |
to | string* | destination card number |
meta | string | |
localId | string | |
status | string* | "Done" |
time | number* | timestamp when withdrawal was created in ms |
Statuses
- Exchanged - your swap is filled and balances are exchanged⏳
- 😡 Failed – can fire before exchanged status or after exchanged status (order not filled, withdraw is not successful and etc. In that case you should check you account in web application)
- Done – withdrawal was sent✅
Webhook request body:
Field | Type | Description |
---|---|---|
kind | "FiatExchangeWithdraw" | |
id | string* | Identifier |
ticker | string* | "UAH" |
amount | string* | amount in decimal format, look at the example |
paidAmount | string* | This field can differ from amount field in specific bank cases so it should be used as source of true. |
failedAmount | string* | withdraw amount that not sent on bank side |
fee | string* | |
meta | string | |
localId | string | |
status | string* | "Done" | "Exchanged" | "Failed" |
time | number* | timestamp when withdrawal was created in ms |
exchangeFee | string* | exchange fee used |
spendTicker | string* | ticker that was withdrawn from balance (exchanged) |
spendAmount | string* | amount that was withdrawn from balance (exchanged) |
price | string* | price value, example: 23000 for BTC -> USDT pair |
pricePair | string*[2] | pair that used in exchange |
exchanged | boolean | balances were swapped and exchanged succeeded |
to | string* | card number |
Statuses:
- 😡 Failed – can fire before exchanged status or after exchanged status (order not filled, exchange is not successful and etc. In that case you should check you account in web application)
- Done – success exchange✅
Webhook request body:
Field | Type | Description |
---|---|---|
id | string* | Identifier |
localId | string | |
time | number* | timestamp when exchange was created in ms |
meta | string | metadata you defined |
status | string* | "Failed", "Done" |
kind | "Exchange" | |
targetTicker | string* | |
targetAmount | string* | amount that was received to balance (exchanged) |
spendTicker | string* | |
spendAmount | string* | amount that was exchange from balance (exchanged) |
fee | string* | |
price | string* | price value, example: 23000 for BTC -> USDT pair |
pricePair | [string*, string*] | array of two tickers (targetTicker, spendTicker).
Values you can find here (Ticker column) + Fiat ticker "UAH" |
merchantId | string* | your own merchant identifier |
failedReason | string | reason why exchange was failed |
Last modified 13d ago