> ## Documentation Index
> Fetch the complete documentation index at: https://docs.billions.works/llms.txt
> Use this file to discover all available pages before exploring further.

# Callbacks and security

> Process invoice notifications without trusting unverified input.

Use callbacks to wake your integration, not as proof of payment.

## Callback payload

Billions sends an HTTP `POST` request with a JSON body:

```json theme={null}
{
  "id": "invoice-id",
  "status": "completed",
  "paid_amount": "100.000000000000000000"
}
```

| Field         | Type   | Description                                                                                 |
| ------------- | ------ | ------------------------------------------------------------------------------------------- |
| `id`          | string | Billions invoice ID. Use it to retrieve the invoice from the authenticated API.             |
| `status`      | string | Invoice status at the time the callback was created. Treat it as untrusted until verified.  |
| `paid_amount` | string | Amount reported as paid. Compare it with the authenticated API response before fulfillment. |

The request uses the `Content-Type: application/json` header.

<Warning>
  The callback payload is not proof of payment. An attacker can send a request
  directly to a public callback endpoint. Retrieve the invoice using `id` and
  trust only the authenticated API response.
</Warning>

## Safe callback algorithm

<Steps>
  <Step title="Accept the request">
    Parse only enough data to identify the invoice. Reject malformed requests
    without exposing internal error details.
  </Step>

  <Step title="Retrieve the invoice">
    Call the authenticated Billions API with the invoice ID.
  </Step>

  <Step title="Match your records">
    Confirm the retrieved invoice belongs to the expected `order_no` and payment
    attempt.
  </Step>

  <Step title="Apply the transition once">
    Update the order in a database transaction and make side effects idempotent.
  </Step>

  <Step title="Return promptly">
    Respond successfully after durable processing, or enqueue slow work for a
    background worker.
  </Step>
</Steps>

## Security checklist

* Keep API keys in server-side secret storage.
* Require HTTPS for the callback endpoint.
* Retrieve invoice state from the API before fulfillment.
* Compare the invoice to the stored order and expected amount.
* Treat all callback fields as untrusted input.
* Avoid logging API keys or complete sensitive payloads.
* Rate-limit the callback endpoint.
* Make duplicate delivery harmless.

<Tip>
  The TypeScript and PHP SDKs include `verifyInvoicePaid()`. It retrieves the
  invoice, requires `completed` status, and compares callback status and paid
  amount with the API result.
</Tip>

## Response behavior

Your endpoint should acknowledge a callback only after the event is stored or
processed durably.

<Note>
  TODO: Add the delivery timeout, retry schedule, expected HTTP success codes,
  signature mechanism if applicable, and source IP policy after the callback
  delivery implementation is finalized.
</Note>