Search…
⌃K

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.
Webhooks require authorization on your side, in order to verify the validity of message received.
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.

Notifications retry timeline:

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.

Crypto

Replenishment

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*
values you can find here (Ticker column)
blockchain
string*
available values you can find here ("API value" column)
from
string[]*
List of sender addresses
to
string*
destination address
amount
string*
amount in decimal format, look at the example
fee
string
service fee, learn more here
meta
string
metadata, you defined when address was allocated
status
string*
"Pending", "Done"

Withdrawal

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*
values you can find here (Ticker column)
blockchain
string*
available values you can find here ("API value" column)
from
string[]*
List of sender addresses
to
string*
destination address
amount
string*
amount in decimal format, look at the example
fee
string
service fee, learn more here
meta
string
metadata you defined when withdrawal was created
localId
string
localId you defined when withdrawal was created
status
string*
"Pending", "Done", "Failed"
time
number*
timestamp when withdrawal was created in ms

Exchange Withdrawal (coming soon)

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*
values you can find here (Ticker column)
amount
string*
amount in decimal format
fee
string*
withdraw service fee, learn more here
meta
string
metadata you defined when withdrawal was created
localId
string
localId you defined when withdrawal was created
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

Invoice

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*
values you can find here (Ticker column)
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
metadata you defined when withdrawal was created
description
string
Invoice description
status
string*
"Expired", "Pending", "Done"
time
number*
timestamp when withdrawal was created in ms
blockchain
string*
available values you can find here ("API value" column)
address
string*
Invoice receive address
price
string
if baseAmountwas specified.baseAmount to the amount conversion price
paidPrice
string
if baseAmountwas specified.baseAmount to the amount conversion price at the moment when the invoice paid. Can differ from price

Fiat

Invoice

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
metadata you defined when withdrawal was created
description
string
Invoice description
status
string*
"Failed", "Pending", "Done"
time
number*
timestamp when withdrawal was created in ms

Withdrawal

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
service fee, learn more here
meta
string
metadata you defined when withdrawal was created
localId
string
localId you defined when withdrawal was created
status
string*
"Failed", "Done"
time
number*
timestamp when withdrawal was created in ms

Batch Withdrawal

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
service fee, learn more here
to
string*
destination card number
meta
string
metadata you defined when withdrawal was created
localId
string
localId you defined when withdrawal was created
status
string*
"Done"
time
number*
timestamp when withdrawal was created in ms

Exchange Withdrawal (coming soon)

Fiat batch withdrawals are used here. Read more about that here.
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*
withdraw service fee, learn more here
meta
string
metadata you defined when withdrawal was created
localId
string
localId you defined when withdrawal was created
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

Exchange

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
localId you defined when exchange was created
time
number*
timestamp when exchange was created in ms
meta
string
metadata you defined
status
string*
"Failed", "Done"
kind
"Exchange"
targetTicker
string*
Ticker you chose to receive. values you can find here (Ticker column) + Fiat ticker "UAH"
targetAmount
string*
amount that was received to balance (exchanged)
spendTicker
string*
Ticker you chose to spend. values you can find here (Ticker column) + Fiat ticker "UAH"
spendAmount
string*
amount that was exchange from balance (exchanged)
fee
string*
withdraw service fee, learn more here
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