Payouts API Reference

Complete REST API for the Payouts Orchestration Platform. Authenticate with an API key or OAuth token, then access payouts, accounts, FX, KYC, cards, webhooks, and more across 100+ payment rails and 190+ countries. Interactive Try-It and downloadable OpenAPI spec included.

Endpoint groups

Authentication

  • POST /v1/auth/register — Register a new client account

    Create a new client account. Returns access token, refresh token, and auto-generated API key.

  • POST /v1/auth/login — Authenticate with email and password

    Authenticate with email and password. Returns JWT access and refresh tokens.

  • POST /v1/auth/refresh — Refresh access token

    Exchange a refresh token for a new access token. Implements token rotation with reuse detection.

  • POST /v1/auth/logout — Invalidate a refresh token

    Invalidate a refresh token to end the session.

  • POST /v1/auth/forgot-password — Request a password reset email

    Request a password reset email.

  • POST /v1/auth/reset-password — Reset password using a token

    Reset password using a token from the reset email.

  • GET /v1/auth/verify-email — Verify email address

    Verify a client user's email address using the token sent to their inbox during registration. On success, the user's API keys are activated and payment account provisioning begins.

  • POST /v1/auth/generate-verification-token — Generate email verification token

    Generate a verification token and link for a portal user belonging to the authenticated client. Returns the raw token and a ready-to-use verification URL. The client can deliver this link to the user through their own channels instead of relying on the platform's built-in email. Requires API key authentication. **Required scope:** `write`

  • POST /v1/auth/resend-verification — Resend verification email

    Resend the email verification link. Rate-limited to 3 requests per email per hour. Response is intentionally vague to prevent email enumeration.

Account

  • GET /v1/me — Get authenticated client profile

    Get the authenticated client's profile information. **Required scope:** `read`

  • GET /v1/balance — Get account balance

    Get account balance across all currencies. **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/fees — Get fee configuration

    Get fee configuration for your account. Priority: provider+client > provider-only > client-only > global. **Required scope:** `read`

  • GET /v1/routing-rules — Get routing rules

    Get routing rules that determine which provider handles each payout method. **Required scope:** `read`

  • GET /v1/ledger — Get platform ledger entries

    Get platform ledger entries for your account. **Required scope:** `read` **Requires active KYC verification.**

Transactions

  • GET /v1/transactions — List all transactions

    List all transactions for your account. **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/transactions/{id} — Get transaction details

    Get details for a specific transaction. **Required scope:** `read` **Requires active KYC verification.**

Payouts

  • GET /v1/payouts — List all payouts

    List all payouts with status, amounts, and timestamps. **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/payouts/{id} — Get payout details

    Get full payout details including provider response and fee breakdown. **Required scope:** `read` **Requires active KYC verification.**

  • POST /v1/payouts/{id}/cancel — Cancel a pending payout

    Cancel a pending payout before it settles. If the payout is in scheduling_status=SCHEDULED, this also cancels any locked Airwallex conversion. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/scheduled — List scheduled future-dated payouts

    List scheduled payouts for the authenticated client. Filter by scheduling_status (SCHEDULED, EXECUTING, CANCELLED, EXECUTED, FAILED). **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/payouts/scheduled/{id} — Get a scheduled payout

    Get details of a single scheduled payout including scheduled_for, fx_mode, fx_lock details, and status. **Required scope:** `read` **Requires active KYC verification.**

  • PATCH /v1/payouts/scheduled/{id} — Reschedule a scheduled payout

    Move a scheduled payout to a new future time. If fx_mode=lock was used and provider is Airwallex, cancels the existing conversion and books a fresh conversion at the new date (falls back to float on lock failure). Only valid while scheduling_status=SCHEDULED. **Required scope:** `payouts` **Requires active KYC verification.**

  • PATCH /v1/payouts/{id}/schedule — Reschedule a scheduled payout (spec path)

    Per task #93: PATCH /v1/payouts/{id}/schedule — move a scheduled payout to a new future time. If fx_mode=lock and provider is Airwallex, cancels the existing conversion and books a fresh conversion at the new date. Only valid while scheduling_status=SCHEDULED. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/scheduled/{id}/cancel — Cancel a scheduled payout

    Cancel a scheduled payout before execution. Atomically transitions scheduling_status SCHEDULED -> CANCELLED. Best-effort cancels any locked Airwallex conversion. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/quote — Get payout cost quote

    Returns the actual cost of a payout before execution. Calls the provider API to get real fees, then adds platform fees to show the total amount that will be debited. Use this to display the true cost before the user confirms. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/preflight — Pre-flight payout validation

    Validates the payout pipeline without executing: routing resolution, beneficiary compatibility, transfer method match, velocity limits, and fee calculation. Returns structured pass/fail checks with actionable fix guidance. Call this before POST /v1/payouts/{method} to catch common errors before they create failed transactions. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/validate — Validate payout data without executing

    Validate payout data without executing. Body is forwarded to the upstream transfer validation engine. Returns validation errors if any. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/confirmation-letter — Generate PDF confirmation letter

    Generate a PDF confirmation letter for a completed payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/methods — Discover available payout methods

    Returns only the payout methods enabled for your account, with endpoint URLs, supported currencies/countries, provider count, and required fields. Use ?include_unavailable=true to see all methods including disabled ones. **Required scope:** `payouts`

  • POST /v1/payouts/local — Execute Local Transfer payout

    Dedicated endpoint for Local Transfer payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/local/quote — Quote Local Transfer payout cost

    Get pre-execution cost breakdown for a Local Transfer payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/local/schema — Get Local Transfer schema

    Get the request schema and field types for Local Transfer payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/wire — Execute Wire Transfer payout

    Dedicated endpoint for Wire Transfer payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/wire/quote — Quote Wire Transfer payout cost

    Get pre-execution cost breakdown for a Wire Transfer payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/wire/schema — Get Wire Transfer schema

    Get the request schema and field types for Wire Transfer payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/crypto — Execute Crypto payout

    Dedicated endpoint for Crypto payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/crypto/quote — Quote Crypto payout cost

    Get pre-execution cost breakdown for a Crypto payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/crypto/schema — Get Crypto schema

    Get the request schema and field types for Crypto payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/stablecoin — Execute Stablecoin payout

    Dedicated endpoint for Stablecoin payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/stablecoin/quote — Quote Stablecoin payout cost

    Get pre-execution cost breakdown for a Stablecoin payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/stablecoin/schema — Get Stablecoin schema

    Get the request schema and field types for Stablecoin payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/push-to-card — Execute Push to Card payout

    Dedicated endpoint for Push to Card payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/push-to-card/quote — Quote Push to Card payout cost

    Get pre-execution cost breakdown for a Push to Card payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/push-to-card/schema — Get Push to Card schema

    Get the request schema and field types for Push to Card payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/paypal — Execute PayPal payout

    Dedicated endpoint for PayPal payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/paypal/quote — Quote PayPal payout cost

    Get pre-execution cost breakdown for a PayPal payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/paypal/schema — Get PayPal schema

    Get the request schema and field types for PayPal payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/venmo — Execute Venmo payout

    Dedicated endpoint for Venmo payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/venmo/quote — Quote Venmo payout cost

    Get pre-execution cost breakdown for a Venmo payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/venmo/schema — Get Venmo schema

    Get the request schema and field types for Venmo payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/gift-card — Execute Gift Card payout

    Dedicated endpoint for Gift Card payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/gift-card/quote — Quote Gift Card payout cost

    Get pre-execution cost breakdown for a Gift Card payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/gift-card/schema — Get Gift Card schema

    Get the request schema and field types for Gift Card payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/check — Execute Check payout

    Dedicated endpoint for Check payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/check/quote — Quote Check payout cost

    Get pre-execution cost breakdown for a Check payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/check/schema — Get Check schema

    Get the request schema and field types for Check payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/prepaid-card — Execute Prepaid Card payout

    Dedicated endpoint for Prepaid Card payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/prepaid-card/quote — Quote Prepaid Card payout cost

    Get pre-execution cost breakdown for a Prepaid Card payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/prepaid-card/schema — Get Prepaid Card schema

    Get the request schema and field types for Prepaid Card payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/reloadable-card — Execute Reloadable Card payout

    Dedicated endpoint for Reloadable Card payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/reloadable-card/quote — Quote Reloadable Card payout cost

    Get pre-execution cost breakdown for a Reloadable Card payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/reloadable-card/schema — Get Reloadable Card schema

    Get the request schema and field types for Reloadable Card payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/liquidation — Execute Liquidation payout

    Dedicated endpoint for Liquidation payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/liquidation/quote — Quote Liquidation payout cost

    Get pre-execution cost breakdown for a Liquidation payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/liquidation/schema — Get Liquidation schema

    Get the request schema and field types for Liquidation payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/pix — Execute PIX Transfer payout

    Dedicated endpoint for PIX Transfer payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/pix/quote — Quote PIX Transfer payout cost

    Get pre-execution cost breakdown for a PIX Transfer payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/pix/schema — Get PIX Transfer schema

    Get the request schema and field types for PIX Transfer payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/faster-payments — Execute Faster Payments payout

    Dedicated endpoint for Faster Payments payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/faster-payments/quote — Quote Faster Payments payout cost

    Get pre-execution cost breakdown for a Faster Payments payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/faster-payments/schema — Get Faster Payments schema

    Get the request schema and field types for Faster Payments payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

  • POST /v1/payouts/digital-check — Execute Digital Check payout

    Dedicated endpoint for Digital Check payouts with type-safe schema. Internally routes via the capability system. **Required scope:** `payouts` **Requires active KYC verification.**

  • POST /v1/payouts/digital-check/quote — Quote Digital Check payout cost

    Get pre-execution cost breakdown for a Digital Check payout. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/digital-check/schema — Get Digital Check schema

    Get the request schema and field types for Digital Check payouts. When country and currency query params are provided, includes routing resolution and dynamic provider-derived beneficiary field schema. **Required scope:** `payouts`

Beneficiaries

  • POST /v1/beneficiaries — Create a new beneficiary

    Create a new beneficiary using the schema from GET /v1/payouts/{method}/schema. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/beneficiaries — List all beneficiaries

    List all beneficiaries for your account. **Required scope:** `read` **Requires active KYC verification.**

Collection Accounts

  • GET /v1/collection-accounts — List all collection accounts

    List all collection and global accounts. Global accounts (virtual bank accounts for receiving funds) are included with full bank details, routing codes, and live status from Airwallex. Items with accountType 'global_account' include a globalAccount object with account number, IBAN, SWIFT code, routing numbers, and supported payment/payout methods. **Required scope:** `read` **Requires active KYC verification.**

  • POST /v1/collection-accounts — Create a new collection account

    Create a new collection account. Supports capability-based routing (recommended) or legacy provider-based routing. Collection capabilities: bank_account, crypto_wallet, virtual_account, liquidation_address. **Required scope:** `write` **Requires active KYC verification.**

  • GET /v1/collection-accounts/{id} — Get collection account details

    Get collection account details including bank details. **Required scope:** `read` **Requires active KYC verification.**

  • POST /v1/collection-accounts/{id}/close — Close a collection account

    Close a collection account. **Required scope:** `write` **Requires active KYC verification.**

  • POST /v1/collection-accounts/{id}/update — Update collection account settings

    Update collection account settings. **Required scope:** `write` **Requires active KYC verification.**

  • GET /v1/collection-accounts/{id}/transactions — List transactions for a collection account

    List transactions (deposits) for a specific collection account. Each transaction includes a `financialTransactionId` field that can be used with `POST /v1/deposits/confirmation-letter` to generate a PDF confirmation letter. **Required scope:** `read` **Requires active KYC verification.**

  • POST /v1/collection-accounts/statement — Generate PDF account statement

    Generate a PDF account statement. Returns the PDF file directly. **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/collection-accounts/{id}/mandates — List direct debit mandates

    List direct debit mandates for a collection account. **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/collection-accounts/{id}/mandates/{mandateId} — Get mandate details

    Get details for a specific mandate. **Required scope:** `read` **Requires active KYC verification.**

  • POST /v1/collection-accounts/{id}/mandates/{mandateId}/cancel — Cancel a direct debit mandate

    Cancel a direct debit mandate. **Required scope:** `write` **Requires active KYC verification.**

  • POST /v1/deposits/confirmation-letter — Generate PDF confirmation letter for a deposit

    Generate a PDF confirmation letter for an incoming deposit into a collection (global) account. Pass the financial transaction ID from the collection account transactions list. **Required scope:** `read` **Requires active KYC verification.**

FX (Foreign Exchange)

  • POST /v1/payouts/fx/conversions — Create an FX conversion

    Create an FX conversion between two currencies. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/payouts/fx/conversions — List all FX conversions

    List all FX conversions. **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/payouts/fx/conversions/{conversionId} — Get FX conversion details

    Get FX conversion details. **Required scope:** `read` **Requires active KYC verification.**

  • POST /v1/payouts/fx/quotes — Get an FX quote

    Get an FX quote without executing. **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/payouts/fx/quotes/{quoteId} — Get FX quote details

    Get details for a specific FX quote. **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/payouts/fx/rates — Get current live FX rates

    Get current live FX rates. Query params: buy_currency, sell_currency (ISO 3-letter codes). **Required scope:** `read` **Requires active KYC verification.**

KYC Verification

  • GET /v1/kyc/status — Get KYC verification status

    Get KYC verification status for your account. **Required scope:** `read`

  • POST /v1/kyc/authorize — Generate KYC authorization code

    Generate an authorization code for the KYC onboarding SDK. **Required scope:** `*`

  • POST /v1/kyc/authorize-rfi — Generate RFI authorization code

    Generate an auth code for uploading additional documents (RFI). **Required scope:** `*`

  • GET /v1/kyc/rfis — List requests for information

    List requests for information (additional docs needed). **Required scope:** `read`

KYC Embed

  • GET /kyc/embed-token — Generate embed token and URL

    Generate a time-limited embed token and embed URL. Pass your API key via x-api-key header or apiKey query param. Token expires in 10 minutes. **Required scope:** `*`

  • GET /kyc/embed — Hosted KYC verification page

    The hosted KYC verification page. Load this URL in an iframe using the token from /kyc/embed-token. Handles the full onboarding flow automatically. **Required scope:** `*`

  • GET /kyc/embed/status — Check KYC status via embed token

    Check KYC status using an embed token. Pass token as query parameter. **Required scope:** `*`

  • POST /kyc/embed/authorize — Generate auth code within embed context

    Generate auth code for the KYC SDK within the embed context. Used internally by the embed page. **Required scope:** `*`

  • POST /kyc/embed/authorize-rfi — Generate RFI auth code within embed context

    Generate auth code for RFI document uploads within the embed context. **Required scope:** `*`

Webhooks

  • POST /v1/webhooks — Register a new webhook endpoint

    Register a new webhook endpoint. A signing secret is auto-generated and returned. **Required scope:** `webhooks`

  • GET /v1/webhooks — List all registered webhooks

    List all registered webhooks. **Required scope:** `read`

  • GET /v1/webhooks/{id} — Get webhook details

    Get webhook details. **Required scope:** `read`

  • PATCH /v1/webhooks/{id} — Update a webhook

    Update a webhook URL, events, status, or description. **Required scope:** `webhooks`

  • DELETE /v1/webhooks/{id} — Delete a webhook

    Delete a webhook. **Required scope:** `webhooks`

  • GET /v1/webhooks/{id}/deliveries — List webhook delivery attempts

    List delivery attempts with status and response codes. **Required scope:** `read`

  • POST /v1/webhooks/{id}/test — Send a test webhook event

    Send a test webhook event to verify your endpoint. **Required scope:** `webhooks`

API Keys

  • POST /v1/api-keys — Generate a new API key

    Generate a new API key with specified scopes. Set `enableHmac: true` to enable HMAC request signing for this key. The HMAC secret is returned once in the response and cannot be retrieved again. **Required scope:** `*`

  • GET /v1/api-keys — List all API keys

    List all API keys (key values are masked). **Required scope:** `read`

  • PATCH /v1/api-keys/{id}/revoke — Revoke an API key

    Revoke an API key. Cannot be undone. **Required scope:** `*`

  • DELETE /v1/api-keys/{id} — Permanently delete an API key

    Permanently delete an API key. **Required scope:** `*`

  • POST /v1/api-keys/{id}/hmac/rotate — Rotate HMAC secret

    Generate a new HMAC secret for an API key. The previous secret is immediately invalidated. The new secret is returned once and cannot be retrieved again. If the key did not previously have HMAC enabled, this effectively enables it. **Required scope:** `*`

  • DELETE /v1/api-keys/{id}/hmac — Disable HMAC signing

    Disable HMAC request signing for an API key. After this, requests with this key will no longer require a signature. **Required scope:** `*`

Settings

  • GET /v1/settings/allowed-origins — List allowed CORS origins

    List all allowed CORS origins for your account. Origins are used for JWT-authenticated browser requests. **Required scope:** `read`

  • POST /v1/settings/allowed-origins — Add an allowed CORS origin

    Add an allowed CORS origin for JWT-authenticated browser requests. Origin must include scheme (https://). **Required scope:** `*`

  • DELETE /v1/settings/allowed-origins — Remove an allowed CORS origin

    Remove an allowed CORS origin from your account. **Required scope:** `*`

Financial Reports

  • GET /v1/reports/types — List available report types

    Returns all supported financial report types with their allowed formats, required fields, and optional filters. **Required scope:** `read`

  • GET /v1/reports — List financial reports

    Get a list of previously generated financial reports including balance activity, transaction reconciliation, settlement, account statement, and aggregated settlement reports. **Required scope:** `read` **Requires active KYC verification.**

  • POST /v1/reports — Create a financial report

    Generate a new financial report. Supported types: ACCOUNT_STATEMENT_REPORT (PDF only, currencies required), BALANCE_ACTIVITY_REPORT (CSV/EXCEL/PDF), TRANSACTION_RECON_REPORT (CSV/EXCEL), ONLINE_PAYMENTS_TRANSACTION_REPORT (EXCEL only), SETTLEMENT_REPORT (CSV/EXCEL). Reports are generated asynchronously -- poll GET /v1/reports/{reportId} until status is COMPLETED, then download. **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/reports/{reportId} — Get financial report by ID

    Retrieve the metadata and status of a specific financial report. Poll this endpoint until status is COMPLETED before downloading. **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/reports/{reportId}/download — Download financial report contents

    Download the contents of a completed financial report. Returns the file in the format specified during creation (CSV, EXCEL, or PDF). Report must have status COMPLETED. **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/balances — Get current balances

    Get available and pending balances for every currency in the account. Optionally filter by account type (cash, yield, credit). **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/balances/history — Get balance history

    Get balance change history for the account. Each record represents a change to the balance. Date range should be within 7 days when paginating with page_num. **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/financial-transactions — List financial transactions

    Get a list of financial transactions that contributed to the account balance. Supports filtering by date range, currency, status, source ID, and batch ID. **Required scope:** `read` **Requires active KYC verification.**

  • GET /v1/global-accounts/{globalAccountId}/transactions — Get global account transactions

    Retrieve transaction details of funds received into a specific global account. **Required scope:** `read` **Requires active KYC verification.**

Cards

  • POST /v1/cards/issue — Issue a card and register its policy

    Provision a new BlueBanc card (or register a pre-issued cardProxy with provision:false) and store its cardControls policy. Policy is enforced on every authorization in real time. Fails closed: if upstream provisioning fails, no record is persisted. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/cards/{cardProxy}/policy — Get card policy

    Retrieve the currently active cardControls policy for a card owned by your account. **Required scope:** `read` **Requires active KYC verification.**

  • PUT /v1/cards/{cardProxy}/policy — Update card policy

    Replace the active cardControls policy for a card. Takes effect on the next authorization. The body is the policy JSON object directly. **Required scope:** `payouts` **Requires active KYC verification.**

  • GET /v1/cards/{cardProxy}/decisions — List card authorization decisions

    Append-only decision log for a card, including the rule that fired, sanitized auth payload, and settlement lifecycle state for approved transactions. Cursor-paginated by createdAt. **Required scope:** `read` **Requires active KYC verification.**