{ "openapi": "3.1.0", "info": { "title": "BoundlessPay Business API", "version": "2026-08-29", "description": "One secure, versioned API over the same services that power the BoundlessPay Business Suite.\n\n- Money is always a decimal string, never a float.\n- Timestamps are ISO 8601 UTC.\n- Every response carries a `request_id`.\n- Every financial POST requires an `Idempotency-Key`.\n- Errors follow RFC 9457 problem details.\n\n## Checkout notifications\n\nRegister an endpoint (POST /v1/webhook-endpoints) and BoundlessPay posts a signed JSON body every time a checkout page changes:\n\n| Event | When it fires |\n| --- | --- |\n| `checkout_session.created` | The payment request was opened and the payer can pay. |\n| `checkout_session.pending` | The first money against this checkout was seen. |\n| `checkout_session.partially_paid` | A further amount landed and the total is still short. |\n| `checkout_session.underpaid` | The countdown ran out with less than the full amount. |\n| `checkout_session.paid` | The total received reached the amount requested. |\n| `checkout_session.expired` | The countdown ran out with nothing received. |\n| `checkout_session.cancelled` | You cancelled the payment request. |\n\nEvery body carries the checkout: `id`, `object`, `status`, `method`, `currency`, `amount_minor`, `paid_amount_minor`, `outstanding_amount_minor`, `reference`, `expires_at`, `paid_at`, `deposit_id`, `metadata`, and on a settling event `surplus_minor` and `payments` (the number of part payments).\n\n### Verifying the signature\n\nEach delivery carries `BoundlessPay-Signature: t=,v1=` where `v1` is HMAC-SHA256 of `` `${t}.${rawBody}` `` using the endpoint secret returned once at creation. Compare with a timing-safe check, and reject anything older than five minutes to stop replays.\n\n```js\nimport { createHmac, timingSafeEqual } from 'node:crypto'\n\nexport function verify(rawBody, header, secret) {\n const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))\n const age = Math.abs(Date.now() / 1000 - Number(parts.t))\n if (!parts.t || !parts.v1 || age > 300) return false\n const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')\n const a = Buffer.from(expected), b = Buffer.from(parts.v1)\n return a.length === b.length && timingSafeEqual(a, b)\n}\n```\n\nHandle deliveries idempotently on the event `id`: an endpoint that times out is retried.\n\n## Embedding the checkout\n\nCreate the session on your server, then either send the payer to `checkout_url`, or embed it:\n\n```html\n
\n\n\n```\n\nOmit `container` for a modal. The widget never sees an API key. The frame shows your business name and logo, and may only be framed by domains you have verified in the Suite — anything else is refused by the browser.\n\n## Part payments\n\nA checkout is marked `paid` only once the total received reaches the amount requested. Anything less stays open and keeps accepting more, each arrival appended to `payments`. Overpayment is `paid` with the surplus recorded, never silently swallowed.\n\n## Getting access\n\nAPI access is granted per business through the Suite, not by self-service key creation.\n\n1. In the Suite, open **Developer → Request API access** and complete the intake questionnaire (legal identity, ownership, business model, products, corridors, expected volumes, funds flow, settlement model, licensing, data handling, downstream merchants and risk indicators).\n2. We score the application, assign a risk tier and generate your agreement pack from versioned templates. You review each document in the app, consent, and sign the pack once.\n3. Compliance, commercial and legal each approve, then the pack is countersigned and sealed. Executed copies, each with its SHA-256 fingerprint, stay downloadable in the document room.\n4. **Sandbox keys** (`bp_test_`) are issued once the minimum KYB checks pass and the pack is executed. **Live keys** (`bp_live_`) are issued after full approval and integration readiness (a verified webhook endpoint, an IP allowlist, and at least one successful sandbox call per product).\n\nOnly the products approved on your application are enabled. Calling a scope outside them returns `PRODUCT_NOT_ENABLED`; calling a live endpoint with a test key (or the reverse) returns `ENVIRONMENT_MISMATCH`. Approved products also switch on the matching Suite modules automatically — anything your account team set by hand always wins and is never reversed.\n\n## Countries and currencies\n\nWe onboard globally. A small list of comprehensively sanctioned countries is refused everywhere — in onboarding, in customer and cardholder records, and in payouts — with `COMPLIANCE_BLOCKED`. That list is reconciled against the official sanctions register and only changes when a compliance officer approves the change, so treat it as data to read from errors rather than a fixed constant to hard-code.\n\nBalances and accounts can be held in NGN, USD, GBP, EUR, CAD, GHS, KES, ZAR and CDF, plus USDT, USDC and cNGN (cNGN is opt-in per business). Payouts reach considerably further: call `GET /v1/transfers/corridors` for the live list of destination countries, currencies and rails available to your business — coverage is resolved per corridor at request time, so the corridor list is the only authoritative answer.\n\nNaira virtual accounts are issued in the legal name of the business that owns them.\n\n## Cards over the API\n\n`POST /v1/cards` issues `virtual` and `physical` cards. Single-use (disposable) cards are currently available in the Suite only and are not yet exposed here; they will appear as a third `card_type` value when they are.\n\nCard issuance is never fire-and-forget: if the issuer has accepted the request but not yet confirmed the card, the call fails with `PROVIDER_UNAVAILABLE` and you retry with the *same* `Idempotency-Key`. Retrying that way can never produce a second card." }, "servers": [ { "url": "https://business.boundlesspay.com/api/public/v1", "description": "Production" } ], "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Bearer :. Test keys start with bp_test_, live keys with bp_live_." } }, "schemas": { "Problem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] }, "Balance": { "type": "object", "properties": { "object": { "type": "string", "const": "balance" }, "currency": { "type": "string", "description": "ISO 4217 or supported asset symbol" }, "available": { "type": "string", "description": "Decimal string" }, "pending": { "type": "string" }, "reserved": { "type": "string" }, "total": { "type": "string" }, "last_reconciled_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Customer": { "type": "object", "properties": { "external_customer_id": { "type": "string" }, "customer_type": { "type": "string", "enum": [ "individual", "business" ] }, "legal_name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "address": { "type": "object" }, "date_of_birth": { "type": "string", "format": "date" }, "metadata": { "type": "object" } }, "required": [ "legal_name" ] }, "VirtualAccount": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "va_12345" ] }, "object": { "type": "string", "const": "virtual_account" }, "status": { "type": "string", "enum": [ "pending", "requires_action", "active", "frozen", "closed", "failed" ] }, "currency": { "type": "string" }, "account_name": { "type": "string", "description": "Name senders are told to transfer to. Chosen as: the request's `account_name`, else the customer's KYC-verified legal name, else a generic `BUSINESS ` placeholder. The issuing bank (Nomba) and the payer's bank control how this name is actually displayed, so treat it as informational, not guaranteed." }, "account_number": { "type": "string" }, "bank_name": { "type": "string" }, "customer_id": { "type": [ "string", "null" ] }, "account_type": { "type": "string", "description": "`dedicated` for accounts issued through this API. `temporary` accounts exist only on checkout sessions." }, "reference": { "type": [ "string", "null" ], "description": "Your `reference`, echoed back so you can match the account to your own record." }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } }, "CheckoutSession": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "chk_9f2b1c7a4d" ] }, "object": { "type": "string", "const": "checkout_session" }, "status": { "type": "string", "enum": [ "awaiting_payment", "paid", "underpaid", "expired", "cancelled" ] }, "method": { "type": "string", "enum": [ "bank_transfer", "crypto", "bpay_tag" ], "description": "bpay_tag returns instructions.bpay_pay_url (/pay/tag/bpi_…) for an exact-amount BpayTag payment. Money movement is switched off until release." }, "amount": { "type": "string", "examples": [ "3000.00" ] }, "currency": { "type": "string", "examples": [ "NGN" ] }, "amount_paid": { "type": [ "string", "null" ], "description": "Total received so far across every part payment." }, "amount_outstanding": { "type": "string", "description": "Still to pay. A session only becomes `paid` when this reaches 0.", "examples": [ "0.00" ] }, "payments": { "type": "array", "description": "Every amount seen against this checkout, oldest first. Several transfers add up; the same provider reference is only ever counted once.", "items": { "type": "object", "properties": { "amount": { "type": "string", "examples": [ "1500.00" ] }, "currency": { "type": "string", "examples": [ "NGN" ] }, "source": { "type": "string", "enum": [ "bank_transfer", "crypto", "bpay_tag" ] }, "source_reference": { "type": [ "string", "null" ], "examples": [ "dep_5c81f0a3d7" ] }, "provider_reference": { "type": "string" }, "seen_at": { "type": "string", "format": "date-time" } } } }, "expires_at": { "type": "string", "format": "date-time" }, "checkout_url": { "type": "string", "description": "Hosted page to send the payer to.", "examples": [ "https://business.boundlesspay.com/checkout/chk_9f2b1c7a4d" ] }, "reference": { "type": [ "string", "null" ], "description": "Your own reference." }, "description": { "type": [ "string", "null" ] }, "customer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } } }, "instructions": { "type": "object", "description": "Bank transfer: account_number, account_name, bank_name, amount, currency, expires_at. Crypto: address, assets, hosted_url, order_reference, amount, currency, expires_at.", "additionalProperties": true }, "deposit_id": { "type": [ "string", "null" ], "description": "The deposit that settled this session, once paid." }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "success_url": { "type": [ "string", "null" ] }, "cancel_url": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 120 }, "description": "Retrying with the same key and payload replays the original response." }, "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" } }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } } }, "x-scopes": [ { "scope": "customers:read", "product": "customers", "product_label": "Customers" }, { "scope": "customers:write", "product": "customers", "product_label": "Customers" }, { "scope": "balances:read", "product": "balances", "product_label": "Balances & transactions" }, { "scope": "virtual_accounts:read", "product": "virtual_accounts", "product_label": "Virtual accounts service" }, { "scope": "virtual_accounts:write", "product": "virtual_accounts", "product_label": "Virtual accounts service" }, { "scope": "checkout:read", "product": "checkout", "product_label": "Checkout page" }, { "scope": "checkout:write", "product": "checkout", "product_label": "Checkout page" }, { "scope": "beneficiaries:read", "product": "remittance", "product_label": "Remittance & transfers" }, { "scope": "beneficiaries:write", "product": "remittance", "product_label": "Remittance & transfers" }, { "scope": "quotes:read", "product": "conversions", "product_label": "Conversions & swaps" }, { "scope": "quotes:write", "product": "conversions", "product_label": "Conversions & swaps" }, { "scope": "conversions:read", "product": "conversions", "product_label": "Conversions & swaps" }, { "scope": "conversions:write", "product": "conversions", "product_label": "Conversions & swaps" }, { "scope": "transfers:read", "product": "remittance", "product_label": "Remittance & transfers" }, { "scope": "transfers:write", "product": "remittance", "product_label": "Remittance & transfers" }, { "scope": "cardholders:read", "product": "cards", "product_label": "Cards" }, { "scope": "cardholders:write", "product": "cards", "product_label": "Cards" }, { "scope": "cards:read", "product": "cards", "product_label": "Cards" }, { "scope": "cards:write", "product": "cards", "product_label": "Cards" }, { "scope": "card_transactions:read", "product": "cards", "product_label": "Cards" }, { "scope": "webhooks:read", "product": "webhooks", "product_label": "Webhooks" }, { "scope": "webhooks:write", "product": "webhooks", "product_label": "Webhooks" }, { "scope": "otc:read", "product": "otc", "product_label": "OTC trading" }, { "scope": "otc:write", "product": "otc", "product_label": "OTC trading" }, { "scope": "usage:read", "product": "balances", "product_label": "Balances & transactions" }, { "scope": "payouts:read", "product": "payouts", "product_label": "Bank payouts" }, { "scope": "payouts:write", "product": "payouts", "product_label": "Bank payouts" }, { "scope": "crypto:read", "product": "crypto", "product_label": "Blockchain addresses & withdrawals" }, { "scope": "crypto:write", "product": "crypto", "product_label": "Blockchain addresses & withdrawals" }, { "scope": "rates:read", "product": "rates", "product_label": "Rates" }, { "scope": "refunds:read", "product": "refunds", "product_label": "Store refunds" }, { "scope": "refunds:write", "product": "refunds", "product_label": "Store refunds" }, { "scope": "digital_services:read", "product": "digital_services", "product_label": "Global Digital Services" }, { "scope": "digital_services:write", "product": "digital_services", "product_label": "Global Digital Services" }, { "scope": "flights:read", "product": "flights", "product_label": "Flights & Travel" }, { "scope": "flights:write", "product": "flights", "product_label": "Flights & Travel" }, { "scope": "payroll:read", "product": "payroll", "product_label": "Payroll" }, { "scope": "payroll:write", "product": "payroll", "product_label": "Payroll" }, { "scope": "financing:read", "product": "financing", "product_label": "Business financing" }, { "scope": "savings:read", "product": "savings", "product_label": "Savings" }, { "scope": "savings:write", "product": "savings", "product_label": "Savings" }, { "scope": "merchant:read", "product": "merchant", "product_label": "Merchant Hub" }, { "scope": "identity_verification:write", "product": "identity_verification", "product_label": "Identity verification (KYC)" }, { "scope": "inventory:read", "product": "inventory", "product_label": "Inventory & products" }, { "scope": "inventory:write", "product": "inventory", "product_label": "Inventory & products" } ], "paths": { "/me": { "get": { "summary": "Describe the calling credential", "operationId": "getApiContext", "x-scope": "balances:read", "responses": { "200": { "description": "API context" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Balances & transactions" ] } }, "/balances": { "get": { "summary": "List balances", "operationId": "listBalances", "x-scope": "balances:read", "responses": { "200": { "description": "Balances from the BoundlessPay ledger", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "balance" }, "currency": { "type": "string", "description": "ISO 4217 or supported asset symbol" }, "available": { "type": "string", "description": "Decimal string" }, "pending": { "type": "string" }, "reserved": { "type": "string" }, "total": { "type": "string" }, "last_reconciled_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Balances & transactions" ] } }, "/balances/{currency}": { "get": { "summary": "Retrieve one balance", "operationId": "getBalance", "x-scope": "balances:read", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "balance" }, "currency": { "type": "string", "description": "ISO 4217 or supported asset symbol" }, "available": { "type": "string", "description": "Decimal string" }, "pending": { "type": "string" }, "reserved": { "type": "string" }, "total": { "type": "string" }, "last_reconciled_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Balances & transactions" ] } }, "/customers": { "post": { "summary": "Create a customer", "operationId": "createCustomer", "x-scope": "customers:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_customer_id": { "type": "string" }, "customer_type": { "type": "string", "enum": [ "individual", "business" ] }, "legal_name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "address": { "type": "object" }, "date_of_birth": { "type": "string", "format": "date" }, "metadata": { "type": "object" } }, "required": [ "legal_name" ] } } } }, "responses": { "201": { "description": "Customer created" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Customers" ] }, "get": { "summary": "List customers", "operationId": "listCustomers", "x-scope": "customers:read", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "email", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Customers" ] } }, "/customers/{id}": { "get": { "summary": "Retrieve a customer", "operationId": "getCustomer", "x-scope": "customers:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Customers" ] }, "patch": { "summary": "Update a customer", "operationId": "updateCustomer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Customer" } ], "description": "Any subset of the customer fields. Omitted fields are left as they are." } } } }, "x-scope": "customers:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Customers" ] } }, "/customers/{id}/submit-kyc": { "post": { "summary": "Verify a customer's identity (BVN/NIN, selfie match, watchlist screening)", "description": "Required before a sub virtual account can be issued. Send bvn and/or nin (11 digits), selfie_image (base64 JPEG/PNG), and date_of_birth (YYYY-MM-DD; required in live unless already on the customer, compared with the BVN/NIN record), optional source (\"boundless\" or \"business_existing\" when passing on KYC you already collected; it is re-checked either way) and external_reference. Each check is charged per call in live mode; checks that fail on our side are refunded. Sandbox: 22222222222 passes, 00000000000 is rejected, 11111111111 goes to review.", "operationId": "submitCustomerKyc", "x-scope": "identity_verification:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "selfie_image" ], "properties": { "bvn": { "type": "string", "pattern": "^\\d{11}$" }, "nin": { "type": "string", "pattern": "^\\d{11}$" }, "selfie_image": { "type": "string", "description": "Base64 JPEG or PNG, under 4 MB" }, "date_of_birth": { "type": "string", "format": "date", "description": "YYYY-MM-DD. Required in live unless set on the customer." }, "source": { "type": "string", "enum": [ "boundless", "business_existing" ] }, "external_reference": { "type": "string", "maxLength": 120 } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Verification submitted" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Identity verification (KYC)" ] } }, "/customers/{id}/verification": { "get": { "summary": "Retrieve verification history", "operationId": "getCustomerVerification", "x-scope": "customers:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification history" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Customers" ] } }, "/customers/{id}/freeze": { "post": { "summary": "Freeze a customer", "operationId": "freezeCustomer", "x-scope": "customers:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Customers" ] } }, "/customers/{id}/unfreeze": { "post": { "summary": "Unfreeze a customer", "operationId": "unfreezeCustomer", "x-scope": "customers:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Customers" ] } }, "/checkout-sessions": { "post": { "summary": "Create a checkout page", "description": "Creates a payment request with its own payment instructions and countdown. Bank transfer sessions get a temporary Naira account bound to this exact amount; the permanent business account is never reused for a checkout.", "operationId": "createCheckoutSession", "x-scope": "checkout:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "crypto": { "summary": "Crypto checkout — payer sends USDT, USDC or cNGN", "value": { "method": "crypto", "amount": "50.00", "currency": "USD", "expires_in_minutes": 60, "assets": [ "USDT", "USDC" ], "reference": "ORDER-4822" } } } } } }, "responses": { "201": { "description": "Checkout session created", "content": { "application/json": { "examples": { "crypto": { "summary": "Crypto checkout — payer sends USDT, USDC or cNGN", "value": { "id": "chk_41ac0d7b92", "object": "checkout_session", "status": "awaiting_payment", "method": "crypto", "amount": "50.00", "currency": "USD", "amount_paid": null, "amount_outstanding": "50.00", "payments": [], "expires_at": "2026-02-04T21:29:46.000Z", "checkout_url": "https://business.boundlesspay.com/checkout/chk_41ac0d7b92", "reference": "ORDER-4822", "description": null, "customer": { "name": null, "email": null, "phone": null }, "instructions": { "type": "crypto", "address": "0x8Ae2C1b7F0d94E31aA5c60b17E9C4d3f0821b7A5", "assets": [ "USDT", "USDC" ], "hosted_url": "https://business.boundlesspay.com/pay/ord_74b1c0e9a2", "order_reference": "ord_74b1c0e9a2", "amount": "50.00", "currency": "USD", "expires_at": "2026-02-04T21:29:46.000Z" }, "deposit_id": null, "paid_at": null, "success_url": null, "cancel_url": null, "metadata": {}, "created_at": "2026-02-04T20:29:46.000Z" } }, "paid": { "summary": "The same session once the transfer has landed", "value": { "id": "chk_9f2b1c7a4d", "object": "checkout_session", "status": "paid", "method": "bank_transfer", "amount": "3000.00", "currency": "NGN", "amount_paid": "3000.00", "amount_outstanding": "0.00", "payments": [ { "amount": "1000.00", "currency": "NGN", "source": "bank_transfer", "source_reference": "dep_4a0f13bb92", "provider_reference": "dep_4a0f13bb92", "seen_at": "2026-02-04T20:30:41.000Z" }, { "amount": "2000.00", "currency": "NGN", "source": "bank_transfer", "source_reference": "dep_5c81f0a3d7", "provider_reference": "dep_5c81f0a3d7", "seen_at": "2026-02-04T20:31:12.000Z" } ], "expires_at": "2026-02-04T20:59:46.000Z", "checkout_url": "https://business.boundlesspay.com/checkout/chk_9f2b1c7a4d", "reference": "ORDER-4821", "description": "Order #4821", "customer": { "name": "Ada Nwosu", "email": "ada@example.com", "phone": null }, "instructions": { "type": "bank_transfer", "account_number": "9902117364", "account_name": "BOUNDLESS/ORDER-4821", "bank_name": "Providus Bank", "amount": "3000.00", "currency": "NGN", "expires_at": "2026-02-04T20:59:46.000Z" }, "deposit_id": "dep_5c81f0a3d7", "paid_at": "2026-02-04T20:31:12.000Z", "success_url": "https://shop.example.com/thanks/4821", "cancel_url": null, "metadata": { "order_id": "4821" }, "created_at": "2026-02-04T20:29:46.000Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Checkout page" ], "x-response-examples": { "crypto": { "summary": "Crypto checkout — payer sends USDT, USDC or cNGN", "value": { "id": "chk_41ac0d7b92", "object": "checkout_session", "status": "awaiting_payment", "method": "crypto", "amount": "50.00", "currency": "USD", "amount_paid": null, "amount_outstanding": "50.00", "payments": [], "expires_at": "2026-02-04T21:29:46.000Z", "checkout_url": "https://business.boundlesspay.com/checkout/chk_41ac0d7b92", "reference": "ORDER-4822", "description": null, "customer": { "name": null, "email": null, "phone": null }, "instructions": { "type": "crypto", "address": "0x8Ae2C1b7F0d94E31aA5c60b17E9C4d3f0821b7A5", "assets": [ "USDT", "USDC" ], "hosted_url": "https://business.boundlesspay.com/pay/ord_74b1c0e9a2", "order_reference": "ord_74b1c0e9a2", "amount": "50.00", "currency": "USD", "expires_at": "2026-02-04T21:29:46.000Z" }, "deposit_id": null, "paid_at": null, "success_url": null, "cancel_url": null, "metadata": {}, "created_at": "2026-02-04T20:29:46.000Z" } }, "paid": { "summary": "The same session once the transfer has landed", "value": { "id": "chk_9f2b1c7a4d", "object": "checkout_session", "status": "paid", "method": "bank_transfer", "amount": "3000.00", "currency": "NGN", "amount_paid": "3000.00", "amount_outstanding": "0.00", "payments": [ { "amount": "1000.00", "currency": "NGN", "source": "bank_transfer", "source_reference": "dep_4a0f13bb92", "provider_reference": "dep_4a0f13bb92", "seen_at": "2026-02-04T20:30:41.000Z" }, { "amount": "2000.00", "currency": "NGN", "source": "bank_transfer", "source_reference": "dep_5c81f0a3d7", "provider_reference": "dep_5c81f0a3d7", "seen_at": "2026-02-04T20:31:12.000Z" } ], "expires_at": "2026-02-04T20:59:46.000Z", "checkout_url": "https://business.boundlesspay.com/checkout/chk_9f2b1c7a4d", "reference": "ORDER-4821", "description": "Order #4821", "customer": { "name": "Ada Nwosu", "email": "ada@example.com", "phone": null }, "instructions": { "type": "bank_transfer", "account_number": "9902117364", "account_name": "BOUNDLESS/ORDER-4821", "bank_name": "Providus Bank", "amount": "3000.00", "currency": "NGN", "expires_at": "2026-02-04T20:59:46.000Z" }, "deposit_id": "dep_5c81f0a3d7", "paid_at": "2026-02-04T20:31:12.000Z", "success_url": "https://shop.example.com/thanks/4821", "cancel_url": null, "metadata": { "order_id": "4821" }, "created_at": "2026-02-04T20:29:46.000Z" } } } }, "get": { "summary": "List checkout pages", "operationId": "listCheckoutSessions", "x-scope": "checkout:read", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "awaiting_payment", "paid", "underpaid", "expired", "cancelled" ] } } ], "responses": { "200": { "description": "Checkout session list", "content": { "application/json": { "example": { "object": "list", "data": [ { "id": "chk_9f2b1c7a4d", "object": "checkout_session", "status": "awaiting_payment", "method": "bank_transfer", "amount": "3000.00", "currency": "NGN", "amount_paid": null, "amount_outstanding": "3000.00", "payments": [], "expires_at": "2026-02-04T20:59:46.000Z", "checkout_url": "https://business.boundlesspay.com/checkout/chk_9f2b1c7a4d", "reference": "ORDER-4821", "description": "Order #4821", "customer": { "name": "Ada Nwosu", "email": "ada@example.com", "phone": null }, "instructions": { "type": "bank_transfer", "account_number": "9902117364", "account_name": "BOUNDLESS/ORDER-4821", "bank_name": "Providus Bank", "amount": "3000.00", "currency": "NGN", "expires_at": "2026-02-04T20:59:46.000Z" }, "deposit_id": null, "paid_at": null, "success_url": "https://shop.example.com/thanks/4821", "cancel_url": null, "metadata": { "order_id": "4821" }, "created_at": "2026-02-04T20:29:46.000Z" }, { "id": "chk_9f2b1c7a4d", "object": "checkout_session", "status": "paid", "method": "bank_transfer", "amount": "3000.00", "currency": "NGN", "amount_paid": "3000.00", "amount_outstanding": "0.00", "payments": [ { "amount": "1000.00", "currency": "NGN", "source": "bank_transfer", "source_reference": "dep_4a0f13bb92", "provider_reference": "dep_4a0f13bb92", "seen_at": "2026-02-04T20:30:41.000Z" }, { "amount": "2000.00", "currency": "NGN", "source": "bank_transfer", "source_reference": "dep_5c81f0a3d7", "provider_reference": "dep_5c81f0a3d7", "seen_at": "2026-02-04T20:31:12.000Z" } ], "expires_at": "2026-02-04T20:59:46.000Z", "checkout_url": "https://business.boundlesspay.com/checkout/chk_9f2b1c7a4d", "reference": "ORDER-4821", "description": "Order #4821", "customer": { "name": "Ada Nwosu", "email": "ada@example.com", "phone": null }, "instructions": { "type": "bank_transfer", "account_number": "9902117364", "account_name": "BOUNDLESS/ORDER-4821", "bank_name": "Providus Bank", "amount": "3000.00", "currency": "NGN", "expires_at": "2026-02-04T20:59:46.000Z" }, "deposit_id": "dep_5c81f0a3d7", "paid_at": "2026-02-04T20:31:12.000Z", "success_url": "https://shop.example.com/thanks/4821", "cancel_url": null, "metadata": { "order_id": "4821" }, "created_at": "2026-02-04T20:29:46.000Z" }, { "id": "chk_41ac0d7b92", "object": "checkout_session", "status": "awaiting_payment", "method": "crypto", "amount": "50.00", "currency": "USD", "amount_paid": null, "amount_outstanding": "50.00", "payments": [], "expires_at": "2026-02-04T21:29:46.000Z", "checkout_url": "https://business.boundlesspay.com/checkout/chk_41ac0d7b92", "reference": "ORDER-4822", "description": null, "customer": { "name": null, "email": null, "phone": null }, "instructions": { "type": "crypto", "address": "0x8Ae2C1b7F0d94E31aA5c60b17E9C4d3f0821b7A5", "assets": [ "USDT", "USDC" ], "hosted_url": "https://business.boundlesspay.com/pay/ord_74b1c0e9a2", "order_reference": "ord_74b1c0e9a2", "amount": "50.00", "currency": "USD", "expires_at": "2026-02-04T21:29:46.000Z" }, "deposit_id": null, "paid_at": null, "success_url": null, "cancel_url": null, "metadata": {}, "created_at": "2026-02-04T20:29:46.000Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Checkout page" ] } }, "/checkout-sessions/{id}": { "get": { "summary": "Retrieve a checkout page", "operationId": "getCheckoutSession", "x-scope": "checkout:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkout session", "content": { "application/json": { "example": { "id": "chk_9f2b1c7a4d", "object": "checkout_session", "status": "paid", "method": "bank_transfer", "amount": "3000.00", "currency": "NGN", "amount_paid": "3000.00", "amount_outstanding": "0.00", "payments": [ { "amount": "1000.00", "currency": "NGN", "source": "bank_transfer", "source_reference": "dep_4a0f13bb92", "provider_reference": "dep_4a0f13bb92", "seen_at": "2026-02-04T20:30:41.000Z" }, { "amount": "2000.00", "currency": "NGN", "source": "bank_transfer", "source_reference": "dep_5c81f0a3d7", "provider_reference": "dep_5c81f0a3d7", "seen_at": "2026-02-04T20:31:12.000Z" } ], "expires_at": "2026-02-04T20:59:46.000Z", "checkout_url": "https://business.boundlesspay.com/checkout/chk_9f2b1c7a4d", "reference": "ORDER-4821", "description": "Order #4821", "customer": { "name": "Ada Nwosu", "email": "ada@example.com", "phone": null }, "instructions": { "type": "bank_transfer", "account_number": "9902117364", "account_name": "BOUNDLESS/ORDER-4821", "bank_name": "Providus Bank", "amount": "3000.00", "currency": "NGN", "expires_at": "2026-02-04T20:59:46.000Z" }, "deposit_id": "dep_5c81f0a3d7", "paid_at": "2026-02-04T20:31:12.000Z", "success_url": "https://shop.example.com/thanks/4821", "cancel_url": null, "metadata": { "order_id": "4821" }, "created_at": "2026-02-04T20:29:46.000Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Checkout page" ] } }, "/checkout-sessions/{id}/cancel": { "post": { "summary": "Cancel a checkout page", "description": "Closes the temporary account and stops the countdown. A session that has already been paid cannot be cancelled.", "operationId": "cancelCheckoutSession", "x-scope": "checkout:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Checkout session", "content": { "application/json": { "example": { "id": "chk_9f2b1c7a4d", "object": "checkout_session", "status": "cancelled", "method": "bank_transfer", "amount": "3000.00", "currency": "NGN", "amount_paid": null, "amount_outstanding": "3000.00", "payments": [], "expires_at": "2026-02-04T20:59:46.000Z", "checkout_url": "https://business.boundlesspay.com/checkout/chk_9f2b1c7a4d", "reference": "ORDER-4821", "description": "Order #4821", "customer": { "name": "Ada Nwosu", "email": "ada@example.com", "phone": null }, "instructions": { "type": "bank_transfer", "account_number": "9902117364", "account_name": "BOUNDLESS/ORDER-4821", "bank_name": "Providus Bank", "amount": "3000.00", "currency": "NGN", "expires_at": "2026-02-04T20:59:46.000Z" }, "deposit_id": null, "paid_at": null, "success_url": "https://shop.example.com/thanks/4821", "cancel_url": null, "metadata": { "order_id": "4821" }, "created_at": "2026-02-04T20:29:46.000Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Checkout page" ] } }, "/virtual-accounts": { "post": { "summary": "Issue a Naira virtual account", "operationId": "createVirtualAccount", "x-scope": "virtual_accounts:write", "description": "Issues a NGN virtual account. For an existing, KYC-verified customer this creates a dedicated account for that customer; for the business it creates (or returns) its own deposit account. Account name precedence: the request's `account_name`, then the customer's KYC-verified legal name, then a generic `BUSINESS ` placeholder. A blank or whitespace-only `account_name` counts as omitted, so the next rule applies. The named request and response examples below show each outcome: an override, the verified-name default, and the placeholder fallback. Caveat: dedicated accounts are registered through our payment partner (Nomba), and the payer's bank controls how the account name is displayed when sending — the exact string a sender sees is not guaranteed.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "examples": [ "cus_12345" ] }, "currency": { "type": "string", "const": "NGN" }, "account_type": { "type": "string", "enum": [ "dedicated", "temporary" ] }, "account_name": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[\\p{L}\\p{M}0-9 .,'&()/-]+$", "description": "Accepted characters: letters in any language (accents included), digits 0-9, spaces, and . , ' - & ( ) /. Anything else (emoji, @, #, _, quotes, line breaks) is rejected with 422. The value is trimmed and repeated spaces are collapsed first; it must then be 2-120 characters. A blank or whitespace-only value counts as omitted. Optional display name for the account. Precedence: (1) this value, (2) the customer's KYC-verified legal name, (3) a generic `BUSINESS ` placeholder. Only send a name your business is entitled to use (for example your platform's name plus your customer). Caveat: the issuing bank (Nomba) registers dedicated accounts under our payment partner's legal name, and each payer's bank decides how the beneficiary name is displayed at send time — we cannot guarantee the exact string a sender sees." }, "reference": { "type": "string" }, "metadata": { "type": "object" } } }, "examples": { "account_name_override": { "summary": "account_name wins over the verified legal name", "value": { "customer_id": "cus_3a0912b25bc208cfa1069cbb", "currency": "NGN", "account_name": "Justxpend Wallet - Chidi Okeke", "reference": "VA-CHIDI-0001" } }, "verified_legal_name": { "summary": "No account_name sent — the verified legal name is used", "value": { "customer_id": "cus_3a0912b25bc208cfa1069cbb", "currency": "NGN", "reference": "VA-CHIDI-0002" } }, "business_fallback": { "summary": "No account_name and no legal name on file — generic placeholder", "value": { "customer_id": "cus_7d41e0a9c2b84f6e1a5d3f80", "currency": "NGN", "reference": "VA-NO-NAME-0003" } }, "account_name_bad_characters": { "summary": "Invalid: emoji and @ in account_name → 422", "value": { "customer_id": "cus_3a0912b25bc208cfa1069cbb", "currency": "NGN", "account_name": "Chidi @ Justxpend 🚀", "reference": "VA-BAD-0001" } }, "account_name_too_short": { "summary": "Invalid: one character after trimming → 422", "value": { "customer_id": "cus_3a0912b25bc208cfa1069cbb", "currency": "NGN", "account_name": " A ", "reference": "VA-BAD-0002" } }, "account_name_allowed_punctuation": { "summary": "Valid: accents and allowed punctuation are accepted", "value": { "customer_id": "cus_3a0912b25bc208cfa1069cbb", "currency": "NGN", "account_name": "Justxpend / Chidi O'Neil-Adébáyọ̀ (Ltd.) & Co", "reference": "VA-OK-0004" } } } } } }, "responses": { "201": { "description": "Virtual account issued. The `account_name` on the response shows which rule won for that request — compare it with the matching request example.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "va_12345" ] }, "object": { "type": "string", "const": "virtual_account" }, "status": { "type": "string", "enum": [ "pending", "requires_action", "active", "frozen", "closed", "failed" ] }, "currency": { "type": "string" }, "account_name": { "type": "string", "description": "Name senders are told to transfer to. Chosen as: the request's `account_name`, else the customer's KYC-verified legal name, else a generic `BUSINESS ` placeholder. The issuing bank (Nomba) and the payer's bank control how this name is actually displayed, so treat it as informational, not guaranteed." }, "account_number": { "type": "string" }, "bank_name": { "type": "string" }, "customer_id": { "type": [ "string", "null" ] }, "account_type": { "type": "string", "description": "`dedicated` for accounts issued through this API. `temporary` accounts exist only on checkout sessions." }, "reference": { "type": [ "string", "null" ], "description": "Your `reference`, echoed back so you can match the account to your own record." }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "account_name_override": { "summary": "The name you sent is the name on the account", "value": { "id": "va_9f2b1c7a4d8e6f0a3b5c7d91", "object": "virtual_account", "status": "active", "currency": "NGN", "account_name": "Justxpend Wallet - Chidi Okeke", "account_number": "9902117364", "bank_name": "Nombank MFB", "account_type": "dedicated", "customer_id": "cus_3a0912b25bc208cfa1069cbb", "reference": "VA-CHIDI-0001", "metadata": {}, "created_at": "2026-10-07T05:12:44.000Z" } }, "verified_legal_name": { "summary": "Falls back to the legal name identity verification returned", "value": { "id": "va_4c8d2e6a0b1f3759ce2d4a68", "object": "virtual_account", "status": "active", "currency": "NGN", "account_name": "Okonkwo Onyebuchi", "account_number": "9902117365", "bank_name": "Nombank MFB", "account_type": "dedicated", "customer_id": "cus_3a0912b25bc208cfa1069cbb", "reference": "VA-CHIDI-0002", "metadata": {}, "created_at": "2026-10-07T05:14:02.000Z" } }, "business_fallback": { "summary": "Generic placeholder built from the first six characters of the workspace id", "value": { "id": "va_b17e9f4a2c6d8035e1a9b7d3", "object": "virtual_account", "status": "active", "currency": "NGN", "account_name": "BUSINESS 7f3c9a", "account_number": "9902117366", "bank_name": "Nombank MFB", "account_type": "dedicated", "customer_id": "cus_7d41e0a9c2b84f6e1a5d3f80", "reference": "VA-NO-NAME-0003", "metadata": {}, "created_at": "2026-10-07T05:15:37.000Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error. `errors` lists each invalid field. Fix the request and resend with a new Idempotency-Key.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] }, "examples": { "account_name_bad_characters": { "summary": "account_name contains characters that aren't allowed (e.g. emoji, @, #, _)", "value": { "type": "https://api.boundlesspay.com/errors/validation-error", "title": "Validation error", "status": 422, "detail": "Some of the details provided are invalid.", "code": "VALIDATION_ERROR", "request_id": "req_5c24e3e89f1e86caad91", "errors": [ { "field": "account_name", "message": "account_name may contain only letters, digits, spaces and . , ' - & ( ) /" } ] } }, "account_name_too_short": { "summary": "account_name is 1 character after trimming (\" A \")", "value": { "type": "https://api.boundlesspay.com/errors/validation-error", "title": "Validation error", "status": 422, "detail": "Some of the details provided are invalid.", "code": "VALIDATION_ERROR", "request_id": "req_5c24e3e89f1e86caad91", "errors": [ { "field": "account_name", "message": "account_name must be at least 2 characters after trimming." } ] } }, "account_name_too_long": { "summary": "account_name is longer than 120 characters", "value": { "type": "https://api.boundlesspay.com/errors/validation-error", "title": "Validation error", "status": 422, "detail": "Some of the details provided are invalid.", "code": "VALIDATION_ERROR", "request_id": "req_5c24e3e89f1e86caad91", "errors": [ { "field": "account_name", "message": "account_name must be at most 120 characters." } ] } }, "missing_customer": { "summary": "customer_id omitted", "value": { "type": "https://api.boundlesspay.com/errors/validation-error", "title": "Validation error", "status": 422, "detail": "customer_id is required. Create the customer and verify them with POST /v1/customers/:id/submit-kyc first.", "code": "VALIDATION_ERROR", "request_id": "req_5c24e3e89f1e86caad91" } }, "wrong_currency": { "summary": "currency other than NGN", "value": { "type": "https://api.boundlesspay.com/errors/validation-error", "title": "Validation error", "status": 422, "detail": "Only NGN virtual accounts are available in this API release.", "code": "VALIDATION_ERROR", "request_id": "req_5c24e3e89f1e86caad91" } }, "temporary_type": { "summary": "account_type \"temporary\" requested", "value": { "type": "https://api.boundlesspay.com/errors/validation-error", "title": "Validation error", "status": 422, "detail": "Temporary accounts are issued by the checkout page. Create a checkout session with POST /v1/checkout-sessions and method \"bank_transfer\" instead.", "code": "VALIDATION_ERROR", "request_id": "req_5c24e3e89f1e86caad91" } } } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "503": { "description": "Account issuance could not be confirmed. An account may already exist. Retry only with the same Idempotency-Key and reference; never create a new request to bypass a hold. pending_confirmation or needs_review may require support reconciliation.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] }, "examples": { "provider_unavailable": { "summary": "Account issuance is awaiting confirmation", "value": { "type": "https://api.boundlesspay.com/errors/provider-unavailable", "title": "Provider unavailable", "status": 503, "detail": "Account issuance could not be confirmed yet. Retry with the same Idempotency-Key and reference; do not create a new request for this account.", "code": "PROVIDER_UNAVAILABLE", "request_id": "req_5c24e3e89f1e86caad91", "errors": { "virtual_account_id": "va_7d41e0a9c2b84f6e1a5d3f80", "issuance_status": "pending_confirmation" } } } } } } } }, "tags": [ "Virtual accounts service" ] }, "get": { "summary": "List virtual accounts", "operationId": "listVirtualAccounts", "x-scope": "virtual_accounts:read", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Virtual account list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Virtual accounts service" ] } }, "/deposit-accounts": { "get": { "summary": "List receiving accounts, including preserved historical ones", "operationId": "listDepositAccounts", "x-scope": "virtual_accounts:read", "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deposit account list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Virtual accounts service" ] } }, "/virtual-accounts/{id}": { "get": { "summary": "Retrieve a virtual account", "operationId": "getVirtualAccount", "x-scope": "virtual_accounts:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Virtual account", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "va_12345" ] }, "object": { "type": "string", "const": "virtual_account" }, "status": { "type": "string", "enum": [ "pending", "requires_action", "active", "frozen", "closed", "failed" ] }, "currency": { "type": "string" }, "account_name": { "type": "string", "description": "Name senders are told to transfer to. Chosen as: the request's `account_name`, else the customer's KYC-verified legal name, else a generic `BUSINESS ` placeholder. The issuing bank (Nomba) and the payer's bank control how this name is actually displayed, so treat it as informational, not guaranteed." }, "account_number": { "type": "string" }, "bank_name": { "type": "string" }, "customer_id": { "type": [ "string", "null" ] }, "account_type": { "type": "string", "description": "`dedicated` for accounts issued through this API. `temporary` accounts exist only on checkout sessions." }, "reference": { "type": [ "string", "null" ], "description": "Your `reference`, echoed back so you can match the account to your own record." }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Virtual accounts service" ] } }, "/virtual-accounts/{id}/freeze": { "post": { "summary": "Freeze a virtual account", "operationId": "freezeVirtualAccount", "x-scope": "virtual_accounts:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Virtual account" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Virtual accounts service" ] } }, "/virtual-accounts/{id}/unfreeze": { "post": { "summary": "Unfreeze a virtual account", "operationId": "unfreezeVirtualAccount", "x-scope": "virtual_accounts:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Virtual account" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Virtual accounts service" ] } }, "/virtual-accounts/{id}/close": { "post": { "summary": "Close a virtual account", "operationId": "closeVirtualAccount", "x-scope": "virtual_accounts:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Virtual account" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Virtual accounts service" ] } }, "/virtual-accounts/{id}/transactions": { "get": { "summary": "List deposits into a virtual account", "operationId": "listVirtualAccountTransactions", "x-scope": "virtual_accounts:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Deposit list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Virtual accounts service" ] } }, "/conversions/pairs": { "get": { "summary": "List supported conversion pairs", "operationId": "listConversionPairs", "x-scope": "quotes:read", "responses": { "200": { "description": "Pair list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Conversions & swaps" ] } }, "/quotes": { "post": { "summary": "Create a conversion quote", "operationId": "createQuote", "x-scope": "quotes:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_currency", "destination_currency", "amount" ], "properties": { "source_currency": { "type": "string", "example": "USD" }, "destination_currency": { "type": "string", "example": "NGN" }, "amount": { "type": "string", "example": "1000.00" }, "type": { "type": "string", "enum": [ "firm", "indicative" ], "default": "firm" } } } } } }, "responses": { "201": { "description": "Quote created" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Conversions & swaps" ] } }, "/quotes/{id}": { "get": { "summary": "Retrieve a quote", "operationId": "getQuote", "x-scope": "quotes:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Quote" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Conversions & swaps" ] } }, "/conversions": { "post": { "summary": "Execute a conversion against a firm quote", "operationId": "createConversion", "x-scope": "conversions:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quote_id" ], "properties": { "quote_id": { "type": "string", "example": "qt_9f2c1a4b7e0d" }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Conversion created" }, "202": { "description": "Awaiting approval" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Conversions & swaps" ] }, "get": { "summary": "List conversions", "operationId": "listConversions", "x-scope": "conversions:read", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Conversion list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Conversions & swaps" ] } }, "/conversions/{id}": { "get": { "summary": "Retrieve a conversion", "operationId": "getConversion", "x-scope": "conversions:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Conversion" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Conversions & swaps" ] } }, "/conversions/{id}/reconcile": { "post": { "summary": "Re-check a conversion with its original provider", "operationId": "reconcileConversion", "x-scope": "conversions:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Conversion" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Conversions & swaps" ] } }, "/beneficiaries": { "post": { "summary": "Save a payout beneficiary", "operationId": "createBeneficiary", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "country" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "nickname": { "type": "string", "maxLength": 80 }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "examples": [ "NG" ] }, "transfer_method": { "type": "string", "examples": [ "bank_transfer", "mobile_money" ] }, "bank_code": { "type": "string" }, "bank_name": { "type": "string" }, "account_number": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email" }, "details": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "x-scope": "beneficiaries:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Beneficiary" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Remittance & transfers" ] }, "get": { "summary": "List beneficiaries", "operationId": "listBeneficiaries", "x-scope": "beneficiaries:read", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "country", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Beneficiary list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Remittance & transfers" ] } }, "/beneficiaries/{id}": { "get": { "summary": "Retrieve a beneficiary", "operationId": "getBeneficiary", "x-scope": "beneficiaries:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Beneficiary" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Remittance & transfers" ] }, "delete": { "summary": "Archive a beneficiary", "operationId": "deleteBeneficiary", "x-scope": "beneficiaries:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Remittance & transfers" ] } }, "/beneficiaries/{id}/verify": { "post": { "summary": "Name-check a Nigerian bank beneficiary", "operationId": "verifyBeneficiary", "x-scope": "beneficiaries:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Beneficiary" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Remittance & transfers" ] } }, "/transfers/corridors": { "get": { "summary": "List payout corridors, methods and limits", "operationId": "listTransferCorridors", "x-scope": "transfers:read", "responses": { "200": { "description": "Corridor list", "content": { "application/json": { "example": { "object": "list", "data": [ { "object": "transfer_corridor", "country": "GH", "country_name": "Ghana", "methods": [ { "transfer_method": "mobile_money", "label": "Mobile money", "currency": "GHS", "minimum_amount": "10.00", "maximum_amount": "50000.00", "delivery": "Within minutes", "required_fields": [ "name", "phone" ] } ] } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Remittance & transfers" ] } }, "/transfers/quote": { "post": { "summary": "Price a transfer before sending it", "operationId": "quoteTransfer", "x-scope": "transfers:read", "responses": { "200": { "description": "Transfer quote", "content": { "application/json": { "example": { "object": "transfer_quote", "source_currency": "NGN", "destination_currency": "GHS", "destination_country": "GH", "transfer_method": "mobile_money", "amount": "250000.00", "fee": "1250.00", "rate": "0.0116", "destination_amount": "2885.00", "delivery": "Within minutes", "expires_at": "2026-08-30T09:29:22.104Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Remittance & transfers" ], "requestBody": { "required": true, "content": { "application/json": { "example": { "source_currency": "NGN", "destination_country": "GH", "transfer_method": "mobile_money", "amount": "250000.00" } } } } } }, "/transfers": { "post": { "summary": "Send a transfer", "operationId": "createTransfer", "x-scope": "transfers:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Transfer", "content": { "application/json": { "examples": { "mobile_money_ngn_ghs": { "summary": "NGN → GHS mobile money (the default example)", "value": { "id": "trf_9f2c41ab77e04d1e8b6a", "object": "transfer", "status": "processing", "reference": "RM-9F2C41AB", "beneficiary_id": "ben_31d0c8a5f4e2", "source_currency": "NGN", "destination_currency": "GHS", "destination_country": "GH", "amount": "250000.00", "fee": "1250.00", "rate": "0.0116", "destination_amount": "2885.00", "recipient_name": "Ama Owusu", "account_number": "0241234567", "bank_name": "MTN Mobile Money", "narration": "October retainer", "failure_reason": null, "metadata": { "invoice_id": "inv_2201" }, "created_at": "2026-08-30T09:14:22.104Z", "updated_at": "2026-08-30T09:14:25.882Z" } }, "bank_usd_kes": { "summary": "USD → KES bank transfer, rate-derived amount rounded to 2dp", "value": { "id": "trf_2b70e5d1c93a4f6a8021", "object": "transfer", "status": "processing", "reference": "RM-2B70E5D1", "beneficiary_id": "ben_31d0c8a5f4e2", "source_currency": "USD", "destination_currency": "KES", "destination_country": "KE", "amount": "1500.00", "fee": "7.50", "rate": "128.9377", "destination_amount": "192436.05", "recipient_name": "Wanjiru Kamau", "account_number": "01100234567890", "bank_name": "Equity Bank", "narration": "October retainer", "failure_reason": null, "metadata": { "invoice_id": "inv_2201" }, "created_at": "2026-08-30T09:14:22.104Z", "updated_at": "2026-08-30T09:14:25.882Z" } }, "beneficiary_only": { "summary": "Send to a saved beneficiary", "value": { "id": "trf_9f2c41ab77e04d1e8b6a", "object": "transfer", "status": "processing", "reference": "RM-9F2C41AB", "beneficiary_id": "ben_31d0c8a5f4e2", "source_currency": "NGN", "destination_currency": "GHS", "destination_country": "GH", "amount": "50000.00", "fee": "1250.00", "rate": "0.0116", "destination_amount": "563.62", "recipient_name": "Ama Owusu", "account_number": "0241234567", "bank_name": "MTN Mobile Money", "narration": "October retainer", "failure_reason": null, "metadata": { "invoice_id": "inv_2201" }, "created_at": "2026-08-30T09:14:22.104Z", "updated_at": "2026-08-30T09:14:25.882Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Remittance & transfers" ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "mobile_money_ngn_ghs": { "summary": "NGN → GHS mobile money (the default example)", "value": { "source_currency": "NGN", "amount": "250000.00", "destination": { "country": "GH", "transfer_method": "mobile_money", "name": "Ama Owusu", "phone": "+233241234567" } } }, "bank_usd_kes": { "summary": "USD → KES bank transfer, rate-derived amount rounded to 2dp", "value": { "source_currency": "USD", "amount": "1500.00", "narration": "Contractor invoice 4471", "destination": { "country": "KE", "transfer_method": "bank", "name": "Wanjiru Kamau", "account_number": "01100234567890", "bank_code": "68", "bank_name": "Equity Bank" } } }, "beneficiary_only": { "summary": "Send to a saved beneficiary", "value": { "beneficiary_id": "ben_31d0c8a5f4e2", "source_currency": "NGN", "amount": "50000.00", "metadata": { "payroll_run": "2026-08" } } } } } } }, "x-response-examples": { "mobile_money_ngn_ghs": { "summary": "NGN → GHS mobile money (the default example)", "value": { "id": "trf_9f2c41ab77e04d1e8b6a", "object": "transfer", "status": "processing", "reference": "RM-9F2C41AB", "beneficiary_id": "ben_31d0c8a5f4e2", "source_currency": "NGN", "destination_currency": "GHS", "destination_country": "GH", "amount": "250000.00", "fee": "1250.00", "rate": "0.0116", "destination_amount": "2885.00", "recipient_name": "Ama Owusu", "account_number": "0241234567", "bank_name": "MTN Mobile Money", "narration": "October retainer", "failure_reason": null, "metadata": { "invoice_id": "inv_2201" }, "created_at": "2026-08-30T09:14:22.104Z", "updated_at": "2026-08-30T09:14:25.882Z" } }, "bank_usd_kes": { "summary": "USD → KES bank transfer, rate-derived amount rounded to 2dp", "value": { "id": "trf_2b70e5d1c93a4f6a8021", "object": "transfer", "status": "processing", "reference": "RM-2B70E5D1", "beneficiary_id": "ben_31d0c8a5f4e2", "source_currency": "USD", "destination_currency": "KES", "destination_country": "KE", "amount": "1500.00", "fee": "7.50", "rate": "128.9377", "destination_amount": "192436.05", "recipient_name": "Wanjiru Kamau", "account_number": "01100234567890", "bank_name": "Equity Bank", "narration": "October retainer", "failure_reason": null, "metadata": { "invoice_id": "inv_2201" }, "created_at": "2026-08-30T09:14:22.104Z", "updated_at": "2026-08-30T09:14:25.882Z" } }, "beneficiary_only": { "summary": "Send to a saved beneficiary", "value": { "id": "trf_9f2c41ab77e04d1e8b6a", "object": "transfer", "status": "processing", "reference": "RM-9F2C41AB", "beneficiary_id": "ben_31d0c8a5f4e2", "source_currency": "NGN", "destination_currency": "GHS", "destination_country": "GH", "amount": "50000.00", "fee": "1250.00", "rate": "0.0116", "destination_amount": "563.62", "recipient_name": "Ama Owusu", "account_number": "0241234567", "bank_name": "MTN Mobile Money", "narration": "October retainer", "failure_reason": null, "metadata": { "invoice_id": "inv_2201" }, "created_at": "2026-08-30T09:14:22.104Z", "updated_at": "2026-08-30T09:14:25.882Z" } } } }, "get": { "summary": "List transfers", "operationId": "listTransfers", "x-scope": "transfers:read", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transfer list", "content": { "application/json": { "example": { "object": "list", "data": [ { "id": "trf_9f2c41ab77e04d1e8b6a", "object": "transfer", "status": "processing", "reference": "RM-9F2C41AB", "beneficiary_id": "ben_31d0c8a5f4e2", "source_currency": "NGN", "destination_currency": "GHS", "destination_country": "GH", "amount": "250000.00", "fee": "1250.00", "rate": "0.0116", "destination_amount": "2885.00", "recipient_name": "Ama Owusu", "account_number": "0241234567", "bank_name": "MTN Mobile Money", "narration": "October retainer", "failure_reason": null, "metadata": { "invoice_id": "inv_2201" }, "created_at": "2026-08-30T09:14:22.104Z", "updated_at": "2026-08-30T09:14:25.882Z" } ], "next_cursor": "2026-08-30T09:14:22.104Z", "has_more": true } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Remittance & transfers" ] } }, "/transfers/{id}": { "get": { "summary": "Retrieve a transfer", "operationId": "getTransfer", "x-scope": "transfers:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transfer", "content": { "application/json": { "example": { "id": "trf_9f2c41ab77e04d1e8b6a", "object": "transfer", "status": "completed", "reference": "RM-9F2C41AB", "beneficiary_id": "ben_31d0c8a5f4e2", "source_currency": "NGN", "destination_currency": "GHS", "destination_country": "GH", "amount": "250000.00", "fee": "1250.00", "rate": "0.0116", "destination_amount": "2885.00", "recipient_name": "Ama Owusu", "account_number": "0241234567", "bank_name": "MTN Mobile Money", "narration": "October retainer", "failure_reason": null, "metadata": { "invoice_id": "inv_2201" }, "created_at": "2026-08-30T09:14:22.104Z", "updated_at": "2026-08-30T09:14:25.882Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Remittance & transfers" ] } }, "/transfers/{id}/reconcile": { "post": { "summary": "Re-check a transfer with its provider", "operationId": "reconcileTransfer", "x-scope": "transfers:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transfer", "content": { "application/json": { "example": { "id": "trf_9f2c41ab77e04d1e8b6a", "object": "transfer", "status": "failed", "reference": "RM-9F2C41AB", "beneficiary_id": "ben_31d0c8a5f4e2", "source_currency": "NGN", "destination_currency": "GHS", "destination_country": "GH", "amount": "250000.00", "fee": "1250.00", "rate": "0.0116", "destination_amount": "2885.00", "recipient_name": "Ama Owusu", "account_number": "0241234567", "bank_name": "MTN Mobile Money", "narration": "October retainer", "failure_reason": "Recipient wallet could not be credited", "metadata": { "invoice_id": "inv_2201" }, "created_at": "2026-08-30T09:14:22.104Z", "updated_at": "2026-08-30T09:14:25.882Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Remittance & transfers" ] } }, "/cardholders": { "post": { "summary": "Register a cardholder", "operationId": "createCardholder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "job_title": { "type": "string" }, "department": { "type": "string" }, "employee_id": { "type": "string" }, "date_of_birth": { "type": "string", "format": "date" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" }, "country": { "type": "string", "minLength": 2, "maxLength": 3 }, "bvn": { "type": "string", "description": "Nigerian cardholders." }, "nin": { "type": "string" }, "national_id": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "x-scope": "cardholders:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Cardholder" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Cards" ] }, "get": { "summary": "List cardholders", "operationId": "listCardholders", "x-scope": "cardholders:read", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cardholder list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Cards" ] } }, "/cardholders/{id}": { "get": { "summary": "Retrieve a cardholder", "operationId": "getCardholder", "x-scope": "cardholders:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cardholder" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Cards" ] } }, "/cards": { "post": { "summary": "Issue a card", "operationId": "createCard", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cardholder_id" ], "properties": { "cardholder_id": { "type": "string", "examples": [ "chd_12345" ] }, "card_type": { "type": "string", "enum": [ "virtual", "physical" ], "default": "virtual", "description": "Single-use (disposable) cards are available in the Suite only and are not yet issued over the API." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "default": "NGN" }, "purpose": { "type": "string", "default": "Business spend" }, "label": { "type": "string" }, "contact_number": { "type": "string" }, "delivery_address": { "type": "string", "description": "Required for physical cards." }, "initial_funding": { "type": "string", "examples": [ "1500.00" ] }, "monthly_limit": { "type": "string", "examples": [ "1500.00" ] }, "daily_limit": { "type": "string", "examples": [ "1500.00" ] }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "x-scope": "cards:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Card" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Cards" ] }, "get": { "summary": "List cards", "operationId": "listCards", "x-scope": "cards:read", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Cards" ] } }, "/cards/{id}": { "get": { "summary": "Retrieve a card", "operationId": "getCard", "x-scope": "cards:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Cards" ] } }, "/cards/{id}/freeze": { "post": { "summary": "Freeze a card", "operationId": "freezeCard", "x-scope": "cards:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Cards" ] } }, "/cards/{id}/unfreeze": { "post": { "summary": "Unfreeze a card", "operationId": "unfreezeCard", "x-scope": "cards:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Cards" ] } }, "/cards/{id}/terminate": { "post": { "summary": "Terminate a card", "operationId": "terminateCard", "x-scope": "cards:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Cards" ] } }, "/cards/{id}/limits": { "post": { "summary": "Update card spend limits", "operationId": "setCardLimits", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "monthly_limit": { "type": "string", "examples": [ "1500.00" ] }, "daily_limit": { "type": "string", "examples": [ "1500.00" ] } } } } } }, "x-scope": "cards:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Cards" ] } }, "/cards/{id}/fund": { "post": { "summary": "Fund a card from a business balance", "operationId": "fundCard", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "string", "examples": [ "1500.00" ] }, "source_currency": { "type": "string", "description": "Balance to debit. Defaults to the card currency." }, "description": { "type": "string", "maxLength": 200 } } } } } }, "x-scope": "cards:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Card funding" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Cards" ] } }, "/cards/{id}/withdraw": { "post": { "summary": "Withdraw funds from a card", "operationId": "withdrawFromCard", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "string", "examples": [ "1500.00" ] }, "source_currency": { "type": "string", "description": "Balance to debit. Defaults to the card currency." }, "description": { "type": "string", "maxLength": 200 } } } } } }, "x-scope": "cards:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Card funding" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Cards" ] } }, "/cards/{id}/transactions": { "get": { "summary": "List card transactions", "operationId": "listCardTransactions", "x-scope": "card_transactions:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Card transaction list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Cards" ] } }, "/digital-services/products": { "get": { "summary": "List digital service products", "description": "Airtime, mobile data, bundles, eSIMs, gift cards and prepaid utilities available to your business, already priced in your billing currency.", "operationId": "listDigitalServiceProducts", "x-scope": "digital_services:read", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "AIRTIME", "MOBILE_DATA", "MOBILE_BUNDLE", "ESIM", "GIFT_CARD", "UTILITY" ] } }, { "name": "country", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "brand", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Product list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Global Digital Services" ] } }, "/digital-services/products/{id}": { "get": { "summary": "Retrieve a digital service product", "operationId": "getDigitalServiceProduct", "x-scope": "digital_services:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Global Digital Services" ] } }, "/digital-services/quotes": { "post": { "summary": "Quote a digital service purchase", "description": "Quotes are held for five minutes and must be used to create a purchase.", "operationId": "createDigitalServiceQuote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "string" }, "amount": { "type": "string", "examples": [ "1500.00" ], "description": "Required for open-value products." }, "business_markup_bps": { "type": "integer", "minimum": 0, "maximum": 10000 } } } } } }, "x-scope": "digital_services:write", "responses": { "201": { "description": "Quote" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Global Digital Services" ] } }, "/digital-services/purchases": { "post": { "summary": "Purchase a digital service", "description": "Requires an Idempotency-Key. A retry with the same key replays the original purchase.", "operationId": "createDigitalServicePurchase", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quote_id" ], "properties": { "quote_id": { "type": "string" }, "recipient_msisdn": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "recipient_name": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Any extra fields the product declares as required." } } } } } }, "x-scope": "digital_services:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Purchase" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Global Digital Services" ] }, "get": { "summary": "List digital service purchases", "operationId": "listDigitalServicePurchases", "x-scope": "digital_services:read", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Purchase list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Global Digital Services" ] } }, "/digital-services/purchases/{id}": { "get": { "summary": "Retrieve a digital service purchase", "operationId": "getDigitalServicePurchase", "x-scope": "digital_services:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Purchase" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Global Digital Services" ] } }, "/digital-services/batches": { "post": { "summary": "Create a bulk digital service batch", "description": "Up to 500 rows. Each row is purchased independently under its own idempotency key; poll the batch for per-row status.", "operationId": "createDigitalServiceBatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "business_markup_bps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "items": { "type": "array", "items": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "string" }, "amount": { "type": "string", "examples": [ "1500.00" ] }, "recipient_msisdn": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "recipient_name": { "type": "string" } } } } } } } } }, "x-scope": "digital_services:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Batch" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Global Digital Services" ] } }, "/digital-services/batches/{id}": { "get": { "summary": "Retrieve a bulk batch with per-row status", "operationId": "getDigitalServiceBatch", "x-scope": "digital_services:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Global Digital Services" ] } }, "/flights/search": { "post": { "summary": "Search flight offers", "operationId": "searchFlights", "x-scope": "flights:read", "description": "Read-only search with a JSON body. Reserves nothing and charges nothing; no Idempotency-Key is required. An offer may expire before booking.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slices", "passengers" ], "properties": { "slices": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "type": "object", "required": [ "origin", "destination", "departure_date" ], "properties": { "origin": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "destination": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "departure_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } } }, "passengers": { "type": "array", "minItems": 1, "maxItems": 9, "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adult", "child", "infant" ], "default": "adult" } } } }, "cabin_class": { "type": "string", "enum": [ "economy", "premium_economy", "business", "first" ], "default": "economy" } } } } } }, "responses": { "200": { "description": "Priced flight offers", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "currency": { "type": "string" }, "searched_at": { "type": "string", "format": "date-time" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque offer id to pass to booking creation." }, "object": { "type": "string", "const": "flight_offer" }, "amount": { "type": "string", "description": "Decimal-string total including markup." }, "currency": { "type": "string" }, "airline": { "type": [ "string", "null" ] }, "airline_name": { "type": [ "string", "null" ] }, "cabin_class": { "type": "string" }, "stops": { "type": "integer" }, "duration_minutes": { "type": [ "integer", "null" ] }, "refundable": { "type": [ "boolean", "null" ] }, "changeable": { "type": [ "boolean", "null" ] }, "baggage": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "passenger_count": { "type": "integer" }, "slices": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "destination": { "type": "string" }, "departure_date": { "type": [ "string", "null" ] }, "duration_minutes": { "type": [ "integer", "null" ] }, "stops": { "type": "integer" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "destination": { "type": "string" }, "departing_at": { "type": [ "string", "null" ] }, "arriving_at": { "type": [ "string", "null" ] }, "duration_minutes": { "type": [ "integer", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "carrier_name": { "type": [ "string", "null" ] }, "flight_number": { "type": [ "string", "null" ] }, "cabin_class": { "type": [ "string", "null" ] }, "baggage": { "type": [ "string", "null" ] } } } } } } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Flights & Travel" ] } }, "/flights/bookings": { "post": { "summary": "Create a flight booking", "operationId": "createFlightBooking", "x-scope": "flights:write", "description": "Ticketing is irreversible. Requires an Idempotency-Key, reused for every retry of this booking. The response may still be processing; reconcile by retrieving it instead of submitting a new booking.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "offer_id", "passengers" ], "properties": { "offer_id": { "type": "string", "minLength": 3, "maxLength": 200 }, "passengers": { "type": "array", "minItems": 1, "maxItems": 9, "items": { "type": "object", "required": [ "given_name", "family_name", "date_of_birth" ], "properties": { "type": { "type": "string", "enum": [ "adult", "child", "infant" ], "default": "adult" }, "title": { "type": [ "string", "null" ], "maxLength": 10 }, "given_name": { "type": "string", "minLength": 1, "maxLength": 60 }, "family_name": { "type": "string", "minLength": 1, "maxLength": 60 }, "date_of_birth": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "gender": { "type": [ "string", "null" ], "maxLength": 12 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 200 }, "phone": { "type": [ "string", "null" ], "maxLength": 32 }, "nationality": { "type": [ "string", "null" ], "maxLength": 2 }, "document_type": { "type": [ "string", "null" ], "maxLength": 24 }, "document_number": { "type": [ "string", "null" ], "maxLength": 40 }, "document_expiry": { "type": [ "string", "null" ], "maxLength": 10 }, "document_issuing_country": { "type": [ "string", "null" ], "maxLength": 2 } } } }, "contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 200 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 32 } } } } } }, "responses": { "201": { "description": "Booking", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "flight_booking" }, "status": { "type": "string", "enum": [ "RESERVED", "SUBMITTED", "PENDING", "PROCESSING", "TICKETED", "FAILED", "CANCELLED", "REFUNDED", "UNKNOWN" ] }, "trip_type": { "type": "string" }, "cabin_class": { "type": "string" }, "origin": { "type": [ "string", "null" ] }, "destination": { "type": [ "string", "null" ] }, "departure_date": { "type": [ "string", "null" ] }, "return_date": { "type": [ "string", "null" ] }, "airline": { "type": [ "string", "null" ] }, "airline_name": { "type": [ "string", "null" ] }, "pnr": { "type": [ "string", "null" ] }, "ticket_numbers": { "type": "array", "items": { "type": "string" } }, "passenger_count": { "type": "integer" }, "passengers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } }, "amount": { "type": "string", "description": "Decimal-string total including markup, in the booking currency." }, "currency": { "type": "string" }, "contact_email": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "ticketed_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Flights & Travel" ] }, "get": { "summary": "List flight bookings", "operationId": "listFlightBookings", "x-scope": "flights:read", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Booking list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "flight_booking" }, "status": { "type": "string", "enum": [ "RESERVED", "SUBMITTED", "PENDING", "PROCESSING", "TICKETED", "FAILED", "CANCELLED", "REFUNDED", "UNKNOWN" ] }, "trip_type": { "type": "string" }, "cabin_class": { "type": "string" }, "origin": { "type": [ "string", "null" ] }, "destination": { "type": [ "string", "null" ] }, "departure_date": { "type": [ "string", "null" ] }, "return_date": { "type": [ "string", "null" ] }, "airline": { "type": [ "string", "null" ] }, "airline_name": { "type": [ "string", "null" ] }, "pnr": { "type": [ "string", "null" ] }, "ticket_numbers": { "type": "array", "items": { "type": "string" } }, "passenger_count": { "type": "integer" }, "passengers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } }, "amount": { "type": "string", "description": "Decimal-string total including markup, in the booking currency." }, "currency": { "type": "string" }, "contact_email": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "ticketed_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Flights & Travel" ] } }, "/flights/bookings/{id}": { "get": { "summary": "Retrieve a flight booking", "operationId": "getFlightBooking", "x-scope": "flights:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Booking", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "flight_booking" }, "status": { "type": "string", "enum": [ "RESERVED", "SUBMITTED", "PENDING", "PROCESSING", "TICKETED", "FAILED", "CANCELLED", "REFUNDED", "UNKNOWN" ] }, "trip_type": { "type": "string" }, "cabin_class": { "type": "string" }, "origin": { "type": [ "string", "null" ] }, "destination": { "type": [ "string", "null" ] }, "departure_date": { "type": [ "string", "null" ] }, "return_date": { "type": [ "string", "null" ] }, "airline": { "type": [ "string", "null" ] }, "airline_name": { "type": [ "string", "null" ] }, "pnr": { "type": [ "string", "null" ] }, "ticket_numbers": { "type": "array", "items": { "type": "string" } }, "passenger_count": { "type": "integer" }, "passengers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } }, "amount": { "type": "string", "description": "Decimal-string total including markup, in the booking currency." }, "currency": { "type": "string" }, "contact_email": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "ticketed_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Flights & Travel" ] } }, "/webhook-events": { "get": { "summary": "List webhook events", "operationId": "listWebhookEvents", "x-scope": "webhooks:read", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Event list", "content": { "application/json": { "example": { "object": "list", "data": [ { "id": "evt_b71f4d9c2a80", "object": "webhook_event", "type": "transfer.completed", "api_version": "2026-08-29", "environment": "live", "business_id": "biz_4410ad", "resource_id": "trf_9f2c41ab77e04d1e8b6a", "data": { "id": "trf_9f2c41ab77e04d1e8b6a", "object": "transfer", "status": "completed", "reference": "RM-9F2C41AB", "beneficiary_id": "ben_31d0c8a5f4e2", "source_currency": "NGN", "destination_currency": "GHS", "destination_country": "GH", "amount": "250000.00", "fee": "1250.00", "rate": "0.0116", "destination_amount": "2885.00", "recipient_name": "Ama Owusu", "account_number": "0241234567", "bank_name": "MTN Mobile Money", "narration": "October retainer", "failure_reason": null, "metadata": { "invoice_id": "inv_2201" }, "created_at": "2026-08-30T09:14:22.104Z", "updated_at": "2026-08-30T09:14:25.882Z" }, "delivery_state": "delivered", "attempts": 1, "created_at": "2026-08-30T09:15:01.902Z" } ], "next_cursor": "2026-08-30T09:15:01.902Z", "has_more": true } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Webhooks" ] } }, "/webhook-events/{id}": { "get": { "summary": "Retrieve a webhook event", "operationId": "getWebhookEvent", "x-scope": "webhooks:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Event", "content": { "application/json": { "example": { "id": "evt_b71f4d9c2a80", "object": "webhook_event", "type": "transfer.completed", "api_version": "2026-08-29", "environment": "live", "business_id": "biz_4410ad", "resource_id": "trf_9f2c41ab77e04d1e8b6a", "data": { "id": "trf_9f2c41ab77e04d1e8b6a", "object": "transfer", "status": "completed", "reference": "RM-9F2C41AB", "beneficiary_id": "ben_31d0c8a5f4e2", "source_currency": "NGN", "destination_currency": "GHS", "destination_country": "GH", "amount": "250000.00", "fee": "1250.00", "rate": "0.0116", "destination_amount": "2885.00", "recipient_name": "Ama Owusu", "account_number": "0241234567", "bank_name": "MTN Mobile Money", "narration": "October retainer", "failure_reason": null, "metadata": { "invoice_id": "inv_2201" }, "created_at": "2026-08-30T09:14:22.104Z", "updated_at": "2026-08-30T09:14:25.882Z" }, "delivery_state": "delivered", "attempts": 1, "created_at": "2026-08-30T09:15:01.902Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Webhooks" ] } }, "/webhook-events/{id}/resend": { "post": { "summary": "Resend an event to one endpoint", "operationId": "resendWebhookEvent", "x-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delivery", "content": { "application/json": { "example": { "id": "whd_84ba0f13c5d9", "object": "webhook_delivery", "endpoint_id": "whe_6d21c9f0a3b7", "event_id": "evt_b71f4d9c2a80", "event_type": "transfer.completed", "status": "pending", "attempts": 0, "response_code": 200, "last_error": null, "next_attempt_at": null, "delivered_at": null, "created_at": "2026-08-30T09:15:01.988Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "example": { "endpoint_id": "whe_6d21c9f0a3b7" } } } } } }, "/webhook-endpoints": { "post": { "summary": "Create a webhook endpoint", "description": "The signing secret is returned once, in this response. Verify deliveries with the BoundlessPay-Signature header (t=,v1=).", "operationId": "createWebhookEndpoint", "x-scope": "webhooks:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Endpoint with signing secret", "content": { "application/json": { "example": { "id": "whe_6d21c9f0a3b7", "object": "webhook_endpoint", "url": "https://merchant.example.com/hooks/boundlesspay", "description": "Production ledger sync", "environment": "live", "enabled_events": [ "transfer.completed", "transfer.failed", "deposit.settled" ], "status": "active", "consecutive_failures": 0, "last_success_at": "2026-08-30T09:15:02.441Z", "last_failure_at": null, "last_error": null, "created_at": "2026-07-04T11:02:19.006Z", "signing_secret": "whsec_9c1f0f8a4c2d47bb9a3e5f7d1b0c8e26" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "example": { "url": "https://merchant.example.com/hooks/boundlesspay", "description": "Production ledger sync", "enabled_events": [ "transfer.completed", "transfer.failed", "deposit.settled" ] } } } } }, "get": { "summary": "List webhook endpoints", "operationId": "listWebhookEndpoints", "x-scope": "webhooks:read", "responses": { "200": { "description": "Endpoint list", "content": { "application/json": { "example": { "object": "list", "data": [ { "id": "whe_6d21c9f0a3b7", "object": "webhook_endpoint", "url": "https://merchant.example.com/hooks/boundlesspay", "description": "Production ledger sync", "environment": "live", "enabled_events": [ "transfer.completed", "transfer.failed", "deposit.settled" ], "status": "active", "consecutive_failures": 0, "last_success_at": "2026-08-30T09:15:02.441Z", "last_failure_at": null, "last_error": null, "created_at": "2026-07-04T11:02:19.006Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Webhooks" ] } }, "/webhook-endpoints/{id}": { "get": { "summary": "Retrieve a webhook endpoint", "operationId": "getWebhookEndpoint", "x-scope": "webhooks:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Endpoint", "content": { "application/json": { "example": { "id": "whe_6d21c9f0a3b7", "object": "webhook_endpoint", "url": "https://merchant.example.com/hooks/boundlesspay", "description": "Production ledger sync", "environment": "live", "enabled_events": [ "transfer.completed", "transfer.failed", "deposit.settled" ], "status": "active", "consecutive_failures": 0, "last_success_at": "2026-08-30T09:15:02.441Z", "last_failure_at": null, "last_error": null, "created_at": "2026-07-04T11:02:19.006Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Webhooks" ] }, "patch": { "summary": "Update a webhook endpoint", "operationId": "updateWebhookEndpoint", "x-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Endpoint", "content": { "application/json": { "example": { "id": "whe_6d21c9f0a3b7", "object": "webhook_endpoint", "url": "https://merchant.example.com/hooks/boundlesspay", "description": "Production ledger sync", "environment": "live", "enabled_events": [ "transfer.completed", "transfer.failed", "deposit.settled" ], "status": "paused", "consecutive_failures": 0, "last_success_at": "2026-08-30T09:15:02.441Z", "last_failure_at": null, "last_error": null, "created_at": "2026-07-04T11:02:19.006Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "example": { "enabled_events": [ "transfer.completed" ], "status": "paused" } } } } }, "delete": { "summary": "Delete a webhook endpoint", "operationId": "deleteWebhookEndpoint", "x-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "example": { "id": "whe_6d21c9f0a3b7", "object": "webhook_endpoint", "deleted": true } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Webhooks" ] } }, "/webhook-endpoints/{id}/rotate-secret": { "post": { "summary": "Rotate an endpoint signing secret", "operationId": "rotateWebhookSecret", "x-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "New signing secret", "content": { "application/json": { "example": { "id": "whe_6d21c9f0a3b7", "object": "webhook_endpoint", "url": "https://merchant.example.com/hooks/boundlesspay", "description": "Production ledger sync", "environment": "live", "enabled_events": [ "transfer.completed", "transfer.failed", "deposit.settled" ], "status": "active", "consecutive_failures": 0, "last_success_at": "2026-08-30T09:15:02.441Z", "last_failure_at": null, "last_error": null, "created_at": "2026-07-04T11:02:19.006Z", "signing_secret": "whsec_5b7a20d3e9114f6c8d2a91fe4c30ab77" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Webhooks" ] } }, "/webhook-deliveries": { "get": { "summary": "List webhook deliveries", "operationId": "listWebhookDeliveries", "x-scope": "webhooks:read", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "endpoint_id", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delivery list", "content": { "application/json": { "example": { "object": "list", "data": [ { "id": "whd_84ba0f13c5d9", "object": "webhook_delivery", "endpoint_id": "whe_6d21c9f0a3b7", "event_id": "evt_b71f4d9c2a80", "event_type": "transfer.completed", "status": "delivered", "attempts": 1, "response_code": 200, "last_error": null, "next_attempt_at": null, "delivered_at": "2026-08-30T09:15:02.441Z", "created_at": "2026-08-30T09:15:01.988Z" } ], "next_cursor": "2026-08-30T09:15:01.988Z", "has_more": true } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Webhooks" ] } }, "/webhook-deliveries/{id}/replay": { "post": { "summary": "Replay a webhook delivery", "operationId": "replayWebhookDelivery", "x-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delivery", "content": { "application/json": { "example": { "id": "whd_84ba0f13c5d9", "object": "webhook_delivery", "endpoint_id": "whe_6d21c9f0a3b7", "event_id": "evt_b71f4d9c2a80", "event_type": "transfer.completed", "status": "pending", "attempts": 1, "response_code": 200, "last_error": null, "next_attempt_at": null, "delivered_at": null, "created_at": "2026-08-30T09:15:01.988Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Webhooks" ] } }, "/webhook-deliveries/replay": { "post": { "summary": "Bulk replay failed webhook deliveries", "description": "Re-attempts deliveries that failed or were dead-lettered — the recovery lever after an endpoint outage. No new event is created; the identical signed body is sent again, so keep your handler idempotent on `event.id`. Filter by `event_prefix` (e.g. `checkout_session.`), `event_type`, `endpoint_id`, `resource_id` or `since`. Delivered rows are skipped unless `include_delivered` is true.", "operationId": "replayWebhookDeliveries", "x-scope": "webhooks:write", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "event_prefix": { "type": "string", "example": "checkout_session." }, "event_type": { "type": "string", "example": "checkout_session.paid" }, "endpoint_id": { "type": "string" }, "resource_id": { "type": "string", "example": "chk_9f2c1d4a" }, "since": { "type": "string", "format": "date-time" }, "include_delivered": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } } } } }, "responses": { "200": { "description": "Replay summary", "content": { "application/json": { "example": { "object": "webhook_replay", "matched": 12, "replayed": 12, "delivered": 11, "retrying": 1, "dead": 0, "skipped": 0, "deliveries": [ { "id": "whd_84ba0f13c5d9", "object": "webhook_delivery", "endpoint_id": "whe_6d21c9f0a3b7", "event_id": "evt_b71f4d9c2a80", "event_type": "transfer.completed", "status": "delivered", "attempts": 2, "response_code": 200, "last_error": null, "next_attempt_at": null, "delivered_at": "2026-08-30T09:15:02.441Z", "created_at": "2026-08-30T09:15:01.988Z" } ] } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Webhooks" ] } }, "/usage": { "get": { "summary": "Metered API usage for the current environment", "operationId": "getUsage", "x-scope": "usage:read", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Usage summary" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Balances & transactions" ] } }, "/otc/pairs": { "get": { "summary": "List OTC trading pairs", "operationId": "listOtcPairs", "x-scope": "otc:read", "responses": { "200": { "description": "Pair list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "OTC trading" ] } }, "/otc/markets/{pair}": { "get": { "summary": "Market summary for one pair", "operationId": "getOtcMarket", "x-scope": "otc:read", "parameters": [ { "name": "pair", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Market snapshot" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "OTC trading" ] } }, "/otc/order-book/{pair}": { "get": { "summary": "Aggregated order book depth", "operationId": "getOtcOrderBook", "x-scope": "otc:read", "parameters": [ { "name": "pair", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "levels", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Order book" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "OTC trading" ] } }, "/otc/trades/{pair}": { "get": { "summary": "Recent public trades", "operationId": "listOtcPublicTrades", "x-scope": "otc:read", "parameters": [ { "name": "pair", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trade list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "OTC trading" ] } }, "/otc/swap/quote": { "post": { "summary": "Request a firm swap quote", "operationId": "createOtcSwapQuote", "x-scope": "otc:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pair", "sell_asset", "buy_asset", "sell_amount" ], "properties": { "pair": { "type": "string", "example": "USDT/NGN" }, "sell_asset": { "type": "string", "example": "USDT" }, "buy_asset": { "type": "string", "example": "NGN" }, "sell_amount": { "type": "string", "example": "1000.00" } } } } } }, "responses": { "201": { "description": "Swap quote" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "OTC trading" ] } }, "/otc/swap/execute": { "post": { "summary": "Execute a swap against a firm quote", "operationId": "executeOtcSwap", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quote_id" ], "properties": { "quote_id": { "type": "string" } } } } } }, "x-scope": "otc:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Swap" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "OTC trading" ] } }, "/otc/swap/{id}": { "get": { "summary": "Retrieve a swap", "operationId": "getOtcSwap", "x-scope": "otc:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Swap" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "OTC trading" ] } }, "/otc/orders": { "post": { "summary": "Place a funded limit or market order", "operationId": "createOtcOrder", "x-scope": "otc:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pair", "side", "order_type", "quantity" ], "properties": { "pair": { "type": "string", "example": "USDT/NGN" }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "order_type": { "type": "string", "enum": [ "LIMIT", "MARKET" ] }, "quantity": { "type": "string", "example": "250.00" }, "price": { "type": "string", "example": "1615.37" }, "time_in_force": { "type": "string", "enum": [ "GTC", "IOC", "FOK", "GTD" ] }, "expires_at": { "type": "string", "format": "date-time" }, "max_spend": { "type": "string", "example": "500000.00" }, "min_receive": { "type": "string" }, "max_slippage_bps": { "type": "integer", "example": 100 } } } } } }, "responses": { "201": { "description": "Order" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "OTC trading" ] }, "get": { "summary": "List orders", "operationId": "listOtcOrders", "x-scope": "otc:read", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "closed", "all" ] } }, { "name": "pair", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "OTC trading" ] } }, "/otc/orders/{id}": { "get": { "summary": "Retrieve an order", "operationId": "getOtcOrder", "x-scope": "otc:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "OTC trading" ] } }, "/otc/orders/{id}/cancel": { "post": { "summary": "Cancel the unfilled remainder of an order", "operationId": "cancelOtcOrder", "x-scope": "otc:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Order" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "OTC trading" ] } }, "/otc/trade-history": { "get": { "summary": "Your executed OTC trades", "operationId": "listOtcTradeHistory", "x-scope": "otc:read", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "name": "pair", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trade list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "OTC trading" ] } }, "/otc/balances": { "get": { "summary": "OTC balances including reserved amounts", "operationId": "listOtcBalances", "x-scope": "otc:read", "responses": { "200": { "description": "Balance list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "OTC trading" ] } }, "/sandbox/deposits": { "post": { "summary": "Simulate a deposit (test credentials only)", "operationId": "simulateDeposit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "virtual_account_id", "amount" ], "properties": { "virtual_account_id": { "type": "string" }, "amount": { "type": "string", "examples": [ "1500.00" ] }, "sender_name": { "type": "string" }, "narration": { "type": "string" } } } } } }, "x-scope": "virtual_accounts:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Simulated deposit" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Virtual accounts service" ] } }, "/payouts/banks": { "get": { "summary": "List banks you can pay out to", "operationId": "listPayoutBanks", "x-scope": "payouts:read", "responses": { "200": { "description": "Bank list", "content": { "application/json": { "example": { "object": "list", "data": [ { "object": "bank", "code": "058", "name": "GTBank" }, { "object": "bank", "code": "044", "name": "Access Bank" } ] } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Bank payouts" ] } }, "/payouts/resolve-account": { "post": { "summary": "Resolve a bank account name", "operationId": "resolvePayoutAccount", "x-scope": "payouts:read", "responses": { "200": { "description": "Account resolution", "content": { "application/json": { "example": { "object": "account_resolution", "account_number": "0123456789", "account_name": "Bright Ideas Ltd" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Bank payouts" ], "requestBody": { "required": true, "content": { "application/json": { "example": { "account_number": "0123456789", "bank_code": "058" } } } } } }, "/tags/{id}": { "get": { "summary": "Resolve a business BpayTag", "description": "Safe display data for a verified business tag. Business namespace only.", "operationId": "resolveBpayTag", "x-scope": "checkout:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "BpayTag" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Checkout page" ] } }, "/payment-intents": { "post": { "summary": "Create a BpayTag payment request", "description": "Binds a payment request to an invoice, checkout, payment link, cashier session or targeted request. Returns an approval_url; the payer approves with their own session and PIN. API keys can never approve a debit.", "operationId": "createPaymentIntent", "x-scope": "checkout:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Payment intent" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Checkout page" ] } }, "/payment-intents/{id}": { "get": { "summary": "Retrieve a payment request", "operationId": "getPaymentIntent", "x-scope": "checkout:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment intent" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Checkout page" ] } }, "/payment-intents/{id}/cancel": { "post": { "summary": "Cancel an unpaid payment request", "operationId": "cancelPaymentIntent", "x-scope": "checkout:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment intent" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Checkout page" ] } }, "/bpay-payments/{id}": { "get": { "summary": "Retrieve a BpayTag payment", "operationId": "getBpayPayment", "x-scope": "checkout:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "BpayTag payment" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Checkout page" ] } }, "/bpay-payments/{id}/refunds": { "post": { "summary": "Refund a BpayTag payment (dashboard approval required)", "operationId": "refundBpayPayment", "x-scope": "refunds:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Refunds must be approved in the dashboard" }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Store refunds" ] } }, "/payouts": { "post": { "summary": "Pay out to a bank account", "description": "Moves money you already hold to a bank account in the same currency. Cross-border sends that need a corridor and a locked rate use POST /transfers instead. The minimum NGN payout is NGN 100.00; smaller amounts return 422 VALIDATION_ERROR.", "operationId": "createBankPayout", "x-scope": "payouts:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Payout", "content": { "application/json": { "example": { "id": "WD-7C41A9E2", "object": "payout", "status": "processing", "reference": "WD-7C41A9E2", "rail": "bank", "currency": "NGN", "amount": "185000.00", "fee": "50.00", "destination": { "account_number": "0123456789", "account_name": "Bright Ideas Ltd", "bank_code": "058", "bank_name": "GTBank" }, "narration": "Supplier settlement", "failure_reason": null, "livemode": true, "created_at": "2026-08-30T10:02:11.417Z", "updated_at": "2026-08-30T10:02:13.902Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Bank payouts" ], "requestBody": { "required": true, "content": { "application/json": { "example": { "currency": "NGN", "amount": "185000.00", "account_number": "0123456789", "account_name": "Bright Ideas Ltd", "bank_code": "058", "bank_name": "GTBank", "narration": "Supplier settlement" } } } } }, "get": { "summary": "List payouts", "operationId": "listPayouts", "x-scope": "payouts:read", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Payout list", "content": { "application/json": { "example": { "object": "list", "data": [ { "id": "WD-7C41A9E2", "object": "payout", "status": "processing", "reference": "WD-7C41A9E2", "rail": "bank", "currency": "NGN", "amount": "185000.00", "fee": "50.00", "destination": { "account_number": "0123456789", "account_name": "Bright Ideas Ltd", "bank_code": "058", "bank_name": "GTBank" }, "narration": "Supplier settlement", "failure_reason": null, "livemode": true, "created_at": "2026-08-30T10:02:11.417Z", "updated_at": "2026-08-30T10:02:13.902Z" }, { "id": "WD-3B90D5F1", "object": "payout", "status": "processing", "reference": "WD-3B90D5F1", "rail": "crypto", "currency": "USDT", "amount": "1250.50", "fee": "1.00", "destination": { "address": "0x8Ae2C1b7F0d94E31aA5c60b17E9C4d3f0821b7A5", "network": "BASE" }, "narration": "Treasury sweep", "failure_reason": null, "livemode": true, "created_at": "2026-08-30T10:20:44.118Z", "updated_at": "2026-08-30T10:20:47.501Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Bank payouts" ] } }, "/payouts/{id}": { "get": { "summary": "Retrieve a payout", "operationId": "getPayout", "x-scope": "payouts:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payout", "content": { "application/json": { "example": { "id": "WD-7C41A9E2", "object": "payout", "status": "completed", "reference": "WD-7C41A9E2", "rail": "bank", "currency": "NGN", "amount": "185000.00", "fee": "50.00", "destination": { "account_number": "0123456789", "account_name": "Bright Ideas Ltd", "bank_code": "058", "bank_name": "GTBank" }, "narration": "Supplier settlement", "failure_reason": null, "livemode": true, "created_at": "2026-08-30T10:02:11.417Z", "updated_at": "2026-08-30T10:02:13.902Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Bank payouts" ] } }, "/payouts/{id}/reconcile": { "post": { "summary": "Re-check a payout with its rail", "operationId": "reconcilePayout", "x-scope": "payouts:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payout", "content": { "application/json": { "example": { "id": "WD-7C41A9E2", "object": "payout", "status": "failed", "reference": "WD-7C41A9E2", "rail": "bank", "currency": "NGN", "amount": "185000.00", "fee": "50.00", "destination": { "account_number": "0123456789", "account_name": "Bright Ideas Ltd", "bank_code": "058", "bank_name": "GTBank" }, "narration": "Supplier settlement", "failure_reason": "Beneficiary account does not accept transfers", "livemode": true, "created_at": "2026-08-30T10:02:11.417Z", "updated_at": "2026-08-30T10:02:13.902Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Bank payouts" ] } }, "/crypto/addresses": { "post": { "summary": "Issue a blockchain deposit address", "description": "Returns the permanent BoundlessPay-custodied address for an asset/network pair, creating it on first use. Calling it again returns the same address.", "operationId": "createCryptoAddress", "x-scope": "crypto:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Deposit address", "content": { "application/json": { "example": { "id": "cad_0f31a7c9d2b4", "object": "crypto_address", "asset": "USDC", "network": "BASE", "address": "0x41C7Ab90e5D2f83B6a17c04E9b25Df3810aC6E72", "memo": null, "status": "active", "livemode": true, "created_at": "2026-08-12T08:41:03.220Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Blockchain addresses & withdrawals" ], "requestBody": { "required": true, "content": { "application/json": { "example": { "asset": "USDC", "network": "BASE" } } } } }, "get": { "summary": "List blockchain deposit addresses", "operationId": "listCryptoAddresses", "x-scope": "crypto:read", "responses": { "200": { "description": "Address list", "content": { "application/json": { "example": { "object": "list", "data": [ { "id": "cad_0f31a7c9d2b4", "object": "crypto_address", "asset": "USDC", "network": "BASE", "address": "0x41C7Ab90e5D2f83B6a17c04E9b25Df3810aC6E72", "memo": null, "status": "active", "livemode": true, "created_at": "2026-08-12T08:41:03.220Z" }, { "id": "cad_71b3", "object": "crypto_address", "asset": "USDT", "network": "BASE", "address": "0x41C7Ab90e5D2f83B6a17c04E9b25Df3810aC6E72", "memo": null, "status": "active", "livemode": true, "created_at": "2026-08-12T08:41:03.220Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Blockchain addresses & withdrawals" ] } }, "/crypto/withdrawals": { "post": { "summary": "Send an on-chain withdrawal", "description": "Debits your balance once and settles on-chain. The destination is validated against the asset's allowed networks and your per-currency limits before anything moves.", "operationId": "createCryptoWithdrawal", "x-scope": "crypto:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Withdrawal", "content": { "application/json": { "example": { "id": "WD-3B90D5F1", "object": "payout", "status": "processing", "reference": "WD-3B90D5F1", "rail": "crypto", "currency": "USDT", "amount": "1250.50", "fee": "1.00", "destination": { "address": "0x8Ae2C1b7F0d94E31aA5c60b17E9C4d3f0821b7A5", "network": "BASE" }, "narration": "Treasury sweep", "failure_reason": null, "livemode": true, "created_at": "2026-08-30T10:20:44.118Z", "updated_at": "2026-08-30T10:20:47.501Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Blockchain addresses & withdrawals" ], "requestBody": { "required": true, "content": { "application/json": { "example": { "asset": "USDT", "network": "BASE", "address": "0x8Ae2C1b7F0d94E31aA5c60b17E9C4d3f0821b7A5", "amount": "1250.50", "narration": "Treasury sweep" } } } } }, "get": { "summary": "List on-chain withdrawals", "operationId": "listCryptoWithdrawals", "x-scope": "crypto:read", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Withdrawal list", "content": { "application/json": { "example": { "object": "list", "data": [ { "id": "WD-3B90D5F1", "object": "payout", "status": "processing", "reference": "WD-3B90D5F1", "rail": "crypto", "currency": "USDT", "amount": "1250.50", "fee": "1.00", "destination": { "address": "0x8Ae2C1b7F0d94E31aA5c60b17E9C4d3f0821b7A5", "network": "BASE" }, "narration": "Treasury sweep", "failure_reason": null, "livemode": true, "created_at": "2026-08-30T10:20:44.118Z", "updated_at": "2026-08-30T10:20:47.501Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Blockchain addresses & withdrawals" ] } }, "/crypto/withdrawals/{id}": { "get": { "summary": "Retrieve an on-chain withdrawal", "operationId": "getCryptoWithdrawal", "x-scope": "crypto:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Withdrawal", "content": { "application/json": { "example": { "id": "WD-3B90D5F1", "object": "payout", "status": "completed", "reference": "WD-3B90D5F1", "rail": "crypto", "currency": "USDT", "amount": "1250.50", "fee": "1.00", "destination": { "address": "0x8Ae2C1b7F0d94E31aA5c60b17E9C4d3f0821b7A5", "network": "BASE" }, "narration": "Treasury sweep", "failure_reason": null, "livemode": true, "created_at": "2026-08-30T10:20:44.118Z", "updated_at": "2026-08-30T10:20:47.501Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Blockchain addresses & withdrawals" ] } }, "/crypto/receive-address": { "get": { "summary": "Resolve the address to receive an asset on", "description": "Returns the current receiving address for an asset, plus any historical addresses that still accept funds. Historical addresses are never re-issued as the primary one.", "operationId": "getCryptoReceiveAddress", "x-scope": "crypto:read", "parameters": [ { "name": "asset", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "network", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Receive address", "content": { "application/json": { "example": { "object": "crypto_receive_address", "asset": "USDT", "network": "BSC", "address": "0x41C7Ab90e5D2f83B6a17c04E9b25Df3810aC6E72", "memo": null, "previous_addresses": [ { "asset": "USDT", "network": "BSC", "address": "0x9D3f0821b7A58Ae2C1b7F0d94E31aA5c60b17E9C", "status": "legacy_active" } ], "livemode": true } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Blockchain addresses & withdrawals" ] } }, "/swaps/quote": { "post": { "summary": "Quote a swap between two assets", "description": "Firm pricing that expires after 15 seconds. Refresh before executing.", "operationId": "createSwapQuote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fromCurrency", "toCurrency" ], "properties": { "fromCurrency": { "type": "string", "examples": [ "USDT" ] }, "toCurrency": { "type": "string", "examples": [ "NGN" ] }, "fromAmount": { "type": "string", "examples": [ "1500.00" ], "description": "Give exactly one of fromAmount or toAmount." }, "toAmount": { "type": "string", "examples": [ "1500.00" ] } } } } } }, "x-scope": "crypto:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Swap quote" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Blockchain addresses & withdrawals" ] } }, "/swaps/{id}/refresh": { "post": { "summary": "Refresh an expiring swap quote", "operationId": "refreshSwapQuote", "x-scope": "crypto:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Swap quote" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Blockchain addresses & withdrawals" ] } }, "/swaps/{id}/execute": { "post": { "summary": "Execute a swap quote", "description": "Executes exactly once per Idempotency-Key, even if the call is retried.", "operationId": "executeSwap", "x-scope": "crypto:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Swap" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Blockchain addresses & withdrawals" ] } }, "/trading/orders": { "post": { "summary": "Place a trading order", "operationId": "createTradeOrder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "market", "side", "volume" ], "properties": { "market": { "type": "string", "examples": [ "usdtngn" ] }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "orderType": { "type": "string", "enum": [ "market", "limit" ], "default": "market" }, "price": { "type": "string", "examples": [ "1500.00" ], "description": "Required for limit orders." }, "volume": { "type": "string", "examples": [ "1500.00" ] } } } } } }, "x-scope": "crypto:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Order" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Blockchain addresses & withdrawals" ] }, "get": { "summary": "List trading orders", "operationId": "listTradeOrders", "x-scope": "crypto:read", "parameters": [ { "name": "market", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Blockchain addresses & withdrawals" ] } }, "/trading/orders/{id}/cancel": { "post": { "summary": "Cancel a trading order", "operationId": "cancelTradeOrder", "x-scope": "crypto:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Order" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Blockchain addresses & withdrawals" ] } }, "/rates": { "get": { "summary": "Conversion rates for any pair type", "description": "Indicative mid-market rates covering fiat/fiat, crypto/fiat and crypto/crypto for every currency we support (see GET /rates/currencies). Pass only `base` to get that base against every supported currency. Up to 250 pairs per call. Pairs we cannot price are left out rather than returned as zero; an invalid code returns VALIDATION_ERROR.\n\nExample — every supported currency against NGN:\n\n```\ncurl https://business.boundlesspay.com/api/public/v1/rates?base=NGN \\\n -H \"Authorization: Bearer :\"\n```\n\nFirm, tradeable pricing comes from POST /quotes or POST /transfers/quote.", "operationId": "listRates", "x-scope": "rates:read", "parameters": [ { "name": "base", "in": "query", "schema": { "type": "string" }, "example": "NGN" }, { "name": "quote", "in": "query", "description": "Comma-separated quote currencies to price against the base.", "schema": { "type": "string" }, "example": "USD,GBP,USDT" }, { "name": "pairs", "in": "query", "description": "Comma-separated BASE/QUOTE pairs. Overrides base and quote.", "schema": { "type": "string" }, "example": "USD/NGN,USDT/USDC" } ], "responses": { "200": { "description": "Rate list", "content": { "application/json": { "examples": { "every_currency": { "summary": "Every supported currency for one base: GET /rates?base=NGN (call GET /rates/currencies for the full list)", "value": { "object": "list", "data": [ { "object": "rate", "pair": "NGN/GBP", "base_currency": "NGN", "quote_currency": "GBP", "rate": "0.00047810", "inverse_rate": "2091.6100", "type": "fiat_fiat", "source": "BoundlessPay indicative rate feed", "as_of": "2026-08-30T11:00:00.000Z" }, { "object": "rate", "pair": "NGN/GHS", "base_currency": "NGN", "quote_currency": "GHS", "rate": "0.00985400", "inverse_rate": "101.4817", "type": "fiat_fiat", "source": "BoundlessPay indicative rate feed", "as_of": "2026-08-30T11:00:00.000Z" }, { "object": "rate", "pair": "NGN/KES", "base_currency": "NGN", "quote_currency": "KES", "rate": "0.08172000", "inverse_rate": "12.236907", "type": "fiat_fiat", "source": "BoundlessPay indicative rate feed", "as_of": "2026-08-30T11:00:00.000Z" }, { "object": "rate", "pair": "NGN/USD", "base_currency": "NGN", "quote_currency": "USD", "rate": "0.00063274", "inverse_rate": "1580.4200", "type": "fiat_fiat", "source": "BoundlessPay indicative rate feed", "as_of": "2026-08-30T11:00:00.000Z" }, { "object": "rate", "pair": "NGN/USDT", "base_currency": "NGN", "quote_currency": "USDT", "rate": "0.00063274", "inverse_rate": "1580.4200", "type": "fiat_crypto", "source": "BoundlessPay indicative rate feed", "as_of": "2026-08-30T11:00:00.000Z" } ], "next_cursor": null, "has_more": false } } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Rates" ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "every_currency": { "summary": "Every supported currency for one base: GET /rates?base=NGN (call GET /rates/currencies for the full list)", "value": { "base": "NGN" } } } } } }, "x-response-examples": { "every_currency": { "summary": "Every supported currency for one base: GET /rates?base=NGN (call GET /rates/currencies for the full list)", "value": { "object": "list", "data": [ { "object": "rate", "pair": "NGN/GBP", "base_currency": "NGN", "quote_currency": "GBP", "rate": "0.00047810", "inverse_rate": "2091.6100", "type": "fiat_fiat", "source": "BoundlessPay indicative rate feed", "as_of": "2026-08-30T11:00:00.000Z" }, { "object": "rate", "pair": "NGN/GHS", "base_currency": "NGN", "quote_currency": "GHS", "rate": "0.00985400", "inverse_rate": "101.4817", "type": "fiat_fiat", "source": "BoundlessPay indicative rate feed", "as_of": "2026-08-30T11:00:00.000Z" }, { "object": "rate", "pair": "NGN/KES", "base_currency": "NGN", "quote_currency": "KES", "rate": "0.08172000", "inverse_rate": "12.236907", "type": "fiat_fiat", "source": "BoundlessPay indicative rate feed", "as_of": "2026-08-30T11:00:00.000Z" }, { "object": "rate", "pair": "NGN/USD", "base_currency": "NGN", "quote_currency": "USD", "rate": "0.00063274", "inverse_rate": "1580.4200", "type": "fiat_fiat", "source": "BoundlessPay indicative rate feed", "as_of": "2026-08-30T11:00:00.000Z" }, { "object": "rate", "pair": "NGN/USDT", "base_currency": "NGN", "quote_currency": "USDT", "rate": "0.00063274", "inverse_rate": "1580.4200", "type": "fiat_crypto", "source": "BoundlessPay indicative rate feed", "as_of": "2026-08-30T11:00:00.000Z" } ], "next_cursor": null, "has_more": false } } } } }, "/rates/currencies": { "get": { "summary": "List every currency and asset we quote", "description": "All fiat currencies (every remittance destination plus the majors) and supported stablecoins (USDT, USDC, cNGN) available in /rates and /quotes.", "operationId": "listRateCurrencies", "x-scope": "rates:read", "responses": { "200": { "description": "Currency list", "content": { "application/json": { "example": { "object": "list", "data": [ { "object": "currency", "code": "GBP", "type": "fiat" }, { "object": "currency", "code": "NGN", "type": "fiat" }, { "object": "currency", "code": "USDT", "type": "crypto" } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Rates" ] } }, "/rates/best": { "get": { "summary": "Best executable rate across all routes", "description": "Compares every eligible execution route's fresh price for the pair and returns the best rate available to you, after our margin, with the winning route attributed by its short route code. Quotes older than 60 seconds are excluded. Indicative for pricing decisions — a firm, time-boxed rate comes from POST /quotes or POST /transfers/quote. Currently supports USD/NGN and NGN/USD.", "operationId": "getBestRate", "x-scope": "rates:read", "parameters": [ { "name": "pair", "in": "query", "description": "BASE/QUOTE pair. Defaults to USD/NGN.", "schema": { "type": "string" }, "example": "USD/NGN" }, { "name": "amount", "in": "query", "description": "Amount in the base currency used to size the comparison.", "schema": { "type": "string" }, "example": "1000" } ], "responses": { "200": { "description": "Best executable rate", "content": { "application/json": { "example": { "object": "best_rate", "pair": "USD/NGN", "base_currency": "USD", "quote_currency": "NGN", "amount": "1000.00", "rate": "1578.9100", "inverse_rate": "0.00063335", "quote_amount": "1578910.00", "source": { "route": "NUV", "type": "partner_route", "quoted_at": "2026-08-30T11:00:00.000Z" }, "routes_compared": 3, "routes": [ { "object": "rate_route", "route": "NUV", "rate": "1578.9100", "behind_best_pct": "0.0000", "fresh": true, "quoted_at": "2026-08-30T11:00:00.000Z", "latency_ms": 412 }, { "object": "rate_route", "route": "QDX", "rate": "1571.2000", "behind_best_pct": "0.4883", "fresh": true, "quoted_at": "2026-08-30T11:00:00.000Z", "latency_ms": 605 } ], "indicative": true, "as_of": "2026-08-30T11:00:00.000Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Rates" ] } }, "/rates/{pair}": { "get": { "summary": "Retrieve one rate", "operationId": "getRate", "x-scope": "rates:read", "parameters": [ { "name": "pair", "in": "path", "required": true, "description": "BASE-QUOTE, for example USD-NGN or USDT-USDC.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rate", "content": { "application/json": { "example": { "object": "rate", "pair": "NGN/USD", "base_currency": "NGN", "quote_currency": "USD", "rate": "0.00063274", "inverse_rate": "1580.4200", "type": "fiat_fiat", "source": "BoundlessPay indicative rate feed", "as_of": "2026-08-30T11:00:00.000Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Rates" ] } }, "/public/rates": { "get": { "summary": "Public conversion rates (no API key)", "description": "The same indicative mid-market rates as GET /rates, callable without an API key for pricing pages and corridor comparisons. Rate-limited per caller IP. Firm, tradeable pricing comes from POST /quotes or POST /transfers/quote with a credential.", "operationId": "listPublicRates", "security": [], "x-scope": "rates:read", "x-public": true, "parameters": [ { "name": "base", "in": "query", "schema": { "type": "string" }, "example": "NGN" }, { "name": "quote", "in": "query", "description": "Comma-separated quote currencies to price against the base.", "schema": { "type": "string" }, "example": "USD,GBP,USDT" }, { "name": "pairs", "in": "query", "description": "Comma-separated BASE/QUOTE pairs. Overrides base and quote.", "schema": { "type": "string" }, "example": "USD/NGN,USDT/USDC" } ], "responses": { "200": { "description": "Rate list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Rates" ] } }, "/public/rates/{pair}": { "get": { "summary": "Retrieve one public rate (no API key)", "operationId": "getPublicRate", "security": [], "x-scope": "rates:read", "x-public": true, "parameters": [ { "name": "pair", "in": "path", "required": true, "description": "BASE-QUOTE, for example USD-NGN or USDT-USDC.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rate" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Rates" ] } }, "/refunds": { "post": { "summary": "Refund a store order", "description": "Books a full or partial refund against a paid order: your balance is debited once and the buyer payout runs on the collecting rail. Retrying with the same Idempotency-Key returns the original refund instead of debiting again.", "operationId": "createRefund", "x-scope": "refunds:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Refund", "content": { "application/json": { "examples": { "partial_crypto": { "summary": "Partial refund paid back to a wallet address", "value": { "id": "ref_9d02f8b71ac5", "object": "refund", "order_id": "ord_74b1c0e9a2", "status": "completed", "kind": "partial", "currency": "USDC", "amount": "37.33", "reason": "Partial return — one of three items", "payout_status": "processing", "payout_reference": "SFR-9D02F8B71AC5", "payout_attempts": 1, "payout_failure_reason": null, "destination": { "type": "crypto", "address": "0x8Ae2C1b7F0d94E31aA5c60b17E9C4d3f0821b7A5", "network": "BASE" }, "livemode": true, "created_at": "2026-08-30T11:22:09.771Z" } }, "full_bank": { "summary": "Full refund to a Nigerian bank account (omit amount)", "value": { "id": "ref_5c81a0d4f236", "object": "refund", "order_id": "ord_74b1c0e9a2", "status": "completed", "kind": "full", "currency": "NGN", "amount": "48500.00", "reason": "Item out of stock", "payout_status": "succeeded", "payout_reference": "SFR-5C81A0D4F236", "payout_attempts": 1, "payout_failure_reason": null, "destination": { "type": "bank", "bank_name": "Kuda", "account_number": "••••4417", "account_name": "Ada Nwosu" }, "livemode": true, "created_at": "2026-08-30T11:04:55.318Z" } }, "manual_other_currency": { "summary": "GHS refund with no destination — settled by hand", "value": { "id": "ref_2f77bc90ae13", "object": "refund", "order_id": "ord_74b1c0e9a2", "status": "completed", "kind": "partial", "currency": "GHS", "amount": "120.05", "reason": "Goodwill adjustment", "payout_status": "manual", "payout_reference": null, "payout_attempts": 0, "payout_failure_reason": null, "destination": { "type": "manual" }, "livemode": true, "created_at": "2026-08-30T11:31:40.006Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Store refunds" ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "partial_crypto": { "summary": "Partial refund paid back to a wallet address", "value": { "order_id": "ord_74b1c0e9a2", "amount": "37.33", "reason": "Partial return — one of three items", "destination": { "type": "crypto", "address": "0x8Ae2C1b7F0d94E31aA5c60b17E9C4d3f0821b7A5", "network": "BASE" } } }, "full_bank": { "summary": "Full refund to a Nigerian bank account (omit amount)", "value": { "order_id": "ord_74b1c0e9a2", "reason": "Item out of stock", "destination": { "type": "bank", "bank_code": "090267", "bank_name": "Kuda", "account_number": "2011234567", "account_name": "Ada Nwosu" } } }, "manual_other_currency": { "summary": "GHS refund with no destination — settled by hand", "value": { "order_id": "ord_11f4ba7c03", "amount": "120.05", "reason": "Goodwill adjustment" } } } } } }, "x-response-examples": { "partial_crypto": { "summary": "Partial refund paid back to a wallet address", "value": { "id": "ref_9d02f8b71ac5", "object": "refund", "order_id": "ord_74b1c0e9a2", "status": "completed", "kind": "partial", "currency": "USDC", "amount": "37.33", "reason": "Partial return — one of three items", "payout_status": "processing", "payout_reference": "SFR-9D02F8B71AC5", "payout_attempts": 1, "payout_failure_reason": null, "destination": { "type": "crypto", "address": "0x8Ae2C1b7F0d94E31aA5c60b17E9C4d3f0821b7A5", "network": "BASE" }, "livemode": true, "created_at": "2026-08-30T11:22:09.771Z" } }, "full_bank": { "summary": "Full refund to a Nigerian bank account (omit amount)", "value": { "id": "ref_5c81a0d4f236", "object": "refund", "order_id": "ord_74b1c0e9a2", "status": "completed", "kind": "full", "currency": "NGN", "amount": "48500.00", "reason": "Item out of stock", "payout_status": "succeeded", "payout_reference": "SFR-5C81A0D4F236", "payout_attempts": 1, "payout_failure_reason": null, "destination": { "type": "bank", "bank_name": "Kuda", "account_number": "••••4417", "account_name": "Ada Nwosu" }, "livemode": true, "created_at": "2026-08-30T11:04:55.318Z" } }, "manual_other_currency": { "summary": "GHS refund with no destination — settled by hand", "value": { "id": "ref_2f77bc90ae13", "object": "refund", "order_id": "ord_74b1c0e9a2", "status": "completed", "kind": "partial", "currency": "GHS", "amount": "120.05", "reason": "Goodwill adjustment", "payout_status": "manual", "payout_reference": null, "payout_attempts": 0, "payout_failure_reason": null, "destination": { "type": "manual" }, "livemode": true, "created_at": "2026-08-30T11:31:40.006Z" } } } }, "get": { "summary": "List refunds", "operationId": "listRefunds", "x-scope": "refunds:read", "parameters": [ { "name": "order_id", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Refund list", "content": { "application/json": { "example": { "object": "list", "data": [ { "id": "ref_9d02f8b71ac5", "object": "refund", "order_id": "ord_74b1c0e9a2", "status": "completed", "kind": "partial", "currency": "USDC", "amount": "37.33", "reason": "Partial return — one of three items", "payout_status": "processing", "payout_reference": "SFR-9D02F8B71AC5", "payout_attempts": 1, "payout_failure_reason": null, "destination": { "type": "crypto", "address": "0x8Ae2C1b7F0d94E31aA5c60b17E9C4d3f0821b7A5", "network": "BASE" }, "livemode": true, "created_at": "2026-08-30T11:22:09.771Z" }, { "id": "ref_5c81a0d4f236", "object": "refund", "order_id": "ord_74b1c0e9a2", "status": "completed", "kind": "full", "currency": "NGN", "amount": "48500.00", "reason": "Item out of stock", "payout_status": "succeeded", "payout_reference": "SFR-5C81A0D4F236", "payout_attempts": 1, "payout_failure_reason": null, "destination": { "type": "bank", "bank_name": "Kuda", "account_number": "••••4417", "account_name": "Ada Nwosu" }, "livemode": true, "created_at": "2026-08-30T11:04:55.318Z" }, { "id": "ref_2f77bc90ae13", "object": "refund", "order_id": "ord_74b1c0e9a2", "status": "completed", "kind": "partial", "currency": "GHS", "amount": "120.05", "reason": "Goodwill adjustment", "payout_status": "manual", "payout_reference": null, "payout_attempts": 0, "payout_failure_reason": null, "destination": { "type": "manual" }, "livemode": true, "created_at": "2026-08-30T11:31:40.006Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Store refunds" ] } }, "/refunds/{id}": { "get": { "summary": "Retrieve a refund", "operationId": "getRefund", "x-scope": "refunds:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Refund", "content": { "application/json": { "example": { "id": "ref_5c81a0d4f236", "object": "refund", "order_id": "ord_74b1c0e9a2", "status": "completed", "kind": "full", "currency": "NGN", "amount": "48500.00", "reason": "Item out of stock", "payout_status": "succeeded", "payout_reference": "SFR-5C81A0D4F236", "payout_attempts": 1, "payout_failure_reason": null, "destination": { "type": "bank", "bank_name": "Kuda", "account_number": "••••4417", "account_name": "Ada Nwosu" }, "livemode": true, "created_at": "2026-08-30T11:04:55.318Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Store refunds" ] } }, "/refunds/{id}/retry-payout": { "post": { "summary": "Retry the buyer payout for a refund", "description": "Re-sends or re-queries the payout under the refund's own rail reference. The refund itself is never re-booked and a settled payout is never sent twice.", "operationId": "retryRefundPayout", "x-scope": "refunds:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Refund", "content": { "application/json": { "example": { "id": "ref_9d02f8b71ac5", "object": "refund", "order_id": "ord_74b1c0e9a2", "status": "completed", "kind": "partial", "currency": "USDC", "amount": "37.33", "reason": "Partial return — one of three items", "payout_status": "succeeded", "payout_reference": "SFR-9D02F8B71AC5", "payout_attempts": 2, "payout_failure_reason": null, "destination": { "type": "crypto", "address": "0x8Ae2C1b7F0d94E31aA5c60b17E9C4d3f0821b7A5", "network": "BASE" }, "livemode": true, "created_at": "2026-08-30T11:22:09.771Z" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Store refunds" ] } }, "/payroll/payrolls": { "get": { "summary": "List payrolls", "description": "Returns every payroll programme your business runs, with currency, frequency and funding status.", "operationId": "listPayrolls", "x-scope": "payroll:read", "responses": { "200": { "description": "Payroll list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Payroll" ] } }, "/payroll/runs": { "get": { "summary": "List payroll runs", "description": "Returns payroll runs across all payrolls, newest first, with status and total per run.", "operationId": "listPayrollRuns", "x-scope": "payroll:read", "parameters": [ { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Payroll run list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Payroll" ] }, "post": { "summary": "Run a payroll", "description": "Creates and starts a payroll run for an existing payroll. The run reserves funding from your balance and dispatches payouts on the same rails the dashboard uses, so an Idempotency-Key is required: retrying with the same key returns the original run instead of paying staff twice.", "operationId": "createPayrollRun", "x-scope": "payroll:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Payroll run started" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Payroll" ] } }, "/payroll/runs/{id}": { "get": { "summary": "Retrieve a payroll run", "description": "Returns one run with its per-member payout lines (amounts, statuses, references).", "operationId": "getPayrollRun", "x-scope": "payroll:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payroll run" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Payroll" ] } }, "/payroll/runs/{id}/payslips": { "get": { "summary": "List payslips for a run", "description": "Payslip metadata for every member in the run — amounts, currencies, statuses and references. Document binaries are not served over the API.", "operationId": "listPayslips", "x-scope": "payroll:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payslip list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Payroll" ] } }, "/payroll/employees": { "get": { "summary": "List payroll employees", "description": "Returns team members on your payrolls. Filter by payroll_id for a single payroll's directory.", "operationId": "listPayrollEmployees", "x-scope": "payroll:read", "parameters": [ { "name": "payroll_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Employee list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Payroll" ] } }, "/payroll/employees/{id}": { "get": { "summary": "Retrieve a payroll employee", "operationId": "getPayrollEmployee", "x-scope": "payroll:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Employee" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Payroll" ] } }, "/financing/credit-score": { "get": { "summary": "Retrieve your credit score", "description": "Your behaviour-based business credit score (0–1,000), band, tier percentage and recent score history — the same assessment the financing dashboard shows.", "operationId": "getCreditScore", "x-scope": "financing:read", "responses": { "200": { "description": "Credit score" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Business financing" ] } }, "/financing/eligibility": { "get": { "summary": "Check financing eligibility", "description": "Eligibility gate results: limit, outstanding, pending and available credit. Read-only — advances are requested from the dashboard.", "operationId": "getFinancingEligibility", "x-scope": "financing:read", "responses": { "200": { "description": "Financing eligibility" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Business financing" ] } }, "/savings/plans": { "get": { "summary": "List savings plans", "description": "Returns your savings plans with balances, accrued interest, rates and status.", "operationId": "listSavingsPlans", "x-scope": "savings:read", "responses": { "200": { "description": "Savings plan list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Savings" ] }, "post": { "summary": "Open a savings plan", "description": "Opens a plan by moving the stated amount from your NGN balance. An Idempotency-Key is required — retrying with the same key returns the original plan instead of moving money twice. Test keys simulate the same lifecycle without touching balances.", "operationId": "createSavingsPlan", "x-scope": "savings:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Savings plan" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Savings" ] } }, "/savings/plans/{id}": { "get": { "summary": "Retrieve a savings plan", "description": "Returns one plan with its transaction timeline.", "operationId": "getSavingsPlan", "x-scope": "savings:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Savings plan" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Savings" ] } }, "/savings/rates": { "get": { "summary": "Current savings rates", "description": "Annual rates per plan type, as currently configured.", "operationId": "getSavingsRates", "x-scope": "savings:read", "responses": { "200": { "description": "Savings rates" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Savings" ] } }, "/inventory/stores": { "get": { "summary": "List stores", "description": "Stores (App Studio commerce sites) whose products share your business inventory. Use a store id when creating products.", "operationId": "listInventoryStores", "x-scope": "inventory:read", "responses": { "200": { "description": "Store list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Inventory & products" ] } }, "/inventory/reviews": { "get": { "summary": "List product reviews", "description": "Reviews left by verified buyers of paid orders on your stores, newest first. Includes reviews you have hidden (see `status`) and your replies. Reviewers appear by display name only; no order, email or phone details are returned. Photo links expire after one hour. Use `since` to poll for new reviews.", "operationId": "listInventoryReviews", "x-scope": "inventory:read", "parameters": [ { "name": "store_id", "in": "query", "schema": { "type": "string" } }, { "name": "product_id", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "visible", "hidden" ] } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Review list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Inventory & products" ] } }, "/inventory/products": { "get": { "summary": "List products and stock", "description": "Products across all stores, or one store, with price, SKU and live stock count. Stock already reflects paid online orders and in-store sales. Use `low_stock=true` to return only tracked products at or below their low-stock threshold.", "operationId": "listInventoryProducts", "x-scope": "inventory:read", "parameters": [ { "name": "store_id", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "hidden" ] } }, { "name": "low_stock", "in": "query", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Product list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Inventory & products" ] }, "post": { "summary": "Create a product", "description": "Creates a product in a store. Leave `sku` empty to have a unique SKU generated. Prices are decimal numbers in major units (for example 2500.00 naira). New products are hidden unless you send `status: active`. An Idempotency-Key is required.", "operationId": "createInventoryProduct", "x-scope": "inventory:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "name", "price" ], "properties": { "store_id": { "type": "string" }, "name": { "type": "string", "maxLength": 140 }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "sku": { "type": "string", "nullable": true }, "price": { "type": "number", "minimum": 0 }, "compare_at_price": { "type": "number", "nullable": true }, "currency": { "type": "string", "example": "NGN" }, "quantity": { "type": "integer", "minimum": 0 }, "track_inventory": { "type": "boolean", "default": true }, "low_stock_threshold": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "active", "hidden", "archived" ] }, "images": { "type": "array", "maxItems": 8, "items": { "type": "string", "format": "uri" } } } } } } }, "responses": { "201": { "description": "Product" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Inventory & products" ] } }, "/inventory/products/{id}": { "get": { "summary": "Retrieve a product", "operationId": "getInventoryProduct", "x-scope": "inventory:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Inventory & products" ] }, "patch": { "summary": "Update a product", "description": "Updates catalogue fields. Omitted fields stay as they are. Stock cannot be changed here — use the stock endpoint so concurrent sales are never overwritten.", "operationId": "updateInventoryProduct", "x-scope": "inventory:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "sku": { "type": "string", "nullable": true }, "price": { "type": "number" }, "compare_at_price": { "type": "number", "nullable": true }, "track_inventory": { "type": "boolean" }, "low_stock_threshold": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "hidden", "archived" ] }, "images": { "type": "array", "items": { "type": "string", "format": "uri" } } } } } } }, "responses": { "200": { "description": "Product" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Inventory & products" ] } }, "/inventory/products/{id}/stock": { "post": { "summary": "Set stock count", "description": "Sets the absolute stock count. Send `expected_quantity` with the count you last read: if a sale changed it in the meantime the request is refused with `STOCK_CONFLICT` (409), so re-read and retry. An Idempotency-Key is required.", "operationId": "setInventoryStock", "x-scope": "inventory:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quantity" ], "properties": { "quantity": { "type": "integer", "minimum": 0 }, "expected_quantity": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Product" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Inventory & products" ] } }, "/merchant/terminals": { "get": { "summary": "List POS terminals", "description": "Your terminal fleet with labels, serial numbers and live status.", "operationId": "listMerchantTerminals", "x-scope": "merchant:read", "responses": { "200": { "description": "Terminal list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Merchant Hub" ] } }, "/merchant/terminals/{id}": { "get": { "summary": "Retrieve a POS terminal", "operationId": "getMerchantTerminal", "x-scope": "merchant:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Terminal" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Merchant Hub" ] } }, "/merchant/transactions": { "get": { "summary": "List merchant transactions", "description": "Merchant payment requests and collections across your terminals, filterable by status.", "operationId": "listMerchantTransactions", "x-scope": "merchant:read", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Transaction list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Merchant Hub" ] } }, "/merchant/disputes": { "get": { "summary": "List merchant disputes", "description": "Chargebacks and customer disputes with reason codes, priorities and respond-by deadlines.", "operationId": "listMerchantDisputes", "x-scope": "merchant:read", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Dispute list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Merchant Hub" ] } }, "/merchant/disputes/{id}": { "get": { "summary": "Retrieve a merchant dispute", "operationId": "getMerchantDispute", "x-scope": "merchant:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dispute" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Merchant Hub" ] } }, "/merchant/settlements": { "get": { "summary": "List merchant settlements", "description": "Settlement history: gross amount, fees and net credited, with settlement status.", "operationId": "listMerchantSettlements", "x-scope": "merchant:read", "parameters": [ { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Settlement list" }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "INVALID_CREDENTIALS", "CREDENTIAL_EXPIRED", "IP_NOT_ALLOWED", "SIGNATURE_INVALID", "REPLAY_DETECTED", "FORBIDDEN_SCOPE", "PRODUCT_NOT_ENABLED", "ENVIRONMENT_MISMATCH", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENT_REQUEST_IN_PROGRESS", "VALIDATION_ERROR", "NOT_FOUND", "INSUFFICIENT_BALANCE", "QUOTE_EXPIRED", "COMPLIANCE_BLOCKED", "NO_PROVIDER_ENABLED", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR", "STOCK_CONFLICT" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ] } } } } }, "tags": [ "Merchant Hub" ] } } }, "x-webhook-events": [ "customer.verification.verified", "customer.verification.rejected", "customer.verification.under_review", "customer.verification.failed", "virtual_account.created", "virtual_account.activated", "virtual_account.frozen", "virtual_account.closed", "checkout_session.created", "checkout_session.pending", "checkout_session.partially_paid", "checkout_session.paid", "checkout_session.underpaid", "checkout_session.overpaid", "checkout_session.expired", "checkout_session.cancelled", "deposit.detected", "deposit.completed", "deposit.failed", "deposit.reversed", "conversion_quote.created", "conversion_quote.expired", "conversion.processing", "conversion.completed", "conversion.failed", "conversion.reversed", "transfer.created", "transfer.requires_action", "transfer.processing", "transfer.completed", "transfer.failed", "transfer.cancelled", "transfer.reversed", "card.created", "card.activated", "card.frozen", "card.unfrozen", "card.terminated", "card.replaced", "card.authorisation.approved", "card.authorisation.declined", "card.authorisation.reversed", "card.transaction.completed", "card.transaction.refunded", "card.transaction.reversed", "physical_card.production_started", "physical_card.dispatched", "physical_card.delivered", "physical_card.delivery_failed", "otc.swap.quoted", "otc.swap.completed", "otc.swap.failed", "otc.order.opened", "otc.order.partially_filled", "otc.order.filled", "otc.order.cancelled", "otc.order.expired", "otc.trade.matched", "otc.trade.settled", "otc.trade.settlement_failed", "digital_service.purchase.processing", "digital_service.purchase.completed", "digital_service.purchase.failed", "digital_service.batch.completed", "flight.booking.ticketed", "flight.booking.failed", "payroll_run.processing", "payroll_run.completed", "payroll_run.failed", "savings_plan.opened", "savings_plan.closed", "merchant_dispute.created", "merchant_dispute.resolved" ], "tags": [ { "name": "Balances & transactions" }, { "name": "Bank payouts" }, { "name": "Blockchain addresses & withdrawals" }, { "name": "Business financing" }, { "name": "Cards" }, { "name": "Checkout page" }, { "name": "Conversions & swaps" }, { "name": "Customers" }, { "name": "Flights & Travel" }, { "name": "Global Digital Services" }, { "name": "Identity verification (KYC)" }, { "name": "Inventory & products" }, { "name": "Merchant Hub" }, { "name": "OTC trading" }, { "name": "Payroll" }, { "name": "Rates" }, { "name": "Remittance & transfers" }, { "name": "Savings" }, { "name": "Store refunds" }, { "name": "Virtual accounts service" }, { "name": "Webhooks" } ] }