Invoice callbacks

Handling callbacks correctly is crucial to ensure your integration’s business logic works as expected. It is highly recommended to validate payment statuses and callbacks before acting on it inside your system.

Refer to this section to get more information on what callbacks are and how to validate them before acting on it inside your system.

Event

status

status_context

Description

transaction_created

new

null

A customer has just broadcast the transaction on the bitcoin network

transaction_confirmed

new

null

The transaction has just been confirmed on the network

status_changed

completed

null

The invoice status has been changed

unresolved

illicit_resource

unresolved

overpaid

unresolved

underpaid

unresolved

paid_late

refunded

null

cancelled

null

Transaction created
Transaction confirmed
Status change
Illicit resource
Transaction created
{
"type": "Invoice",
"event": "transaction_created",
"data": {
"id": "cc75b958-5780-4b34-a33a-cf63b349fbab",
"status": "new",
"status_context": null,
"address": "2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB",
"price_amount": "100.0",
"price_currency": "EUR",
"pay_amount": "0.02038328",
"pay_currency": "BTC",
"paid_amount": "0.02038328",
"exchange": {
"pair": "BTCEUR",
"rate": "4905.9838"
},
"transactions": [
{
"txid": "502e6de0c3b1d129974c55e6cd127fd548e4501ff8e8d9330ea9a30a83dbd16e",
"risk": {
"score": 3.1,
"level": "low",
"resource_name": "Bitstamp",
"resource_category": "Exchange"
}
}
],
"name": "invoice name",
"description": "invoice description",
"metadata": {
"foo": "bar"
},
"success_redirect_url": null,
"hosted_page_url": "https://hosted-business.cryptopay.me/invoices/cc75b958-5780-4b34-a33a-cf63b349fbab",
"custom_id": "209584732",
"created_at": "2019-05-02T13:56:56+00:00",
"expires_at": "2019-05-02T14:06:56+00:00"
}
}
Transaction confirmed
{
"type": "Invoice",
"event": "transaction_confirmed",
"data": {
"id": "cc75b958-5780-4b34-a33a-cf63b349fbab",
"status": "new",
"status_context": null,
"address": "2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB",
"price_amount": "100.0",
"price_currency": "EUR",
"pay_amount": "0.02038328",
"pay_currency": "BTC",
"paid_amount": "0.02038328",
"exchange": {
"pair": "BTCEUR",
"rate": "4905.9838"
},
"transactions": [
{
"txid": "502e6de0c3b1d129974c55e6cd127fd548e4501ff8e8d9330ea9a30a83dbd16e",
"risk": {
"score": 3.1,
"level": "low",
"resource_name": "Bitstamp",
"resource_category": "Exchange"
}
}
],
"name": "invoice name",
"description": "invoice description",
"metadata": {
"foo": "bar"
},
"success_redirect_url": null,
"hosted_page_url": "https://hosted-business.cryptopay.me/invoices/cc75b958-5780-4b34-a33a-cf63b349fbab",
"custom_id": "209584732",
"created_at": "2019-05-02T13:56:56+00:00",
"expires_at": "2019-05-02T14:06:56+00:00"
}
}
Status change
{
"type": "Invoice",
"event": "status_changed",
"data": {
"id": "cc75b958-5780-4b34-a33a-cf63b349fbab",
"status": "completed",
"status_context": null,
"address": "2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB",
"price_amount": "100.0",
"price_currency": "EUR",
"pay_amount": "0.02038328",
"pay_currency": "BTC",
"paid_amount": "0.02038328",
"exchange": {
"pair": "BTCEUR",
"rate": "4905.9838"
},
"transactions": [
{
"txid": "502e6de0c3b1d129974c55e6cd127fd548e4501ff8e8d9330ea9a30a83dbd16e",
"risk": {
"score": 3.1,
"level": "low",
"resource_name": "Bitstamp",
"resource_category": "Exchange"
}
}
],
"name": "invoice name",
"description": "invoice description",
"metadata": {
"foo": "bar"
},
"success_redirect_url": null,
"hosted_page_url": "https://hosted-business.cryptopay.me/invoices/cc75b958-5780-4b34-a33a-cf63b349fbab",
"custom_id": "209584732",
"created_at": "2019-05-02T13:56:56+00:00",
"expires_at": "2019-05-02T14:06:56+00:00"
}
}
Illicit resource
{
"type": "Invoice",
"event": "status_changed",
"data": {
"id": "cc75b958-5780-4b34-a33a-cf63b349fbab",
"status": "unresolved",
"status_context": "illicit_resource",
"address": "2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB",
"price_amount": "100.0",
"price_currency": "EUR",
"pay_amount": "0.02038328",
"pay_currency": "BTC",
"paid_amount": "0.02038328",
"exchange": {
"pair": "BTCEUR",
"rate": "4905.9838"
},
"transactions": [
{
"txid": "502e6de0c3b1d129974c55e6cd127fd548e4501ff8e8d9330ea9a30a83dbd16e",
"risk": {
"score": 10.0,
"level": "low",
"resource_name": "Hydra Marketplace",
"resource_category": "Dark Market - Centralised"
}
}
],
"name": "invoice name",
"description": "invoice description",
"metadata": {
"foo": "bar"
},
"success_redirect_url": null,
"hosted_page_url": "https://hosted-business.cryptopay.me/invoices/cc75b958-5780-4b34-a33a-cf63b349fbab",
"custom_id": "209584732",
"created_at": "2019-05-02T13:56:56+00:00",
"expires_at": "2019-05-02T14:06:56+00:00"
}
}
Navigate to the
Invoice statuses
section to

Navigate to the Invoice statuses section to get more information about invoice statuses and exceptions.