Callbacks

Overview

When a payment is sent to an address generated by Blockonomics, our system sends an HTTP GET request to your configured callback URL. This lets you fulfill orders and update payment state without polling the API.

Setting Up a Callback URL

In your Blockonomics dashboard, configure a callback URL for each store:

Include a secret query parameter — you'll use it to verify the callback is genuine.

Callback Payload

Blockonomics sends a GET request (not POST) to your callback URL with these query parameters:

Status Values

For most e-commerce use cases, treat status ≥ 2 as a confirmed payment.

Example Callback

Handling the Callback

// Express.js example
app.get('/api/payment-callback', (req, res) => {
  const { secret, addr, status, value, txid } = req.query

  // Verify the secret
  if (secret !== process.env.BLOCKONOMICS_CALLBACK_SECRET) {
    return res.status(403).send('Forbidden')
  }

  // Only act on confirmed payments
  if (parseInt(status) >= 2) {
    const btcAmount = parseInt(value) / 1e8
    // Fulfill the order associated with `addr`
    fulfillOrder(addr, btcAmount, txid)
  }

  res.send('OK')
})

Callback Behavior

• A callback is successful when your server returns HTTP 200
• Failed callbacks are retried up to 7 times with exponential backoff starting at 4 seconds
• Callbacks are only sent for transactions with a value greater than zero
• Each unique combination of txid, status, and addr is sent only once

Best Practices

• Always verify the secret before processing any callback
• Be idempotent — the same callback may arrive multiple times with increasing status
• Respond quickly — return 200 OK immediately, do heavy work in the background
• Wait for confirmations — always wait for status >= 2 before delivering products or services
• Watch for RBF — if you need to accept unconfirmed transactions (status = 0), reject any callback that includes the rbf parameter. RBF transactions can be cancelled or replaced by the sender before confirmation
• For USDT callbacks, see the Monitor USDT Transaction endpoint