List payments

GET

/v1/payments

Shell / cURL

curl --request GET \
  --url 'https://api.b-paid.com/v1/payments?limit=100' \
  --header 'X-Api-Key: <X-Api-Key>'

Returns the payments sent from or to your account, in every status, including payments made in the b-paid app. The payments are sorted with the most recently created first. To get the next page, pass next_cursor as cursor, with the same filters, until next_cursor is null. A payment can appear a moment after a newer one, so to poll for new payments, list with created_at.on_or_after a few minutes before the newest created_at you have, and skip ids you already have.

Authorizations

ApiKey

Parameters

Query Parameters

limit

integer format: int32

default: 100 >= 1 <= 100

The number of payments to return, 1 to 100. The default is 100.

cursor

string

The next_cursor of the previous page. Omit it for the first page.

source_account_id

string

Only return payments sent from this bpid. Use your own bpid to list the payments you sent.

destination_account_id

string

Only return payments sent to this bpid. Use your own bpid to list the payments you received.

status.in

Array<string>

Allowed values: pending scheduled complete failed canceled

Only return payments with these statuses, comma-separated, for example pending,scheduled.

created_at.after

string format: date-time

/^[0-9]{4}-[0-9]{2}-[0-9]{2}[Tt][0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?([Zz]|[+-][0-9]{2}:[0-9]{2})$/

Only return payments created after this ISO 8601 timestamp, with Z or an offset (send + as %2B), for example 2026-10-01T00:00:00Z.

created_at.before

string format: date-time

/^[0-9]{4}-[0-9]{2}-[0-9]{2}[Tt][0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?([Zz]|[+-][0-9]{2}:[0-9]{2})$/

Only return payments created before this ISO 8601 timestamp, with Z or an offset (send + as %2B).

created_at.on_or_after

string format: date-time

/^[0-9]{4}-[0-9]{2}-[0-9]{2}[Tt][0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?([Zz]|[+-][0-9]{2}:[0-9]{2})$/

Only return payments created on or after this ISO 8601 timestamp, with Z or an offset (send + as %2B).

created_at.on_or_before

string format: date-time

/^[0-9]{4}-[0-9]{2}-[0-9]{2}[Tt][0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?([Zz]|[+-][0-9]{2}:[0-9]{2})$/

Only return payments created on or before this ISO 8601 timestamp, with Z or an offset (send + as %2B).

idempotency_key

string

>= 1 characters <= 200 characters

Only return the payment created with this Idempotency-Key. The list is empty if the key is unused.

Responses

200

One page of payments.

application/json

One page of payments, newest first.

object

data

The payments on this page, newest first.

Array<object>

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

object

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"
}

next_cursor

Pass this as cursor to get the next page of older payments. null when there are no more results. Treat it as an opaque string.

string

nullable

Example

{
  "data": [
    {
      "id": "BPT-000000-000002-00",
      "status": "complete",
      "amount": 145000,
      "amount_paid": 141375,
      "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-15T14:05:31.2468135Z",
      "created_at": "2026-09-15T14:05:31.2468135Z"
    }
  ],
  "next_cursor": "BPT-000000-000002-00"
}

400

A query parameter is unknown, empty, repeated or invalid, or cursor is not a next_cursor from your account (invalid_parameters_error). detail names the parameter.

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.

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 the same request.

503

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