Create a payment

POST

/v1/payments

Code sample: Shell / cURL

curl --request POST \
  --url https://api.b-paid.com/v1/payments \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <unique-key-per-payment>' \
  --header 'X-Api-Key: <X-Api-Key>' \
  --data '{ "amount": 145000, "destination_account_id": "SIM-PAY-002-BZ", "net_terms_days": 30, "quick_pay_percent": 2.5 }'

Pays another b-paid account from your account, now or on a due date (net_terms_days). If your available balance doesn’t cover the amount, you get the payment back with status failed, and nothing is taken from your balance.

Authorizations

• ApiKey

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters <= 200 characters

A unique value you choose for each new payment, such as a UUID, 1 to 200 ASCII characters. Strongly recommended. If you send the same payment again with the same key, you get back the payment the first request created, as it is now, and no second payment is made. Without a key, every request creates a new payment.

• Reusing a key with a different amount, destination_account_id, net_terms_days or quick_pay_percent returns 409 idempotency_key_already_used_error.
• A 400 creates nothing, so you can use its key again.
• A failed payment keeps its key. To try again, use a new key.
• Idempotency keys are shared by all the API keys of your account, separately for live and sandbox.

Example

<unique-key-per-payment>

Request Body^required

Media typeapplication/json

A payment to create. Only amount and destination_account_id are required.

object

amount

required

A positive integer in cents (USD), at most 99999999 ($999,999.99). For example, $1,450.00 is 145000.

integer format: int64

>= 1 <= 99999999

destination_account_id

required

The bpid of the account that will receive the payment. In the sandbox, you can pay only the test accounts, such as SIM-PAY-002-BZ.

string

net_terms_days

The number of days until the payment is due, 1 to 180. Omit it to pay now. The payment is due exactly that many 24-hour days after you create it, weekends included. Until then, the amount is set aside from your available balance.

integer format: int32

nullable >= 1 <= 180

quick_pay_percent

Quick pay: a discount you offer the recipient for being paid before the due date, as a flat percent of amount (not an annual rate). 0.01 to 99.99, with at most two decimal places. Requires net_terms_days. The recipient accepts it in the b-paid app. The full percent applies for the first 24 hours after you create the payment, then drops by an equal step every 24 hours, reaching 0 at scheduled_for. Each day’s percent is rounded to two decimal places, and the discount to the nearest cent (halves round to even). For example, with net_terms_days 30 and quick_pay_percent 2.5, a $1,450.00 payment accepted in the first 24 hours pays $1,413.75. The percent drops to 2.42 for the next 24 hours, and down to 0.08 in the last 24.

number format: double

nullable >= 0.01 <= 99.99

Example

{
  "amount": 145000,
  "destination_account_id": "SIM-PAY-002-BZ",
  "net_terms_days": 30,
  "quick_pay_percent": 2.5
}

Responses

200

The created payment. Also returned, with Idempotent-Replayed: true, when you send the same payment again with the same Idempotency-Key.

Media typeapplication/json

A payment between your account and another b-paid account, sent or received.

object

id

Unique identifier for the payment. The b-paid app shows it as the payment’s reference number. Treat it as an opaque string.

string

status

Where the payment stands.

• pending: The payment is being processed. The money may already have moved. A payment with a due date is pending while it is being paid, and can be pending briefly before it is scheduled. It can be canceled only once it is scheduled.
• scheduled: The payment is waiting for its due date. The amount is set aside from the sender’s available balance.
• complete: The payment has been paid. This is final.
• failed: The payment was not paid, for example because the sender’s available balance was too low, or because by the due date one of the accounts could no longer send or receive payments. Any amount set aside is returned to the sender’s available balance. To find out why a payment failed, contact b-paid support with its id. This is final.
• canceled: The sender canceled the scheduled payment. The amount is returned to the sender’s available balance. This is final.

string

Allowed values: pending scheduled complete failed canceled

amount

The payment amount in cents (USD), as created. It never changes.

integer format: int64

amount_paid

The amount paid in cents (USD), once the payment is complete; null until then. If the recipient accepted quick pay, this is amount minus the discount.

integer format: int64

nullable

source_account_id

The bpid of the account that sends the payment.

string

destination_account_id

The bpid of the account that receives the payment.

string

net_terms_days

The number of days from creation to the due date. null for a payment made now.

integer format: int32

nullable

quick_pay_percent

The quick pay discount, in percent, offered to the recipient for being paid before the due date. null if none was offered.

number format: double

nullable

scheduled_for

The ISO 8601 date and time at which the payment is due. The payment is made shortly after this time. null for a payment made now. A payment the recipient accepted early with quick pay keeps its original scheduled_for.

string format: date-time

nullable

created_at

The ISO 8601 date and time at which the payment was created.

string format: date-time

Example

{
  "id": "BPT-000000-000001-00",
  "status": "scheduled",
  "amount": 145000,
  "amount_paid": null,
  "source_account_id": "ACC-ONE-000-BZ",
  "destination_account_id": "SIM-PAY-002-BZ",
  "net_terms_days": 30,
  "quick_pay_percent": 2.5,
  "scheduled_for": "2026-10-22T17:42:08.1234567Z",
  "created_at": "2026-09-22T17:42:08.1234567Z"
}

Headers

Idempotent-Replayed

string

Allowed values: true

true when this response returns the payment an earlier request with the same Idempotency-Key created. Absent otherwise.

400

No payment was created (invalid_parameters_error). detail says what to fix, for example a destination_account_id that isn’t a b-paid account that can receive payments.

401

The API key is missing, unknown or revoked (invalid_api_key_error).

403

API access isn’t turned on for your account (insufficient_permissions_error); b-paid support can turn it on. Or your business isn’t verified yet (verification_required_error); finish verifying it in the b-paid app.

409

This Idempotency-Key was already used to create a different payment (idempotency_key_already_used_error). resource_id is the id of that payment.

415

Send the body as Content-Type: application/json (unsupported_media_type_error).

429

Too many requests (rate_limited_error). Wait the number of seconds in the Retry-After header, then retry.

Headers

Retry-After

integer

Seconds to wait before retrying.

500

Something went wrong on our side (internal_server_error). Retry with the same Idempotency-Key.

503

The b-paid API is temporarily unavailable (service_unavailable_error). Retry in a moment with the same Idempotency-Key.