Skip to main content
Before integrating, prepare the following:
  • A Billions API key stored only on your backend.
  • A public HTTPS callback endpoint.
  • A unique order reference in your system.
  • A persistent place to store the Billions invoice ID.
  • A strategy for retrying network requests safely.
Sign up in the Billions app, then open Settings → API to create separate API keys for sandbox and production. Use each key only with its matching environment.
The SDKs use https://api.billions.works and public API version v1 by default. Use https://api-sandbox.billions.works while testing.

Choose an environment

Keep separate credentials and configuration for each environment. Make the API base URL an environment variable so production cannot be selected accidentally:

Keep credentials server-side

Never embed the API key in browser code, a mobile application, a public repository, or logs. Load it from a secret manager or environment variable. For signed money operations and optional webhook signature verification, also store the original API key secret. It is displayed only once when the API key is created and must be treated as a server-side secret.

Define two identifiers

Use separate identifiers for separate jobs: An order may have more than one payment attempt. In that case, keep order_no stable and use a new idempotency key for each intentional attempt.
Reuse an idempotency key only when retrying the same logical invoice creation. Do not reuse one key for unrelated orders.
Use the public currencies endpoint instead of hard-coding a currency list.