{ "openapi": "3.0.4", "info": { "title": "b-paid API", "description": "The b-paid API lets you pay other b-paid accounts and see the payments you send and receive. Send your API key in the `X-Api-Key` header. The key you use determines whether the request runs live or in the sandbox, where no real money moves.", "contact": { "name": "b-paid support", "email": "support@b-paid.com" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.b-paid.com" } ], "paths": { "/v1/account": { "get": { "tags": [ "Account" ], "summary": "Retrieve your account", "description": "Retrieves the account your API key belongs to, with its available balance.", "operationId": "retrieve_account", "responses": { "400": { "description": "A query parameter is unknown, empty or repeated (`invalid_parameters_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "401": { "description": "The API key is missing, unknown or revoked (`invalid_api_key_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "403": { "description": "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.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "429": { "description": "Too many requests (`rate_limited_error`). Wait the number of seconds in the `Retry-After` header, then retry.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "500": { "description": "Something went wrong on our side (`internal_server_error`). Retry the same request.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "503": { "description": "The b-paid API is temporarily unavailable (`service_unavailable_error`). Retry the same request in a moment.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "200": { "description": "Your account.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } } } } }, "/v1/payments": { "post": { "tags": [ "Payments" ], "summary": "Create a payment", "description": "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.", "operationId": "create_payment", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "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.\n\n- Reusing a key with a different `amount`, `destination_account_id`, `net_terms_days` or `quick_pay_percent` returns `409 idempotency_key_already_used_error`.\n- A `400` creates nothing, so you can use its key again.\n- A `failed` payment keeps its key. To try again, use a new key.\n- Idempotency keys are shared by all the API keys of your account, separately for live and sandbox.", "schema": { "maxLength": 200, "minLength": 1, "type": "string" }, "example": "" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" } } }, "required": true }, "responses": { "400": { "description": "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.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "401": { "description": "The API key is missing, unknown or revoked (`invalid_api_key_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "403": { "description": "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.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "429": { "description": "Too many requests (`rate_limited_error`). Wait the number of seconds in the `Retry-After` header, then retry.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "500": { "description": "Something went wrong on our side (`internal_server_error`). Retry with the same `Idempotency-Key`.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "503": { "description": "The b-paid API is temporarily unavailable (`service_unavailable_error`). Retry in a moment with the same `Idempotency-Key`.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "200": { "description": "The created payment. Also returned, with `Idempotent-Replayed: true`, when you send the same payment again with the same `Idempotency-Key`.", "headers": { "Idempotent-Replayed": { "description": "`true` when this response returns the payment an earlier request with the same `Idempotency-Key` created. Absent otherwise.", "schema": { "enum": [ "true" ], "type": "string" } }, "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "409": { "description": "This `Idempotency-Key` was already used to create a different payment (`idempotency_key_already_used_error`). `resource_id` is the id of that payment.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "415": { "description": "Send the body as `Content-Type: application/json` (`unsupported_media_type_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } } } }, "get": { "tags": [ "Payments" ], "summary": "List payments", "description": "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.", "operationId": "list_payments", "parameters": [ { "name": "limit", "in": "query", "description": "The number of payments to return, 1 to 100. The default is 100.", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "name": "cursor", "in": "query", "description": "The `next_cursor` of the previous page. Omit it for the first page.", "schema": { "type": "string" } }, { "name": "source_account_id", "in": "query", "description": "Only return payments sent from this bpid. Use your own bpid to list the payments you sent.", "schema": { "type": "string" } }, { "name": "destination_account_id", "in": "query", "description": "Only return payments sent to this bpid. Use your own bpid to list the payments you received.", "schema": { "type": "string" } }, { "name": "status.in", "in": "query", "description": "Only return payments with these statuses, comma-separated, for example `pending,scheduled`.", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentStatus" } } }, { "name": "created_at.after", "in": "query", "description": "Only return payments created after this ISO 8601 timestamp, with `Z` or an offset (send `+` as `%2B`), for example `2026-10-01T00:00:00Z`.", "schema": { "pattern": "^[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})$", "type": "string", "format": "date-time" } }, { "name": "created_at.before", "in": "query", "description": "Only return payments created before this ISO 8601 timestamp, with `Z` or an offset (send `+` as `%2B`).", "schema": { "pattern": "^[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})$", "type": "string", "format": "date-time" } }, { "name": "created_at.on_or_after", "in": "query", "description": "Only return payments created on or after this ISO 8601 timestamp, with `Z` or an offset (send `+` as `%2B`).", "schema": { "pattern": "^[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})$", "type": "string", "format": "date-time" } }, { "name": "created_at.on_or_before", "in": "query", "description": "Only return payments created on or before this ISO 8601 timestamp, with `Z` or an offset (send `+` as `%2B`).", "schema": { "pattern": "^[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})$", "type": "string", "format": "date-time" } }, { "name": "idempotency_key", "in": "query", "description": "Only return the payment created with this `Idempotency-Key`. The list is empty if the key is unused.", "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "responses": { "400": { "description": "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.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "401": { "description": "The API key is missing, unknown or revoked (`invalid_api_key_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "403": { "description": "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.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "429": { "description": "Too many requests (`rate_limited_error`). Wait the number of seconds in the `Retry-After` header, then retry.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "500": { "description": "Something went wrong on our side (`internal_server_error`). Retry the same request.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "503": { "description": "The b-paid API is temporarily unavailable (`service_unavailable_error`). Retry the same request in a moment.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "200": { "description": "One page of payments.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentList" } } } } } } }, "/v1/payments/{id}": { "get": { "tags": [ "Payments" ], "summary": "Retrieve a payment", "description": "Retrieves a payment sent from or to your account. Supply the payment's `id` from Create a payment or List payments.", "operationId": "retrieve_payment", "parameters": [ { "name": "id", "in": "path", "description": "The payment's id.", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "A query parameter is unknown, empty or repeated (`invalid_parameters_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "401": { "description": "The API key is missing, unknown or revoked (`invalid_api_key_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "403": { "description": "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.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "429": { "description": "Too many requests (`rate_limited_error`). Wait the number of seconds in the `Retry-After` header, then retry.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "500": { "description": "Something went wrong on our side (`internal_server_error`). Retry the same request.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "503": { "description": "The b-paid API is temporarily unavailable (`service_unavailable_error`). Retry the same request in a moment.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "200": { "description": "The payment.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "404": { "description": "No payment with this id was sent to or from your account (`object_not_found_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } } } } }, "/v1/payments/{id}/cancel": { "post": { "tags": [ "Payments" ], "summary": "Cancel a payment", "description": "Cancels a scheduled payment you sent. You can cancel a payment only while its `status` is `scheduled`. The amount is returned to your available balance. Canceling a payment that is already `canceled` returns it unchanged.", "operationId": "cancel_payment", "parameters": [ { "name": "id", "in": "path", "description": "The payment's id.", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "A query parameter is unknown, empty or repeated (`invalid_parameters_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "401": { "description": "The API key is missing, unknown or revoked (`invalid_api_key_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "403": { "description": "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.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "429": { "description": "Too many requests (`rate_limited_error`). Wait the number of seconds in the `Retry-After` header, then retry.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "500": { "description": "Something went wrong on our side (`internal_server_error`). Retry the same request.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "503": { "description": "The b-paid API is temporarily unavailable (`service_unavailable_error`). Retry the same request in a moment.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "200": { "description": "The payment.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "BPT-000000-000001-00", "status": "canceled", "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" } } } }, "404": { "description": "No payment with this id was sent to or from your account (`object_not_found_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "409": { "description": "The payment can't be canceled (`invalid_operation_error`). Only the sender can cancel a payment, and only while its `status` is `scheduled`.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } } } } }, "/v1/simulations/inbound_payments": { "post": { "tags": [ "Payments" ], "summary": "Sandbox: Receive a payment", "description": "Simulates a payment to your sandbox account from the test account SIM-PAY-001-BZ. The payment completes at once, so the amount is available right away. Use it to add money to your sandbox account. Each call creates a new payment: this endpoint doesn't use `Idempotency-Key`.", "operationId": "sandbox_create_inbound_payment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateInboundPaymentRequest" } } }, "required": true }, "responses": { "400": { "description": "No payment was made (`invalid_parameters_error`): `amount` is missing or out of range, a field is unknown, or a query parameter is unknown. `detail` says what to fix.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "401": { "description": "The API key is missing, unknown or revoked (`invalid_api_key_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "403": { "description": "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.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "429": { "description": "Too many requests (`rate_limited_error`). Wait the number of seconds in the `Retry-After` header, then retry.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "500": { "description": "Something went wrong on our side (`internal_server_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "503": { "description": "The b-paid API is temporarily unavailable (`service_unavailable_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "200": { "description": "The payment from SIM-PAY-001-BZ to you.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "BPT-000000-000003-00", "status": "complete", "amount": 500000, "amount_paid": 500000, "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-09-22T17:42:08.1234567Z" } } } }, "404": { "description": "Sandbox operations work only with a sandbox key. A live key gets `api_method_not_found_error`.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "409": { "description": "The payment could not be made (`invalid_operation_error`). Contact b-paid support.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "415": { "description": "Send the body as `Content-Type: application/json` (`unsupported_media_type_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } } }, "x-sandbox-only": true } }, "/v1/simulations/payments/{id}/accept_quick_pay": { "post": { "tags": [ "Payments" ], "summary": "Sandbox: Accept a quick pay offer", "description": "Simulates the recipient accepting the quick pay offer on a scheduled payment you sent. The payment must first have a `status` of `scheduled` and a `quick_pay_percent`. It is paid at once at the current discount: once `complete`, `amount_paid` is `amount` minus the discount. This endpoint doesn't use `Idempotency-Key`.", "operationId": "sandbox_accept_quick_pay", "parameters": [ { "name": "id", "in": "path", "description": "The payment's id.", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "A query parameter is unknown, empty or repeated (`invalid_parameters_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "401": { "description": "The API key is missing, unknown or revoked (`invalid_api_key_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "403": { "description": "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.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "429": { "description": "Too many requests (`rate_limited_error`). Wait the number of seconds in the `Retry-After` header, then retry.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "500": { "description": "Something went wrong on our side (`internal_server_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "503": { "description": "The b-paid API is temporarily unavailable (`service_unavailable_error`).", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "200": { "description": "The payment.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "BPT-000000-000001-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-22T17:42:08.1234567Z", "created_at": "2026-09-22T17:42:08.1234567Z" } } } }, "404": { "description": "No payment with this id was sent to or from your account (`object_not_found_error`). Sandbox operations work only with a sandbox key. A live key gets `api_method_not_found_error`.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } }, "409": { "description": "The quick pay offer can't be accepted (`invalid_operation_error`), for example because the payment isn't `scheduled` with a quick pay offer, or you received it rather than sent it.", "headers": { "Request-Id": { "description": "The request's unique identifier. Include it when you contact b-paid support about this request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } } }, "x-sandbox-only": true } } }, "components": { "schemas": { "Account": { "required": [ "id", "name", "available_balance" ], "type": "object", "properties": { "id": { "type": "string", "description": "The account's bpid. Other b-paid accounts use it to pay you." }, "name": { "type": "string", "description": "The account's name." }, "available_balance": { "type": "integer", "description": "The account's available balance in cents (USD): the money you can send now. Amounts set aside for scheduled payments you sent are already taken out. `null` until your account can send payments; if it stays `null`, contact b-paid support.", "format": "int64", "nullable": true } }, "additionalProperties": { }, "description": "The account your API key belongs to.", "example": { "id": "ACC-ONE-000-BZ", "name": "Your Business", "available_balance": 12500000 } }, "ApiProblem": { "required": [ "status", "type", "title" ], "type": "object", "properties": { "status": { "type": "integer", "description": "The HTTP status code, the same as the response's.", "format": "int32" }, "type": { "type": "string", "description": "The type of error that occurred, as a machine-readable string. New types may be added." }, "title": { "type": "string", "description": "A human-readable summary of the error type." }, "detail": { "type": "string", "description": "A human-readable explanation of this error and how to fix it. Omitted when there is none." }, "resource_id": { "type": "string", "description": "On `idempotency_key_already_used_error`: the id of the payment the key created. Omitted otherwise." }, "retry_after": { "type": "integer", "description": "On `rate_limited_error`: the seconds to wait before retrying, as in the `Retry-After` header. Omitted otherwise.", "format": "int32" } }, "additionalProperties": { }, "description": "An error, in the RFC 9457 problem details format. Use `type` to handle errors in your code; `title` and `detail` are human-readable and may change." }, "CreatePaymentRequest": { "required": [ "amount", "destination_account_id" ], "type": "object", "properties": { "amount": { "maximum": 99999999, "minimum": 1, "type": "integer", "description": "A positive integer in cents (USD), at most 99999999 ($999,999.99). For example, $1,450.00 is `145000`.", "format": "int64" }, "destination_account_id": { "type": "string", "description": "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." }, "net_terms_days": { "maximum": 180, "minimum": 1, "type": "integer", "description": "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.", "format": "int32", "nullable": true }, "quick_pay_percent": { "maximum": 99.99, "minimum": 0.01, "type": "number", "description": "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.", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "A payment to create. Only `amount` and `destination_account_id` are required.", "example": { "amount": 145000, "destination_account_id": "SIM-PAY-002-BZ", "net_terms_days": 30, "quick_pay_percent": 2.5 } }, "Payment": { "required": [ "id", "status", "amount", "amount_paid", "source_account_id", "destination_account_id", "net_terms_days", "quick_pay_percent", "scheduled_for", "created_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment. The b-paid app shows it as the payment's reference number. Treat it as an opaque string." }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "amount": { "type": "integer", "description": "The payment amount in cents (USD), as created. It never changes.", "format": "int64" }, "amount_paid": { "type": "integer", "description": "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.", "format": "int64", "nullable": true }, "source_account_id": { "type": "string", "description": "The bpid of the account that sends the payment." }, "destination_account_id": { "type": "string", "description": "The bpid of the account that receives the payment." }, "net_terms_days": { "type": "integer", "description": "The number of days from creation to the due date. `null` for a payment made now.", "format": "int32", "nullable": true }, "quick_pay_percent": { "type": "number", "description": "The quick pay discount, in percent, offered to the recipient for being paid before the due date. `null` if none was offered.", "format": "double", "nullable": true }, "scheduled_for": { "type": "string", "description": "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`.", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "description": "The ISO 8601 date and time at which the payment was created.", "format": "date-time" } }, "additionalProperties": { }, "description": "A payment between your account and another b-paid account, sent or received.", "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" } }, "PaymentList": { "required": [ "data", "next_cursor" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" }, "description": "The payments on this page, newest first." }, "next_cursor": { "type": "string", "description": "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.", "nullable": true } }, "additionalProperties": { }, "description": "One page of payments, newest first.", "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" } }, "PaymentStatus": { "enum": [ "pending", "scheduled", "complete", "failed", "canceled" ], "type": "string", "description": "Where the payment stands.\n\n- `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`.\n- `scheduled`: The payment is waiting for its due date. The amount is set aside from the sender's available balance.\n- `complete`: The payment has been paid. This is final.\n- `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.\n- `canceled`: The sender canceled the scheduled payment. The amount is returned to the sender's available balance. This is final." }, "SimulateInboundPaymentRequest": { "required": [ "amount" ], "type": "object", "properties": { "amount": { "maximum": 99999999, "minimum": 1, "type": "integer", "description": "A positive integer in cents (USD), at most 99999999 ($999,999.99). For example, $1,450.00 is `145000`.", "format": "int64" } }, "additionalProperties": false, "description": "A payment to your sandbox account from the test account SIM-PAY-001-BZ.", "example": { "amount": 500000 } } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "Your API key, from the Developers page in the b-paid web app. Live and sandbox keys are separate. Keep keys on your server.", "name": "X-Api-Key", "in": "header" } } }, "security": [ { "ApiKey": [ ] } ], "tags": [ { "name": "Account" }, { "name": "Payments" } ] }