Changelog

This page lists all notable changes to the WorldFirst Enhanced API and its documentation, with the most recent changes first.

Versioning Policy

The WorldFirst Enhanced API uses date-based versioning (e.g.,
2026-08-08
). Our compatibility promise:
  • Backward-compatible changes ship continuously — adding new API endpoints, adding new optional request parameters, adding new response fields, adding new enum values to existing fields, and adding new webhook event types are considered backward compatible and are released without a version change. Your integration must tolerate unknown fields and unknown enum values.
  • Breaking changes always require a new dated version — removing or renaming a field, changing a field type, or making an optional parameter required will only ever appear in a new version, announced on this page in advance with a full list of affected endpoints and migration guidance.
  • Every entry on this page is machine-readable by design — changes are grouped by date, each with the affected endpoints and field-level details, so both developers and AI agents can parse this page to determine migration impact automatically.

2026-10-01 — Batch Payouts, Referral, and API Key Authentication

16 new endpoints across 3 new resources, 7 new webhook event types, and a simpler way to authenticate. This release lets you pay many beneficiaries in a single submission, gives platform partners a link-based way to onboard merchants, and introduces API Key authentication for faster integration. The API now covers 89 endpoints across 26 resources.

Highlights

  • Pay up to 100 beneficiaries in one batch. Create a batch, add items, preview indicative totals, fees, and rates per currency pair, then submit — with an optional approval step in the WorldFirst portal. Track the whole batch from a single ID and drill into any item through its
    payoutId
    .
  • Onboard merchants with invitation links. Referral links support two modes:
    CONNECTED_ONLY
    attributes multiple registrations to one link, while
    AUTHORIZED
    is a one-to-one invitation that also activates the authorization scopes the invited account grants you.
  • Integrate with an API Key. Send a Bearer API Key in the
    Authorization
    header — no request signing, no response verification, and no token exchange. Webhooks for API Key integrations are signed with HMAC-SHA256 using your Webhook Secret.
  • Generate reports on demand. Create account statement reports in CSV, XLSX, or PDF asynchronously and download them through a time-limited link.

Authentication

  • API Key authentication (Suggested). Create an API Key integration in the Developer Center, select the APIs it can access, and authenticate each request with
    Authorization: Bearer <API_KEY>
    . The
    Client-Id
    ,
    Request-Time
    , and
    Signature
    headers are not required.
  • Webhook signature verification for API Key integrations. Each notification is signed with HMAC-SHA256 using your integration's Webhook Secret. See Authentication for verification steps.
  • RSA signature authentication remains supported. Existing integrations continue to work unchanged. To switch to API Key authentication, arrange the change with WorldFirst and update both your API requests and your webhook verification before switching.
  • Code examples across the API reference now use API Key authentication.

New resources and endpoints

Payouts

  • Batch Payouts — group up to 100 payouts into a single batch for payroll runs, supplier settlements, marketplace payouts, and other bulk disbursements. Add up to 10 items per request, and cancel a batch while it is in
    INIT
    or
    PENDING_APPROVAL
    .
    • POST /api/open/v1/batchPayouts/create
      — Create a Batch Payout
    • POST /api/open/v1/batchPayouts/addItems
      — Add Items to a Batch Payout
    • POST /api/open/v1/batchPayouts/removeItems
      — Remove Items from a Batch Payout
    • POST /api/open/v1/batchPayouts/listItems
      — List Batch Payout Items
    • POST /api/open/v1/batchPayouts/calculate
      — Calculate a Batch Payout
    • POST /api/open/v1/batchPayouts/submit
      — Submit a Batch Payout
    • POST /api/open/v1/batchPayouts/query
      — Query a Batch Payout
    • POST /api/open/v1/batchPayouts/delete
      — Delete a Batch Payout
    • POST /api/open/v1/batchPayouts/cancel
      — Cancel a Batch Payout
  • Payouts — retrieve single and batch payout transactions in one list, filtered by transaction type, status, and creation time (up to 100 days).
    • POST /api/open/v1/payouts/list
      — List Payouts

Connected

  • Referral — create invitation links to onboard and connect other WorldFirst accounts, and track each link's status and attributions. Available to approved partners only.
    • POST /api/open/v1/referrals/create
      — Create a Referral
    • POST /api/open/v1/referrals/query
      — Query a Referral
  • Connected Accounts — close connected accounts via API to complete the account lifecycle. Closing is synchronous; accounts with outstanding obligations or a non-zero balance cannot be closed.
    • POST /api/open/v1/accounts/close
      — Close a Connected Account

Reporting

  • Download Report — create, track, and list downloadable account statement reports in CSV, XLSX, or PDF.
    • POST /api/open/v1/reports/create
      — Create a Report
    • POST /api/open/v1/reports/query
      — Query a Report
    • POST /api/open/v1/reports/list
      — List Reports

New webhook events

7 event types ship in this release:
  • Batch Payouts —
    batchPayouts.APPROVED
    ,
    batchPayouts.REJECTED
    ,
    batchPayouts.COMPLETED
    ,
    batchPayouts.CANCELLED
  • Connected Accounts —
    connectedAccounts.SUBMITTED
  • Reports —
    reports.SUCCESS
    ,
    reports.FAILED

2026-09-01 — Card Issuing, Charges, Agreements, and RFIs

26 new endpoints across 8 new resources, plus 18 new webhook event types. This release introduces Issuing as a new product line — fund budgets, issue virtual and physical cards, and track every card transaction via API — and adds partner and compliance capabilities: collecting charges, managing merchant authorizations, and responding to information requests.

Highlights

  • Issue and control cards end-to-end. Register cardholders, issue virtual or physical cards with transaction limits and authorization controls, freeze or update cards, and retrieve sensitive card data (full card number, CVV) on demand.
  • Budget-controlled spending. Allocate funds to dedicated budget accounts, top up or withdraw at any time, and monitor multi-currency balances and daily fund flows.
  • 3DS OTP via API. Choose to receive 3DS one-time password notifications via API and build the verification experience into your own product.
  • Collect fees from connected merchants. Charges let platform partners debit platform fees, subscription fees, and adjustments from a merchant's WorldFirst balance.
  • Act on behalf of merchants with explicit authorization. Agreements record a merchant's authorization for specific business scenarios — such as collection, payout, withdrawal, and transfer — and can be cancelled when no longer needed.
  • Resolve compliance reviews via API. List RFIs, retrieve their questions, and submit text or file answers — including on behalf of connected accounts — so onboarding and due-diligence reviews keep moving.

New resources and endpoints

Issuing

  • Budget — allocate and control funds for card spending, with multi-currency balances and daily fund flows.
    • POST /api/open/v1/issuing/budgets/create
      — Create a Budget
    • POST /api/open/v1/issuing/budgets/query
      — Query a Budget
    • POST /api/open/v1/issuing/budgets/list
      — List Budgets
    • POST /api/open/v1/issuing/budgets/deposit
      — Deposit to a Budget
    • POST /api/open/v1/issuing/budgets/withdraw
      — Withdraw from a Budget
    • POST /api/open/v1/issuing/budgets/listDailyBalance
      — List Daily Balances
  • Cardholders — register cardholders with identity documents for KYC review. A cardholder must be
    ACTIVE
    before cards can be issued.
    • POST /api/open/v1/issuing/cardholders/create
      — Create a Cardholder
    • POST /api/open/v1/issuing/cardholders/query
      — Query a Cardholder
    • POST /api/open/v1/issuing/cardholders/list
      — List Cardholders
    • POST /api/open/v1/issuing/cardholders/delete
      — Delete a Cardholder
  • Cards Management — issue virtual or physical cards with transaction limits and authorization controls, and manage their status and configuration.
    • POST /api/open/v1/issuing/cards/create
      — Create a Card
    • POST /api/open/v1/issuing/cards/query
      — Query a Card
    • POST /api/open/v1/issuing/cards/list
      — List Cards
    • POST /api/open/v1/issuing/cards/querySensitiveInfo
      — Query Card Sensitive Info
    • POST /api/open/v1/issuing/cards/update
      — Update a Card
  • Transactions — query card payments and refunds with amounts, merchant details, and payer information.
    • POST /api/open/v1/issuing/transactions/list
      — List Card Transactions
  • OTP Management — control whether 3DS OTP notifications are delivered via API.
    • POST /api/open/v1/issuing/cards/queryOtpConfig
      — Query OTP Config
    • POST /api/open/v1/issuing/cards/updateOtpConfig
      — Update OTP Config

Authorization

  • Agreements — grant and cancel a merchant's authorization for a platform partner, one business scenario at a time. Requests are idempotent by
    accountId
    +
    authBusinessScenarios
    . Available to approved partners only.
    • POST /api/open/v1/agreements/create
      — Create an Agreement
    • POST /api/open/v1/agreements/cancel
      — Cancel an Agreement

Connected

  • Charge — debit platform fees, subscription fees, adjustments, and other partner-initiated deductions from a connected merchant's balance, processed asynchronously. Available to approved partners only.
    • POST /api/open/v1/charges/create
      — Create a Charge
    • POST /api/open/v1/charges/query
      — Query a Charge
    • POST /api/open/v1/charges/list
      — List Charges

Supporting Service

  • Request for Information — receive and answer WorldFirst's compliance information requests, with optional file attachments.
    • POST /api/open/v1/rfis/list
      — List RFIs
    • POST /api/open/v1/rfis/query
      — Retrieve an RFI
    • POST /api/open/v1/rfis/respond
      — Respond to an RFI

New webhook events

18 event types ship in this release:
  • Cardholders —
    issuing.cardholders.statusChange
  • Cards —
    issuing.cards.ACTIVE
    ,
    issuing.cards.FROZEN
    ,
    issuing.cards.CANCELLED
    ,
    issuing.cards.FAILED
    ,
    issuing.cards.OTP_RECEIVED
  • Card Transactions —
    issuing.transactions.WAITING_DEDUCT
    ,
    issuing.transactions.WAITING_CLEARANCE
    ,
    issuing.transactions.SUCCESS
    ,
    issuing.transactions.FAILED
    ,
    issuing.transactions.CANCELLED
    ,
    issuing.transactions.PARTIAL_CANCELLED
    ,
    issuing.transactions.REFUNDED
    ,
    issuing.transactions.PARTIAL_REFUNDED
  • RFIs —
    rfis.ACTION_REQUIRED
    ,
    rfis.ANSWERED
    ,
    rfis.CLOSED
    ,
    rfis.EXPIRED

2026-08-01 — Initial Release

🎉 WorldFirst Enhanced API is now generally available.
This initial release delivers a complete, production-ready API suite: 47 endpoints across 15 resources, plus 25 webhook event types — covering the full cross-border money movement lifecycle: global account opening, receiving, foreign exchange, payouts, reconciliation, connected account management, and supporting services.

Built for developers

  • One consistent contract everywhere. Every response returns HTTP
    200 OK
    with a unified Result object (
    resultStatus
    S
    /
    F
    /
    U
    ,
    resultCode
    ,
    resultMessage
    ). Branch your logic on
    resultCode
    — never on message text.
  • Idempotency by default. Write operations that expose a
    requestId
    use it as an idempotency key.
  • Cursor-based pagination. All list endpoints share the same
    limit
    /
    nextCursor
    /
    prevCursor
    pattern — stable under concurrent writes, no page-drift.
  • OAuth 2.0 authorization. Standard authorization-code flow with token issuance and revocation endpoints.
  • Copy-paste-ready code examples. Every endpoint ships working examples in five languages: cURL, JavaScript (axios), Python, C# (RestSharp), and Java (Unirest).
  • Actionable error handling. Every endpoint documents its full error code table with a dedicated Troubleshooting column, telling you exactly how to resolve each failure — not just what went wrong.

Built for AI agents

The API and its documentation are engineered to be consumed by LLMs and autonomous agents as first-class citizens:
  • Deterministic, machine-parseable docs. Every endpoint page follows the identical structure — endpoint definition, Request field tree, Response field tree, JSON examples, error codes — so agents can reliably extract schemas without page-specific heuristics.
  • Strict typing and standards. Fields use standardized Data Types: ISO 3166 country/region codes, ISO 4217 currency codes, and integer amounts expressed in each currency's minor unit to avoid floating-point precision loss.
  • Closed enum vocabularies. Every enum field documents its complete value set inline with per-value semantics, enabling agents to generate valid requests and interpret responses without guesswork.
  • Programmatic error recovery. The three-state
    resultStatus
    model (
    S
    success /
    F
    failure /
    U
    unknown) gives agents an unambiguous retry contract:
    F
    is terminal,
    U
    means query before retrying.

New resources and endpoints

Accounts

  • Global Accounts — open and manage multi-currency receiving accounts with local clearing and SWIFT capabilities.
    • POST /api/open/v1/globalAccounts/create
      — Create a Global Account
    • POST /api/open/v1/globalAccounts/query
      — Query a Global Account
    • POST /api/open/v1/globalAccounts/update
      — Update a Global Account
    • POST /api/open/v1/globalAccounts/list
      — List Global Accounts
    • POST /api/open/v1/globalAccounts/close
      — Close a Global Account
  • Balance — real-time balance inquiry and full balance movement history.
    • POST /api/open/v1/balances/query
      — Query Account Balance
    • POST /api/open/v1/balances/listHistory
      — List Balance History

Authorization

  • OAuth 2.0 — standard authorization for secure, scoped API access.
    • GET /api/open/v1/oauth/authorize
      — Authorize
    • POST /api/open/v1/oauth/token
      — Request a Token
    • POST /api/open/v1/oauth/revoke
      — Revoke a Token

Receiving

  • Deposits — track incoming funds with full lifecycle status.
    • POST /api/open/v1/deposits/query
      — Query a Deposit
    • POST /api/open/v1/deposits/list
      — List Deposits

Payouts

  • Beneficiaries — dynamic, region-aware beneficiary management.
    queryTemplate
    returns the exact field requirements for any bank region, currency, and payment method combination — so you always collect the right data the first time.
    • POST /api/open/v1/beneficiaries/queryTemplate
      — Query Beneficiary Template
    • POST /api/open/v1/beneficiaries/create
      — Create a Beneficiary
    • POST /api/open/v1/beneficiaries/query
      — Query a Beneficiary
    • POST /api/open/v1/beneficiaries/list
      — List Beneficiaries
    • POST /api/open/v1/beneficiaries/update
      — Update a Beneficiary
    • POST /api/open/v1/beneficiaries/delete
      — Delete a Beneficiary
    • POST /api/open/v1/beneficiaries/validate
      — Validate a Beneficiary
  • Payouts — consult-before-create design: pre-validate fees, FX, and delivery estimates before committing funds.
    • POST /api/open/v1/payouts/consult
      — Consult a Payout
    • POST /api/open/v1/payouts/create
      — Create a Payout
    • POST /api/open/v1/payouts/query
      — Query a Payout

Foreign Exchange (FX)

  • Quote — live rates, historical rate series, and lockable quotes.
    • POST /api/open/v1/fx/rates/query
      — Query Rates
    • POST /api/open/v1/fx/rates/queryHistory
      — Query Rate History
    • POST /api/open/v1/fx/quotes/create
      — Create a Quote
  • Deal — spot and forward FX deal booking with full margin transparency.
    • POST /api/open/v1/fx/deals/create
      — Create a Deal
    • POST /api/open/v1/fx/deals/cancel
      — Cancel a Deal
    • POST /api/open/v1/fx/deals/query
      — Query a Deal
    • POST /api/open/v1/fx/deals/list
      — List Deals
    • POST /api/open/v1/fx/deals/listMarginChargeRecords
      — List Margin Charge Records
  • Settlement — settle booked FX deals in full or in part.
    • POST /api/open/v1/fx/settlements/create
      — Create a Settlement
    • POST /api/open/v1/fx/settlements/query
      — Query a Settlement
    • POST /api/open/v1/fx/settlements/list
      — List Settlements
  • Reference — programmatic access to FX reference data.
    • POST /api/open/v1/fx/references/queryCurrencies
      — Query Supported Currencies
    • POST /api/open/v1/fx/references/queryCalendar
      — Query Trading Calendar

Connected

  • Connected Accounts — platform partners can onboard merchants end-to-end via API, with full KYC/KYB status visibility.
    • POST /api/open/v1/accounts/create
      — Create a Connected Account
    • POST /api/open/v1/accounts/query
      — Query a Connected Account
    • POST /api/open/v1/accounts/list
      — List Connected Accounts

Reporting

  • Statement Report — reconciliation-grade statements covering every fund movement on your account.
    • POST /api/open/v1/statements/list
      — List Statements
    • POST /api/open/v1/statements/query
      — Query a Statement

Supporting Service

  • File Upload/Download — exchange compliance documents and attachments programmatically.
    • POST /api/open/v1/files/upload
      — Upload a File
    • POST /api/open/v1/files/download
      — Download a File
  • Trade Orders — submit B2B/B2C trade orders for authentication and build up CNY cross-border payout quota.
    • POST /api/open/v1/tradeOrders/submit
      — Submit Trade Orders
    • POST /api/open/v1/tradeOrders/query
      — Query Trade Orders
    • POST /api/open/v1/tradeOrders/queryQuota
      — Query Available Settlement Quota
  • Confirmation Letters — generate and retrieve official account confirmation letters on demand.
    • POST /api/open/v1/confirmationLetters/create
      — Create a Confirmation Letter
    • POST /api/open/v1/confirmationLetters/query
      — Query a Confirmation Letter

New webhook events

Register a notification URL and receive real-time HTTP POST events instead of polling. 25 event types across five resources ship in this release:
  • Deposits —
    deposits.PROCESSING
    ,
    deposits.SUCCESS
    ,
    deposits.PARTIAL_REFUNDED
    ,
    deposits.REFUNDED
    ,
    deposits.CANCELLED
    ,
    deposits.WAITING_CLAIM
    ,
    deposits.UNDER_CLAIM
  • Payouts —
    payouts.SUCCESS
    ,
    payouts.FAILED
    ,
    payouts.RETURNED
  • Beneficiaries —
    beneficiaries.ACTIVE
    ,
    beneficiaries.REJECTED
  • FX Deals —
    fx.deals.PROCESSING
    ,
    fx.deals.SUCCESS
    ,
    fx.deals.FAILED
    ,
    fx.deals.CANCELLED
    , plus six margin lifecycle events (
    fx.deals.MARGIN_CHARGE_*
    )
  • FX Settlements —
    fx.settlements.PROCESSING
    ,
    fx.settlements.SUCCESS
    ,
    fx.settlements.FAILED

Documentation

  • Overview, Authentication, Data Types, and Result guides published alongside the reference.
  • Every endpoint documented with Request/Response field trees, request and response JSON examples, five-language code samples, and error code tables with troubleshooting guidance.
Questions or feedback? Contact your WorldFirst account manager or our developer support team at techsupport@worldfirst.com — our team is ready to assist you.