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
​

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

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"

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

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

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

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

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

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

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

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

Exchange + Withdrawal

Notification Examples

Last modified 13d ago