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

{
  "type": "Invoice",
  "event": "transaction_created",
  "data": {
    "id": "cc75b958-5780-4b34-a33a-cf63b349fbab",
    "fee": "1.0",
    "fee_currency": "EUR",
    "uri": "bitcoin:2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB?amount=0.02038328",
    "status": "new",
    "status_context": null,
    "address": "2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB",
    "network": "bitcoin",
    "price_amount": "100.0",
    "price_currency": "EUR",
    "pay_amount": "0.02038328",
    "pay_currency": "BTC",
    "paid_amount": "0.02038328",
    "exchange": {
      "fee": "0.0",
      "pair": "BTCEUR",
      "rate": "4905.9838",
      "fee_currency": "EUR"
    },
    "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",
    "customer_id": null,
    "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",
    "fee": "1.0",
    "fee_currency": "EUR",
    "uri": "bitcoin:2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB?amount=0.02038328",
    "status": "new",
    "status_context": null,
    "address": "2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB",
    "network": "bitcoin",
    "price_amount": "100.0",
    "price_currency": "EUR",
    "pay_amount": "0.02038328",
    "pay_currency": "BTC",
    "paid_amount": "0.02038328",
    "exchange": {
      "fee": "0.0",
      "pair": "BTCEUR",
      "rate": "4905.9838",
      "fee_currency": "EUR"
    },
    "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",
    "customer_id": null,
    "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",
    "fee": "1.0",
    "fee_currency": "EUR",
    "uri": "bitcoin:2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB?amount=0.02038328",
    "status": "completed",
    "status_context": null,
    "address": "2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB",
    "network": "bitcoin",
    "price_amount": "100.0",
    "price_currency": "EUR",
    "pay_amount": "0.02038328",
    "pay_currency": "BTC",
    "paid_amount": "0.02038328",
    "exchange": {
      "fee": "0.0",
      "pair": "BTCEUR",
      "rate": "4905.9838",
      "fee_currency": "EUR"
    },
    "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",
    "customer_id": null,
    "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",
    "fee": "1.0",
    "fee_currency": "EUR",
    "uri": "bitcoin:2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB?amount=0.02038328",
    "status": "unresolved",
    "status_context": "illicit_resource",
    "address": "2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB",
    "network": "bitcoin",
    "price_amount": "100.0",
    "price_currency": "EUR",
    "pay_amount": "0.02038328",
    "pay_currency": "BTC",
    "paid_amount": "0.02038328",
    "exchange": {
      "fee": "0.0",
      "pair": "BTCEUR",
      "rate": "4905.9838",
      "fee_currency": "EUR"
    },
    "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",
    "customer_id": null,
    "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 get more information about invoice statuses and exceptions.