Quickstart
This guide walks you through your first payment with the b-paid API: you get a sandbox API key, add money to your sandbox account, then send a payment and check it. Everything here runs in the sandbox, where no real money moves. Before you start, set up API access.
1. Get your sandbox API key
Section titled “1. Get your sandbox API key”In the b-paid web app, open Developers and select Create API key under Sandbox API keys. Select Show keys and copy the Primary value.
Test the key by retrieving your account:
curl https://api.b-paid.com/v1/account \ --header "X-Api-Key: <your sandbox API key>"If the key works, you get your account back:
{ "id": "ACC-ONE-000-BZ", "name": "Your Business", "available_balance": 0}id is your bpid. Other b-paid accounts use it to pay you.
2. Add money to your sandbox account
Section titled “2. Add money to your sandbox account”Your sandbox account starts at $0.00. Call Sandbox: Receive a payment to have the test account SIM-PAY-001-BZ pay you $1,000.00. Amounts are in cents, so $1,000.00 is 100000:
curl https://api.b-paid.com/v1/simulations/inbound_payments \ --header "X-Api-Key: <your sandbox API key>" \ --header "Content-Type: application/json" \ --data '{"amount": 100000}'In response you get the payment, already complete:
{ "id": "BPT-000000-000003-00", "status": "complete", "amount": 100000, "amount_paid": 100000, "source_account_id": "SIM-PAY-001-BZ", "destination_account_id": "ACC-ONE-000-BZ", "net_terms_days": null, "quick_pay_percent": null, "scheduled_for": null, "created_at": "2026-10-22T17:42:08.1234567Z"}The $1,000.00 is now in your available balance.
3. Send a payment
Section titled “3. Send a payment”Pay $250.00 to the test account SIM-PAY-002-BZ. Send a unique Idempotency-Key with every new payment, such as a UUID. If the request fails or times out, send it again with the same key: you get the first payment back instead of paying twice. See Idempotent requests.
curl https://api.b-paid.com/v1/payments \ --header "X-Api-Key: <your sandbox API key>" \ --header "Idempotency-Key: <a new UUID>" \ --header "Content-Type: application/json" \ --data '{"amount": 25000, "destination_account_id": "SIM-PAY-002-BZ"}'In the sandbox, a payment to SIM-PAY-001-BZ through SIM-PAY-010-BZ is complete at once:
{ "id": "BPT-000000-000004-00", "status": "complete", "amount": 25000, "amount_paid": 25000, "source_account_id": "ACC-ONE-000-BZ", "destination_account_id": "SIM-PAY-002-BZ", "net_terms_days": null, "quick_pay_percent": null, "scheduled_for": null, "created_at": "2026-10-22T17:43:51.5550912Z"}4. Check the payment
Section titled “4. Check the payment”Retrieve the payment by the id from step 3 to see its current status:
curl https://api.b-paid.com/v1/payments/<id from step 3> \ --header "X-Api-Key: <your sandbox API key>"List payments shows every payment from or to your account, including the one from step 2.