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 before writing a custom gateway. Follow that module’s own installation and callback instructions.
- For a custom backend, use the official SDK for the project’s runtime when suitable. Otherwise use the Public API.
- Use the Unified Merchant API 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 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 and create separate sandbox and production API keys in Settings → API.
- Start with
https://api-sandbox.billions.worksand sandbox credentials. Keep them separate from production credentials andhttps://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.
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_nostable for the business order. Use a stableidempotencyKeyfor 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_urlunchanged. Do not construct a checkout URL or treat the customer’s return as payment proof. - Follow the payment flow and create-invoice example.
5. Confirm payment from the authoritative API
- Accept the documented callback payload and read
data.invoice_idfor new integrations. Treat the callback as a signal, not as proof of payment. - Optionally verify
x-billions-signaturewith 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, andsettlement_currencyagainst the stored payment attempt before changing the order.currencymay be a network-specific internal ticker such asUSDT_TRON. - Fulfill only after the API returns
completed. Keeppending,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 and the callback example.
6. Add optional money operations only when requested
- Do not add withdrawals or refunds unless they are in scope. If needed, follow request signing and withdrawals and refunds 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. 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.