Skip to main content
The BillStack API gives you programmatic access to virtual accounts, transactions, and webhooks so you can collect payments and receive real-time notifications from your own systems. Every interaction follows a consistent set of conventions : once you understand them here, they apply uniformly across every endpoint in this reference.

​
Base URL

All API requests are made over HTTPS to the following base URL:
There is no trailing slash. Every endpoint path in this reference is appended directly to this base URL (e.g., https://api.billstack.co/v2/reserved-accounts).

​
Request & Response Format

All request bodies must be JSON, and all responses are returned as JSON. Set the Content-Type header on every request that includes a body:
You do not need to set an Accept header : the API always responds with application/json.

​
Authentication

Authenticate your requests by passing your secret key as a Bearer token in the Authorization header:
Requests made without a valid, active key receive a 401 Unauthorized response. See the Authentication page for full details on public vs. secret keys and how to rotate them.

​
Response Envelope

Every API response : success or error : is wrapped in the same envelope. It always contains a boolean status, a human-readable message, and a data field. List responses additionally include a meta object with pagination details:
On failure, status is false, message describes what went wrong, and data is null:
Check the boolean status field to determine success or failure, and read message for context. See the Errors reference for HTTP status codes and how to handle them.

​
Pagination

All list endpoints support page-based pagination via two query parameters:
​
integer
default:"1"
The page number to retrieve. Starts at 1.
​
integer
default:"20"
The number of results to return per page.
The response meta object tells you where you are in the full result set:
​
object
Pagination metadata included on all list responses.
To page through a full result set, request page=1, then keep incrementing page until it reaches meta.totalPages.

​
Idempotency

When you initiate a transfer, you can include an idempotency_key in the request body to safely retry without risking a duplicate payout. If a transfer with the same key has already been accepted for your account, BillStack returns the existing transfer instead of creating a second one.
Use a UUID or another sufficiently random string as your key, and generate a fresh one per distinct transfer.
Always include an idempotency_key when initiating a transfer. Without it, a network timeout that prompts a retry could send the same payout twice.

​
Explore the API

Authentication

Learn how to obtain, use, and rotate your public and secret keys.

Errors

Browse the HTTP status codes BillStack returns and how to handle them gracefully.

Create Virtual Account

Provision a virtual bank account to start collecting payments for a customer.

Webhooks

Receive and verify real-time payment and transaction events on your server.