Changelog

2026-08-13

• Customer deposit wallets accept an ownership declaration: walletType (SELF_CUSTODY or CUSTODIAL) and ownershipAttested: true, plus vaspName and optional vaspAccountRef for custodial wallets. These fields are optional today and will become required in a future release — start sending them now to avoid a breaking change later.
• When you supply walletType, ownershipAttested: true is required, and custodial wallets also require vaspName. Omitting the declaration on an update leaves any existing declaration unchanged, except when you change the wallet address: a declaration covers the address it was made about, so changing the address without supplying a new declaration clears walletType, vaspName, vaspAccountRef and ownershipAttestedAt. Send the declaration alongside the new address to keep the wallet declared.
• Wallet responses now include walletType, vaspName, vaspAccountRef and ownershipAttestedAt. They are null on wallets with no declaration on file. Existing wallets continue to receive deposits without this information.

2026-08-04

• Withdrawal bank create and list responses now include postalCode. It is null when no postal code is on file for that beneficiary yet.
• Creating a withdrawal bank now requires postalCode whenever you send an address: always for OTHER_INDIVIDUAL and OTHER_BUSINESS recipients, and for CUSTOMER recipients if you supply addressLine1 or city. Omit those fields to keep resolving the address from the customer's verified address.
• Note that country is unchanged — it is still resolved from verified data when omitted, and sending country on its own does not require a postalCode.

2026-08-01

• GET /customers/{customerId} now returns a banking object describing what that customer can transact in: supportedFiatCurrencies and whether a dedicated virtual account is available to them. Use it instead of assuming every customer in your organization supports the same currencies.

2026-07-30

• POST /customers/{customerId}/withdrawal now returns 400 when the selected withdrawal bank's currency is unavailable for your organization, instead of failing later in processing.
• POST /customers/{customerId}/virtual-account now returns customer-specific 403 wording when virtual accounts are unavailable for that customer.
• Deposit details, rate availability, and withdrawal bank availability now use the banking configuration effective for the requested customer.

2026-07-29

• POST /customers/{customerId}/virtual-account now returns 403 when virtual accounts are unavailable for your organization.
• GET /customers/{customerId}/deposit now returns 404 when EUR deposit details are unavailable for your organization, matching the existing USD behavior.

2026-07-28

• Corporate customers who request a KYC link are now directed to [email protected] to complete onboarding.

2026-07-23

• Customer deposit details: EUR/SEPA responses may reference a different receiving bank (for example PayDo EU Ltd. in Malta) depending on your organization's banking configuration. USD deposit details continue to return 404 when USD is not available for your organization.
• GET /rates: requests for a USD rate now return 400 "USD is not available for your organization" when USD is not offered for your organization.
• POST /customers/{customerId}/withdrawal/banks: now returns 400 when a withdrawal bank is created in a currency that is not available for your organization.

2026-07-13

• Withdrawal bank list and create responses now include fundingSource, indicating whether withdrawals are expected to use a customer virtual account or the Compose shared account.

2026-07-09

• USD FedWire deposit details now include the beneficiary bank BIC in addition to account and routing numbers.
• USD SWIFT deposit details now include the ClearBank IBAN on shared reference account responses.
• USD SWIFT deposit details now identify the ClearBank account with iban instead of also duplicating that value in accountNumber.

2026-07-07

• Added Wallets and Allowance guides to Getting Started, and clarified that GET /customers/withdrawal/allowance returns 200 with { "enabled": false, "allowance": null } when API withdrawals are unavailable.

2026-07-03

• USD SWIFT deposit details now return a dedicated iban and depositModel: "virtual_account" when the customer has an active USD virtual account; otherwise the shared reference account is returned with depositModel: "reference".

2026-07-02

• expectedMonthlyVolume on customer create is deprecated for KYC routing: all new customers now start basic KYC and enter their expected volume during the verification flow.
• Optional email on customer create is deprecated but remains accepted and stored on the customer record. Email for KYC verification is collected during the verification flow.

2026-07-01

• POST /customers/{customerId}/documents now accepts DRIVERS (driver's license) and RESIDENCE_PERMIT (residence permit) as idDocType values, in addition to PASSPORT, ID_CARD, and PROOF_OF_ADDRESS.
• Verification links returned by POST /customers/{customerId}/kyc are now referred to as "KYC flow links".
• Deprecated legacy KYC levels (customers-flow, customers-ui-flow, customers-ui-flow-enhanced, customers-api-basic, customers-api-enhanced). Existing customers on these levels are unaffected.
• Customers with an EU/EEA proof of address now complete an additional EU declaration step, surfaced as an extra questionnaire step in kyc.steps.

2026-06-29

• When the verification link (kycFlowLink) is embedded in an iframe, the page now forwards Sumsub verification events to the parent window via window.postMessage (idCheck.onApplicantSubmitted, idCheck.onApplicantStatusChanged, and idCheck.onError), so your UI can detect submission, approval, rejection, and errors. See "Detecting events in an iframe" in the integration guide.

2026-06-27

• POST /customers/{customerId}/kyc now returns the stable Compose-hosted verification link for hosted customer verification, including customers with an existing applicant record.

2026-06-26

• POST /customers/{customerId}/kyc now continues returning a Sumsub WebSDK link for existing customers with an in-progress legacy verification, while new customers receive the hosted Compose verification link when available.

2026-06-19

• POST /customers/{customerId}/virtual-account now supports corporate customers via API key. Corporate customers must have KYC approved and a complete business address and registration number on file before creation. Contact support if onboarding is incomplete.
• POST /customers/{customerId}/documents no longer accepts DRIVERS (driver's license) or RESIDENCE_PERMIT (residence permit) as idDocType values. The accepted values are now PASSPORT, ID_CARD, and PROOF_OF_ADDRESS. Requests using the removed types will receive a 400 response.

2026-06-07

• GET /customers/{customerId} now includes an identity object with nationality, countryOfResidence, and dateOfBirth (ISO YYYY-MM-DD) for licensed organizations.

2026-06-01

• POST /customers/{customerId}/kyc now returns a stable Compose-hosted verification link (https://www.auth.compose.finance/en/signup?c={customerId}) instead of a time-limited Sumsub WebSDK URL.

2026-05-28

• Fiat deposit, withdrawal bank, and transaction payloads are keyed by paymentRail (SEPA, FEDWIRE, SWIFT) rather than currency alone. Each response variant includes only the bank identifiers for that rail: SEPA uses iban and bic; Fedwire uses accountNumber and routingNumber; SWIFT uses accountNumber, bic, and beneficiary bank details (bankName, bankAddress, bankCountry where applicable).
• USD SWIFT is supported end to end. GET /customers/{customerId}/deposit can return SWIFT deposit instructions (account number and BIC). Create USD withdrawal banks with paymentRail: "SWIFT"; bankName, bankAddress, and bankCountry are required. You may pass an IBAN in accountNumber for SWIFT banks.
• POST /customers/{customerId}/withdrawal/banks requires currency (EUR or USD) and paymentRail. Existing integrations that send only currency continue to work and receive the default rail for that currency (EUR → SEPA, USD → FEDWIRE).
• GET /customers/{customerId}/deposit accepts paymentRail as the primary query parameter. The currency parameter remains supported and selects the default rail when paymentRail is omitted.
• GET /customers/{customerId}/transactions and GET /customers/{customerId}/transactions/{transactionId} include paymentRail on each transaction. For withdrawals, rail-specific bank fields are on the nested withdrawalBank object.
• GET /rates accepts optional payment_rail (SEPA, FEDWIRE, or SWIFT) so USD quotes can use Fedwire or SWIFT fee rules. Responses include payment_rail for the rail used in the quote (your request value or the currency default).

2026-05-24

• GET /rates responses may now include an optional developer_fee object (amount, currency, developerSpreadFeeBps) when quoting a fiat-to-crypto deposit with customer_id and the customer has an enabled deposit wallet with a spread fee configured. Platform fees remain in fee / fee_currency; quote amounts are unchanged.

2026-05-18

• GET /rates now accepts an optional deposit_model query parameter (REFERENCE or VIRTUAL_ACCOUNT, case-insensitive). When omitted, the cheapest available deposit channel is selected automatically so the quote matches the price you will actually pay. Ignored for withdrawals.

2026-05-15

• POST /customers now accepts both individual and corporate values for accountType.
• Corporate customers requesting a KYC link now receive guidance that onboarding will be completed by email.
• Added kyc.rejection object to GET /customers/{customerId} response. Populated with rejectLabels[] and reviewRejectType (FINAL or RETRY) when the customer is currently in a rejected KYC state; null otherwise.
• GET /customers/{customerId} may now include an optional kyc.rejection.clientComment string with a human-readable rejection reason when the verification provider supplied one.

2026-04-29

• Added USD rails across customer deposit and withdrawal APIs.
• GET /customers/{customerId}/deposit now supports both currency=eur and currency=usd. EUR responses include iban/bic; USD responses include FedWire accountNumber/routingNumber.
• POST /customers/{customerId}/withdrawal/banks now accepts currency-specific bank details: EUR uses iban/bic, while USD uses accountNumber/routingNumber. GET /customers/{customerId}/withdrawal/banks returns the same currency-specific format.
• Withdrawal responses from POST /customers/{customerId}/withdrawal, GET /customers/{customerId}/transactions, and GET /customers/{customerId}/transactions/{transactionId} now return withdrawalBank details in the correct format for the withdrawal currency (EUR or USD).
• GET /rates now supports USD quotes for the USD->USDC pair.

2026-03-17

• Added GET /api/v2/rates endpoint for indicative exchange rate quotes. Returns a stateless quote for fiat↔crypto currency pairs (EUR ↔ USDC, EURC) including fees.
• source_currency and target_currency query parameters on GET /api/v2/rates are case-insensitive
• exchangeRate description on deposit, withdrawal, and rate quote responses now clarifies the formula: targetAmount = sourceAmount × exchangeRate (before fees)

2026-03-12

• POST /customers/{customerId}/documents and POST /customers/{customerId}/kyc/submit now return 403 when manual KYC upload is unavailable for your organization.

2026-03-09

• Added reference field to deposit and withdrawal transaction responses. For deposits, this is the inbound bank reference included in the transfer. For withdrawals, this is the reference included in the outbound bank transfer (transaction id).

2026-03-04

• Added GET /balances endpoint to retrieve custodial and non-custodial (Safe wallet) balances for your organization, including availableBalance and lockedBalance
• Added nullable address object (addressLine1, city, country) to GET /customers/{customerId} response. Returns verified address from KYC or stored metadata when available, null otherwise.
• Added optional country field to POST /customers/{customerId}/withdrawal/banks request body (ISO 3166-1 alpha-2 code). Auto-resolved from KYC/metadata for CUSTOMER recipients; required explicitly for OTHER_INDIVIDUAL and OTHER_BUSINESS. Returns 400 if address cannot be resolved.
• Standardized error response descriptions and examples for 401, 403, and 500 across all endpoints
• Renamed currencyTicker to currency (lowercased) in GET /developer-fees response
• sourceCurrency in POST /customers/{customerId}/withdrawal is now case-insensitive
• accountType in POST /customers is now case-insensitive
• recipientType in POST /customers/{customerId}/withdrawal/banks is now case-insensitive

2026-02-25

• Added addressLine1, city, and country to GET /customers/{customerId}/withdrawal/banks responses

2026-02-24

• Renamed ticker to currency across deposit wallet request/response payloads (/customers/{customerId}/deposit/wallets and /customers/{customerId}/deposit/wallets/{walletId})
• Renamed deposit wallet filter query parameter ticker to currency on GET /customers/{customerId}/deposit/wallets
• Renamed withdrawal bank wallet field ticker to currency in GET /customers/{customerId}/withdrawal/banks and POST /customers/{customerId}/withdrawal/banks responses

2026-02-23

• Added wallets to GET /customers/{customerId}/withdrawal/banks and POST /customers/{customerId}/withdrawal/banks responses
• POST /customers/{customerId}/withdrawal/banks now auto-creates a linked withdrawal wallet and returns it when successful

2026-02-20

• Added GET /customers/{customerId}/kyc/address endpoint to retrieve a customer's verified address
• Made addressLine1 and city optional for CUSTOMER recipient type — address is auto-resolved from KYC data when not provided
• Changed recipientType enum values from MYSELF/INDIVIDUAL/BUSINESS to CUSTOMER/OTHER_INDIVIDUAL/OTHER_BUSINESS

2026-02-19

• Added isThirdParty field to withdrawal bank responses
• Third-party withdrawal banks now require approval (PENDING_APPROVAL status)