> ## 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.

# AI integration implementation checklist

> A task-by-task checklist for coding agents implementing Billions payments.

This page is a working checklist for a coding agent, not a replacement for the
[full Billions documentation](https://docs.billions.works/llms-full.txt).
Read the relevant source pages before writing code. If a requirement conflicts
with the current API schema or an SDK's current README, verify the deployed
environment and report the discrepancy instead of guessing.

## 1. Understand the project

* [ ] Inspect the application stack, existing checkout flow, order model,
  payment status transitions, background jobs, and test conventions.
* [ ] Identify where server-side secrets, the Billions API base URL, and
  callback URLs are configured. Never put credentials in frontend or mobile
  code, URLs, logs, or committed files.
* [ ] Identify the order's stable reference, the place to persist a Billions
  invoice ID, and the code path that fulfills an order exactly once.
* [ ] Ask for missing business decisions—such as settlement currency, supported
  payment methods, or fulfillment policy—rather than inventing them.

## 2. Choose one documented integration path

* [ ] For an existing store or billing platform, check the relevant
  [platform integration](https://docs.billions.works/store-integrations/overview.md) before writing a custom
  gateway. Follow that module's own installation and callback instructions.
* [ ] For a custom backend, use the [official SDK](https://docs.billions.works/sdks/overview.md) for the
  project's runtime when suitable. Otherwise use the [Public API](https://docs.billions.works/api/overview.md).
* [ ] Use the [Unified Merchant API](https://docs.billions.works/integration/unified-merchant-api.md) only
  when adapting an existing compatible SDK or module; it is a partial
  compatibility layer, not the default path for a new integration.
* [ ] Check the currently deployed [OpenAPI schema](https://docs.billions.works/api/overview.md#discover-the-api)
  for exact request and response fields. Do not invent endpoints or SDK methods.

## 3. Prepare the environment and credentials

* [ ] Direct the merchant to [sign up in the Billions app](https://app.billions.works/sign-up)
  and create separate sandbox and production API keys in **Settings → API**.
* [ ] Start with `https://api-sandbox.billions.works` and sandbox credentials.
  Keep them separate from production credentials and
  `https://api.billions.works`.
* [ ] Do not assume that a platform module can switch hosts: the current
  WooCommerce and WHMCS modules call production only. BILLmanager has a
  configurable API origin. Follow each module's guide.
* [ ] Store the API key in server-side secret storage. Store the original API
  key secret only if the chosen flow needs signed money operations or optional
  webhook signature verification.
* [ ] Configure a publicly reachable HTTPS callback URL for a custom
  integration. Check that the deployed service can reach the Billions API.
* [ ] Confirm supported currencies through the API instead of assuming a
  hard-coded list. Follow [prerequisites](https://docs.billions.works/integration/prerequisites.md).

## 4. Create an invoice safely

* [ ] Create invoices on the backend, never in the browser. Send the documented
  currency, amount, `order_no`, `idempotencyKey`, and callback URL.
* [ ] Keep `order_no` stable for the business order. Use a stable
  `idempotencyKey` for retries of the **same logical creation attempt**, and a
  new key for a deliberately new payment attempt.
* [ ] Persist the invoice ID, order reference, idempotency key, status, and
  expiration when provided. Handle network timeouts without creating an
  accidental second payment attempt.
* [ ] Redirect the customer using the returned `invoice_url` unchanged. Do not
  construct a checkout URL or treat the customer's return as payment proof.
* [ ] Follow the [payment flow](https://docs.billions.works/integration/payment-flow.md) and
  [create-invoice example](https://docs.billions.works/examples/create-an-invoice.md).

## 5. Confirm payment from the authoritative API

* [ ] Accept the documented callback payload and read `data.invoice_id` for
  new integrations. Treat the callback as a signal, not as proof of payment.
* [ ] Optionally verify `x-billions-signature` with the original API key
  secret and RFC 8785 JCS as defense in depth. Do not skip the API lookup even
  when the signature is valid.
* [ ] Retrieve the invoice through the authenticated Billions API. Match its
  invoice ID, order reference, `amount`, and `settlement_currency` against the
  stored payment attempt before changing the order. `currency` may be a
  network-specific internal ticker such as `USDT_TRON`.
* [ ] Fulfill only after the API returns `completed`. Keep `pending`,
  `processing`, `expired`, `failed`, and AML-related states distinct. Handle
  refund states if the application supports refunds.
* [ ] Make callbacks, polling, and fulfillment idempotent. Persist the state
  transition before acknowledging the callback; enqueue slow side effects.
* [ ] Add a recovery path for delayed or missed callbacks by retrieving the
  invoice from the API. Follow [callbacks and security](https://docs.billions.works/integration/callbacks-and-security.md)
  and the [callback example](https://docs.billions.works/examples/handle-a-callback.md).

## 6. Add optional money operations only when requested

* [ ] Do not add withdrawals or refunds unless they are in scope. If needed,
  follow [request signing](https://docs.billions.works/api/request-signing.md) and
  [withdrawals and refunds](https://docs.billions.works/api/withdrawals-and-refunds.md) exactly.
* [ ] Use the original API key secret, RFC 8785 canonical JSON, HMAC-SHA256,
  and the documented request-ID and retry rules. Never reuse a request ID for
  different operation data.

## 7. Test and hand off

* [ ] Test a successful sandbox payment end to end and confirm that only the
  authenticated API response marks the order paid.
* [ ] Test abandoned checkout, expired or failed invoice, duplicate and
  delayed callbacks, callback before customer return, and API timeouts.
* [ ] Test invalid signatures and mismatched invoice details where applicable.
  Confirm that repeated callbacks cannot repeat fulfillment.
* [ ] Run the project's relevant automated tests and the
  [go-live checklist](https://docs.billions.works/integration/go-live-checklist.md). Do not claim an
  end-to-end payment was tested unless it actually was.
* [ ] Report what was implemented, the files changed, tests run, remaining
  assumptions, and any steps that require merchant credentials or a real
  checkout. Do not silently switch to production.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.