Skip to main content

TypeScript SDK on GitHub

Browse the source code, examples, releases, and issue tracker.

Installation

Initialize the client

The TypeScript SDK uses https://api.billions.works when baseUrl is omitted. Set BILLIONS_API_URL=https://api-sandbox.billions.works explicitly before running any example with sandbox credentials.
Use BILLIONS_API_URL=https://api-sandbox.billions.works for testing. Omit baseUrl to use production. secretKey is the original secret issued with the API key; it enables signed money operations and webhook verification.

Create an invoice

Withdrawals and refunds

The SDK signs these operations automatically. Store a unique requestId for each intended operation before sending it; reuse that ID and the same payload if the response is lost.
Passing no second argument makes the SDK generate a fresh request ID. Save each ID before the call and reuse it with the identical payload on retry. See Withdrawals and refunds for validation rules and response fields.

Common operations

getCountries() returns country codes and names. estimateFees() returns amount, finalPrice, fee, and merchantReceiveAmount; summaryFee may also be present. Invoice objects include invoice_url, order_no, expires_at, network_and_other_fees, and status.

Verify a webhook signature

Pass the received X-Billions-Signature header and JSON body to the SDK:
The body may be the raw JSON text, UTF-8 bytes, or an already parsed object. The SDK canonicalizes the JSON according to RFC 8785 JCS, then verifies its HMAC-SHA256 signature using secretKey. It accepts both the full jcs-sha256=<hex> header and a plain hex digest. A valid signature does not replace the authenticated invoice lookup.

Verify a payment callback

verifyInvoicePaid() retrieves the invoice from the authenticated API, requires the invoice status to be completed, and compares the callback status and paid amount with the API result.
verifyInvoicePaid() accepts the current webhook envelope as well as legacy callback objects. For intermediate events, use getInvoiceFromWebhook() and base any order state change on the API response.

Handle errors

Wrap API calls in try/catch, log a correlation identifier instead of secrets, and retry only operations that are safe to repeat. Reuse the same idempotency key when retrying the same invoice creation.