TypeScript SDK on GitHub
Browse the source code, examples, releases, and issue tracker.
Installation
Initialize the client
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 uniquerequestId for
each intended operation before sending it; reuse that ID and the same payload
if the response is lost.
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 receivedX-Billions-Signature header and JSON body to the SDK:
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 intry/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.