Callbacks

Methods for inspecting callbacks sent by B2BINPAY DeFi API for invoices and payouts

Get callbacks by operation ID

get

Retrieve a paginated list of callbacks for a specific operation ID

Authorizations

ApiKeyAuth

x-api-keystringRequired

Provide API key in X-API-Key header

Query parameters

operationIdstring · min: 1Required

ID of the operation to get callbacks for

Example: 97005662411689989

pageintegerOptional

Page number (starts from 1)

Default: 1

pageSizeinteger · max: 100Optional

Number of items per page (max 100)

Default: 10

Responses

200

Successfully retrieved callbacks

application/json

totalnumberRequired

Total number of items across all pages

pagenumberRequired

Current page number (starts from 1)

pageSizenumberRequired

Number of items per page

401

Invalid or missing token

get

/api/v1/callbacks

HTTPcURLJavaScriptPython

GET /api/v1/callbacks?operationId=97005662411689989 HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "url": "https://example.com/webhook",
      "type": "INVOICE_CREATED",
      "status": "CREATED",
      "operationId": "1234567890123456789",
      "operationType": "invoice",
      "attempt": 0,
      "timeSent": "2026-02-21T18:09:47.068Z",
      "responseCode": 200,
      "responseBody": {},
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}

---

Callback payload

Every callback body uses the same top-level structure:

id string · UUID

The unique callback identifier, in the UUID format.

type string

The callback type.

Invoice-related types:

• INVOICE_CREATED: The invoice was created.

• INVOICE_DEPOSIT_RECEIVED: An incoming deposit transaction was detected on the invoice address.

• INVOICE_DEPOSIT_CONFIRMED: The incoming transaction has reached the required number of confirmations.

• INVOICE_PAID: The paid amount is equal the requested amount and the invoice status changes to Paid* (for invoices with indicated amount).

• INVOICE_UNRESOLVED: The paid amount is greater than the requested amount and the invoice status changes to Unresolved* (for invoices with indicated amount).

• INVOICE_CLAIMED: Funds from the invoice address have been claimed to the account multisig wallet.

Payout-related types:

• PAYOUT_CREATED: The payout was created.

• PAYOUT_SENT: The payout transaction was sent to the blockchain.

• PAYOUT_EXECUTED: The payout transaction was mined to a block and executed successfully.

• PAYOUT_FAILED: The payout transaction failed in the blockchain.

operation_id string · UUID

The identifier of the original operation: invoiceId for invoice-related callback types, payoutId for payout-related callback types.

operation_type string

The original operation type: invoice or payout.

timestamp string

The date and time the callback was generated, in ISO 8601 format (UTC). Updated with each callback resend attempt.

data object

The callback-specific payload.

Always includes the original operation object (invoice or payout). May include transactions, claims, and other associated objects.

Below you can find examples of payloads for different callback types.

INVOICE_CREATED

{
  "id": "f7f2a2f4-2a8a-48cb-9c7a-6b5f2c1b1a33",
  "type": "INVOICE_CREATED",
  "operation_id": "93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
  "operation_type": "invoice",
  "timestamp": "2025-08-22T10:00:00Z",
  "data": {
    "invoice": {
      "id": "93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
      "invoiceAddress": "0x1234567890123456789012345678901234567890",
      "requestedAmount": "150.00",
      "paidAmount": "0.00",
      "status": "CREATED",
      "trackingId": "INV-2024-0001",
      "callbackUrl": "https://merchant.example.com/webhook/invoice",
      "paymentPageButtonUrl": "https://example.com/invoice/pay",
      "paymentPageButtonText": "Pay Invoice",
      "paymentPageUrl": "https://frontend.example.com/pay/93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
      "createdAt": "2025-08-22T10:00:00Z",
      "updatedAt": "2025-08-22T10:00:00Z"
    }
  }
}

INVOICE_DEPOSIT_RECEIVED

{
  "id": "dd08d1b9-0a1e-4e0b-9c8e-7a6f5e4d3c2b",
  "type": "INVOICE_DEPOSIT_RECEIVED",
  "operation_id": "93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
  "operation_type": "invoice",
  "timestamp": "2025-08-22T10:05:00Z",
  "data": {
    "invoice": {
      "id": "93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
      "invoiceAddress": "0x1234567890123456789012345678901234567890",
      "requestedAmount": "150.00",
      "paidAmount": "0.00",
      "status": "CREATED",
      "trackingId": "INV-2024-0001",
      "callbackUrl": "https://merchant.example.com/webhook/invoice",
      "paymentPageButtonUrl": "https://example.com/invoice/pay",
      "paymentPageButtonText": "Pay Invoice",
      "paymentPageUrl": "https://frontend.example.com/pay/93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
      "createdAt": "2025-08-22T10:00:00Z",
      "updatedAt": "2025-08-22T10:00:00Z"
    },
    "transaction": {
      "id": "9af6d8b1-6a2b-4c47-9c56-3a34a2e5d3d7",
      "direction": "IN",
      "chainId": 1,
      "txHash": "0x5555666677778888999900001111222233334444555566667777888899990000",
      "currencyId": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
      "amount": "150.00",
      "status": "PENDING",
      "fromAddress": "0xaaaa...aaaa",
      "toAddress": "0x1234567890123456789012345678901234567890",
      "blockNumber": 12345670,
      "confirmations": 0,
      "createdAt": "2025-08-22T10:05:00Z",
      "updatedAt": "2025-08-22T10:05:00Z",
      "isClaimed": false
    }
  }
}

INVOICE_DEPOSIT_CONFIRMED

{
  "id": "3f5a2a2b-4c1d-49d2-8e8a-9f3b0b0a1a22",
  "type": "INVOICE_DEPOSIT_CONFIRMED",
  "operation_id": "93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
  "operation_type": "invoice",
  "timestamp": "2025-08-22T10:10:00Z",
  "data": {
    "invoice": {
      "id": "93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
      "invoiceAddress": "0x1234567890123456789012345678901234567890",
      "requestedAmount": "150.00",
      "paidAmount": "0.00",
      "status": "CREATED",
      "trackingId": "INV-2024-0001",
      "callbackUrl": "https://merchant.example.com/webhook/invoice",
      "paymentPageButtonUrl": "https://example.com/invoice/pay",
      "paymentPageButtonText": "Pay Invoice",
      "paymentPageUrl": "https://frontend.example.com/pay/93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
      "createdAt": "2025-08-22T10:00:00Z",
      "updatedAt": "2025-08-22T10:00:00Z"
    },
    "transaction": {
      "id": "9af6d8b1-6a2b-4c47-9c56-3a34a2e5d3d7",
      "direction": "IN",
      "chainId": 1,
      "txHash": "0x5555666677778888999900001111222233334444555566667777888899990000",
      "currencyId": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
      "amount": "150.00",
      "status": "EXECUTED",
      "fromAddress": "0xaaaa...aaaa",
      "toAddress": "0x1234567890123456789012345678901234567890",
      "blockNumber": 12345678,
      "blockchainFee": "0.001",
      "confirmations": 12,
      "createdAt": "2025-08-22T10:05:00Z",
      "updatedAt": "2025-08-22T10:10:00Z",
      "confirmedAt": "2025-08-22T10:10:00Z",
      "isClaimed": false
    }
  }
}

INVOICE_PAID

{
  "id": "d2a5ee9c-6d9a-4f6a-a6a7-6efaf0a5b6f7",
  "type": "INVOICE_PAID",
  "operation_id": "93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
  "operation_type": "invoice",
  "timestamp": "2025-08-22T10:12:00Z",
  "data": {
    "invoice": {
      "id": "93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
      "invoiceAddress": "0x1234567890123456789012345678901234567890",
      "requestedAmount": "150.00",
      "paidAmount": "150.00",
      "status": "PAID",
      "trackingId": "INV-2024-0001",
      "callbackUrl": "https://merchant.example.com/webhook/invoice",
      "paymentPageButtonUrl": "https://example.com/invoice/pay",
      "paymentPageButtonText": "Pay Invoice",
      "paymentPageUrl": "https://frontend.example.com/pay/93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
      "createdAt": "2025-08-22T10:00:00Z",
      "updatedAt": "2025-08-22T10:00:00Z"
    }
  }
}

INVOICE_UNRESOLVED

{
  "id": "a8a4c8b7-3a4b-4f74-9e3d-bb3b0f9d0c9a",
  "type": "INVOICE_UNRESOLVED",
  "operation_id": "93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
  "operation_type": "invoice",
  "timestamp": "2025-08-22T10:15:00Z",
  "data": {
    "invoice": {
      "id": "93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
      "invoiceAddress": "0x1234567890123456789012345678901234567890",
      "requestedAmount": "150.00",
      "paidAmount": "160.00",
      "status": "UNRESOLVED",
      "trackingId": "INV-2024-0001",
      "callbackUrl": "https://merchant.example.com/webhook/invoice",
      "paymentPageButtonUrl": "https://example.com/invoice/pay",
      "paymentPageButtonText": "Pay Invoice",
      "paymentPageUrl": "https://frontend.example.com/pay/93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
      "createdAt": "2025-08-22T10:00:00Z",
      "updatedAt": "2025-08-22T10:00:00Z"
    }
  }
}

INVOICE_CLAIMED

{
  "id": "b1f2c3d4-e5f6-47a8-9123-4567890abcde",
  "type": "INVOICE_CLAIMED",
  "operation_id": "93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
  "operation_type": "invoice",
  "timestamp": "2025-08-22T10:20:00Z",
  "data": {
    "invoice": {
      "id": "93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
      "invoiceAddress": "0x1234567890123456789012345678901234567890",
      "requestedAmount": "150.00",
      "paidAmount": "0.00",
      "status": "PAID",
      "trackingId": "INV-2024-0001",
      "callbackUrl": "https://merchant.example.com/webhook/invoice",
      "paymentPageButtonUrl": "https://example.com/invoice/pay",
      "paymentPageButtonText": "Pay Invoice",
      "paymentPageUrl": "https://frontend.example.com/pay/93c75c47-40c3-4e2a-a65f-0f8fd48f6d83",
      "createdAt": "2025-08-22T10:00:00Z",
      "updatedAt": "2025-08-22T10:00:00Z"
    },
    "claim": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "PENDING",
      "chainId": 1,
      "currencyId": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
      "amount": "300.00",
      "fromAddress": "0x1234567890123456789012345678901234567890",
      "toAddress": "0x9876543210987654321098765432109876543210",
      "txHash": "0x5555666677778888999900001111222233334444555566667777888899990000",
      "linkedTransfers": [
        "001e4567-e89b-12d3-a456-426614174000",
        "002e4567-e89b-12d3-a456-426614174000"
      ],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "ethAmount": 0.5,
      "tokenAmount": 100
    }
  }
}

PAYOUT_CREATED

{
  "id": "0c9d8e7f-6a5b-4c3d-9e0f-1a2b3c4d5e6f",
  "type": "PAYOUT_CREATED",
  "operation_id": "abc12345-6789-4def-9012-34567890abcd",
  "operation_type": "payout",
  "timestamp": "2025-08-22T10:30:00Z",
  "data": {
    "payout": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "amount": "100.50",
      "toAddress": "0x9876543210987654321098765432109876543210",
      "trackingId": "INV-2024-0001",
      "callbackUrl": "https://example.com/webhook/invoice",
      "nonce": "42",
      "status": "CREATED",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "currency": {
        "id": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
        "symbol": "USDT",
        "name": "Tether USD",
        "chainId": 1,
        "address": "0xdac17f958d2ee523a2206206994597c13d831ec7"
      }
    }
  }
}

PAYOUT_SENT

{
  "id": "92f13f4b-5c7d-4f3a-912a-37b7e6a23f90",
  "type": "PAYOUT_SENT",
  "operation_id": "abc12345-6789-4def-9012-34567890abcd",
  "operation_type": "payout",
  "timestamp": "2025-08-22T10:33:00Z",
  "data": {
    "payout": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "amount": "100.50",
      "toAddress": "0x9876543210987654321098765432109876543210",
      "trackingId": "INV-2024-0001",
      "callbackUrl": "https://example.com/webhook/invoice",
      "nonce": "42",
      "status": "SENT",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "currency": {
        "id": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
        "symbol": "USDT",
        "name": "Tether USD",
        "chainId": 1,
        "address": "0xdac17f958d2ee523a2206206994597c13d831ec7"
      }
    },
    "transaction": {
      "id": "e7a89cde-1f23-45ab-9876-12c34d5678ef",
      "direction": "OUT",
      "chainId": 1,
      "txHash": "0xaaaabbbbccccddddeeeeffff1111222233334444555566667777888899990000",
      "currencyId": "1-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "amount": "500.00",
      "status": "PENDING",
      "fromAddress": "0xteamWallet...",
      "toAddress": "0xmerchantWallet...",
      "blockNumber": null,
      "confirmations": 0,
      "createdAt": "2025-08-22T10:33:00Z"
    }
  }
}

PAYOUT_EXECUTED

{
  "id": "2e4f6a8c-0b1d-4f2a-93c7-3d2e1f0a9b8c",
  "type": "PAYOUT_EXECUTED",
  "operation_id": "abc12345-6789-4def-9012-34567890abcd",
  "operation_type": "payout",
  "timestamp": "2025-08-22T10:37:00Z",
  "data": {
    "payout": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "amount": "100.50",
      "toAddress": "0x9876543210987654321098765432109876543210",
      "trackingId": "INV-2024-0001",
      "callbackUrl": "https://example.com/webhook/invoice",
      "nonce": "42",
      "status": "EXECUTED",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "currency": {
        "id": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
        "symbol": "USDT",
        "name": "Tether USD",
        "chainId": 1,
        "address": "0xdac17f958d2ee523a2206206994597c13d831ec7"
      }
    },
    "transaction": {
      "id": "def56789-1234-4abc-5678-901234567890",
      "direction": "OUT",
      "chainId": 1,
      "txHash": "0xaaaa...bbbb",
      "currencyId": "1-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "amount": "500.00",
      "status": "EXECUTED",
      "fromAddress": "0xteamWallet...",
      "toAddress": "0xmerchantWallet...",
      "blockNumber": 23456789,
      "confirmations": 15,
      "createdAt": "2025-08-22T10:35:00Z",
      "confirmedAt": "2025-08-22T10:37:00Z"
    }
  }
}

PAYOUT_FAILED

{
  "id": "6a7b8c9d-0e1f-4a2b-93c7-5d6e7f8a9b0c",
  "type": "PAYOUT_FAILED",
  "operation_id": "abc12345-6789-4def-9012-34567890abcd",
  "operation_type": "payout",
  "timestamp": "2025-08-22T10:40:00Z",
  "data": {
    "payout": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "amount": "100.50",
      "toAddress": "0x9876543210987654321098765432109876543210",
      "trackingId": "INV-2024-0001",
      "callbackUrl": "https://example.com/webhook/invoice",
      "nonce": "42",
      "status": "FAILED",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "currency": {
        "id": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
        "symbol": "USDT",
        "name": "Tether USD",
        "chainId": 1,
        "address": "0xdac17f958d2ee523a2206206994597c13d831ec7"
      }
    },
    "error": {
      "code": "INSUFFICIENT_FUNDS",
      "message": "Account balance at execution time was insufficient"
    }
  }
}

PAYOUT_CANCELLED

{
  "id": "6a7b8c9d-0e1f-4a2b-93c7-5d6e7f8a9b0c",
  "type": "PAYOUT_CANCELLED",
  "operation_id": "abc12345-6789-4def-9012-34567890abcd",
  "operation_type": "payout",
  "timestamp": "2025-08-22T10:40:00Z",
  "data": {
    "payout": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "amount": "100.50",
      "toAddress": "0x9876543210987654321098765432109876543210",
      "trackingId": "INV-2024-0001",
      "callbackUrl": "https://example.com/webhook/invoice",
      "nonce": "42",
      "status": "CANCELLED",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "currency": {
        "id": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
        "symbol": "USDT",
        "name": "Tether USD",
        "chainId": 1,
        "address": "0xdac17f958d2ee523a2206206994597c13d831ec7"
      }
    }
  }
}

Callback verification

Each callback request is signed to confirm that it was sent by the B2BINPAY DeFi API and was not modified in transit.

The signature is provided in the X-CALLBACK-SIGNATURE HTTP header, that contains an HMAC-SHA256 hash of the raw JSON payload and your callback secret.

Verification steps

1

Read the raw request body

Capture the exact HTTP body bytes as received:

• Do not re-serialize the JSON before verification.

• Use JSON.stringify(payload) without custom replacers/spacing (no pretty print).

• Ensure numbers and booleans stay as JSON primitives (do not stringify them).

• Timestamps must be in the UTC ISO 8601 format, for example: 2025-08-22T10:10:00Z.

2

Read the signature header

Get the value of the X-CALLBACK-SIGNATURE header.

→ If the header is missing, reject the request (HTTP code 400).

3

Compute the expected signature

Use HMAC with SHA-256:

• Key: callback_secret (UTF-8)

• Message: raw request body bytes (UTF-8)

• Output: hex string

4

Compare signatures

Compare the received signature with the computed one using a constant-time comparison.

5

Accept or reject

• If signatures match → process the callback (HTTP code 200).

• If they do not match → reject the request (HTTP code 401).

Callback processing example

// Express.js handler example
import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Capture the raw HTTP request body.
// This preserves the exact byte sequence used to generate the HMAC signature.
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf;
  }
}));

// Computes an HMAC-SHA256 signature (hex) over the raw request body.
function computeHmacHex(rawBodyBuffer, secret) {
  return crypto
    .createHmac('sha256', Buffer.from(secret, 'utf8'))
    .update(rawBodyBuffer) // IMPORTANT: use the raw body bytes, not a re-stringified JSON object.
    .digest('hex');
}

app.post('/webhook/invoice', (req, res) => {
  // Read the signature provided by the sender.
  const provided = req.get('X-CALLBACK-SIGNATURE');
  if (!provided) {
    return res.status(400).send('Missing X-CALLBACK-SIGNATURE');
  }

  // Shared callback secret (account-specific).
  const secret = process.env.CALLBACK_SECRET;

  // Recompute the expected signature from the raw request body.
  const expected = computeHmacHex(req.rawBody, secret);

  // Compare signatures using a constant-time algorithm to prevent timing attacks.
  const ok = crypto.timingSafeEqual(
    Buffer.from(provided, 'utf8'),
    Buffer.from(expected, 'utf8')
  );

  if (!ok) {
    return res.status(401).send('Invalid signature');
  }

  // (Optional) Apply replay protection here:
  // - Reject callbacks with duplicate IDs.
  // - Reject callbacks with stale timestamps.

  return res.sendStatus(200);

  // At this point, the callback is verified and can be safely processed
  const { type, operation_type, operation_id, data, timestamp } = req.body;
  // ... Your business logic ...
});

app.listen(3000, () => {
  console.log('Callback receiver listening on port 3000');
});