components: schemas: BankAccountListResponseDto: properties: data: description: Array of bank account objects items: oneOf: - properties: accountDetails: description: 'USD account details. For ACH/Wire: accountNumber, routingNumber, accountType. For SWIFT: accountNumber (masked), bic.' oneOf: - properties: accountNumber: description: The bank account number for the US bank account (masked, last 4 characters visible). Present when currency is usd. example: '****7890' type: string accountType: description: The type of US bank account. Present when currency is usd. enum: - checking - savings - instapay - pesonet example: checking type: string x-enumNames: - Checking - Savings - Instapay - Pesonet routingNumber: description: The 9-digit ABA routing number (also known as routing transit number) that identifies the US financial institution. Present when currency is usd. example: '021000021' type: string required: - accountNumber - routingNumber - accountType type: object - properties: accountNumber: description: The account number for SWIFT transfers (masked, last 4 characters visible). Present when currency is usd and networks is ["swift"]. example: '******7890' type: string bic: description: The BIC/SWIFT code of the beneficiary bank. Present when currency is usd and networks is ["swift"]. example: DEUTDEFF type: string intermediaryBics: description: Ordered list of BIC/SWIFT codes for intermediary correspondent banks, if any were set on this account. Omitted from the response when no intermediary BICs are set. example: - CHASUS33 items: type: string type: array required: - accountNumber - bic type: object accountName: description: A descriptive name for this bank account. example: Checking Account type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: Bank of America type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - usd example: usd type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For USD ACH/Wire accounts, includes at least one of "ach" or "wire". For USD SWIFT accounts, is exactly ["swift"]. example: - wire - ach oneOf: - items: enum: - ach - wire type: string type: array - items: oneOf: - enum: - swift type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: USD type: object - properties: accountDetails: description: EUR/SEPA account details including iban and bic. properties: bic: description: The Bank Identifier Code (BIC), also known as SWIFT code. Present when currency is eur. example: COBADEFFXXX type: string iban: description: The International Bank Account Number (IBAN) for SEPA transfers (masked). Country code, check digits, and last 4 characters are unmasked. Present when currency is eur. example: GB29****************6819 type: string required: - iban - bic type: object accountName: description: A descriptive name for this bank account. example: Hauptkonto type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: Deutsche Bank type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - eur example: eur type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For EUR accounts, is exactly ["sepa"]. example: - sepa items: enum: - sepa type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: EUR type: object - properties: accountDetails: description: BRL/PIX account details including pixKey and pixKeyType. properties: pixKey: description: The masked PIX key for Brazilian PIX transfers. Present when currency is brl. example: a*c@g***l.com type: string pixKeyType: description: The type of PIX key. Present when currency is brl. enum: - cpf - cnpj - email - phone - random example: email type: string required: - pixKey - pixKeyType type: object accountName: description: A descriptive name for this bank account. example: Conta PIX Alice Santos type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: Itau type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - brl example: brl type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For BRL accounts, is exactly ["pix"]. example: - pix items: enum: - pix type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: BRL type: object - properties: accountDetails: description: MXN/SPEI account details including the masked clabe. properties: clabe: description: The 18-digit CLABE for MXN/SPEI transfers (masked, last 4 digits visible). Present when currency is mxn. example: '**************7899' type: string required: - clabe type: object accountName: description: A descriptive name for this bank account. example: Cuenta SPEI María García type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: BBVA México type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - mxn example: mxn type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For MXN accounts, is exactly ["spei"]. example: - spei items: enum: - spei type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: MXN type: object type: array pagination: properties: hasNext: description: Whether there is a next page example: false type: boolean hasPrevious: description: Whether there is a previous page example: false type: boolean limit: description: Number of items per page example: 10 exclusiveMaximum: false exclusiveMinimum: false maximum: 100 minimum: 1 type: number page: description: Current page number example: 1 type: number total: description: Total number of items example: 1 type: number totalPages: description: Total number of pages example: 1 type: number required: - page - limit - total - totalPages - hasNext - hasPrevious type: object required: - data - pagination type: object BusinessRepresentativeResponseDto: properties: address: description: The business representative's residential address. properties: city: type: string country: type: string line1: type: string line2: type: string postalCode: type: string state: type: string type: object createdAt: description: The date and time the business representative was created. example: '2026-03-10T00:00:08.986Z' type: string customerId: description: Customer ID example: customer_2f283221a9d44ada800ac7f11f640402 type: string dateOfBirth: description: The business representative's date of birth in YYYY-MM-DD format. example: '1985-03-12' type: string email: description: Email address example: james.wilson@acmecorp.example.com type: string firstName: description: The business representative's legal first name. example: James type: string id: description: Business Representative ID example: associatedPerson_d972d2f70b9f4d3c8d7cfb32593f395b type: string lastName: description: The business representative's legal last name. example: Wilson type: string phone: description: Phone number example: '+13125559876' type: string representationDetails: description: Representation details properties: ownershipPercentage: description: The ownership percentage of the business representative. example: '50' type: string relationshipEstablishedAt: description: The date the business representative was established in the company. example: '2020-03-15' type: string roles: description: The roles of the business representative. example: - ubo items: enum: - ubo - control_person - signer - director type: string type: array title: description: The title of the business representative. example: CEO type: string required: - roles type: object type: description: Customer type enum: - individual example: individual type: string updatedAt: description: The date and time the business representative was last updated. example: '2026-03-10T00:00:08.986Z' type: string verificationProfiles: description: Array of verification profiles for the business representative. example: - criteria: complete: - email_address - phone_number - residential_address - tax_identification_number - ownership_percentage - is_control_person - is_signer - relationship_established_at - title errors: [] pending: [] required: - identity_document - liveness_report_document - proof_of_address_document name: ubo_kyc_profile_a status: incomplete items: properties: criteria: description: The criteria for the verification profile. example: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document properties: complete: description: Completed fields. example: - email_address - phone_number - residential_address - tax_identification_number items: type: string type: array errors: description: The errors that occurred while verifying the fields. example: [] items: properties: detail: type: string name: enum: - email_verification - phone_verification - residential_address - identity_document - tax_identification_number - liveness_check - terms_of_service - email_address - phone_number - master_service_agreement - legal_name - trade_name - entity_type - entity_type_description - description - registered_address - operating_address - business_representatives - naics_code - website - incorporated_on - identification_number - registration_number - estimated_annual_revenue - expected_monthly_payments - account_purpose - account_purpose_description - source_of_funds - source_of_funds_description - is_dao - regulated_activities - regulated_activities_description - participates_in_regulated_financial_activity - regulated_financial_activity_description - money_services_description - compliance_screening_explanation - operates_in_prohibited_countries - incorporation_cert_document - incorporation_articles_document - shareholder_registry_document - proof_of_nature_of_business_document - proof_of_address_document - liveness_report_document - ownership_percentage - is_control_person - control_person_added - is_signer - relationship_established_at - title - employment_status - acting_as_intermediary - sex - country_of_birth - nationality - middle_name - occupation_soc_code - w8_ben_document - w9_document - state_of_birth - ip_address - ip_address_approved - expected_monthly_transaction_count - transaction_frequency - expected_counterparty_types - expected_geographies - w8_ben_e_document - corporate_resolution_document - source_of_funds_document - financial_statements_document - bank_statement_document - regulated_activity_document - flow_of_funds_document - kyc_b_approval - kyb_b_approval type: string required: - name type: object type: array pending: description: Pending fields. These fields are currently being verified. example: [] items: type: string type: array required: description: Required fields. These fields are required to be completed before the verification profile can be approved. example: - identity_document - liveness_report_document items: type: string type: array required: - complete - pending - required - errors type: object name: description: The name of the verification profile. enum: - kyc_profile_a - kyb_profile_a - ubo_kyc_profile_a - kyc_profile_b - kyb_profile_b - kyb_profile_c - kyc_profile_c - ubo_kyc_profile_c - kyb_profile_d - kyc_profile_d - ubo_kyc_profile_d example: kyc_profile_a type: string status: description: The status of the verification profile. enum: - incomplete - pending - approved - rejected - rejected_final - manual_review - resubmission_required example: incomplete type: string required: - name - status type: object type: array required: - id - customerId - type - verificationProfiles - createdAt - updatedAt type: object CancelTransferResponseDto: properties: created: description: The datetime the transfer was created. example: '2021-01-01T00:00:00.000Z' format: date-time type: string customer: description: The customer ID. example: customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7 type: string depositAccount: oneOf: - description: The deposit bank account for an on ramp transfer. properties: bankDetails: properties: accountHolderName: description: The name of the bank account holder that the source funds will be transferred to. example: John Doe type: string accountNumber: description: The account number of the bank account, used for wires, ACH transfers and other applicable networks. example: '1234567890' type: string accountType: description: 'The type of bank account: savings or checking.' enum: - savings - checking example: savings type: string bankAddress: description: The address of the deposit bank account. example: 123 Main St, Anytown, USA type: string bankName: description: The name of the bank that the source funds will be transferred to. example: Bank of America type: string beneficiaryAddress: description: The address of the beneficiary that will receive the funds. example: 123 Main St, Anytown, USA type: string bic: description: The BIC of the bank account, used for SEPA transfers and other applicable networks. example: '1234567890' type: string brCode: description: The PIX BR code for on-ramp payments. Encode this as a QR code for the customer to scan and pay. example: 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string clabe: description: The CLABE of the deposit bank account, used for SPEI transfers in Mexico. example: '012345678901234567' type: string iban: description: The IBAN of the bank account, used for SEPA transfers and other applicable networks. example: '1234567890' type: string memo: description: The memo of the transfer. This must be provided when initiating wire, ACH and SEPA transfers. This is the memo that will be used to identify the transfer to the deposit account. example: BBE6C7EB4A3F type: string pixKey: description: The PIX key of the deposit bank account, used for PIX transfers. example: '+5511999999999' type: string routingNumber: description: The routing number of the bank account, used for wires, ACH transfers and other applicable networks. example: '1234567890' type: string type: object type: description: The type of the deposit account. enum: - bank_account example: bank_account type: string required: - type - bankDetails title: Deposit Bank Account type: object - description: The deposit wallet for an off ramp transfer. properties: type: description: The type of the deposit account. enum: - wallet example: wallet type: string walletDetails: properties: address: description: The address of the wallet that the source funds will be transferred to. example: '0x1234567890abcdef1234567890abcdef12345678' type: string currency: description: The currency that should be transferred to the wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string network: description: The network that the source funds will be transferred on. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: ethereum type: string required: - address - currency - network type: object required: - type - walletDetails title: Deposit Wallet type: object destination: oneOf: - description: The destination of an `On-ramp` transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: amount: type: string currency: description: The destination wallet currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string exchangeRate: description: The exchange rate applied to the destination amount when converting the source amount to the destination currency. example: '5.455' type: string id: description: The destination wallet ID. example: wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2 pattern: ^wallet_[a-z0-9]+$ type: string network: description: The destination wallet network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: sol type: string type: description: The destination wallet type. enum: - wallet example: wallet type: string required: - id - type - currency - network title: Destination Wallet type: object - description: The destination of an `Off-ramp` transfer. properties: achReference: description: The ACH reference string. example: ABC123456789 type: string amount: description: The destination amount being transferred to the bank account. example: '98.90' type: string currency: description: The destination bank account currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usd - eur - brl - mxn example: usd type: string exchangeRate: description: The exchange rate applied to the destination amount when converting the source amount to the destination currency. example: '5.455' type: string id: description: The destination bank account ID. example: bankAccount_f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3 pattern: ^bankAccount_[a-z0-9]+$ type: string network: description: The destination bank account network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach - wire - sepa - pix - swift - spei example: wire type: string sepaReference: description: The SEPA reference string. example: ABC123456789 type: string type: description: The destination account type. enum: - bank_account example: bank_account type: string wireMessage: description: The message included with the wire transfer. example: Payment for invoice 12345 type: string required: - id - type - currency - network title: Destination Bank Account type: object externalId: description: The external reference (not stored as unique). example: merchant_ref_123 type: string fees: description: Fee breakdown for the transfer. For floating-rate BRL transfers, this is omitted until settlement is complete. properties: integratorFee: description: The integrator fee, this is the portion of the fee that the API integrator will receive. example: bpsAmount: '0.10' bpsRate: '10' currency: usd fixedAmount: '1.00' totalAmount: '1.10' properties: bpsAmount: description: The dollar amount derived from the BPS rate. Equal to totalAmount minus fixedAmount. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc - usd - eur - brl - mxn example: usd type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object platformFee: description: The platform fee, this is the portion of the fee that Sphere will receive. example: bpsAmount: '0.10' bpsRate: '10' currency: usd fixedAmount: '2.00' totalAmount: '2.10' properties: bpsAmount: description: The dollar amount derived from the BPS rate. Equal to totalAmount minus fixedAmount. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc - usd - eur - brl - mxn example: usd type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object required: - integratorFee - platformFee type: object fundingDeadline: description: The datetime by which the deposit must arrive into the deposit account. A later deposit is not applied to this transfer. Present only on bank-funded transfers that have a deadline. Distinct from `quote.expiresAt`, which is the expiry of the quoted rate. example: '2026-11-03T12:00:00.000Z' format: date-time type: string id: description: A unique identifier for transfer. example: payout_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 pattern: ^payout_[a-z0-9]{32}$ type: string paymentDescription: description: A free-text description of the payment purpose. Present on third-party off-ramp transfers. example: INV-2026-004 - Q1 software services type: string paymentReason: description: The reason for the payment. Present on BRL transfers and third-party off-ramp transfers. example: professional_services type: string quote: description: The quote used for this transfer, if any. When present, the locked exchange rate from the quote was applied to the destination amount and exchange rate. properties: expiresAt: description: The datetime the quote expires. example: '2021-01-01T00:00:00.000Z' format: date-time type: string id: description: The unique identifier for the quote used for this transfer. example: quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string required: - id - expiresAt type: object returnAddress: description: Crypto wallet address where funds are sent if the transfer fails or is refunded. Only present on off-ramp transfers created with a custom return address. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string source: oneOf: - description: The source of an on ramp transfer. example: id: bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: bank_account properties: achReference: description: The ACH reference string. example: ABC123456789 type: string amount: description: The source amount being transferred out of the source bank account. example: '100.00' type: string currency: description: The source bank account currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usd - eur - brl - mxn example: usd type: string id: description: The source bank account ID. example: bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 pattern: ^bankAccount_[a-z0-9]+$ type: string network: description: The source bank account network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach - wire - sepa - pix - swift - spei example: wire type: string sepaReference: description: The SEPA reference string. example: ABC123456789 type: string type: description: The source account type. enum: - bank_account example: bank_account type: string wireMessage: description: The message included with the wire transfer. example: Payment for invoice 12345 type: string required: - id - type - currency - network - amount title: Source Bank Account type: object - description: The source of an off ramp transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: amount: description: The source amount being transferred out of the source wallet. example: '100.00' type: string currency: description: The source wallet currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string id: description: The source wallet ID. example: wallet_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1 pattern: ^wallet_[a-z0-9]+$ type: string network: description: The source wallet network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: sol type: string type: description: The source type. enum: - wallet example: wallet type: string required: - id - type - currency - network - amount title: Source Wallet type: object status: description: The transfer status. See [Transfer Lifecycle](/concepts/transfers/lifecycle) for status definitions and transitions. enum: - pendingFunding - pendingReview - fundsReceived - processing - succeeded - undeliverable - returned - processingRefund - refundFailed - pendingRefundInformation - failed - canceled - refunded - unexpectedError - failedPrecondition - expired - unfunded example: pendingFunding type: string x-enumNames: - PENDING_FUNDING - PENDING_REVIEW - FUNDS_RECEIVED - PROCESSING - SUCCEEDED - UNDELIVERABLE - RETURNED - PROCESSING_REFUND - REFUND_FAILED - PENDING_REFUND_INFO - FAILED - CANCELED - REFUNDED - UNEXPECTED_ERROR - FAILED_PRECONDITION - EXPIRED - UNFUNDED statusHistory: description: Timeline of status transitions for this transfer, ascending by transitionedAt. example: - status: pendingFunding transitionedAt: '2026-06-20T14:03:21.000Z' - status: processing transitionedAt: '2026-06-20T14:05:10.000Z' items: description: A single transfer status transition. properties: status: enum: - pendingFunding - pendingReview - fundsReceived - processing - succeeded - undeliverable - returned - processingRefund - refundFailed - pendingRefundInformation - failed - canceled - refunded - unexpectedError - failedPrecondition - expired - unfunded type: string x-enumNames: - PENDING_FUNDING - PENDING_REVIEW - FUNDS_RECEIVED - PROCESSING - SUCCEEDED - UNDELIVERABLE - RETURNED - PROCESSING_REFUND - REFUND_FAILED - PENDING_REFUND_INFO - FAILED - CANCELED - REFUNDED - UNEXPECTED_ERROR - FAILED_PRECONDITION - EXPIRED - UNFUNDED transitionedAt: description: ISO 8601 timestamp of when the transfer entered this status. example: '2026-06-20T14:05:10.000Z' format: date-time type: string required: - status - transitionedAt title: Transfer Status History Entry type: object type: array tracking: description: Tracking references for the transfer. Only included when at least one reference exists. properties: destination: description: Tracking references for the destination side of the transfer. properties: imad: description: The Input Message Accountability Data (IMAD) assigned by the Federal Reserve to uniquely identify a wire transfer. example: 20250224MMQFMP0B000012 type: string omad: description: The OMAD of a wire transfer (offramp WIRE only). example: '123456789012345678901234' type: string refundReferenceId: description: The provider refund / return reference identifying the movement that sent funds back. Present on the refund side; may also appear on the source side for transfers refunded before the refund side existed. example: 010F2712624525KD type: string speiTrackingKey: description: The SPEI clave de rastreo assigned to track a SPEI transfer in Mexico. Present on the source side of MXN pay-ins. example: CR20260716TITAN0000000000000000001 type: string traceNumber: description: The ACH trace number assigned by the originating bank to track the transfer through the ACH network. example: '021000021234567' type: string transactionId: description: The on-chain transaction hash. example: 4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b type: string uetr: description: The Unique End-to-End Transaction Reference (UETR) assigned to track a SEPA or SWIFT transfer. example: 097B365480122XK9 type: string type: object refund: description: Tracking references for the refund leg of the transfer, when funds have been sent back. properties: imad: description: The Input Message Accountability Data (IMAD) assigned by the Federal Reserve to uniquely identify a wire transfer. example: 20250224MMQFMP0B000012 type: string omad: description: The OMAD of a wire transfer (offramp WIRE only). example: '123456789012345678901234' type: string refundReferenceId: description: The provider refund / return reference identifying the movement that sent funds back. Present on the refund side; may also appear on the source side for transfers refunded before the refund side existed. example: 010F2712624525KD type: string speiTrackingKey: description: The SPEI clave de rastreo assigned to track a SPEI transfer in Mexico. Present on the source side of MXN pay-ins. example: CR20260716TITAN0000000000000000001 type: string traceNumber: description: The ACH trace number assigned by the originating bank to track the transfer through the ACH network. example: '021000021234567' type: string transactionId: description: The on-chain transaction hash. example: 4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b type: string uetr: description: The Unique End-to-End Transaction Reference (UETR) assigned to track a SEPA or SWIFT transfer. example: 097B365480122XK9 type: string type: object source: description: Tracking references for the source side of the transfer. properties: imad: description: The Input Message Accountability Data (IMAD) assigned by the Federal Reserve to uniquely identify a wire transfer. example: 20250224MMQFMP0B000012 type: string omad: description: The OMAD of a wire transfer (offramp WIRE only). example: '123456789012345678901234' type: string refundReferenceId: description: The provider refund / return reference identifying the movement that sent funds back. Present on the refund side; may also appear on the source side for transfers refunded before the refund side existed. example: 010F2712624525KD type: string speiTrackingKey: description: The SPEI clave de rastreo assigned to track a SPEI transfer in Mexico. Present on the source side of MXN pay-ins. example: CR20260716TITAN0000000000000000001 type: string traceNumber: description: The ACH trace number assigned by the originating bank to track the transfer through the ACH network. example: '021000021234567' type: string transactionId: description: The on-chain transaction hash. example: 4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b type: string uetr: description: The Unique End-to-End Transaction Reference (UETR) assigned to track a SEPA or SWIFT transfer. example: 097B365480122XK9 type: string type: object type: object type: description: The transfer type. enum: - on_ramp - off_ramp - fiat_to_fiat - unmatched_deposit - microdeposit example: on_ramp type: string updated: description: The last datetime the transfer was updated. example: '2021-01-01T00:00:00.000Z' format: date-time type: string required: - id - type - status - statusHistory - customer - source - destination - depositAccount - updated - created type: object CreateCustomerKycLinkDto: properties: address: description: The customer's address. For individual customers this is the residential address; for business customers this is the registered business address. properties: city: description: The city name example: Chicago maxLength: 100 minLength: 1 type: string country: description: The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string line1: description: The first line of the street address example: 233 South Wacker Drive maxLength: 100 minLength: 1 type: string line2: description: The second line of the street address (apartment, suite, etc.) example: Suite 4700 maxLength: 100 type: string postalCode: description: The postal or ZIP code. Required for countries that use postal codes example: '60606' type: string state: description: The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: IL type: string required: - line1 - city - country type: object email: description: The customer email address. example: jane.smith@example.com format: email maxLength: 254 type: string enabledVerificationProfiles: description: Restricts which verification profile families this customer may onboard through. Must be a subset of the families enabled on your application; supplying one that is not enabled is rejected with a 422. Omit the field to inherit the application's setting. example: - a - c items: enum: - a - b - c - d type: string minItems: 1 type: array phone: description: The customer phone number in E.164 format. example: '+14155550123' pattern: ^\+(?:[0-9]){6,14}[0-9]$ type: string type: description: The type of customer to onboard. enum: - individual - business example: individual type: string required: - type - email - phone - address type: object CreateOffloaderWalletRequestDto: properties: currency: description: The crypto currency the offloader wallet accepts for deposits. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string customerId: description: The customer who owns the destination bank account. example: customer_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string destination: description: The bank account destination where converted funds are sent. See [Bank Accounts guide](/concepts/transfers/bank-accounts). example: achReference: REF123 bankAccountId: bankAccount_6221e8d4299f4a889bd882255e92f581 currency: usd network: ach oneOf: - properties: achReference: description: Reference sent to the receiving institution with ACH transfers, 1-10 characters. example: REF123 maxLength: 10 minLength: 1 type: string bankAccountId: description: The ID of the bank account that converted funds will be sent to. See [Bank Accounts guide](/concepts/transfers/bank-accounts). example: bankAccount_6221e8d4299f4a889bd882255e92f581 type: string currency: description: The fiat currency the crypto will be converted into. enum: - usd example: usd type: string network: description: The banking network used to deliver funds to the destination account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach example: ach type: string required: - bankAccountId - currency - network title: ACH type: object - properties: bankAccountId: description: The ID of the bank account that converted funds will be sent to. See [Bank Accounts guide](/concepts/transfers/bank-accounts). example: bankAccount_6221e8d4299f4a889bd882255e92f581 type: string currency: description: The fiat currency the crypto will be converted into. enum: - usd example: usd type: string network: description: The banking network used to deliver funds to the destination account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - wire example: wire type: string wireMessage: description: Message sent to the receiving institution with wire transfers, 1-105 characters. example: 'Invoice #1024' maxLength: 105 minLength: 1 type: string required: - bankAccountId - currency - network title: Wire type: object - properties: bankAccountId: description: The ID of the bank account that converted funds will be sent to. See [Bank Accounts guide](/concepts/transfers/bank-accounts). example: bankAccount_6221e8d4299f4a889bd882255e92f581 type: string currency: description: The fiat currency the crypto will be converted into. enum: - eur example: eur type: string network: description: The banking network used to deliver funds to the destination account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sepa example: sepa type: string sepaReference: description: Reference sent to the receiving institution with SEPA transfers, 6-140 characters. example: INV-2024-001 maxLength: 140 minLength: 6 type: string required: - bankAccountId - currency - network title: SEPA type: object integratorBpsFeeRate: description: Integrator fee in basis points (0-1000). example: '100' type: string network: description: The blockchain network the offloader wallet is on. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - ethereum - arbitrum - polygon - base - avalanche - tron example: ethereum type: string returnAddress: description: Crypto address where funds are returned on failed transactions. Must be valid for the selected network. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string required: - customerId - currency - network - destination type: object CreateQuoteRequestDto: properties: amount: description: The quote amount. For MXN/USD RFQ it is denominated by referenceSide; all other corridors retain their existing source-amount behavior. example: '100.00' pattern: ^\d+(\.\d{2})?$ type: string customerId: description: The customer's ID. example: customer_3faa484998f44cfead9668608b9ee1f5 pattern: ^customer_[a-z0-9]+$ type: string destination: description: The destination currency and network for the quote. properties: currency: description: 'The destination currency. For off-ramp: a fiat currency (e.g., "brl"). For on-ramp: a stablecoin (e.g., "usdc").' enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: brl type: string network: description: 'The destination network. For off-ramp: a payment rail (e.g., "pix"). For on-ramp: a blockchain (e.g., "polygon").' example: pix oneOf: - enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid type: string - enum: - wire - ach - achPush - achPull - achSameDay - swift - sepa - pix - spei - spei type: string required: - currency - network type: object integratorBpsFeeRate: description: The integrator BPS fee rate. The BPS rate must be an integer string between 0 and 10000. example: '20' pattern: ^\d+$ type: string quoteDurationSeconds: description: For MXN/SPEI to USD/wire or USD/swift quotes, the field may be omitted or must be 45; omission defaults to 45. For all other supported routes, explicit values must be 30, 60, or 300 seconds and omission defaults to 60. example: 60 type: number referenceSide: description: MXN/USD RFQ only. The side denominating amount; defaults to source when omitted. enum: - source - destination example: source type: string source: description: The source currency and network for the quote. properties: currency: description: 'The source currency. For off-ramp: a stablecoin (e.g., "usdc"). For on-ramp: a fiat currency (e.g., "brl").' enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: usdc type: string network: description: 'The source network. For off-ramp: a blockchain (e.g., "polygon"). For on-ramp: a payment rail (e.g., "pix").' example: polygon oneOf: - enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid type: string - enum: - wire - ach - achPush - achPull - achSameDay - swift - sepa - pix - spei - spei type: string required: - currency - network type: object required: - amount - customerId - source - destination type: object CreateQuoteResponseDto: properties: created: description: The datetime the quote was created. example: '2025-01-01T00:00:00.000Z' format: date-time type: string customerId: description: The customer ID. example: customer_d243ab2b1de4447d8a046d87fefe58cf type: string destination: properties: amount: description: The destination amount after exchange. example: '545.50' type: string currency: description: The destination currency. enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: brl type: string exchangeRate: description: The exchange rate applied to convert source to destination. example: '5.455' type: string network: description: The destination network. example: pix oneOf: - description: A blockchain network. enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: polygon type: string - enum: - wire - ach - achPush - achPull - achSameDay - swift - sepa - pix - spei - spei type: string required: - currency - network - amount - exchangeRate type: object expiresAt: description: The datetime when this quote expires. example: '2025-01-01T00:01:00.000Z' format: date-time type: string fees: properties: integratorFee: description: The integrator fee portion. example: bpsRate: '0' currency: usdc fixedAmount: '0.00' totalAmount: '0.00' properties: bpsAmount: description: The sum of the individually rounded percentage-based fee components. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: brl type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object platformFee: description: The platform fee portion. example: bpsRate: '20' currency: usdc fixedAmount: '0.00' totalAmount: '2.00' properties: bpsAmount: description: The sum of the individually rounded percentage-based fee components. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: brl type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object required: - integratorFee - platformFee type: object id: description: A unique identifier for the quote. example: quote_d243ab2b1de4447d8a046d87fefe58cf pattern: ^quote_[a-z0-9]+$ type: string quoteDurationSeconds: description: RFQ-only quote duration in seconds. example: 45 exclusiveMinimum: true minimum: 0 type: integer referenceSide: description: RFQ-only side whose amount was referenced for pricing. enum: - source - destination example: source type: string source: properties: amount: description: The source amount. example: '100.00' type: string currency: description: The source currency. enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: usdc type: string network: description: The source network. example: polygon oneOf: - description: A blockchain network. enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: polygon type: string - enum: - wire - ach - achPush - achPull - achSameDay - swift - sepa - pix - spei - spei type: string required: - currency - network - amount type: object status: description: The current status of the quote. enum: - active - used - expired example: active type: string type: description: The transfer type this quote is for. enum: - on_ramp - off_ramp - fiat_to_fiat example: off_ramp type: string required: - id - type - customerId - fees - source - destination - expiresAt - created type: object CreateTransferResponseDto: properties: created: description: The datetime the transfer was created. example: '2021-01-01T00:00:00.000Z' format: date-time type: string customer: description: The customer ID. example: customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7 type: string depositAccount: oneOf: - description: The deposit bank account for an on ramp transfer. properties: bankDetails: properties: accountHolderName: description: The name of the bank account holder that the source funds will be transferred to. example: John Doe type: string accountNumber: description: The account number of the bank account, used for wires, ACH transfers and other applicable networks. example: '1234567890' type: string accountType: description: 'The type of bank account: savings or checking.' enum: - savings - checking example: savings type: string bankAddress: description: The address of the deposit bank account. example: 123 Main St, Anytown, USA type: string bankName: description: The name of the bank that the source funds will be transferred to. example: Bank of America type: string beneficiaryAddress: description: The address of the beneficiary that will receive the funds. example: 123 Main St, Anytown, USA type: string bic: description: The BIC of the bank account, used for SEPA transfers and other applicable networks. example: '1234567890' type: string brCode: description: The PIX BR code for on-ramp payments. Encode this as a QR code for the customer to scan and pay. example: 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string clabe: description: The CLABE of the deposit bank account, used for SPEI transfers in Mexico. example: '012345678901234567' type: string iban: description: The IBAN of the bank account, used for SEPA transfers and other applicable networks. example: '1234567890' type: string memo: description: The memo of the transfer. This must be provided when initiating wire, ACH and SEPA transfers. This is the memo that will be used to identify the transfer to the deposit account. example: BBE6C7EB4A3F type: string pixKey: description: The PIX key of the deposit bank account, used for PIX transfers. example: '+5511999999999' type: string routingNumber: description: The routing number of the bank account, used for wires, ACH transfers and other applicable networks. example: '1234567890' type: string type: object type: description: The type of the deposit account. enum: - bank_account example: bank_account type: string required: - type - bankDetails title: Deposit Bank Account type: object - description: The deposit wallet for an off ramp transfer. properties: type: description: The type of the deposit account. enum: - wallet example: wallet type: string walletDetails: properties: address: description: The address of the wallet that the source funds will be transferred to. example: '0x1234567890abcdef1234567890abcdef12345678' type: string currency: description: The currency that should be transferred to the wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string network: description: The network that the source funds will be transferred on. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: ethereum type: string required: - address - currency - network type: object required: - type - walletDetails title: Deposit Wallet type: object destination: oneOf: - description: The destination of an `On-ramp` transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: amount: type: string currency: description: The destination wallet currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string exchangeRate: description: The exchange rate applied to the destination amount when converting the source amount to the destination currency. example: '5.455' type: string id: description: The destination wallet ID. example: wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2 pattern: ^wallet_[a-z0-9]+$ type: string network: description: The destination wallet network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: sol type: string type: description: The destination wallet type. enum: - wallet example: wallet type: string required: - id - type - currency - network title: Destination Wallet type: object - description: The destination of an `Off-ramp` transfer. properties: achReference: description: The ACH reference string. example: ABC123456789 type: string amount: description: The destination amount being transferred to the bank account. example: '98.90' type: string currency: description: The destination bank account currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usd - eur - brl - mxn example: usd type: string exchangeRate: description: The exchange rate applied to the destination amount when converting the source amount to the destination currency. example: '5.455' type: string id: description: The destination bank account ID. example: bankAccount_f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3 pattern: ^bankAccount_[a-z0-9]+$ type: string network: description: The destination bank account network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach - wire - sepa - pix - swift - spei example: wire type: string sepaReference: description: The SEPA reference string. example: ABC123456789 type: string type: description: The destination account type. enum: - bank_account example: bank_account type: string wireMessage: description: The message included with the wire transfer. example: Payment for invoice 12345 type: string required: - id - type - currency - network title: Destination Bank Account type: object externalId: description: The external reference (not stored as unique). example: merchant_ref_123 type: string fees: description: Fee breakdown for the transfer. For floating-rate BRL transfers, this is omitted until settlement is complete. properties: integratorFee: description: The integrator fee, this is the portion of the fee that the API integrator will receive. example: bpsAmount: '0.10' bpsRate: '10' currency: usd fixedAmount: '1.00' totalAmount: '1.10' properties: bpsAmount: description: The dollar amount derived from the BPS rate. Equal to totalAmount minus fixedAmount. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc - usd - eur - brl - mxn example: usd type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object platformFee: description: The platform fee, this is the portion of the fee that Sphere will receive. example: bpsAmount: '0.10' bpsRate: '10' currency: usd fixedAmount: '2.00' totalAmount: '2.10' properties: bpsAmount: description: The dollar amount derived from the BPS rate. Equal to totalAmount minus fixedAmount. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc - usd - eur - brl - mxn example: usd type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object required: - integratorFee - platformFee type: object fundingDeadline: description: The datetime by which the deposit must arrive into the deposit account. A later deposit is not applied to this transfer. Present only on bank-funded transfers that have a deadline. Distinct from `quote.expiresAt`, which is the expiry of the quoted rate. example: '2026-11-03T12:00:00.000Z' format: date-time type: string id: description: A unique identifier for transfer. example: payout_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 pattern: ^payout_[a-z0-9]{32}$ type: string paymentDescription: description: A free-text description of the payment purpose. Present on third-party off-ramp transfers. example: INV-2026-004 - Q1 software services type: string paymentReason: description: The reason for the payment. Present on BRL transfers and third-party off-ramp transfers. example: professional_services type: string quote: description: The quote used for this transfer, if any. When present, the locked exchange rate from the quote was applied to the destination amount and exchange rate. properties: expiresAt: description: The datetime the quote expires. example: '2021-01-01T00:00:00.000Z' format: date-time type: string id: description: The unique identifier for the quote used for this transfer. example: quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string required: - id - expiresAt type: object returnAddress: description: Crypto wallet address where funds are sent if the transfer fails or is refunded. Only present on off-ramp transfers created with a custom return address. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string source: oneOf: - description: The source of an on ramp transfer. example: id: bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: bank_account properties: achReference: description: The ACH reference string. example: ABC123456789 type: string amount: description: The source amount being transferred out of the source bank account. example: '100.00' type: string currency: description: The source bank account currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usd - eur - brl - mxn example: usd type: string id: description: The source bank account ID. example: bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 pattern: ^bankAccount_[a-z0-9]+$ type: string network: description: The source bank account network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach - wire - sepa - pix - swift - spei example: wire type: string sepaReference: description: The SEPA reference string. example: ABC123456789 type: string type: description: The source account type. enum: - bank_account example: bank_account type: string wireMessage: description: The message included with the wire transfer. example: Payment for invoice 12345 type: string required: - id - type - currency - network - amount title: Source Bank Account type: object - description: The source of an off ramp transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: amount: description: The source amount being transferred out of the source wallet. example: '100.00' type: string currency: description: The source wallet currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string id: description: The source wallet ID. example: wallet_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1 pattern: ^wallet_[a-z0-9]+$ type: string network: description: The source wallet network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: sol type: string type: description: The source type. enum: - wallet example: wallet type: string required: - id - type - currency - network - amount title: Source Wallet type: object status: description: The transfer status. See [Transfer Lifecycle](/concepts/transfers/lifecycle) for status definitions and transitions. enum: - pendingFunding - pendingReview - fundsReceived - processing - succeeded - undeliverable - returned - processingRefund - refundFailed - pendingRefundInformation - failed - canceled - refunded - unexpectedError - failedPrecondition - expired - unfunded example: pendingFunding type: string x-enumNames: - PENDING_FUNDING - PENDING_REVIEW - FUNDS_RECEIVED - PROCESSING - SUCCEEDED - UNDELIVERABLE - RETURNED - PROCESSING_REFUND - REFUND_FAILED - PENDING_REFUND_INFO - FAILED - CANCELED - REFUNDED - UNEXPECTED_ERROR - FAILED_PRECONDITION - EXPIRED - UNFUNDED statusHistory: description: Timeline of status transitions for this transfer, ascending by transitionedAt. example: - status: pendingFunding transitionedAt: '2026-06-20T14:03:21.000Z' - status: processing transitionedAt: '2026-06-20T14:05:10.000Z' items: description: A single transfer status transition. properties: status: enum: - pendingFunding - pendingReview - fundsReceived - processing - succeeded - undeliverable - returned - processingRefund - refundFailed - pendingRefundInformation - failed - canceled - refunded - unexpectedError - failedPrecondition - expired - unfunded type: string x-enumNames: - PENDING_FUNDING - PENDING_REVIEW - FUNDS_RECEIVED - PROCESSING - SUCCEEDED - UNDELIVERABLE - RETURNED - PROCESSING_REFUND - REFUND_FAILED - PENDING_REFUND_INFO - FAILED - CANCELED - REFUNDED - UNEXPECTED_ERROR - FAILED_PRECONDITION - EXPIRED - UNFUNDED transitionedAt: description: ISO 8601 timestamp of when the transfer entered this status. example: '2026-06-20T14:05:10.000Z' format: date-time type: string required: - status - transitionedAt title: Transfer Status History Entry type: object type: array type: description: The transfer type. enum: - on_ramp - off_ramp - fiat_to_fiat - unmatched_deposit - microdeposit example: on_ramp type: string updated: description: The last datetime the transfer was updated. example: '2021-01-01T00:00:00.000Z' format: date-time type: string required: - id - type - status - statusHistory - customer - source - destination - depositAccount - updated - created type: object CreateVirtualAccountRequestDto: properties: customerId: description: The customer who will own the virtual account. example: customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7 type: string destinationCurrency: description: The crypto currency deposited funds are converted into. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string integratorFeeBps: description: Integrator fee in basis points (1 bps = 0.01%). Defaults to 0 if not provided. example: '100' type: string network: description: The blockchain network the destination wallet is on. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - arbitrum - avalanche - base - ethereum - polygon - sol - tron example: ethereum type: string sourceCurrency: description: The fiat currency the virtual account accepts for deposits. enum: - usd - eur example: usd type: string walletAddress: description: The on-chain wallet address where converted crypto is sent. Must be valid for the selected network. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string required: - destinationCurrency - network - walletAddress - customerId - sourceCurrency type: object CreateWalletDto: properties: address: description: The wallet address on the specified network. Must be a valid address format for the network. example: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU minLength: 1 type: string customerId: description: The unique identifier of the customer who owns this wallet. example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string network: description: The blockchain network for this wallet. Must be a supported crypto network. enum: - arbitrum - avalanche - base - ethereum - polygon - sol - tron example: sol type: string required: - customerId - address - network type: object CustomerListResponseDto: properties: customers: description: Array of customer objects items: oneOf: - description: Response containing information about an individual customer. properties: createdAt: description: ISO 8601 formatted customer creation timestamp example: '2026-03-09T20:46:31.305Z' type: string dateOfBirth: description: The customer's date of birth in YYYY-MM-DD format (individual customers only). example: '1990-01-15' type: string email: description: Customer email address example: jane.smith@example.com type: string enabledVerificationProfiles: description: Which verification profile families this customer may onboard through. Set explicitly at creation — from the request when supplied, otherwise a snapshot of the application's families at that moment — and thereafter changed only by an explicit update, so it does not follow later changes to the application. Always a subset of the application's families. Distinct from `verificationProfiles`, which reports the evaluated profiles and their statuses. example: - a - c items: enum: - a - b - c - d type: string nullable: true type: array firstName: description: Customer first name (individual customers only) example: Jane type: string id: description: Customer ID example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string lastName: description: Customer last name (individual customers only) example: Smith type: string meta: additionalProperties: {} type: object personalInformation: description: Personal information for an individual customer, echoed back from the most recent submission. The tax identification number is omitted from responses for privacy. properties: accountPurpose: type: string accountPurposeDescription: type: string actingAsIntermediary: description: Whether the customer is acting as an intermediary on behalf of a third party. Required by some verification providers. example: false type: boolean countryOfBirth: description: The ISO3166-1 Alpha-3 country code of the country where the customer was born. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string employmentStatus: type: string expectedMonthlyPayments: type: string gender: type: string middleName: description: The customer's middle name. Required for some verification flows. example: James type: string nationality: description: The ISO3166-1 Alpha-3 country code of the customer's nationality. Required by some verification providers. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string occupationSocCode: description: The customer's occupation as a 6-digit Standard Occupational Classification (SOC) code, validated against the supported occupation list. Required for some verification flows. example: '151252' type: string residencyCountry: description: The ISO3166-1 Alpha-3 country code of the customer's country of residency. Often satisfied by the address country, but some verification providers require it as a separate attribute. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string sourceOfFunds: type: string stateOfBirth: description: The subdivision code of the state/province where the customer was born, without the country prefix (e.g. `JAL`, not `MX-JAL`). Requires `countryOfBirth`. Required by some verification providers. example: JAL type: string taxIdentificationNumberCountry: description: The ISO3166-1 Alpha-3 country code for the tax identification number. Required when providing tax identification information. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string taxIdentificationNumberDescription: description: Description of the tax identification number. Required when type is `other` type: string taxIdentificationNumberType: description: The type of tax identification number of the customer. Required when providing tax identification information. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference. example: ssn type: string type: object phone: description: Customer phone number example: '+14155550123' type: string statusDetails: description: Additional context on why the customer's verification reached its current status. example: message: Please re-upload a clear photo of the front and back of the director's ID and correct the tax ID number. reasons: - externalReason: Cannot validate ID — upload a photo of the ID that is clear reasonCode: poor_image_quality verificationProfiles: - kyb_profile_a - externalReason: The tax identification number is not in a valid format for the selected country and ID type. reasonCode: invalid_tax_identification_number verificationProfiles: - kyb_profile_a updatedAt: '2026-07-16T21:04:00Z' properties: message: type: string reasons: items: properties: externalReason: type: string reasonCode: type: string verificationProfiles: items: type: string type: array required: - reasonCode - verificationProfiles type: object type: array updatedAt: type: string required: - reasons - updatedAt type: object tosStatus: description: Customer Terms of Service acceptance status (incomplete | pending | approved). enum: - incomplete - pending - approved example: incomplete type: string x-enumNames: - Incomplete - Pending - Approved type: description: Customer type enum: - individual example: individual type: string updatedAt: description: ISO 8601 formatted customer update timestamp example: '2026-03-09T20:46:31.305Z' type: string verificationProfiles: description: The evaluated verification profiles for this customer and their statuses — what the customer is being assessed against right now, as opposed to `enabledVerificationProfiles`, which says which families they are permitted to use. Array of verification profiles. For individual customers, this will include kyc_profile_a. For business customers, this will include kyb_profile_a. See [KYC Flow](/concepts/onboarding/individual-kyc) for individuals or [KYB Flow](/concepts/onboarding/business-kyb) for businesses. See [Verification Profile](/concepts/onboarding/verification-profile) for individual status definitions and criteria breakdown or [Verification Profile](/concepts/onboarding/verification-profile) for business status definitions and criteria breakdown. example: - criteria: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document name: kyc_profile_a status: incomplete items: properties: criteria: description: The criteria for the verification profile. example: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document properties: complete: description: Completed fields. example: - email_address - phone_number - residential_address - tax_identification_number items: type: string type: array errors: description: The errors that occurred while verifying the fields. example: [] items: properties: detail: type: string name: enum: - email_verification - phone_verification - residential_address - identity_document - tax_identification_number - liveness_check - terms_of_service - email_address - phone_number - master_service_agreement - legal_name - trade_name - entity_type - entity_type_description - description - registered_address - operating_address - business_representatives - naics_code - website - incorporated_on - identification_number - registration_number - estimated_annual_revenue - expected_monthly_payments - account_purpose - account_purpose_description - source_of_funds - source_of_funds_description - is_dao - regulated_activities - regulated_activities_description - participates_in_regulated_financial_activity - regulated_financial_activity_description - money_services_description - compliance_screening_explanation - operates_in_prohibited_countries - incorporation_cert_document - incorporation_articles_document - shareholder_registry_document - proof_of_nature_of_business_document - proof_of_address_document - liveness_report_document - ownership_percentage - is_control_person - control_person_added - is_signer - relationship_established_at - title - employment_status - acting_as_intermediary - sex - country_of_birth - nationality - middle_name - occupation_soc_code - w8_ben_document - w9_document - state_of_birth - ip_address - ip_address_approved - expected_monthly_transaction_count - transaction_frequency - expected_counterparty_types - expected_geographies - w8_ben_e_document - corporate_resolution_document - source_of_funds_document - financial_statements_document - bank_statement_document - regulated_activity_document - flow_of_funds_document - kyc_b_approval - kyb_b_approval type: string required: - name type: object type: array pending: description: Pending fields. These fields are currently being verified. example: [] items: type: string type: array required: description: Required fields. These fields are required to be completed before the verification profile can be approved. example: - identity_document - liveness_report_document items: type: string type: array required: - complete - pending - required - errors type: object name: description: The name of the verification profile. enum: - kyc_profile_a - kyb_profile_a - ubo_kyc_profile_a - kyc_profile_b - kyb_profile_b - kyb_profile_c - kyc_profile_c - ubo_kyc_profile_c - kyb_profile_d - kyc_profile_d - ubo_kyc_profile_d example: kyc_profile_a type: string status: description: The status of the verification profile. enum: - incomplete - pending - approved - rejected - rejected_final - manual_review - resubmission_required example: incomplete type: string required: - name - status type: object type: array required: - id - enabledVerificationProfiles - verificationProfiles - tosStatus - createdAt - updatedAt - type title: Individual type: object - description: Response containing information about a business customer. properties: businessLegalName: description: Customer business legal name (business customers only) example: Acme Corporation Inc. type: string businessTradeName: description: Customer business trade name (business customers only) example: Acme Corp type: string createdAt: description: ISO 8601 formatted customer creation timestamp example: '2026-03-09T20:46:31.305Z' type: string email: description: Customer email address example: jane.smith@example.com type: string enabledVerificationProfiles: description: Which verification profile families this customer may onboard through. Set explicitly at creation — from the request when supplied, otherwise a snapshot of the application's families at that moment — and thereafter changed only by an explicit update, so it does not follow later changes to the application. Always a subset of the application's families. Distinct from `verificationProfiles`, which reports the evaluated profiles and their statuses. example: - a - c items: enum: - a - b - c - d type: string nullable: true type: array id: description: Customer ID example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string meta: additionalProperties: {} type: object phone: description: Customer phone number example: '+14155550123' type: string statusDetails: description: Additional context on why the customer's verification reached its current status. example: message: Please re-upload a clear photo of the front and back of the director's ID and correct the tax ID number. reasons: - externalReason: Cannot validate ID — upload a photo of the ID that is clear reasonCode: poor_image_quality verificationProfiles: - kyb_profile_a - externalReason: The tax identification number is not in a valid format for the selected country and ID type. reasonCode: invalid_tax_identification_number verificationProfiles: - kyb_profile_a updatedAt: '2026-07-16T21:04:00Z' properties: message: type: string reasons: items: properties: externalReason: type: string reasonCode: type: string verificationProfiles: items: type: string type: array required: - reasonCode - verificationProfiles type: object type: array updatedAt: type: string required: - reasons - updatedAt type: object tosStatus: description: Customer Terms of Service acceptance status (incomplete | pending | approved). enum: - incomplete - pending - approved example: incomplete type: string x-enumNames: - Incomplete - Pending - Approved type: description: Customer type enum: - business example: business type: string updatedAt: description: ISO 8601 formatted customer update timestamp example: '2026-03-09T20:46:31.305Z' type: string verificationProfiles: description: The evaluated verification profiles for this customer and their statuses — what the customer is being assessed against right now, as opposed to `enabledVerificationProfiles`, which says which families they are permitted to use. Array of verification profiles. For individual customers, this will include kyc_profile_a. For business customers, this will include kyb_profile_a. See [KYC Flow](/concepts/onboarding/individual-kyc) for individuals or [KYB Flow](/concepts/onboarding/business-kyb) for businesses. See [Verification Profile](/concepts/onboarding/verification-profile) for individual status definitions and criteria breakdown or [Verification Profile](/concepts/onboarding/verification-profile) for business status definitions and criteria breakdown. example: - criteria: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document name: kyc_profile_a status: incomplete items: properties: criteria: description: The criteria for the verification profile. example: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document properties: complete: description: Completed fields. example: - email_address - phone_number - residential_address - tax_identification_number items: type: string type: array errors: description: The errors that occurred while verifying the fields. example: [] items: properties: detail: type: string name: enum: - email_verification - phone_verification - residential_address - identity_document - tax_identification_number - liveness_check - terms_of_service - email_address - phone_number - master_service_agreement - legal_name - trade_name - entity_type - entity_type_description - description - registered_address - operating_address - business_representatives - naics_code - website - incorporated_on - identification_number - registration_number - estimated_annual_revenue - expected_monthly_payments - account_purpose - account_purpose_description - source_of_funds - source_of_funds_description - is_dao - regulated_activities - regulated_activities_description - participates_in_regulated_financial_activity - regulated_financial_activity_description - money_services_description - compliance_screening_explanation - operates_in_prohibited_countries - incorporation_cert_document - incorporation_articles_document - shareholder_registry_document - proof_of_nature_of_business_document - proof_of_address_document - liveness_report_document - ownership_percentage - is_control_person - control_person_added - is_signer - relationship_established_at - title - employment_status - acting_as_intermediary - sex - country_of_birth - nationality - middle_name - occupation_soc_code - w8_ben_document - w9_document - state_of_birth - ip_address - ip_address_approved - expected_monthly_transaction_count - transaction_frequency - expected_counterparty_types - expected_geographies - w8_ben_e_document - corporate_resolution_document - source_of_funds_document - financial_statements_document - bank_statement_document - regulated_activity_document - flow_of_funds_document - kyc_b_approval - kyb_b_approval type: string required: - name type: object type: array pending: description: Pending fields. These fields are currently being verified. example: [] items: type: string type: array required: description: Required fields. These fields are required to be completed before the verification profile can be approved. example: - identity_document - liveness_report_document items: type: string type: array required: - complete - pending - required - errors type: object name: description: The name of the verification profile. enum: - kyc_profile_a - kyb_profile_a - ubo_kyc_profile_a - kyc_profile_b - kyb_profile_b - kyb_profile_c - kyc_profile_c - ubo_kyc_profile_c - kyb_profile_d - kyc_profile_d - ubo_kyc_profile_d example: kyc_profile_a type: string status: description: The status of the verification profile. enum: - incomplete - pending - approved - rejected - rejected_final - manual_review - resubmission_required example: incomplete type: string required: - name - status type: object type: array required: - id - enabledVerificationProfiles - verificationProfiles - tosStatus - createdAt - updatedAt - type title: Business type: object type: array pagination: properties: hasNext: description: Whether there is a next page example: false type: boolean hasPrevious: description: Whether there is a previous page example: false type: boolean limit: description: Number of items per page example: 10 exclusiveMaximum: false exclusiveMinimum: false maximum: 100 minimum: 1 type: number page: description: Current page number example: 1 type: number total: description: Total number of items example: 1 type: number totalPages: description: Total number of pages example: 1 type: number required: - page - limit - total - totalPages - hasNext - hasPrevious type: object required: - customers - pagination type: object CustomerResponseDto: oneOf: - description: Response containing information about an individual customer. properties: createdAt: description: ISO 8601 formatted customer creation timestamp example: '2026-03-09T20:46:31.305Z' type: string dateOfBirth: description: The customer's date of birth in YYYY-MM-DD format (individual customers only). example: '1990-01-15' type: string email: description: Customer email address example: jane.smith@example.com type: string enabledVerificationProfiles: description: Which verification profile families this customer may onboard through. Set explicitly at creation — from the request when supplied, otherwise a snapshot of the application's families at that moment — and thereafter changed only by an explicit update, so it does not follow later changes to the application. Always a subset of the application's families. Distinct from `verificationProfiles`, which reports the evaluated profiles and their statuses. example: - a - c items: enum: - a - b - c - d type: string nullable: true type: array firstName: description: Customer first name (individual customers only) example: Jane type: string id: description: Customer ID example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string lastName: description: Customer last name (individual customers only) example: Smith type: string meta: additionalProperties: {} type: object personalInformation: description: Personal information for an individual customer, echoed back from the most recent submission. The tax identification number is omitted from responses for privacy. properties: accountPurpose: type: string accountPurposeDescription: type: string actingAsIntermediary: description: Whether the customer is acting as an intermediary on behalf of a third party. Required by some verification providers. example: false type: boolean countryOfBirth: description: The ISO3166-1 Alpha-3 country code of the country where the customer was born. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string employmentStatus: type: string expectedMonthlyPayments: type: string gender: type: string middleName: description: The customer's middle name. Required for some verification flows. example: James type: string nationality: description: The ISO3166-1 Alpha-3 country code of the customer's nationality. Required by some verification providers. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string occupationSocCode: description: The customer's occupation as a 6-digit Standard Occupational Classification (SOC) code, validated against the supported occupation list. Required for some verification flows. example: '151252' type: string residencyCountry: description: The ISO3166-1 Alpha-3 country code of the customer's country of residency. Often satisfied by the address country, but some verification providers require it as a separate attribute. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string sourceOfFunds: type: string stateOfBirth: description: The subdivision code of the state/province where the customer was born, without the country prefix (e.g. `JAL`, not `MX-JAL`). Requires `countryOfBirth`. Required by some verification providers. example: JAL type: string taxIdentificationNumberCountry: description: The ISO3166-1 Alpha-3 country code for the tax identification number. Required when providing tax identification information. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string taxIdentificationNumberDescription: description: Description of the tax identification number. Required when type is `other` type: string taxIdentificationNumberType: description: The type of tax identification number of the customer. Required when providing tax identification information. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference. example: ssn type: string type: object phone: description: Customer phone number example: '+14155550123' type: string statusDetails: description: Additional context on why the customer's verification reached its current status. example: message: Please re-upload a clear photo of the front and back of the director's ID and correct the tax ID number. reasons: - externalReason: Cannot validate ID — upload a photo of the ID that is clear reasonCode: poor_image_quality verificationProfiles: - kyb_profile_a - externalReason: The tax identification number is not in a valid format for the selected country and ID type. reasonCode: invalid_tax_identification_number verificationProfiles: - kyb_profile_a updatedAt: '2026-07-16T21:04:00Z' properties: message: type: string reasons: items: properties: externalReason: type: string reasonCode: type: string verificationProfiles: items: type: string type: array required: - reasonCode - verificationProfiles type: object type: array updatedAt: type: string required: - reasons - updatedAt type: object tosStatus: description: Customer Terms of Service acceptance status (incomplete | pending | approved). enum: - incomplete - pending - approved example: incomplete type: string x-enumNames: - Incomplete - Pending - Approved type: description: Customer type enum: - individual example: individual type: string updatedAt: description: ISO 8601 formatted customer update timestamp example: '2026-03-09T20:46:31.305Z' type: string verificationProfiles: description: The evaluated verification profiles for this customer and their statuses — what the customer is being assessed against right now, as opposed to `enabledVerificationProfiles`, which says which families they are permitted to use. Array of verification profiles. For individual customers, this will include kyc_profile_a. For business customers, this will include kyb_profile_a. See [KYC Flow](/concepts/onboarding/individual-kyc) for individuals or [KYB Flow](/concepts/onboarding/business-kyb) for businesses. See [Verification Profile](/concepts/onboarding/verification-profile) for individual status definitions and criteria breakdown or [Verification Profile](/concepts/onboarding/verification-profile) for business status definitions and criteria breakdown. example: - criteria: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document name: kyc_profile_a status: incomplete items: properties: criteria: description: The criteria for the verification profile. example: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document properties: complete: description: Completed fields. example: - email_address - phone_number - residential_address - tax_identification_number items: type: string type: array errors: description: The errors that occurred while verifying the fields. example: [] items: properties: detail: type: string name: enum: - email_verification - phone_verification - residential_address - identity_document - tax_identification_number - liveness_check - terms_of_service - email_address - phone_number - master_service_agreement - legal_name - trade_name - entity_type - entity_type_description - description - registered_address - operating_address - business_representatives - naics_code - website - incorporated_on - identification_number - registration_number - estimated_annual_revenue - expected_monthly_payments - account_purpose - account_purpose_description - source_of_funds - source_of_funds_description - is_dao - regulated_activities - regulated_activities_description - participates_in_regulated_financial_activity - regulated_financial_activity_description - money_services_description - compliance_screening_explanation - operates_in_prohibited_countries - incorporation_cert_document - incorporation_articles_document - shareholder_registry_document - proof_of_nature_of_business_document - proof_of_address_document - liveness_report_document - ownership_percentage - is_control_person - control_person_added - is_signer - relationship_established_at - title - employment_status - acting_as_intermediary - sex - country_of_birth - nationality - middle_name - occupation_soc_code - w8_ben_document - w9_document - state_of_birth - ip_address - ip_address_approved - expected_monthly_transaction_count - transaction_frequency - expected_counterparty_types - expected_geographies - w8_ben_e_document - corporate_resolution_document - source_of_funds_document - financial_statements_document - bank_statement_document - regulated_activity_document - flow_of_funds_document - kyc_b_approval - kyb_b_approval type: string required: - name type: object type: array pending: description: Pending fields. These fields are currently being verified. example: [] items: type: string type: array required: description: Required fields. These fields are required to be completed before the verification profile can be approved. example: - identity_document - liveness_report_document items: type: string type: array required: - complete - pending - required - errors type: object name: description: The name of the verification profile. enum: - kyc_profile_a - kyb_profile_a - ubo_kyc_profile_a - kyc_profile_b - kyb_profile_b - kyb_profile_c - kyc_profile_c - ubo_kyc_profile_c - kyb_profile_d - kyc_profile_d - ubo_kyc_profile_d example: kyc_profile_a type: string status: description: The status of the verification profile. enum: - incomplete - pending - approved - rejected - rejected_final - manual_review - resubmission_required example: incomplete type: string required: - name - status type: object type: array required: - id - enabledVerificationProfiles - verificationProfiles - tosStatus - createdAt - updatedAt - type title: Individual type: object - description: Response containing information about a business customer. properties: businessLegalName: description: Customer business legal name (business customers only) example: Acme Corporation Inc. type: string businessTradeName: description: Customer business trade name (business customers only) example: Acme Corp type: string createdAt: description: ISO 8601 formatted customer creation timestamp example: '2026-03-09T20:46:31.305Z' type: string email: description: Customer email address example: jane.smith@example.com type: string enabledVerificationProfiles: description: Which verification profile families this customer may onboard through. Set explicitly at creation — from the request when supplied, otherwise a snapshot of the application's families at that moment — and thereafter changed only by an explicit update, so it does not follow later changes to the application. Always a subset of the application's families. Distinct from `verificationProfiles`, which reports the evaluated profiles and their statuses. example: - a - c items: enum: - a - b - c - d type: string nullable: true type: array id: description: Customer ID example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string meta: additionalProperties: {} type: object phone: description: Customer phone number example: '+14155550123' type: string statusDetails: description: Additional context on why the customer's verification reached its current status. example: message: Please re-upload a clear photo of the front and back of the director's ID and correct the tax ID number. reasons: - externalReason: Cannot validate ID — upload a photo of the ID that is clear reasonCode: poor_image_quality verificationProfiles: - kyb_profile_a - externalReason: The tax identification number is not in a valid format for the selected country and ID type. reasonCode: invalid_tax_identification_number verificationProfiles: - kyb_profile_a updatedAt: '2026-07-16T21:04:00Z' properties: message: type: string reasons: items: properties: externalReason: type: string reasonCode: type: string verificationProfiles: items: type: string type: array required: - reasonCode - verificationProfiles type: object type: array updatedAt: type: string required: - reasons - updatedAt type: object tosStatus: description: Customer Terms of Service acceptance status (incomplete | pending | approved). enum: - incomplete - pending - approved example: incomplete type: string x-enumNames: - Incomplete - Pending - Approved type: description: Customer type enum: - business example: business type: string updatedAt: description: ISO 8601 formatted customer update timestamp example: '2026-03-09T20:46:31.305Z' type: string verificationProfiles: description: The evaluated verification profiles for this customer and their statuses — what the customer is being assessed against right now, as opposed to `enabledVerificationProfiles`, which says which families they are permitted to use. Array of verification profiles. For individual customers, this will include kyc_profile_a. For business customers, this will include kyb_profile_a. See [KYC Flow](/concepts/onboarding/individual-kyc) for individuals or [KYB Flow](/concepts/onboarding/business-kyb) for businesses. See [Verification Profile](/concepts/onboarding/verification-profile) for individual status definitions and criteria breakdown or [Verification Profile](/concepts/onboarding/verification-profile) for business status definitions and criteria breakdown. example: - criteria: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document name: kyc_profile_a status: incomplete items: properties: criteria: description: The criteria for the verification profile. example: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document properties: complete: description: Completed fields. example: - email_address - phone_number - residential_address - tax_identification_number items: type: string type: array errors: description: The errors that occurred while verifying the fields. example: [] items: properties: detail: type: string name: enum: - email_verification - phone_verification - residential_address - identity_document - tax_identification_number - liveness_check - terms_of_service - email_address - phone_number - master_service_agreement - legal_name - trade_name - entity_type - entity_type_description - description - registered_address - operating_address - business_representatives - naics_code - website - incorporated_on - identification_number - registration_number - estimated_annual_revenue - expected_monthly_payments - account_purpose - account_purpose_description - source_of_funds - source_of_funds_description - is_dao - regulated_activities - regulated_activities_description - participates_in_regulated_financial_activity - regulated_financial_activity_description - money_services_description - compliance_screening_explanation - operates_in_prohibited_countries - incorporation_cert_document - incorporation_articles_document - shareholder_registry_document - proof_of_nature_of_business_document - proof_of_address_document - liveness_report_document - ownership_percentage - is_control_person - control_person_added - is_signer - relationship_established_at - title - employment_status - acting_as_intermediary - sex - country_of_birth - nationality - middle_name - occupation_soc_code - w8_ben_document - w9_document - state_of_birth - ip_address - ip_address_approved - expected_monthly_transaction_count - transaction_frequency - expected_counterparty_types - expected_geographies - w8_ben_e_document - corporate_resolution_document - source_of_funds_document - financial_statements_document - bank_statement_document - regulated_activity_document - flow_of_funds_document - kyc_b_approval - kyb_b_approval type: string required: - name type: object type: array pending: description: Pending fields. These fields are currently being verified. example: [] items: type: string type: array required: description: Required fields. These fields are required to be completed before the verification profile can be approved. example: - identity_document - liveness_report_document items: type: string type: array required: - complete - pending - required - errors type: object name: description: The name of the verification profile. enum: - kyc_profile_a - kyb_profile_a - ubo_kyc_profile_a - kyc_profile_b - kyb_profile_b - kyb_profile_c - kyc_profile_c - ubo_kyc_profile_c - kyb_profile_d - kyc_profile_d - ubo_kyc_profile_d example: kyc_profile_a type: string status: description: The status of the verification profile. enum: - incomplete - pending - approved - rejected - rejected_final - manual_review - resubmission_required example: incomplete type: string required: - name - status type: object type: array required: - id - enabledVerificationProfiles - verificationProfiles - tosStatus - createdAt - updatedAt - type title: Business type: object DeleteBankAccountResponseDto: properties: ok: description: Indicates whether the deletion was successful example: true type: boolean required: - ok type: object DeleteBusinessRepresentativeResponseDto: properties: ok: description: Indicates whether the deletion was successful example: true type: boolean required: - ok type: object DeleteWalletResponseDto: properties: ok: description: Indicates whether the deletion was successful example: true type: boolean required: - ok type: object FaucetMintResponseDto: properties: address: type: string amount: type: string createdAt: type: string currency: enum: - SPHEREUSDC type: string id: description: Mint id. Poll GET /v2/sandbox/faucet/{id} for the tx hash. type: string network: enum: - ethereum - sol type: string status: description: 'pending: queued; submitted: sent to the chain; succeeded: confirmed on chain (txHash set); failed: not minted, request again with a new Idempotency-Key.' enum: - pending - submitted - succeeded - failed type: string txHash: nullable: true type: string required: - id - status - network - address - amount - currency - txHash - createdAt type: object GenerateFaceVerificationLinkResponseDto: properties: expiresAt: description: ISO 8601 formatted date and time of the face verification URL expiration example: '2026-03-09T20:46:31.305Z' type: string url: description: Hosted face verification URL example: https://in.sumsub.com/websdk/p/sbx_uq30ag1ov7oHZhmx type: string required: - url - expiresAt type: object GenerateKycUrlResponseDto: properties: customerId: description: The ID of the customer the KYC link belongs to example: customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7 type: string expiresAt: description: ISO 8601 formatted date and time of the KYC URL expiration. By default, links expire 4 weeks (28 days) after creation, but this default may change without notice - always rely on this field rather than assuming a fixed duration. example: '2026-03-09T20:46:31.305Z' type: string url: description: Hosted KYC URL example: https://in.sumsub.com/websdk/p/sbx_uq30ag1ov7oHZhmx type: string required: - customerId - url - expiresAt type: object GenerateTosLinkResponseDto: properties: expiresAt: description: ISO 8601 formatted date and time of the TOS link expiration example: '2026-03-09T20:46:31.305Z' type: string link: description: Terms of Service link URL example: https://spherepay.co/tos?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjdXN0b21lcl9lMDE2MzNjNWY1OTY0MThiOGU5ZTQzNDEyMzQ2OTk0YyIsImFwcGxpY2F0aW9uSWQiOiJhcHBsaWNhdGlvbl84NWM5ZmE2ZTFjMjk0YzJmOTA2NDcwNWFlYTE3Y2ZkMyIsImN1c3RvbWVyVHlwZSI6ImluZGl2aWR1YWwiLCJtc2FTdGF0dXMiOiJpbmNvbXBsZXRlIiwibXNhUmVxdWlyZWQiOmZhbHNlLCJpYXQiOjE3NjQwMzQwMDUsImV4cCI6MTc2NjQ1MzIwNX0.6z3976YqDxDr5LkMJxoZhw526cu1PGE3nFZtAE8vIfY type: string required: - link - expiresAt type: object GetQuoteResponseDto: properties: created: description: The datetime the quote was created. example: '2025-01-01T00:00:00.000Z' format: date-time type: string customerId: description: The customer ID. example: customer_d243ab2b1de4447d8a046d87fefe58cf type: string destination: properties: amount: description: The destination amount after exchange. example: '545.50' type: string currency: description: The destination currency. enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: brl type: string exchangeRate: description: The exchange rate applied to convert source to destination. example: '5.455' type: string network: description: The destination network. example: pix oneOf: - description: A blockchain network. enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: polygon type: string - enum: - wire - ach - achPush - achPull - achSameDay - swift - sepa - pix - spei - spei type: string required: - currency - network - amount - exchangeRate type: object expiresAt: description: The datetime when this quote expires. example: '2025-01-01T00:01:00.000Z' format: date-time type: string fees: properties: integratorFee: description: The integrator fee portion. example: bpsRate: '0' currency: usdc fixedAmount: '0.00' totalAmount: '0.00' properties: bpsAmount: description: The sum of the individually rounded percentage-based fee components. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: brl type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object platformFee: description: The platform fee portion. example: bpsRate: '20' currency: usdc fixedAmount: '0.00' totalAmount: '2.00' properties: bpsAmount: description: The sum of the individually rounded percentage-based fee components. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: brl type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object required: - integratorFee - platformFee type: object id: description: A unique identifier for the quote. example: quote_d243ab2b1de4447d8a046d87fefe58cf pattern: ^quote_[a-z0-9]+$ type: string quoteDurationSeconds: description: RFQ-only quote duration in seconds. example: 45 exclusiveMinimum: true minimum: 0 type: integer referenceSide: description: RFQ-only side whose amount was referenced for pricing. enum: - source - destination example: source type: string source: properties: amount: description: The source amount. example: '100.00' type: string currency: description: The source currency. enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: usdc type: string network: description: The source network. example: polygon oneOf: - description: A blockchain network. enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: polygon type: string - enum: - wire - ach - achPush - achPull - achSameDay - swift - sepa - pix - spei - spei type: string required: - currency - network - amount type: object status: description: The current status of the quote. enum: - active - used - expired example: active type: string type: description: The transfer type this quote is for. enum: - on_ramp - off_ramp - fiat_to_fiat example: off_ramp type: string updated: description: The datetime the quote was last updated. example: '2025-01-01T00:00:30.000Z' format: date-time type: string required: - id - status - type - customerId - fees - source - destination - expiresAt - created - updated type: object GetTransferResponseDto: properties: created: description: The datetime the transfer was created. example: '2021-01-01T00:00:00.000Z' format: date-time type: string customer: description: The customer ID. example: customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7 type: string depositAccount: oneOf: - description: The deposit bank account for an on ramp transfer. properties: bankDetails: properties: accountHolderName: description: The name of the bank account holder that the source funds will be transferred to. example: John Doe type: string accountNumber: description: The account number of the bank account, used for wires, ACH transfers and other applicable networks. example: '1234567890' type: string accountType: description: 'The type of bank account: savings or checking.' enum: - savings - checking example: savings type: string bankAddress: description: The address of the deposit bank account. example: 123 Main St, Anytown, USA type: string bankName: description: The name of the bank that the source funds will be transferred to. example: Bank of America type: string beneficiaryAddress: description: The address of the beneficiary that will receive the funds. example: 123 Main St, Anytown, USA type: string bic: description: The BIC of the bank account, used for SEPA transfers and other applicable networks. example: '1234567890' type: string brCode: description: The PIX BR code for on-ramp payments. Encode this as a QR code for the customer to scan and pay. example: 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string clabe: description: The CLABE of the deposit bank account, used for SPEI transfers in Mexico. example: '012345678901234567' type: string iban: description: The IBAN of the bank account, used for SEPA transfers and other applicable networks. example: '1234567890' type: string memo: description: The memo of the transfer. This must be provided when initiating wire, ACH and SEPA transfers. This is the memo that will be used to identify the transfer to the deposit account. example: BBE6C7EB4A3F type: string pixKey: description: The PIX key of the deposit bank account, used for PIX transfers. example: '+5511999999999' type: string routingNumber: description: The routing number of the bank account, used for wires, ACH transfers and other applicable networks. example: '1234567890' type: string type: object type: description: The type of the deposit account. enum: - bank_account example: bank_account type: string required: - type - bankDetails title: Deposit Bank Account type: object - description: The deposit wallet for an off ramp transfer. properties: type: description: The type of the deposit account. enum: - wallet example: wallet type: string walletDetails: properties: address: description: The address of the wallet that the source funds will be transferred to. example: '0x1234567890abcdef1234567890abcdef12345678' type: string currency: description: The currency that should be transferred to the wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string network: description: The network that the source funds will be transferred on. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: ethereum type: string required: - address - currency - network type: object required: - type - walletDetails title: Deposit Wallet type: object destination: oneOf: - description: The destination of an `On-ramp` transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: amount: type: string currency: description: The destination wallet currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string exchangeRate: description: The exchange rate applied to the destination amount when converting the source amount to the destination currency. example: '5.455' type: string id: description: The destination wallet ID. example: wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2 pattern: ^wallet_[a-z0-9]+$ type: string network: description: The destination wallet network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: sol type: string type: description: The destination wallet type. enum: - wallet example: wallet type: string required: - id - type - currency - network title: Destination Wallet type: object - description: The destination of an `Off-ramp` transfer. properties: achReference: description: The ACH reference string. example: ABC123456789 type: string amount: description: The destination amount being transferred to the bank account. example: '98.90' type: string currency: description: The destination bank account currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usd - eur - brl - mxn example: usd type: string exchangeRate: description: The exchange rate applied to the destination amount when converting the source amount to the destination currency. example: '5.455' type: string id: description: The destination bank account ID. example: bankAccount_f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3 pattern: ^bankAccount_[a-z0-9]+$ type: string network: description: The destination bank account network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach - wire - sepa - pix - swift - spei example: wire type: string sepaReference: description: The SEPA reference string. example: ABC123456789 type: string type: description: The destination account type. enum: - bank_account example: bank_account type: string wireMessage: description: The message included with the wire transfer. example: Payment for invoice 12345 type: string required: - id - type - currency - network title: Destination Bank Account type: object externalId: description: The external reference (not stored as unique). example: merchant_ref_123 type: string fees: description: Fee breakdown for the transfer. For floating-rate BRL transfers, this is omitted until settlement is complete. properties: integratorFee: description: The integrator fee, this is the portion of the fee that the API integrator will receive. example: bpsAmount: '0.10' bpsRate: '10' currency: usd fixedAmount: '1.00' totalAmount: '1.10' properties: bpsAmount: description: The dollar amount derived from the BPS rate. Equal to totalAmount minus fixedAmount. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc - usd - eur - brl - mxn example: usd type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object platformFee: description: The platform fee, this is the portion of the fee that Sphere will receive. example: bpsAmount: '0.10' bpsRate: '10' currency: usd fixedAmount: '2.00' totalAmount: '2.10' properties: bpsAmount: description: The dollar amount derived from the BPS rate. Equal to totalAmount minus fixedAmount. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc - usd - eur - brl - mxn example: usd type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object required: - integratorFee - platformFee type: object fundingDeadline: description: The datetime by which the deposit must arrive into the deposit account. A later deposit is not applied to this transfer. Present only on bank-funded transfers that have a deadline. Distinct from `quote.expiresAt`, which is the expiry of the quoted rate. example: '2026-11-03T12:00:00.000Z' format: date-time type: string id: description: A unique identifier for transfer. example: payout_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 pattern: ^payout_[a-z0-9]{32}$ type: string paymentDescription: description: A free-text description of the payment purpose. Present on third-party off-ramp transfers. example: INV-2026-004 - Q1 software services type: string paymentReason: description: The reason for the payment. Present on BRL transfers and third-party off-ramp transfers. example: professional_services type: string quote: description: The quote used for this transfer, if any. When present, the locked exchange rate from the quote was applied to the destination amount and exchange rate. properties: expiresAt: description: The datetime the quote expires. example: '2021-01-01T00:00:00.000Z' format: date-time type: string id: description: The unique identifier for the quote used for this transfer. example: quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string required: - id - expiresAt type: object returnAddress: description: Crypto wallet address where funds are sent if the transfer fails or is refunded. Only present on off-ramp transfers created with a custom return address. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string source: oneOf: - description: The source of an on ramp transfer. example: id: bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: bank_account properties: achReference: description: The ACH reference string. example: ABC123456789 type: string amount: description: The source amount being transferred out of the source bank account. example: '100.00' type: string currency: description: The source bank account currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usd - eur - brl - mxn example: usd type: string id: description: The source bank account ID. example: bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 pattern: ^bankAccount_[a-z0-9]+$ type: string network: description: The source bank account network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach - wire - sepa - pix - swift - spei example: wire type: string sepaReference: description: The SEPA reference string. example: ABC123456789 type: string type: description: The source account type. enum: - bank_account example: bank_account type: string wireMessage: description: The message included with the wire transfer. example: Payment for invoice 12345 type: string required: - id - type - currency - network - amount title: Source Bank Account type: object - description: The source of an off ramp transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: amount: description: The source amount being transferred out of the source wallet. example: '100.00' type: string currency: description: The source wallet currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string id: description: The source wallet ID. example: wallet_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1 pattern: ^wallet_[a-z0-9]+$ type: string network: description: The source wallet network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: sol type: string type: description: The source type. enum: - wallet example: wallet type: string required: - id - type - currency - network - amount title: Source Wallet type: object status: description: The transfer status. See [Transfer Lifecycle](/concepts/transfers/lifecycle) for status definitions and transitions. enum: - pendingFunding - pendingReview - fundsReceived - processing - succeeded - undeliverable - returned - processingRefund - refundFailed - pendingRefundInformation - failed - canceled - refunded - unexpectedError - failedPrecondition - expired - unfunded example: pendingFunding type: string x-enumNames: - PENDING_FUNDING - PENDING_REVIEW - FUNDS_RECEIVED - PROCESSING - SUCCEEDED - UNDELIVERABLE - RETURNED - PROCESSING_REFUND - REFUND_FAILED - PENDING_REFUND_INFO - FAILED - CANCELED - REFUNDED - UNEXPECTED_ERROR - FAILED_PRECONDITION - EXPIRED - UNFUNDED statusHistory: description: Timeline of status transitions for this transfer, ascending by transitionedAt. example: - status: pendingFunding transitionedAt: '2026-06-20T14:03:21.000Z' - status: processing transitionedAt: '2026-06-20T14:05:10.000Z' items: description: A single transfer status transition. properties: status: enum: - pendingFunding - pendingReview - fundsReceived - processing - succeeded - undeliverable - returned - processingRefund - refundFailed - pendingRefundInformation - failed - canceled - refunded - unexpectedError - failedPrecondition - expired - unfunded type: string x-enumNames: - PENDING_FUNDING - PENDING_REVIEW - FUNDS_RECEIVED - PROCESSING - SUCCEEDED - UNDELIVERABLE - RETURNED - PROCESSING_REFUND - REFUND_FAILED - PENDING_REFUND_INFO - FAILED - CANCELED - REFUNDED - UNEXPECTED_ERROR - FAILED_PRECONDITION - EXPIRED - UNFUNDED transitionedAt: description: ISO 8601 timestamp of when the transfer entered this status. example: '2026-06-20T14:05:10.000Z' format: date-time type: string required: - status - transitionedAt title: Transfer Status History Entry type: object type: array tracking: description: Tracking references for the transfer. Only included when at least one reference exists. properties: destination: description: Tracking references for the destination side of the transfer. properties: imad: description: The Input Message Accountability Data (IMAD) assigned by the Federal Reserve to uniquely identify a wire transfer. example: 20250224MMQFMP0B000012 type: string omad: description: The OMAD of a wire transfer (offramp WIRE only). example: '123456789012345678901234' type: string refundReferenceId: description: The provider refund / return reference identifying the movement that sent funds back. Present on the refund side; may also appear on the source side for transfers refunded before the refund side existed. example: 010F2712624525KD type: string speiTrackingKey: description: The SPEI clave de rastreo assigned to track a SPEI transfer in Mexico. Present on the source side of MXN pay-ins. example: CR20260716TITAN0000000000000000001 type: string traceNumber: description: The ACH trace number assigned by the originating bank to track the transfer through the ACH network. example: '021000021234567' type: string transactionId: description: The on-chain transaction hash. example: 4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b type: string uetr: description: The Unique End-to-End Transaction Reference (UETR) assigned to track a SEPA or SWIFT transfer. example: 097B365480122XK9 type: string type: object refund: description: Tracking references for the refund leg of the transfer, when funds have been sent back. properties: imad: description: The Input Message Accountability Data (IMAD) assigned by the Federal Reserve to uniquely identify a wire transfer. example: 20250224MMQFMP0B000012 type: string omad: description: The OMAD of a wire transfer (offramp WIRE only). example: '123456789012345678901234' type: string refundReferenceId: description: The provider refund / return reference identifying the movement that sent funds back. Present on the refund side; may also appear on the source side for transfers refunded before the refund side existed. example: 010F2712624525KD type: string speiTrackingKey: description: The SPEI clave de rastreo assigned to track a SPEI transfer in Mexico. Present on the source side of MXN pay-ins. example: CR20260716TITAN0000000000000000001 type: string traceNumber: description: The ACH trace number assigned by the originating bank to track the transfer through the ACH network. example: '021000021234567' type: string transactionId: description: The on-chain transaction hash. example: 4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b type: string uetr: description: The Unique End-to-End Transaction Reference (UETR) assigned to track a SEPA or SWIFT transfer. example: 097B365480122XK9 type: string type: object source: description: Tracking references for the source side of the transfer. properties: imad: description: The Input Message Accountability Data (IMAD) assigned by the Federal Reserve to uniquely identify a wire transfer. example: 20250224MMQFMP0B000012 type: string omad: description: The OMAD of a wire transfer (offramp WIRE only). example: '123456789012345678901234' type: string refundReferenceId: description: The provider refund / return reference identifying the movement that sent funds back. Present on the refund side; may also appear on the source side for transfers refunded before the refund side existed. example: 010F2712624525KD type: string speiTrackingKey: description: The SPEI clave de rastreo assigned to track a SPEI transfer in Mexico. Present on the source side of MXN pay-ins. example: CR20260716TITAN0000000000000000001 type: string traceNumber: description: The ACH trace number assigned by the originating bank to track the transfer through the ACH network. example: '021000021234567' type: string transactionId: description: The on-chain transaction hash. example: 4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b type: string uetr: description: The Unique End-to-End Transaction Reference (UETR) assigned to track a SEPA or SWIFT transfer. example: 097B365480122XK9 type: string type: object type: object type: description: The transfer type. enum: - on_ramp - off_ramp - fiat_to_fiat - unmatched_deposit - microdeposit example: on_ramp type: string updated: description: The last datetime the transfer was updated. example: '2021-01-01T00:00:00.000Z' format: date-time type: string required: - id - type - status - statusHistory - customer - source - destination - depositAccount - updated - created type: object ListBusinessRepresentativesResponseDto: properties: data: items: properties: address: description: The business representative's residential address. properties: city: type: string country: type: string line1: type: string line2: type: string postalCode: type: string state: type: string type: object createdAt: description: The date and time the business representative was created. example: '2026-03-10T00:00:08.986Z' type: string customerId: description: Customer ID example: customer_2f283221a9d44ada800ac7f11f640402 type: string dateOfBirth: description: The business representative's date of birth in YYYY-MM-DD format. example: '1985-03-12' type: string email: description: Email address example: james.wilson@acmecorp.example.com type: string firstName: description: The business representative's legal first name. example: James type: string id: description: Business Representative ID example: associatedPerson_d972d2f70b9f4d3c8d7cfb32593f395b type: string lastName: description: The business representative's legal last name. example: Wilson type: string phone: description: Phone number example: '+13125559876' type: string representationDetails: description: Representation details properties: ownershipPercentage: description: The ownership percentage of the business representative. example: '50' type: string relationshipEstablishedAt: description: The date the business representative was established in the company. example: '2020-03-15' type: string roles: description: The roles of the business representative. example: - ubo items: enum: - ubo - control_person - signer - director type: string type: array title: description: The title of the business representative. example: CEO type: string required: - roles type: object type: description: Customer type enum: - individual example: individual type: string updatedAt: description: The date and time the business representative was last updated. example: '2026-03-10T00:00:08.986Z' type: string verificationProfiles: description: Array of verification profiles for the business representative. example: - criteria: complete: - email_address - phone_number - residential_address - tax_identification_number - ownership_percentage - is_control_person - is_signer - relationship_established_at - title errors: [] pending: [] required: - identity_document - liveness_report_document - proof_of_address_document name: ubo_kyc_profile_a status: incomplete items: properties: criteria: description: The criteria for the verification profile. example: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document properties: complete: description: Completed fields. example: - email_address - phone_number - residential_address - tax_identification_number items: type: string type: array errors: description: The errors that occurred while verifying the fields. example: [] items: properties: detail: type: string name: enum: - email_verification - phone_verification - residential_address - identity_document - tax_identification_number - liveness_check - terms_of_service - email_address - phone_number - master_service_agreement - legal_name - trade_name - entity_type - entity_type_description - description - registered_address - operating_address - business_representatives - naics_code - website - incorporated_on - identification_number - registration_number - estimated_annual_revenue - expected_monthly_payments - account_purpose - account_purpose_description - source_of_funds - source_of_funds_description - is_dao - regulated_activities - regulated_activities_description - participates_in_regulated_financial_activity - regulated_financial_activity_description - money_services_description - compliance_screening_explanation - operates_in_prohibited_countries - incorporation_cert_document - incorporation_articles_document - shareholder_registry_document - proof_of_nature_of_business_document - proof_of_address_document - liveness_report_document - ownership_percentage - is_control_person - control_person_added - is_signer - relationship_established_at - title - employment_status - acting_as_intermediary - sex - country_of_birth - nationality - middle_name - occupation_soc_code - w8_ben_document - w9_document - state_of_birth - ip_address - ip_address_approved - expected_monthly_transaction_count - transaction_frequency - expected_counterparty_types - expected_geographies - w8_ben_e_document - corporate_resolution_document - source_of_funds_document - financial_statements_document - bank_statement_document - regulated_activity_document - flow_of_funds_document - kyc_b_approval - kyb_b_approval type: string required: - name type: object type: array pending: description: Pending fields. These fields are currently being verified. example: [] items: type: string type: array required: description: Required fields. These fields are required to be completed before the verification profile can be approved. example: - identity_document - liveness_report_document items: type: string type: array required: - complete - pending - required - errors type: object name: description: The name of the verification profile. enum: - kyc_profile_a - kyb_profile_a - ubo_kyc_profile_a - kyc_profile_b - kyb_profile_b - kyb_profile_c - kyc_profile_c - ubo_kyc_profile_c - kyb_profile_d - kyc_profile_d - ubo_kyc_profile_d example: kyc_profile_a type: string status: description: The status of the verification profile. enum: - incomplete - pending - approved - rejected - rejected_final - manual_review - resubmission_required example: incomplete type: string required: - name - status type: object type: array required: - id - customerId - type - verificationProfiles - createdAt - updatedAt type: object type: array pagination: properties: hasNext: description: Whether there is a next page example: false type: boolean hasPrevious: description: Whether there is a previous page example: false type: boolean limit: description: Number of items per page example: 10 exclusiveMaximum: false exclusiveMinimum: false maximum: 100 minimum: 1 type: number page: description: Current page number example: 1 type: number total: description: Total number of items example: 1 type: number totalPages: description: Total number of pages example: 1 type: number required: - page - limit - total - totalPages - hasNext - hasPrevious type: object required: - data - pagination type: object ListOffloaderWalletsResponseDto: properties: data: description: Array of offloader wallet objects. items: description: See the [Offloader Wallets guide](/concepts/automation/offloader-wallets). properties: address: description: The on-chain deposit address for the offloader wallet. Send crypto to this address to trigger automatic conversion. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string created: description: Timestamp when the offloader wallet was created (ISO 8601). example: '2024-06-15T10:30:00.000Z' type: string currency: description: The crypto currency the offloader wallet accepts for deposits. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string customerId: description: The customer who owns the offloader wallet. example: customer_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string destination: description: The bank account destination where converted funds are sent. See [Bank Accounts guide](/concepts/transfers/bank-accounts). example: achReference: REF123 bankAccountId: bankAccount_6221e8d4299f4a889bd882255e92f581 currency: usd network: ach oneOf: - properties: achReference: description: Reference sent to the receiving institution with ACH transfers, 1-10 characters. example: REF123 maxLength: 10 minLength: 1 type: string bankAccountId: description: The ID of the bank account that converted funds will be sent to. See [Bank Accounts guide](/concepts/transfers/bank-accounts). example: bankAccount_6221e8d4299f4a889bd882255e92f581 type: string currency: description: The fiat currency the crypto will be converted into. enum: - usd example: usd type: string network: description: The banking network used to deliver funds to the destination account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach example: ach type: string required: - bankAccountId - currency - network title: ACH type: object - properties: bankAccountId: description: The ID of the bank account that converted funds will be sent to. See [Bank Accounts guide](/concepts/transfers/bank-accounts). example: bankAccount_6221e8d4299f4a889bd882255e92f581 type: string currency: description: The fiat currency the crypto will be converted into. enum: - usd example: usd type: string network: description: The banking network used to deliver funds to the destination account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - wire example: wire type: string wireMessage: description: Message sent to the receiving institution with wire transfers, 1-105 characters. example: 'Invoice #1024' maxLength: 105 minLength: 1 type: string required: - bankAccountId - currency - network title: Wire type: object - properties: bankAccountId: description: The ID of the bank account that converted funds will be sent to. See [Bank Accounts guide](/concepts/transfers/bank-accounts). example: bankAccount_6221e8d4299f4a889bd882255e92f581 type: string currency: description: The fiat currency the crypto will be converted into. enum: - eur example: eur type: string network: description: The banking network used to deliver funds to the destination account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sepa example: sepa type: string sepaReference: description: Reference sent to the receiving institution with SEPA transfers, 6-140 characters. example: INV-2024-001 maxLength: 140 minLength: 6 type: string required: - bankAccountId - currency - network title: SEPA type: object fees: description: Fee configuration for the offloader wallet, including integrator and platform fees. example: integratorFee: bpsRate: '100' currency: usdc platformFee: bpsRate: '30' currency: usdc properties: integratorFee: properties: bpsRate: description: Integrator fee rate in basis points (1 bps = 0.01%). example: '100' type: string currency: description: The currency the integrator fee is denominated in (matches the wallet deposit currency). enum: - usdc - usdt - eurc example: usdc type: string required: - bpsRate - currency type: object platformFee: properties: bpsRate: description: Platform fee rate in basis points (1 bps = 0.01%). example: '30' type: string currency: description: The currency the platform fee is denominated in (matches the wallet deposit currency). enum: - usdc - usdt - eurc example: usdc type: string required: - bpsRate - currency type: object required: - integratorFee - platformFee type: object id: description: Unique identifier for the offloader wallet. example: wallet_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string network: description: The blockchain network the offloader wallet is on. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - ethereum - arbitrum - polygon - base - avalanche - tron example: ethereum type: string returnAddress: description: Crypto address where funds are returned on failed transactions. Must be valid for the wallet network. Null if not configured. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string status: description: Lifecycle status of the offloader wallet. `active` accepts deposits and settles; `deactivated` no longer settles. enum: - active - deactivated example: active type: string x-enumNames: - ACTIVE - DEACTIVATED updated: description: Timestamp when the offloader wallet was last updated (ISO 8601). example: '2024-06-15T12:00:00.000Z' type: string required: - id - customerId - address - currency - network - status - destination - fees - created - updated type: object type: array pagination: properties: hasNext: description: Whether there is a next page example: false type: boolean hasPrevious: description: Whether there is a previous page example: false type: boolean limit: description: Number of items per page example: 10 exclusiveMaximum: false exclusiveMinimum: false maximum: 100 minimum: 1 type: number page: description: Current page number example: 1 type: number total: description: Total number of items example: 1 type: number totalPages: description: Total number of pages example: 1 type: number required: - page - limit - total - totalPages - hasNext - hasPrevious type: object required: - data - pagination type: object ListQuotesResponseDto: properties: data: description: The list of quotes for the current page. items: properties: created: description: The datetime the quote was created. example: '2025-01-01T00:00:00.000Z' format: date-time type: string customerId: description: The customer ID. example: customer_d243ab2b1de4447d8a046d87fefe58cf type: string destination: properties: amount: description: The destination amount after exchange. example: '545.50' type: string currency: description: The destination currency. enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: brl type: string exchangeRate: description: The exchange rate applied to convert source to destination. example: '5.455' type: string network: description: The destination network. example: pix oneOf: - description: A blockchain network. enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: polygon type: string - enum: - wire - ach - achPush - achPull - achSameDay - swift - sepa - pix - spei - spei type: string required: - currency - network - amount - exchangeRate type: object expiresAt: description: The datetime when this quote expires. example: '2025-01-01T00:01:00.000Z' format: date-time type: string fees: properties: integratorFee: description: The integrator fee portion. example: bpsRate: '0' currency: usdc fixedAmount: '0.00' totalAmount: '0.00' properties: bpsAmount: description: The sum of the individually rounded percentage-based fee components. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: brl type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object platformFee: description: The platform fee portion. example: bpsRate: '20' currency: usdc fixedAmount: '0.00' totalAmount: '2.00' properties: bpsAmount: description: The sum of the individually rounded percentage-based fee components. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: brl type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object required: - integratorFee - platformFee type: object id: description: A unique identifier for the quote. example: quote_d243ab2b1de4447d8a046d87fefe58cf pattern: ^quote_[a-z0-9]+$ type: string quoteDurationSeconds: description: RFQ-only quote duration in seconds. example: 45 exclusiveMinimum: true minimum: 0 type: integer referenceSide: description: RFQ-only side whose amount was referenced for pricing. enum: - source - destination example: source type: string source: properties: amount: description: The source amount. example: '100.00' type: string currency: description: The source currency. enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn example: usdc type: string network: description: The source network. example: polygon oneOf: - description: A blockchain network. enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: polygon type: string - enum: - wire - ach - achPush - achPull - achSameDay - swift - sepa - pix - spei - spei type: string required: - currency - network - amount type: object status: description: The current status of the quote. enum: - active - used - expired example: active type: string type: description: The transfer type this quote is for. enum: - on_ramp - off_ramp - fiat_to_fiat example: off_ramp type: string updated: description: The datetime the quote was last updated. example: '2025-01-01T00:00:30.000Z' format: date-time type: string required: - id - status - type - customerId - fees - source - destination - expiresAt - created - updated type: object type: array hasNext: description: Whether there is a next page example: false type: boolean hasPrevious: description: Whether there is a previous page example: false type: boolean limit: description: Number of items per page example: 10 exclusiveMaximum: false exclusiveMinimum: false maximum: 100 minimum: 1 type: number page: description: Current page number example: 1 type: number total: description: Total number of items example: 1 type: number totalPages: description: Total number of pages example: 1 type: number required: - page - limit - total - totalPages - hasNext - hasPrevious - data type: object ListTransfersResponseDto: properties: data: description: Array of transfer objects. example: [] items: properties: created: description: The datetime the transfer was created. example: '2021-01-01T00:00:00.000Z' format: date-time type: string customer: description: The customer ID. example: customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7 type: string depositAccount: oneOf: - description: The deposit bank account for an on ramp transfer. properties: bankDetails: properties: accountHolderName: description: The name of the bank account holder that the source funds will be transferred to. example: John Doe type: string accountNumber: description: The account number of the bank account, used for wires, ACH transfers and other applicable networks. example: '1234567890' type: string accountType: description: 'The type of bank account: savings or checking.' enum: - savings - checking example: savings type: string bankAddress: description: The address of the deposit bank account. example: 123 Main St, Anytown, USA type: string bankName: description: The name of the bank that the source funds will be transferred to. example: Bank of America type: string beneficiaryAddress: description: The address of the beneficiary that will receive the funds. example: 123 Main St, Anytown, USA type: string bic: description: The BIC of the bank account, used for SEPA transfers and other applicable networks. example: '1234567890' type: string brCode: description: The PIX BR code for on-ramp payments. Encode this as a QR code for the customer to scan and pay. example: 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string clabe: description: The CLABE of the deposit bank account, used for SPEI transfers in Mexico. example: '012345678901234567' type: string iban: description: The IBAN of the bank account, used for SEPA transfers and other applicable networks. example: '1234567890' type: string memo: description: The memo of the transfer. This must be provided when initiating wire, ACH and SEPA transfers. This is the memo that will be used to identify the transfer to the deposit account. example: BBE6C7EB4A3F type: string pixKey: description: The PIX key of the deposit bank account, used for PIX transfers. example: '+5511999999999' type: string routingNumber: description: The routing number of the bank account, used for wires, ACH transfers and other applicable networks. example: '1234567890' type: string type: object type: description: The type of the deposit account. enum: - bank_account example: bank_account type: string required: - type - bankDetails title: Deposit Bank Account type: object - description: The deposit wallet for an off ramp transfer. properties: type: description: The type of the deposit account. enum: - wallet example: wallet type: string walletDetails: properties: address: description: The address of the wallet that the source funds will be transferred to. example: '0x1234567890abcdef1234567890abcdef12345678' type: string currency: description: The currency that should be transferred to the wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string network: description: The network that the source funds will be transferred on. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: ethereum type: string required: - address - currency - network type: object required: - type - walletDetails title: Deposit Wallet type: object destination: oneOf: - description: The destination of an `On-ramp` transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: amount: type: string currency: description: The destination wallet currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string exchangeRate: description: The exchange rate applied to the destination amount when converting the source amount to the destination currency. example: '5.455' type: string id: description: The destination wallet ID. example: wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2 pattern: ^wallet_[a-z0-9]+$ type: string network: description: The destination wallet network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: sol type: string type: description: The destination wallet type. enum: - wallet example: wallet type: string required: - id - type - currency - network title: Destination Wallet type: object - description: The destination of an `Off-ramp` transfer. properties: achReference: description: The ACH reference string. example: ABC123456789 type: string amount: description: The destination amount being transferred to the bank account. example: '98.90' type: string currency: description: The destination bank account currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usd - eur - brl - mxn example: usd type: string exchangeRate: description: The exchange rate applied to the destination amount when converting the source amount to the destination currency. example: '5.455' type: string id: description: The destination bank account ID. example: bankAccount_f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3 pattern: ^bankAccount_[a-z0-9]+$ type: string network: description: The destination bank account network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach - wire - sepa - pix - swift - spei example: wire type: string sepaReference: description: The SEPA reference string. example: ABC123456789 type: string type: description: The destination account type. enum: - bank_account example: bank_account type: string wireMessage: description: The message included with the wire transfer. example: Payment for invoice 12345 type: string required: - id - type - currency - network title: Destination Bank Account type: object externalId: description: The external reference (not stored as unique). example: merchant_ref_123 type: string fees: description: Fee breakdown for the transfer. For floating-rate BRL transfers, this is omitted until settlement is complete. properties: integratorFee: description: The integrator fee, this is the portion of the fee that the API integrator will receive. example: bpsAmount: '0.10' bpsRate: '10' currency: usd fixedAmount: '1.00' totalAmount: '1.10' properties: bpsAmount: description: The dollar amount derived from the BPS rate. Equal to totalAmount minus fixedAmount. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc - usd - eur - brl - mxn example: usd type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object platformFee: description: The platform fee, this is the portion of the fee that Sphere will receive. example: bpsAmount: '0.10' bpsRate: '10' currency: usd fixedAmount: '2.00' totalAmount: '2.10' properties: bpsAmount: description: The dollar amount derived from the BPS rate. Equal to totalAmount minus fixedAmount. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: The currency of the fee. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc - usd - eur - brl - mxn example: usd type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object required: - integratorFee - platformFee type: object fundingDeadline: description: The datetime by which the deposit must arrive into the deposit account. A later deposit is not applied to this transfer. Present only on bank-funded transfers that have a deadline. Distinct from `quote.expiresAt`, which is the expiry of the quoted rate. example: '2026-11-03T12:00:00.000Z' format: date-time type: string id: description: A unique identifier for transfer. example: payout_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 pattern: ^payout_[a-z0-9]{32}$ type: string paymentDescription: description: A free-text description of the payment purpose. Present on third-party off-ramp transfers. example: INV-2026-004 - Q1 software services type: string paymentReason: description: The reason for the payment. Present on BRL transfers and third-party off-ramp transfers. example: professional_services type: string quote: description: The quote used for this transfer, if any. When present, the locked exchange rate from the quote was applied to the destination amount and exchange rate. properties: expiresAt: description: The datetime the quote expires. example: '2021-01-01T00:00:00.000Z' format: date-time type: string id: description: The unique identifier for the quote used for this transfer. example: quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string required: - id - expiresAt type: object returnAddress: description: Crypto wallet address where funds are sent if the transfer fails or is refunded. Only present on off-ramp transfers created with a custom return address. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string source: oneOf: - description: The source of an on ramp transfer. example: id: bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: bank_account properties: achReference: description: The ACH reference string. example: ABC123456789 type: string amount: description: The source amount being transferred out of the source bank account. example: '100.00' type: string currency: description: The source bank account currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usd - eur - brl - mxn example: usd type: string id: description: The source bank account ID. example: bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 pattern: ^bankAccount_[a-z0-9]+$ type: string network: description: The source bank account network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach - wire - sepa - pix - swift - spei example: wire type: string sepaReference: description: The SEPA reference string. example: ABC123456789 type: string type: description: The source account type. enum: - bank_account example: bank_account type: string wireMessage: description: The message included with the wire transfer. example: Payment for invoice 12345 type: string required: - id - type - currency - network - amount title: Source Bank Account type: object - description: The source of an off ramp transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: amount: description: The source amount being transferred out of the source wallet. example: '100.00' type: string currency: description: The source wallet currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string id: description: The source wallet ID. example: wallet_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1 pattern: ^wallet_[a-z0-9]+$ type: string network: description: The source wallet network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: sol type: string type: description: The source type. enum: - wallet example: wallet type: string required: - id - type - currency - network - amount title: Source Wallet type: object status: description: The transfer status. See [Transfer Lifecycle](/concepts/transfers/lifecycle) for status definitions and transitions. enum: - pendingFunding - pendingReview - fundsReceived - processing - succeeded - undeliverable - returned - processingRefund - refundFailed - pendingRefundInformation - failed - canceled - refunded - unexpectedError - failedPrecondition - expired - unfunded example: pendingFunding type: string x-enumNames: - PENDING_FUNDING - PENDING_REVIEW - FUNDS_RECEIVED - PROCESSING - SUCCEEDED - UNDELIVERABLE - RETURNED - PROCESSING_REFUND - REFUND_FAILED - PENDING_REFUND_INFO - FAILED - CANCELED - REFUNDED - UNEXPECTED_ERROR - FAILED_PRECONDITION - EXPIRED - UNFUNDED statusHistory: description: Timeline of status transitions for this transfer, ascending by transitionedAt. example: - status: pendingFunding transitionedAt: '2026-06-20T14:03:21.000Z' - status: processing transitionedAt: '2026-06-20T14:05:10.000Z' items: description: A single transfer status transition. properties: status: enum: - pendingFunding - pendingReview - fundsReceived - processing - succeeded - undeliverable - returned - processingRefund - refundFailed - pendingRefundInformation - failed - canceled - refunded - unexpectedError - failedPrecondition - expired - unfunded type: string x-enumNames: - PENDING_FUNDING - PENDING_REVIEW - FUNDS_RECEIVED - PROCESSING - SUCCEEDED - UNDELIVERABLE - RETURNED - PROCESSING_REFUND - REFUND_FAILED - PENDING_REFUND_INFO - FAILED - CANCELED - REFUNDED - UNEXPECTED_ERROR - FAILED_PRECONDITION - EXPIRED - UNFUNDED transitionedAt: description: ISO 8601 timestamp of when the transfer entered this status. example: '2026-06-20T14:05:10.000Z' format: date-time type: string required: - status - transitionedAt title: Transfer Status History Entry type: object type: array type: description: The transfer type. enum: - on_ramp - off_ramp - fiat_to_fiat - unmatched_deposit - microdeposit example: on_ramp type: string updated: description: The last datetime the transfer was updated. example: '2021-01-01T00:00:00.000Z' format: date-time type: string required: - id - type - status - statusHistory - customer - source - destination - depositAccount - updated - created type: object type: array pagination: properties: hasNext: description: Whether there is a next page example: false type: boolean hasPrevious: description: Whether there is a previous page example: false type: boolean limit: description: Number of items per page example: 10 exclusiveMaximum: false exclusiveMinimum: false maximum: 100 minimum: 1 type: number page: description: Current page number example: 1 type: number total: description: Total number of items example: 1 type: number totalPages: description: Total number of pages example: 1 type: number required: - page - limit - total - totalPages - hasNext - hasPrevious type: object required: - data - pagination type: object ListVirtualAccountsResponseDto: items: description: A virtual account provides deposit instructions (bank details) that automatically convert incoming fiat deposits to crypto. See the [Virtual Accounts guide](/concepts/automation/onramper-accounts). properties: active: description: Whether the virtual account is currently active and accepting deposits. example: true type: boolean created: description: Timestamp when the virtual account was created (ISO 8601). example: '2025-01-15T10:30:00.000Z' type: string customer: description: The customer ID who owns the virtual account. example: customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7 type: string depositInstructions: description: Bank account details that depositors should use to send fiat funds into the virtual account. properties: bankAccountNumber: description: Bank account number for deposits (USD accounts). Null for EUR accounts. example: '9876543210' nullable: true type: string bankAddress: description: Address of the bank holding the virtual account. example: 1801 Main St, Kansas City, MO 64108 type: string bankBeneficiaryAddress: description: Address of the beneficiary on the account. example: 123 Finance St, San Francisco, CA 94105 type: string bankBeneficiaryName: description: Name of the beneficiary on the account. example: Bridge Financial Inc. type: string bankName: description: Name of the bank holding the virtual account. example: Lead Bank type: string bankRoutingNumber: description: Bank routing number for deposits (USD accounts). Null for EUR accounts. example: '021000089' nullable: true type: string bic: description: BIC/SWIFT code for deposits (EUR accounts). Null for USD accounts. example: COBADEFFXXX nullable: true type: string currency: description: The fiat currency accepted for deposits into the virtual account. enum: - usd - eur example: usd type: string iban: description: IBAN for deposits (EUR accounts). Null for USD accounts. example: DE89370400440532013000 nullable: true type: string required: - currency - bankName - bankAddress - bankAccountNumber - bankRoutingNumber - bankBeneficiaryName - bankBeneficiaryAddress - iban - bic type: object destination: description: The crypto destination where converted funds are sent after deposit. properties: currency: description: The crypto currency deposited funds are converted into. enum: - usdc - usdt - eurc example: usdc type: string network: description: The blockchain network the destination wallet is on. enum: - arbitrum - avalanche - base - ethereum - polygon - sol - tron example: ethereum type: string walletAddress: description: The on-chain wallet address where converted crypto is sent. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string required: - currency - walletAddress - network type: object fee: description: Fee breakdown for the virtual account, including integrator and platform fees. properties: integratorFee: description: Fee charged by the integrator. properties: bpsRate: description: Integrator fee rate in basis points (1 bps = 0.01%). example: '100' type: string required: - bpsRate type: object platformFee: description: Fee charged by the platform. properties: bpsRate: description: Platform fee rate in basis points (1 bps = 0.01%). example: '30' type: string required: - bpsRate type: object totalBpsRate: description: Total fee rate in basis points (integrator + platform). 1 bps = 0.01%. example: '130' type: string required: - totalBpsRate - integratorFee - platformFee type: object id: description: Unique identifier for the virtual account. example: virtualAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string updated: description: Timestamp when the virtual account was last updated (ISO 8601). example: '2025-01-15T12:00:00.000Z' type: string required: - id - active - depositInstructions - destination - created - updated type: object type: array OffloaderWalletResponseDto: properties: address: description: The on-chain deposit address for the offloader wallet. Send crypto to this address to trigger automatic conversion. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string created: description: Timestamp when the offloader wallet was created (ISO 8601). example: '2024-06-15T10:30:00.000Z' type: string currency: description: The crypto currency the offloader wallet accepts for deposits. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string customerId: description: The customer who owns the offloader wallet. example: customer_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string destination: description: The bank account destination where converted funds are sent. See [Bank Accounts guide](/concepts/transfers/bank-accounts). example: achReference: REF123 bankAccountId: bankAccount_6221e8d4299f4a889bd882255e92f581 currency: usd network: ach oneOf: - properties: achReference: description: Reference sent to the receiving institution with ACH transfers, 1-10 characters. example: REF123 maxLength: 10 minLength: 1 type: string bankAccountId: description: The ID of the bank account that converted funds will be sent to. See [Bank Accounts guide](/concepts/transfers/bank-accounts). example: bankAccount_6221e8d4299f4a889bd882255e92f581 type: string currency: description: The fiat currency the crypto will be converted into. enum: - usd example: usd type: string network: description: The banking network used to deliver funds to the destination account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach example: ach type: string required: - bankAccountId - currency - network title: ACH type: object - properties: bankAccountId: description: The ID of the bank account that converted funds will be sent to. See [Bank Accounts guide](/concepts/transfers/bank-accounts). example: bankAccount_6221e8d4299f4a889bd882255e92f581 type: string currency: description: The fiat currency the crypto will be converted into. enum: - usd example: usd type: string network: description: The banking network used to deliver funds to the destination account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - wire example: wire type: string wireMessage: description: Message sent to the receiving institution with wire transfers, 1-105 characters. example: 'Invoice #1024' maxLength: 105 minLength: 1 type: string required: - bankAccountId - currency - network title: Wire type: object - properties: bankAccountId: description: The ID of the bank account that converted funds will be sent to. See [Bank Accounts guide](/concepts/transfers/bank-accounts). example: bankAccount_6221e8d4299f4a889bd882255e92f581 type: string currency: description: The fiat currency the crypto will be converted into. enum: - eur example: eur type: string network: description: The banking network used to deliver funds to the destination account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sepa example: sepa type: string sepaReference: description: Reference sent to the receiving institution with SEPA transfers, 6-140 characters. example: INV-2024-001 maxLength: 140 minLength: 6 type: string required: - bankAccountId - currency - network title: SEPA type: object fees: description: Fee configuration for the offloader wallet, including integrator and platform fees. example: integratorFee: bpsRate: '100' currency: usdc platformFee: bpsRate: '30' currency: usdc properties: integratorFee: properties: bpsRate: description: Integrator fee rate in basis points (1 bps = 0.01%). example: '100' type: string currency: description: The currency the integrator fee is denominated in (matches the wallet deposit currency). enum: - usdc - usdt - eurc example: usdc type: string required: - bpsRate - currency type: object platformFee: properties: bpsRate: description: Platform fee rate in basis points (1 bps = 0.01%). example: '30' type: string currency: description: The currency the platform fee is denominated in (matches the wallet deposit currency). enum: - usdc - usdt - eurc example: usdc type: string required: - bpsRate - currency type: object required: - integratorFee - platformFee type: object id: description: Unique identifier for the offloader wallet. example: wallet_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string network: description: The blockchain network the offloader wallet is on. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - ethereum - arbitrum - polygon - base - avalanche - tron example: ethereum type: string returnAddress: description: Crypto address where funds are returned on failed transactions. Must be valid for the wallet network. Null if not configured. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string status: description: Lifecycle status of the offloader wallet. `active` accepts deposits and settles; `deactivated` no longer settles. enum: - active - deactivated example: active type: string x-enumNames: - ACTIVE - DEACTIVATED updated: description: Timestamp when the offloader wallet was last updated (ISO 8601). example: '2024-06-15T12:00:00.000Z' type: string required: - id - customerId - address - currency - network - status - destination - fees - created - updated type: object ProblemDetailsDto: properties: code: type: string correlationId: type: string detail: type: string errors: items: properties: detail: type: string header: type: string parameter: type: string pointer: type: string required: - detail type: object type: array status: type: integer title: type: string required: - status - detail type: object SendCustomerVerificationCodeDto: properties: type: description: Type of verification code to send enum: - phone - email example: email type: string required: - type type: object SendVerificationCodeResponseDto: properties: customerId: description: Customer ID example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string expiresAt: description: ISO 8601 formatted date and time of the verification code expiration example: '2026-03-09T20:46:31.305Z' type: string required: - customerId - expiresAt type: object SetPayoutFeeDTO: properties: {} type: object SubmitBusinessRepresentativeVerificationResponseDto: properties: id: description: Business Representative ID example: associatedPerson_d972d2f70b9f4d3c8d7cfb32593f395b type: string required: - id type: object SubmitVerificationResponseDto: properties: customerId: description: Customer ID example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string required: - customerId type: object UpdateOffloaderWalletRequestDto: properties: destination: description: The bank account destination where converted funds are sent. example: achReference: REF456 bankAccountId: bankAccount_6221e8d4299f4a889bd882255e92f581 properties: achReference: description: Reference sent to the receiving institution with ACH transfers, 1-10 characters. example: REF456 maxLength: 10 minLength: 1 type: string bankAccountId: description: The ID of the bank account that converted funds will be sent to. example: bankAccount_6221e8d4299f4a889bd882255e92f581 type: string sepaReference: description: Reference sent to the receiving institution with SEPA transfers, 6-140 characters. example: INV-2024-002 maxLength: 140 minLength: 6 type: string wireMessage: description: Message sent to the receiving institution with wire transfers, 1-105 characters. example: 'Invoice #1024' maxLength: 105 minLength: 1 type: string type: object integratorBpsFeeRate: description: Integrator fee override in basis points (0-1000). Send "0" to remove the integrator fee. example: '75' type: string returnAddress: description: Crypto address where funds are returned on failed transactions. Must be valid for the wallet network. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string type: object UpdateQuoteStatusDto: properties: status: description: The new status for the quote. Only active quotes can be updated. enum: - used - expired example: used type: string required: - status type: object UpdateVirtualAccountRequestDto: properties: destinationCurrency: description: The crypto currency deposited funds are converted into. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string integratorFeeBps: description: Integrator fee in basis points (1 bps = 0.01%). Defaults to 0 if not provided. example: '100' type: string network: description: The blockchain network the destination wallet is on. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - arbitrum - avalanche - base - ethereum - polygon - sol - tron example: ethereum type: string walletAddress: description: The on-chain wallet address where converted crypto is sent. Must be valid for the selected network. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string required: - destinationCurrency - network - walletAddress type: object VerifyCustomerVerificationCodeDto: properties: code: description: Verification code example: '123456' maxLength: 10 minLength: 1 type: string type: description: Type of verification code enum: - phone - email example: email type: string required: - type - code type: object VerifyCustomerVerificationCodeResponseDto: properties: customerId: description: Customer ID example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string verifiedAt: description: ISO 8601 formatted date and time of the verification code verification example: '2026-03-09T20:46:31.305Z' type: string required: - customerId - verifiedAt type: object VirtualAccountResponseDto: properties: active: description: Whether the virtual account is currently active and accepting deposits. example: true type: boolean created: description: Timestamp when the virtual account was created (ISO 8601). example: '2025-01-15T10:30:00.000Z' type: string customer: description: The customer ID who owns the virtual account. example: customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7 type: string depositInstructions: description: Bank account details that depositors should use to send fiat funds into the virtual account. properties: bankAccountNumber: description: Bank account number for deposits (USD accounts). Null for EUR accounts. example: '9876543210' nullable: true type: string bankAddress: description: Address of the bank holding the virtual account. example: 1801 Main St, Kansas City, MO 64108 type: string bankBeneficiaryAddress: description: Address of the beneficiary on the account. example: 123 Finance St, San Francisco, CA 94105 type: string bankBeneficiaryName: description: Name of the beneficiary on the account. example: Bridge Financial Inc. type: string bankName: description: Name of the bank holding the virtual account. example: Lead Bank type: string bankRoutingNumber: description: Bank routing number for deposits (USD accounts). Null for EUR accounts. example: '021000089' nullable: true type: string bic: description: BIC/SWIFT code for deposits (EUR accounts). Null for USD accounts. example: COBADEFFXXX nullable: true type: string currency: description: The fiat currency accepted for deposits into the virtual account. enum: - usd - eur example: usd type: string iban: description: IBAN for deposits (EUR accounts). Null for USD accounts. example: DE89370400440532013000 nullable: true type: string required: - currency - bankName - bankAddress - bankAccountNumber - bankRoutingNumber - bankBeneficiaryName - bankBeneficiaryAddress - iban - bic type: object destination: description: The crypto destination where converted funds are sent after deposit. properties: currency: description: The crypto currency deposited funds are converted into. enum: - usdc - usdt - eurc example: usdc type: string network: description: The blockchain network the destination wallet is on. enum: - arbitrum - avalanche - base - ethereum - polygon - sol - tron example: ethereum type: string walletAddress: description: The on-chain wallet address where converted crypto is sent. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string required: - currency - walletAddress - network type: object fee: description: Fee breakdown for the virtual account, including integrator and platform fees. properties: integratorFee: description: Fee charged by the integrator. properties: bpsRate: description: Integrator fee rate in basis points (1 bps = 0.01%). example: '100' type: string required: - bpsRate type: object platformFee: description: Fee charged by the platform. properties: bpsRate: description: Platform fee rate in basis points (1 bps = 0.01%). example: '30' type: string required: - bpsRate type: object totalBpsRate: description: Total fee rate in basis points (integrator + platform). 1 bps = 0.01%. example: '130' type: string required: - totalBpsRate - integratorFee - platformFee type: object id: description: Unique identifier for the virtual account. example: virtualAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string updated: description: Timestamp when the virtual account was last updated (ISO 8601). example: '2025-01-15T12:00:00.000Z' type: string required: - id - active - depositInstructions - destination - created - updated type: object WalletListResponseDto: properties: data: description: Array of wallet objects items: properties: address: description: The wallet address on the specified network. example: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU type: string created: description: The ISO 8601 timestamp when the wallet was created. example: '2025-01-01T00:00:00.000Z' type: string customerId: description: The unique identifier of the customer who owns this wallet. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the wallet. example: wallet_ce745ef7f3df4b9a8bff1301ce24b045 type: string network: description: The blockchain network for this wallet. enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: sol type: string updated: description: The ISO 8601 timestamp when the wallet was last updated. example: '2025-01-01T00:00:00.000Z' type: string required: - id - address - network - customerId - created - updated type: object type: array pagination: properties: hasNext: description: Whether there is a next page example: false type: boolean hasPrevious: description: Whether there is a previous page example: false type: boolean limit: description: Number of items per page example: 10 exclusiveMaximum: false exclusiveMinimum: false maximum: 100 minimum: 1 type: number page: description: Current page number example: 1 type: number total: description: Total number of items example: 1 type: number totalPages: description: Total number of pages example: 1 type: number required: - page - limit - total - totalPages - hasNext - hasPrevious type: object required: - data - pagination type: object WalletResponseDto: properties: address: description: The wallet address on the specified network. example: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU type: string created: description: The ISO 8601 timestamp when the wallet was created. example: '2025-01-01T00:00:00.000Z' type: string customerId: description: The unique identifier of the customer who owns this wallet. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the wallet. example: wallet_ce745ef7f3df4b9a8bff1301ce24b045 type: string network: description: The blockchain network for this wallet. enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: sol type: string updated: description: The ISO 8601 timestamp when the wallet was last updated. example: '2025-01-01T00:00:00.000Z' type: string required: - id - address - network - customerId - created - updated type: object securitySchemes: bearer: bearerFormat: JWT scheme: bearer type: http info: contact: {} description: The Sphere REST API for payments, transfers, and accounts. title: Sphere API version: '2' openapi: 3.0.0 paths: /v1/transfer/fee: post: deprecated: true description: Set a percentage-based transfer fee for a customer. operationId: postV1TransferFee parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SetPayoutFeeDTO' required: true responses: '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Create Transfer Fee /v1/transfer/fee/{id}: get: deprecated: true description: Retrieve a transfer fee by its ID. operationId: getV1TransferFeeById parameters: - in: path name: id required: true schema: type: string responses: '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Get a Transfer Fee by ID /v2/bank-account: get: description: List all bank accounts for a customer with pagination operationId: getV2BankAccount parameters: - description: 'Page number of the list (default: 1)' in: query name: page required: true schema: default: '1' example: 1 type: string - description: 'Number of items per page (default: 10)' in: query name: limit required: true schema: default: '10' example: 10 type: string - description: Filter by customer ID in: query name: customerId required: false schema: example: customer_66c4168d418a410eae282b83883bdc39 type: string - in: query name: network required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/BankAccountListResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: List Bank Accounts post: description: Create a new bank account for a customer. Requires at least one of the customer's verification profiles to be approved. operationId: postV2BankAccount parameters: [] requestBody: content: application/json: schema: oneOf: - properties: accountDetails: description: 'USD account details. For ACH/Wire: accountNumber, routingNumber, accountType. For SWIFT: accountNumber, bic.' accountName: description: A descriptive name for this bank account (e.g., "Checking Account", "Business Account"). example: Checking Account minLength: 1 type: string accountOwner: description: Information about the account owner, including their name, address, and relationship to the customer. properties: accountHolderName: description: 'The name of the account holder as it appears on the bank account. Only alphanumeric characters, spaces, and the following special characters are allowed: !"#$%&''()+,-./:;<=>?@\_`~' example: Sarah Johnson maxLength: 35 minLength: 1 pattern: ^[ \w!"#$%&'()+,\-./:;<=>?@\\_`~]*$ type: string address: description: The address of the account owner. Must be a valid address format (ISO3166-1 Alpha-3 country code). properties: city: description: The city name example: Chicago maxLength: 35 minLength: 1 type: string country: description: The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string line1: description: The first line of the street address example: 233 South Wacker Drive maxLength: 35 minLength: 4 type: string line2: description: The second line of the street address (apartment, suite, etc.) example: Suite 4700 maxLength: 35 type: string postalCode: description: The postal or ZIP code. Required for countries that use postal codes example: '60606' type: string state: description: The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: IL type: string required: - line1 - city - country type: object relationship: default: self description: The relationship of the account owner to the customer. Defaults to "self" if not provided. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - address type: object bankName: description: The name of the financial institution where the account is held. example: Bank of America minLength: 1 type: string currency: description: The currency of the bank account. When set to usd, accountDetails must contain either (accountNumber, routingNumber, accountType) for ACH/Wire or (accountNumber, bic) for SWIFT. enum: - usd example: usd type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string networks: description: The payment networks supported by this bank account. For USD ACH/Wire accounts, must include at least one of "ach" or "wire". For USD SWIFT accounts, must be exactly ["swift"]. example: - wire - ach oneOf: - items: enum: - ach - wire type: string minItems: 1 type: array - items: oneOf: - enum: - swift type: string type: array required: - customerId - bankName - accountName - currency - accountDetails - accountOwner - networks type: object - properties: accountDetails: description: 'EUR/SEPA account details. Required fields: iban, bic.' properties: bic: description: The Bank Identifier Code (BIC), also known as SWIFT code. This is required when currency is eur. example: BNPAFRPPXXX type: string iban: description: The International Bank Account Number (IBAN) for SEPA transfers. This is required when currency is eur. example: FR1420041010050500013M02606 type: string required: - iban - bic type: object accountName: description: A descriptive name for this bank account (e.g., "Checking Account", "Business Account"). example: Hauptkonto minLength: 1 type: string accountOwner: description: Information about the account owner, including their name, address, and relationship to the customer. properties: accountHolderName: description: 'The name of the account holder as it appears on the bank account. Only alphanumeric characters, spaces, and the following special characters are allowed: !"#$%&''()+,-./:;<=>?@\_`~' example: Lukas Muller maxLength: 35 minLength: 1 pattern: ^[ \w!"#$%&'()+,\-./:;<=>?@\\_`~]*$ type: string address: description: The address of the account owner. Must be a valid address format (ISO3166-1 Alpha-3 country code). properties: city: description: The city name example: Berlin maxLength: 35 minLength: 1 type: string country: description: The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: DEU type: string line1: description: The first line of the street address example: Unter den Linden 77 maxLength: 35 minLength: 4 type: string line2: description: The second line of the street address (apartment, suite, etc.) example: Suite 4700 maxLength: 35 type: string postalCode: description: The postal or ZIP code. Required for countries that use postal codes example: '10117' type: string state: description: The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: BE type: string required: - line1 - city - country type: object relationship: default: self description: The relationship of the account owner to the customer. Defaults to "self" if not provided. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - address type: object bankName: description: The name of the financial institution where the account is held. example: Deutsche Bank minLength: 1 type: string currency: description: The currency of the bank account. When set to eur, accountDetails must contain iban and bic. enum: - eur example: eur type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string networks: description: The payment networks supported by this bank account. For EUR accounts, must be exactly ["sepa"]. example: - sepa items: enum: - sepa type: string type: array required: - customerId - bankName - accountName - currency - accountDetails - accountOwner - networks title: EUR type: object - properties: accountDetails: description: 'BRL/PIX account details. Required fields: pixKey, pixKeyType.' properties: pixKey: description: 'The PIX key for BRL bank accounts. Required when currency is brl. Format depends on pixKeyType: `email` must be a valid email address; `cpf` must contain exactly 11 digits (non-digits are stripped); `cnpj` must contain exactly 14 digits (non-digits are stripped); `phone` must contain 10-15 digits (non-digits are stripped); `random` accepts any non-empty string up to 512 characters (Banco Central typically issues a UUID, but no UUID format is enforced here).' example: alice@spherepay.co type: string pixKeyType: description: 'The PIX key type associated with pixKey. Required when currency is brl. One of: `cpf` (Brazilian individual tax ID), `cnpj` (Brazilian business tax ID), `email`, `phone`, or `random` (UUID-style random key issued by Banco Central).' enum: - cpf - cnpj - email - phone - random example: email type: string required: - pixKey - pixKeyType type: object accountName: description: A descriptive name for this bank account (e.g., "Checking Account", "Business Account"). example: Conta PIX Alice Santos minLength: 1 type: string accountOwner: description: The bank account holder details. properties: accountHolderName: description: 'The name of the account holder as it appears on the bank account. Only alphanumeric characters, spaces, and the following special characters are allowed: !"#$%&''()+,-./:;<=>?@\_`~' example: Alice Santos maxLength: 35 minLength: 1 pattern: ^[ \w!"#$%&'()+,\-./:;<=>?@\\_`~]*$ type: string address: description: The address of the account owner. Must be a valid address format (ISO3166-1 Alpha-3 country code). properties: city: description: The city name example: Sao Paulo maxLength: 35 minLength: 1 type: string country: description: The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: BRA type: string line1: description: The first line of the street address example: Rua Augusta 100 maxLength: 35 minLength: 4 type: string line2: description: The second line of the street address (apartment, suite, etc.) example: Suite 4700 maxLength: 35 type: string postalCode: description: The postal or ZIP code. Required for countries that use postal codes example: 01304-001 type: string state: description: The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: SP type: string required: - line1 - city - country type: object relationship: default: self description: The relationship of the account owner to the customer. Defaults to "self" if not provided. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - address title: Account Owner (Basic) type: object bankName: description: The name of the financial institution where the account is held. example: Itau minLength: 1 type: string currency: description: The currency of the bank account. When set to brl, accountDetails must contain pixKey and pixKeyType. enum: - brl example: brl type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string networks: description: The payment networks supported by this bank account. For BRL accounts, must be exactly ["pix"]. example: - pix items: enum: - pix type: string type: array required: - customerId - bankName - accountName - currency - accountDetails - accountOwner - networks title: BRL type: object - properties: accountDetails: description: 'MXN/SPEI account details. Required field: clabe.' properties: clabe: description: The 18-digit CLABE (Clave Bancaria Estandarizada) for MXN/SPEI transfers. Required when currency is mxn. The final digit is a control digit validated against the standard CLABE checksum. example: '012345678901234568' type: string required: - clabe type: object accountName: description: A descriptive name for this bank account (e.g., "Checking Account", "Business Account"). example: Cuenta SPEI María García minLength: 1 type: string accountOwner: description: Information about the account owner, including their name, address, and relationship to the customer. properties: accountHolderName: description: 'The name of the account holder as it appears on the bank account. Only alphanumeric characters, spaces, and the following special characters are allowed: !"#$%&''()+,-./:;<=>?@\_`~' example: María García maxLength: 35 minLength: 1 pattern: ^[ \w!"#$%&'()+,\-./:;<=>?@\\_`~]*$ type: string address: description: The address of the account owner. Must be a valid address format (ISO3166-1 Alpha-3 country code). properties: city: description: The city name example: Ciudad de México maxLength: 35 minLength: 1 type: string country: description: The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: MEX type: string line1: description: The first line of the street address example: Avenida Reforma 222 maxLength: 35 minLength: 4 type: string line2: description: The second line of the street address (apartment, suite, etc.) example: Suite 4700 maxLength: 35 type: string postalCode: description: The postal or ZIP code. Required for countries that use postal codes example: '06600' type: string state: description: The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: CMX type: string required: - line1 - city - country type: object relationship: default: self description: The relationship of the account owner to the customer. Defaults to "self" if not provided. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - address type: object bankName: description: The name of the financial institution where the account is held. example: BBVA México minLength: 1 type: string currency: description: The currency of the bank account. When set to mxn, accountDetails must contain a valid 18-digit clabe. enum: - mxn example: mxn type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string networks: description: The payment networks supported by this bank account. For MXN accounts, must be exactly ["spei"]. example: - spei items: enum: - spei type: string type: array required: - customerId - bankName - accountName - currency - accountDetails - accountOwner - networks title: MXN type: object required: true responses: '201': content: application/json: schema: oneOf: - properties: accountDetails: description: 'USD account details. For ACH/Wire: accountNumber, routingNumber, accountType. For SWIFT: accountNumber (masked), bic.' oneOf: - properties: accountNumber: description: The bank account number for the US bank account (masked, last 4 characters visible). Present when currency is usd. example: '****7890' type: string accountType: description: The type of US bank account. Present when currency is usd. enum: - checking - savings - instapay - pesonet example: checking type: string x-enumNames: - Checking - Savings - Instapay - Pesonet routingNumber: description: The 9-digit ABA routing number (also known as routing transit number) that identifies the US financial institution. Present when currency is usd. example: '021000021' type: string required: - accountNumber - routingNumber - accountType type: object - properties: accountNumber: description: The account number for SWIFT transfers (masked, last 4 characters visible). Present when currency is usd and networks is ["swift"]. example: '******7890' type: string bic: description: The BIC/SWIFT code of the beneficiary bank. Present when currency is usd and networks is ["swift"]. example: DEUTDEFF type: string intermediaryBics: description: Ordered list of BIC/SWIFT codes for intermediary correspondent banks, if any were set on this account. Omitted from the response when no intermediary BICs are set. example: - CHASUS33 items: type: string type: array required: - accountNumber - bic type: object accountName: description: A descriptive name for this bank account. example: Checking Account type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: Bank of America type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - usd example: usd type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For USD ACH/Wire accounts, includes at least one of "ach" or "wire". For USD SWIFT accounts, is exactly ["swift"]. example: - wire - ach oneOf: - items: enum: - ach - wire type: string type: array - items: oneOf: - enum: - swift type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: USD type: object - properties: accountDetails: description: EUR/SEPA account details including iban and bic. properties: bic: description: The Bank Identifier Code (BIC), also known as SWIFT code. Present when currency is eur. example: COBADEFFXXX type: string iban: description: The International Bank Account Number (IBAN) for SEPA transfers (masked). Country code, check digits, and last 4 characters are unmasked. Present when currency is eur. example: GB29****************6819 type: string required: - iban - bic type: object accountName: description: A descriptive name for this bank account. example: Hauptkonto type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: Deutsche Bank type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - eur example: eur type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For EUR accounts, is exactly ["sepa"]. example: - sepa items: enum: - sepa type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: EUR type: object - properties: accountDetails: description: BRL/PIX account details including pixKey and pixKeyType. properties: pixKey: description: The masked PIX key for Brazilian PIX transfers. Present when currency is brl. example: a*c@g***l.com type: string pixKeyType: description: The type of PIX key. Present when currency is brl. enum: - cpf - cnpj - email - phone - random example: email type: string required: - pixKey - pixKeyType type: object accountName: description: A descriptive name for this bank account. example: Conta PIX Alice Santos type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: Itau type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - brl example: brl type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For BRL accounts, is exactly ["pix"]. example: - pix items: enum: - pix type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: BRL type: object - properties: accountDetails: description: MXN/SPEI account details including the masked clabe. properties: clabe: description: The 18-digit CLABE for MXN/SPEI transfers (masked, last 4 digits visible). Present when currency is mxn. example: '**************7899' type: string required: - clabe type: object accountName: description: A descriptive name for this bank account. example: Cuenta SPEI María García type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: BBVA México type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - mxn example: mxn type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For MXN accounts, is exactly ["spei"]. example: - spei items: enum: - spei type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: MXN type: object description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Create a Bank Account /v2/bank-account/{id}: delete: description: Delete a bank account by its ID. operationId: deleteV2BankAccountById parameters: - description: The bank account ID in: path name: id required: true schema: example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 minLength: 1 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/DeleteBankAccountResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Delete a Bank Account get: description: Get information about a bank account by its ID operationId: getV2BankAccountById parameters: - description: The bank account ID in: path name: id required: true schema: example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 minLength: 1 type: string responses: '200': content: application/json: schema: oneOf: - properties: accountDetails: description: 'USD account details. For ACH/Wire: accountNumber, routingNumber, accountType. For SWIFT: accountNumber (masked), bic.' oneOf: - properties: accountNumber: description: The bank account number for the US bank account (masked, last 4 characters visible). Present when currency is usd. example: '****7890' type: string accountType: description: The type of US bank account. Present when currency is usd. enum: - checking - savings - instapay - pesonet example: checking type: string x-enumNames: - Checking - Savings - Instapay - Pesonet routingNumber: description: The 9-digit ABA routing number (also known as routing transit number) that identifies the US financial institution. Present when currency is usd. example: '021000021' type: string required: - accountNumber - routingNumber - accountType type: object - properties: accountNumber: description: The account number for SWIFT transfers (masked, last 4 characters visible). Present when currency is usd and networks is ["swift"]. example: '******7890' type: string bic: description: The BIC/SWIFT code of the beneficiary bank. Present when currency is usd and networks is ["swift"]. example: DEUTDEFF type: string intermediaryBics: description: Ordered list of BIC/SWIFT codes for intermediary correspondent banks, if any were set on this account. Omitted from the response when no intermediary BICs are set. example: - CHASUS33 items: type: string type: array required: - accountNumber - bic type: object accountName: description: A descriptive name for this bank account. example: Checking Account type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: Bank of America type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - usd example: usd type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For USD ACH/Wire accounts, includes at least one of "ach" or "wire". For USD SWIFT accounts, is exactly ["swift"]. example: - wire - ach oneOf: - items: enum: - ach - wire type: string type: array - items: oneOf: - enum: - swift type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: USD type: object - properties: accountDetails: description: EUR/SEPA account details including iban and bic. properties: bic: description: The Bank Identifier Code (BIC), also known as SWIFT code. Present when currency is eur. example: COBADEFFXXX type: string iban: description: The International Bank Account Number (IBAN) for SEPA transfers (masked). Country code, check digits, and last 4 characters are unmasked. Present when currency is eur. example: GB29****************6819 type: string required: - iban - bic type: object accountName: description: A descriptive name for this bank account. example: Hauptkonto type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: Deutsche Bank type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - eur example: eur type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For EUR accounts, is exactly ["sepa"]. example: - sepa items: enum: - sepa type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: EUR type: object - properties: accountDetails: description: BRL/PIX account details including pixKey and pixKeyType. properties: pixKey: description: The masked PIX key for Brazilian PIX transfers. Present when currency is brl. example: a*c@g***l.com type: string pixKeyType: description: The type of PIX key. Present when currency is brl. enum: - cpf - cnpj - email - phone - random example: email type: string required: - pixKey - pixKeyType type: object accountName: description: A descriptive name for this bank account. example: Conta PIX Alice Santos type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: Itau type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - brl example: brl type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For BRL accounts, is exactly ["pix"]. example: - pix items: enum: - pix type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: BRL type: object - properties: accountDetails: description: MXN/SPEI account details including the masked clabe. properties: clabe: description: The 18-digit CLABE for MXN/SPEI transfers (masked, last 4 digits visible). Present when currency is mxn. example: '**************7899' type: string required: - clabe type: object accountName: description: A descriptive name for this bank account. example: Cuenta SPEI María García type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: BBVA México type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - mxn example: mxn type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For MXN accounts, is exactly ["spei"]. example: - spei items: enum: - spei type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: MXN type: object description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Get a Bank Account patch: description: Update a bank account by its ID. Update either the networks on a non-SWIFT account, or the intermediary BIC on a USD SWIFT account that does not already have one. operationId: patchV2BankAccountById parameters: - description: The bank account ID in: path name: id required: true schema: example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 minLength: 1 type: string requestBody: content: application/json: schema: oneOf: - properties: networks: description: 'The payment networks supported by this bank account. Must match the bank account currency: USD accounts support ["ach", "wire"], EUR accounts support ["sepa"], BRL accounts support ["pix"].' example: - wire - ach items: enum: - ach - wire - sepa - pix type: string minItems: 1 type: array required: - networks title: Networks type: object - properties: intermediaryBics: description: Ordered list of BIC/SWIFT codes for intermediary correspondent banks used to route the wire to the beneficiary bank. Each BIC must be exactly 8 or 11 characters. At most 3 BICs; no duplicates. Pass an empty array to clear existing intermediary BICs. Only allowed on USD SWIFT bank accounts. example: - CHASUS33 items: type: string maxItems: 3 type: array required: - intermediaryBics title: IntermediaryBics type: object required: true responses: '200': content: application/json: schema: oneOf: - properties: accountDetails: description: 'USD account details. For ACH/Wire: accountNumber, routingNumber, accountType. For SWIFT: accountNumber (masked), bic.' oneOf: - properties: accountNumber: description: The bank account number for the US bank account (masked, last 4 characters visible). Present when currency is usd. example: '****7890' type: string accountType: description: The type of US bank account. Present when currency is usd. enum: - checking - savings - instapay - pesonet example: checking type: string x-enumNames: - Checking - Savings - Instapay - Pesonet routingNumber: description: The 9-digit ABA routing number (also known as routing transit number) that identifies the US financial institution. Present when currency is usd. example: '021000021' type: string required: - accountNumber - routingNumber - accountType type: object - properties: accountNumber: description: The account number for SWIFT transfers (masked, last 4 characters visible). Present when currency is usd and networks is ["swift"]. example: '******7890' type: string bic: description: The BIC/SWIFT code of the beneficiary bank. Present when currency is usd and networks is ["swift"]. example: DEUTDEFF type: string intermediaryBics: description: Ordered list of BIC/SWIFT codes for intermediary correspondent banks, if any were set on this account. Omitted from the response when no intermediary BICs are set. example: - CHASUS33 items: type: string type: array required: - accountNumber - bic type: object accountName: description: A descriptive name for this bank account. example: Checking Account type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: Bank of America type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - usd example: usd type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For USD ACH/Wire accounts, includes at least one of "ach" or "wire". For USD SWIFT accounts, is exactly ["swift"]. example: - wire - ach oneOf: - items: enum: - ach - wire type: string type: array - items: oneOf: - enum: - swift type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: USD type: object - properties: accountDetails: description: EUR/SEPA account details including iban and bic. properties: bic: description: The Bank Identifier Code (BIC), also known as SWIFT code. Present when currency is eur. example: COBADEFFXXX type: string iban: description: The International Bank Account Number (IBAN) for SEPA transfers (masked). Country code, check digits, and last 4 characters are unmasked. Present when currency is eur. example: GB29****************6819 type: string required: - iban - bic type: object accountName: description: A descriptive name for this bank account. example: Hauptkonto type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: Deutsche Bank type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - eur example: eur type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For EUR accounts, is exactly ["sepa"]. example: - sepa items: enum: - sepa type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: EUR type: object - properties: accountDetails: description: BRL/PIX account details including pixKey and pixKeyType. properties: pixKey: description: The masked PIX key for Brazilian PIX transfers. Present when currency is brl. example: a*c@g***l.com type: string pixKeyType: description: The type of PIX key. Present when currency is brl. enum: - cpf - cnpj - email - phone - random example: email type: string required: - pixKey - pixKeyType type: object accountName: description: A descriptive name for this bank account. example: Conta PIX Alice Santos type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: Itau type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - brl example: brl type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For BRL accounts, is exactly ["pix"]. example: - pix items: enum: - pix type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: BRL type: object - properties: accountDetails: description: MXN/SPEI account details including the masked clabe. properties: clabe: description: The 18-digit CLABE for MXN/SPEI transfers (masked, last 4 digits visible). Present when currency is mxn. example: '**************7899' type: string required: - clabe type: object accountName: description: A descriptive name for this bank account. example: Cuenta SPEI María García type: string accountOwner: description: Information about the account owner, including their name and relationship to the customer. properties: accountHolderName: description: The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: The relationship of the account owner to the customer. enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown example: self type: string required: - accountHolderName - relationship type: object bankName: description: The name of the financial institution where the account is held. example: BBVA México type: string created: description: The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string currency: description: The currency of the bank account. enum: - mxn example: mxn type: string customerId: description: The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string networks: description: The payment networks supported by this bank account. For MXN accounts, is exactly ["spei"]. example: - spei items: enum: - spei type: string type: array status: description: The current status of the bank account. enum: - pending - active - inactive - invalid example: active type: string x-enumNames: - Pending - Active - Inactive - Invalid updated: description: The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks title: MXN type: object description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Update Bank Account /v2/business-representative: get: description: List all business representatives for a customer operationId: getV2BusinessRepresentative parameters: - description: 'Page number of the list (default: 1)' in: query name: page required: true schema: default: '1' example: 1 type: string - description: 'Number of items per page (default: 10)' in: query name: limit required: true schema: default: '10' example: 10 type: string - in: query name: customerId required: false schema: minLength: 1 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListBusinessRepresentativesResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: List Business Representatives post: description: Create a new business representative for a customer. operationId: postV2BusinessRepresentative parameters: [] requestBody: content: application/json: schema: properties: address: description: The address of the business representative. properties: city: description: The city name example: Chicago maxLength: 100 minLength: 1 type: string country: description: The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string line1: description: The first line of the street address example: 233 South Wacker Drive maxLength: 100 minLength: 1 type: string line2: description: The second line of the street address (apartment, suite, etc.) example: Suite 4700 maxLength: 100 type: string postalCode: description: The postal or ZIP code. Required for countries that use postal codes example: '60606' type: string state: description: The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: IL type: string required: - line1 - city - country type: object customerId: description: The ID of the business customer this representative belongs to. example: customer_2f283221a9d44ada800ac7f11f640402 minLength: 1 type: string dateOfBirth: description: The business representative's date of birth in YYYY-MM-DD format. example: '1990-01-15' type: string email: description: The email address of the business representative. example: james.wilson@acmecorp.example.com format: email maxLength: 254 type: string firstName: description: The business representative's legal first name. example: Carlos maxLength: 100 minLength: 1 type: string lastName: description: The business representative's legal last name. example: Souza maxLength: 100 minLength: 1 type: string middleName: description: The business representative's legal middle name. example: Carlos maxLength: 100 minLength: 1 type: string personalInformation: description: Personal information including tax identification details for individual customers. When any tax identification field is provided, all tax identification fields (number, type, country) and address are required. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference. properties: accountPurpose: description: The purpose of the account. Required for EEA-resident individuals before they can be submitted for verification. enum: - personal_or_living_expenses - payments_to_friends_or_family_abroad - receive_salary - receive_payment_for_freelancing - protect_wealth - purchase_goods_and_services - charitable_donations - ecommerce_retail_payments - investment_purposes - operating_a_company - other example: receive_salary type: string accountPurposeDescription: description: A free-text description of the account purpose. Required when `accountPurpose` is `other`. minLength: 1 type: string actingAsIntermediary: description: Whether the customer is acting as an intermediary on behalf of a third party. Required by some verification providers. example: false type: boolean countryOfBirth: description: The ISO3166-1 Alpha-3 country code of the country where the customer was born. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string employmentStatus: description: The customer's employment status. Required by some verification providers. enum: - employed - homemaker - retired - self_employed - student - unemployed example: employed type: string expectedMonthlyPayments: description: The expected monthly payment volume in USD, as a bucket range. Required by some verification providers. enum: - 0_4999 - 5000_9999 - 10000_49999 - 50000_plus example: 5000_9999 type: string gender: description: The gender of the customer. Required by some verification providers. enum: - male - female - other example: male type: string nationality: description: The ISO3166-1 Alpha-3 country code of the customer's nationality. Required by some verification providers. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string occupationSocCode: description: The customer's occupation as a 6-digit Standard Occupational Classification (SOC) code, validated against the supported occupation list. Required for some verification flows. example: '151252' maxLength: 20 minLength: 1 type: string residencyCountry: description: The ISO3166-1 Alpha-3 country code of the customer's country of residency. Often satisfied by the address country, but some verification providers require it as a separate attribute. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string sourceOfFunds: description: The customer's primary source of funds. Required by some verification providers. enum: - company_funds - ecommerce_reseller - gambling_proceeds - gifts - government_benefits - inheritance - investments_loans - pension_retirement - salary - sale_of_assets_real_estate - savings - someone_elses_funds example: salary type: string x-enumNames: - company_funds - ecommerce_reseller - gambling_proceeds - gifts - government_benefits - inheritance - investments_loans - pension_retirement - salary - sale_of_assets_real_estate - savings - someone_elses_funds stateOfBirth: description: The subdivision code of the state/province where the customer was born, without the country prefix (e.g. `JAL`, not `MX-JAL`). Requires `countryOfBirth`. Required by some verification providers. example: JAL maxLength: 10 minLength: 1 type: string taxIdentificationNumber: description: The tax identification number. Required when providing tax identification information. Only alphanumeric characters (letters and numbers) are accepted - omit separators such as dashes or spaces (e.g. send "123456789", not "123-45-6789"). example: '123456789' minLength: 1 pattern: ^[a-zA-Z0-9]+$ type: string taxIdentificationNumberCountry: description: The ISO3166-1 Alpha-3 country code for the tax identification number. Required when providing tax identification information. See [Country Codes](/concepts/reference/supported-countries). example: USA minLength: 1 type: string taxIdentificationNumberDescription: description: Description of the tax identification number. Required when type is `other` type: string taxIdentificationNumberType: description: The type of tax identification number of the customer. Required when providing tax identification information. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference. example: ssn minLength: 1 type: string required: - taxIdentificationNumber - taxIdentificationNumberType - taxIdentificationNumberCountry type: object phone: description: The phone number of the business representative. example: '+13125559876' pattern: ^\+(?:[0-9]){6,14}[0-9]$ type: string representationDetails: description: The representation details of the business representative. example: isControlPerson: true isSigner: true ownershipPercentage: '50' relationshipEstablishedAt: '2020-03-15' roles: - ubo title: CEO properties: isControlPerson: deprecated: true description: Deprecated — send `control_person` in `roles` instead. Whether the business representative has control over the company or able to make decisions on behalf of the company. example: true type: boolean isSigner: deprecated: true description: Deprecated — send `signer` in `roles` instead. Whether the business representative is a signer on the company's documents. example: true type: boolean ownershipPercentage: description: The ownership percentage of the business representative. Must be an integer between 0 and 100 (inclusive), supplied as either a string or a JSON number. When roles includes `ubo` it must be at least 25; otherwise 0-24 is allowed. example: '50' oneOf: - type: string - type: number relationshipEstablishedAt: description: The date the business representative was established in the company. example: '2020-03-15' minLength: 1 type: string roles: description: The roles this person holds in the organization. A person may hold more than one. example: - ubo items: enum: - ubo - control_person - signer - director type: string maxItems: 4 minItems: 1 type: array title: description: The title of the business representative. example: CEO minLength: 1 type: string required: - roles - ownershipPercentage - relationshipEstablishedAt type: object type: description: The type of the business representative. Must be "individual". enum: - individual example: individual type: string required: - customerId - type - email - phone - address - personalInformation - representationDetails type: object required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/BusinessRepresentativeResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Create a Business Representative /v2/business-representative/{id}: delete: description: Delete a business representative by their ID operationId: deleteV2BusinessRepresentativeById parameters: - description: Business Representative ID in: path name: id required: true schema: example: associatedPerson_d972d2f70b9f4d3c8d7cfb32593f395b minLength: 1 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/DeleteBusinessRepresentativeResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Delete a Business Representative get: description: Retrieve a business representative by their ID operationId: getV2BusinessRepresentativeById parameters: - description: Business Representative ID in: path name: id required: true schema: example: associatedPerson_d972d2f70b9f4d3c8d7cfb32593f395b minLength: 1 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/BusinessRepresentativeResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Get a Business Representative by ID patch: description: Update an existing business representative operationId: patchV2BusinessRepresentativeById parameters: - description: Business Representative ID in: path name: id required: true schema: example: associatedPerson_d972d2f70b9f4d3c8d7cfb32593f395b minLength: 1 type: string requestBody: content: application/json: schema: properties: address: description: The address of the business representative. Required if personalInformation is provided. example: city: Chicago country: USA line1: 742 North Wabash Avenue line2: Apt 4B postalCode: '60611' state: IL properties: city: description: The city name example: Chicago maxLength: 100 minLength: 1 type: string country: description: The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string line1: description: The first line of the street address example: 233 South Wacker Drive maxLength: 100 minLength: 1 type: string line2: description: The second line of the street address (apartment, suite, etc.) example: Suite 4700 maxLength: 100 type: string postalCode: description: The postal or ZIP code. Required for countries that use postal codes example: '60606' type: string state: description: The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: IL type: string required: - line1 - city - country type: object personalInformation: description: Personal information including tax identification details for individual customers. When any tax identification field is provided, all tax identification fields (number, type, country) and address are required. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference. properties: accountPurpose: description: The purpose of the account. Required for EEA-resident individuals before they can be submitted for verification. enum: - personal_or_living_expenses - payments_to_friends_or_family_abroad - receive_salary - receive_payment_for_freelancing - protect_wealth - purchase_goods_and_services - charitable_donations - ecommerce_retail_payments - investment_purposes - operating_a_company - other example: receive_salary type: string accountPurposeDescription: description: A free-text description of the account purpose. Required when `accountPurpose` is `other`. minLength: 1 type: string actingAsIntermediary: description: Whether the customer is acting as an intermediary on behalf of a third party. Required by some verification providers. example: false type: boolean countryOfBirth: description: The ISO3166-1 Alpha-3 country code of the country where the customer was born. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string employmentStatus: description: The customer's employment status. Required by some verification providers. enum: - employed - homemaker - retired - self_employed - student - unemployed example: employed type: string expectedMonthlyPayments: description: The expected monthly payment volume in USD, as a bucket range. Required by some verification providers. enum: - 0_4999 - 5000_9999 - 10000_49999 - 50000_plus example: 5000_9999 type: string gender: description: The gender of the customer. Required by some verification providers. enum: - male - female - other example: male type: string middleName: description: The customer's middle name. Required for some verification flows. example: James maxLength: 255 minLength: 1 type: string nationality: description: The ISO3166-1 Alpha-3 country code of the customer's nationality. Required by some verification providers. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string occupationSocCode: description: The customer's occupation as a 6-digit Standard Occupational Classification (SOC) code, validated against the supported occupation list. Required for some verification flows. example: '151252' maxLength: 20 minLength: 1 type: string residencyCountry: description: The ISO3166-1 Alpha-3 country code of the customer's country of residency. Often satisfied by the address country, but some verification providers require it as a separate attribute. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string sourceOfFunds: description: The customer's primary source of funds. Required by some verification providers. enum: - company_funds - ecommerce_reseller - gambling_proceeds - gifts - government_benefits - inheritance - investments_loans - pension_retirement - salary - sale_of_assets_real_estate - savings - someone_elses_funds example: salary type: string x-enumNames: - company_funds - ecommerce_reseller - gambling_proceeds - gifts - government_benefits - inheritance - investments_loans - pension_retirement - salary - sale_of_assets_real_estate - savings - someone_elses_funds stateOfBirth: description: The subdivision code of the state/province where the customer was born, without the country prefix (e.g. `JAL`, not `MX-JAL`). Requires `countryOfBirth`. Required by some verification providers. example: JAL maxLength: 10 minLength: 1 type: string taxIdentificationNumber: description: The tax identification number. Required when providing tax identification information. Only alphanumeric characters (letters and numbers) are accepted - omit separators such as dashes or spaces (e.g. send "123456789", not "123-45-6789"). example: '123456789' minLength: 1 pattern: ^[a-zA-Z0-9]+$ type: string taxIdentificationNumberCountry: description: The ISO3166-1 Alpha-3 country code for the tax identification number. Required when providing tax identification information. See [Country Codes](/concepts/reference/supported-countries). example: USA minLength: 1 type: string taxIdentificationNumberDescription: description: Description of the tax identification number. Required when type is `other`, on update too. For other types, omit it to keep the stored value or send null to clear it. nullable: true type: string taxIdentificationNumberType: description: The type of tax identification number of the customer. Required when providing tax identification information. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference. example: ssn minLength: 1 type: string required: - taxIdentificationNumber - taxIdentificationNumberType - taxIdentificationNumberCountry type: object representationDetails: description: The representation details of the business representative. example: isControlPerson: true isSigner: true ownershipPercentage: '50' relationshipEstablishedAt: '2020-03-15' roles: - ubo title: CEO properties: isControlPerson: deprecated: true description: Deprecated — send `control_person` in `roles` instead. Whether the business representative has control over the company or able to make decisions on behalf of the company. example: true type: boolean isSigner: deprecated: true description: Deprecated — send `signer` in `roles` instead. Whether the business representative is a signer on the company's documents. example: true type: boolean ownershipPercentage: description: The ownership percentage of the business representative. Must be an integer between 0 and 100 (inclusive), supplied as either a string or a JSON number. When roles includes `ubo` it must be at least 25; otherwise 0-24 is allowed. example: '50' oneOf: - type: string - type: number relationshipEstablishedAt: description: The date the business representative was established in the company. example: '2020-03-15' minLength: 1 type: string roles: description: The roles this person holds in the organization. A person may hold more than one. example: - ubo items: enum: - ubo - control_person - signer - director type: string maxItems: 4 minItems: 1 type: array title: description: The title of the business representative. example: CEO minLength: 1 type: string required: - roles - ownershipPercentage - relationshipEstablishedAt type: object type: object required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/BusinessRepresentativeResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Update a Business Representative /v2/business-representative/{id}/face-verification-link: post: description: Generate a face verification link for a business representative. operationId: postV2BusinessRepresentativeByIdFaceVerificationLink parameters: - description: Business Representative ID in: path name: id required: true schema: example: associatedPerson_d972d2f70b9f4d3c8d7cfb32593f395b minLength: 1 type: string responses: '201': content: application/json: schema: $ref: '#/components/schemas/GenerateFaceVerificationLinkResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Generate Face Verification Link for Business Representative x-doc-path: - v2 - enhanced-due-diligence - ubo-face-verification-link /v2/business-representative/{id}/submit-verification: post: description: Submit a business representative for verification. This triggers automatic document checks and allows passport details to be extracted after transitioning from intent to non-intent level. operationId: postV2BusinessRepresentativeByIdSubmitVerification parameters: - description: Business Representative ID in: path name: id required: true schema: example: associatedPerson_d972d2f70b9f4d3c8d7cfb32593f395b minLength: 1 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/SubmitBusinessRepresentativeVerificationResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Submit Business Representative for Verification x-doc-path: - v2 - identity - ubo-submit-verification /v2/customer: get: description: List customers with optional server-side search, filters, and sort. operationId: getV2Customer parameters: - in: query name: '' required: true schema: properties: country: description: Filter by customer address country (ISO 3166-1 Alpha-3, e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string email: description: Filter by exact customer email (individual or business) example: jane@example.com format: email type: string limit: default: '10' description: 'Number of items per page (default: 10)' example: 10 type: string page: default: '1' description: 'Page number of the list (default: 1)' example: 1 type: string search: description: Substring search across customer first name, last name, legal name, trade name, and email fields example: jane maxLength: 255 minLength: 1 type: string sort: default: '-created' description: 'Comma-separated sort fields. Prefix with "-" for descending, "+" (or no prefix) for ascending. Allowed fields: created, updated. Example: "created,-updated".' example: '-created' type: string required: - page - limit - sort type: object responses: '200': content: application/json: schema: $ref: '#/components/schemas/CustomerListResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: List Customers post: description: Create a new customer. operationId: postV2Customer parameters: [] requestBody: content: application/json: schema: oneOf: - properties: address: description: The customer's address. Deprecated — prefer `addresses`. properties: city: description: The city name example: Chicago maxLength: 100 minLength: 1 type: string country: description: The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string line1: description: The first line of the street address example: 233 South Wacker Drive maxLength: 100 minLength: 1 type: string line2: description: The second line of the street address (apartment, suite, etc.) example: Suite 4700 maxLength: 100 type: string postalCode: description: The postal or ZIP code. Required for countries that use postal codes example: '60606' type: string state: description: The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: IL type: string required: - line1 - city - country type: object addresses: description: The customer's addresses. Individual customers support exactly one residential address. Provide either this field or the deprecated `address` field, not both. example: - address: city: Chicago country: USA line1: 233 South Wacker Drive line2: Suite 4700 postalCode: '60606' state: IL type: residential items: properties: address: properties: city: description: The city name example: Chicago maxLength: 100 minLength: 1 type: string country: description: The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string line1: description: The first line of the street address example: 233 South Wacker Drive maxLength: 100 minLength: 1 type: string line2: description: The second line of the street address (apartment, suite, etc.) example: Suite 4700 maxLength: 100 type: string postalCode: description: The postal or ZIP code. Required for countries that use postal codes example: '60606' type: string state: description: The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: IL type: string required: - line1 - city - country type: object type: enum: - residential - registered - operating type: string x-enumNames: - residential - registered - operating required: - type - address type: object type: array dateOfBirth: description: The date string in YYYY-MM-DD format example: '2026-01-01' type: string email: description: The customer email address example: jane.smith@example.com format: email maxLength: 254 type: string enabledVerificationProfiles: description: Restricts which verification profile families this customer may onboard through. Must be a subset of the families enabled on your application; supplying one that is not enabled is rejected with a 422. Omit the field to inherit the application's setting. example: - a - c items: enum: - a - b - c - d type: string minItems: 1 type: array firstName: description: The customer's legal first name. example: Jane maxLength: 100 minLength: 1 type: string ipAddress: description: The IP address the customer used to sign up. Required by some verification providers. example: 203.0.113.4 type: string lastName: description: The customer's legal last name. example: Smith maxLength: 100 minLength: 1 type: string meta: additionalProperties: type: string description: Additional metadata associated with the customer type: object middleName: description: The customer's legal middle name. example: Anne maxLength: 100 minLength: 1 type: string personalExpectedActivity: description: The individual customer's expected transaction activity. Only accepted on individual customers. properties: expectedCounterpartyTypes: description: The types of counterparties transactions are expected to involve. example: - domestic_individual - foreign_business items: enum: - domestic_individual - foreign_individual - domestic_business - foreign_business - financial_institution - government_entity - nonprofit - self type: string minItems: 1 type: array expectedGeographies: description: The ISO3166-1 Alpha-3 country codes transactions are expected to involve. See [Country Codes](/concepts/reference/supported-countries). example: - MEX - USA items: type: string maxItems: 10 minItems: 1 type: array expectedMonthlyTransactionCount: description: The expected number of transactions per month, as a bucket range. enum: - less_than_5 - 5_15 - 16_50 - 51_200 - 200_plus example: 16_50 type: string transactionFrequency: description: How often transactions are expected to occur. enum: - daily - weekly - biweekly - monthly - quarterly example: monthly type: string title: Personal Expected Activity type: object personalInformation: description: Personal information including tax identification details for individual customers. When any tax identification field is provided, all tax identification fields (number, type, country) and address are required. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference. properties: accountPurpose: description: The purpose of the account. Required for EEA-resident individuals before they can be submitted for verification. enum: - personal_or_living_expenses - payments_to_friends_or_family_abroad - receive_salary - receive_payment_for_freelancing - protect_wealth - purchase_goods_and_services - charitable_donations - ecommerce_retail_payments - investment_purposes - operating_a_company - other example: receive_salary type: string accountPurposeDescription: description: A free-text description of the account purpose. Required when `accountPurpose` is `other`. minLength: 1 type: string actingAsIntermediary: description: Whether the customer is acting as an intermediary on behalf of a third party. Required by some verification providers. example: false type: boolean countryOfBirth: description: The ISO3166-1 Alpha-3 country code of the country where the customer was born. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string employmentStatus: description: The customer's employment status. Required by some verification providers. enum: - employed - homemaker - retired - self_employed - student - unemployed example: employed type: string expectedMonthlyPayments: description: The expected monthly payment volume in USD, as a bucket range. Required by some verification providers. enum: - 0_4999 - 5000_9999 - 10000_49999 - 50000_plus example: 5000_9999 type: string gender: description: The gender of the customer. Required by some verification providers. enum: - male - female - other example: male type: string nationality: description: The ISO3166-1 Alpha-3 country code of the customer's nationality. Required by some verification providers. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string occupationSocCode: description: The customer's occupation as a 6-digit Standard Occupational Classification (SOC) code, validated against the supported occupation list. Required for some verification flows. example: '151252' maxLength: 20 minLength: 1 type: string residencyCountry: description: The ISO3166-1 Alpha-3 country code of the customer's country of residency. Often satisfied by the address country, but some verification providers require it as a separate attribute. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string sourceOfFunds: description: The customer's primary source of funds. Required by some verification providers. enum: - company_funds - ecommerce_reseller - gambling_proceeds - gifts - government_benefits - inheritance - investments_loans - pension_retirement - salary - sale_of_assets_real_estate - savings - someone_elses_funds example: salary type: string x-enumNames: - company_funds - ecommerce_reseller - gambling_proceeds - gifts - government_benefits - inheritance - investments_loans - pension_retirement - salary - sale_of_assets_real_estate - savings - someone_elses_funds stateOfBirth: description: The subdivision code of the state/province where the customer was born, without the country prefix (e.g. `JAL`, not `MX-JAL`). Requires `countryOfBirth`. Required by some verification providers. example: JAL maxLength: 10 minLength: 1 type: string taxIdentificationNumber: description: The tax identification number. Required when providing tax identification information. Only alphanumeric characters (letters and numbers) are accepted - omit separators such as dashes or spaces (e.g. send "123456789", not "123-45-6789"). example: '123456789' minLength: 1 pattern: ^[a-zA-Z0-9]+$ type: string taxIdentificationNumberCountry: description: The ISO3166-1 Alpha-3 country code for the tax identification number. Required when providing tax identification information. See [Country Codes](/concepts/reference/supported-countries). example: USA minLength: 1 type: string taxIdentificationNumberDescription: description: Description of the tax identification number. Required when type is `other` type: string taxIdentificationNumberType: description: The type of tax identification number of the customer. Required when providing tax identification information. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference. example: ssn minLength: 1 type: string required: - taxIdentificationNumber - taxIdentificationNumberType - taxIdentificationNumberCountry type: object phone: description: The customer phone number in E.164 format example: '+14155550123' pattern: ^\+(?:[0-9]){6,14}[0-9]$ type: string type: enum: - individual type: string required: - type - email - phone title: Individual Customer Create type: object - properties: addresses: description: The business customer's addresses which includes a registered address and an operating address. items: description: The business customer's address. example: city: Chicago country: USA line1: 123 Main Street line2: Suite 100 postalCode: '60601' state: IL type: registered properties: city: description: The city name example: Chicago maxLength: 100 minLength: 1 type: string country: description: The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string line1: description: The first line of the street address example: 233 South Wacker Drive maxLength: 100 minLength: 1 type: string line2: description: The second line of the street address (apartment, suite, etc.) example: Suite 4700 maxLength: 100 type: string postalCode: description: The postal or ZIP code. Required for countries that use postal codes example: '60606' type: string state: description: The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: IL type: string type: enum: - operating - registered type: string required: - line1 - city - country - type type: object maxItems: 2 minItems: 2 type: array businessExpectedActivity: description: The business customer's expected transaction activity. Only accepted on business customers. properties: expectedCounterpartyTypes: description: The types of counterparties transactions are expected to involve. example: - domestic_individual - foreign_business items: enum: - domestic_individual - foreign_individual - domestic_business - foreign_business - financial_institution - government_entity - nonprofit - self type: string minItems: 1 type: array expectedGeographies: description: The ISO3166-1 Alpha-3 country codes transactions are expected to involve. See [Country Codes](/concepts/reference/supported-countries). example: - MEX - USA items: type: string maxItems: 10 minItems: 1 type: array expectedMonthlyTransactionCount: description: The expected number of transactions per month, as a bucket range. enum: - less_than_5 - 5_15 - 16_50 - 51_200 - 200_plus example: 16_50 type: string transactionFrequency: description: How often transactions are expected to occur. enum: - daily - weekly - biweekly - monthly - quarterly example: monthly type: string title: Business Expected Activity type: object businessInformation: description: Business information including identification number and all other relevant information to onboard the business customer. See [Business Verification Criteria](/concepts/onboarding/verification-profile). properties: accountPurpose: description: The business account purpose enum: - charitable_donations - ecommerce_retail_payments - investment_purposes - payments_to_friends_or_family_abroad - payroll - personal_or_living_expenses - protect_wealth - purchase_goods_and_services - receive_payments_for_goods_and_services - tax_optimization - third_party_money_transmission - treasury_management - other example: investment_purposes type: string accountPurposeDescription: description: The business account purpose description. This is required when accountPurpose is "other". example: Business checking account minLength: 1 type: string complianceScreeningExplanation: description: The business compliance screening explanation. This is required when regulatedActivities contains "money_services". example: The business complies with all applicable regulations minLength: 1 type: string description: description: The business description. example: Acme Corporation provides enterprise software solutions for supply chain management and logistics optimization. maxLength: 1000 minLength: 1 type: string entityType: description: The business entity type. enum: - cooperative - corporation - llc - partnership - sole_proprietorship - trust - other example: corporation type: string entityTypeDescription: description: The business entity type description. This is required when entityType is "other". example: Limited Liability Partnership minLength: 1 type: string estimatedAnnualRevenueInUsd: description: The business estimated annual revenue in USD. Please refer to [estimated annual revenue in USD](/concepts/onboarding/verification-profile) for the list of valid ranges. enum: - 0_99999 - 100000_999999 - 1000000_9999999 - 10000000_49999999 - 50000000_249999999 - 250000000_plus example: 1000000_9999999 type: string expectedMonthlyPaymentsInUsd: description: The business expected monthly payments in USD. Please refer to [expected monthly payments in USD](/concepts/onboarding/verification-profile) for the list of valid ranges. example: '50000' type: string hasAuditedFinancialStatementsAttested: description: Must be true when `totalAssetsUsd` is at or above the audited-financials threshold (PD-16), confirming readiness to supply audited financial statements during verification. example: true type: boolean identificationNumber: description: The business tax or primary identification number (e.g. EIN). Distinct from `registrationNumber`. Only alphanumeric characters (letters and numbers) are accepted - omit separators such as dashes or spaces (e.g. send "123456789", not "12-3456789"). example: '123456789' maxLength: 100 minLength: 1 pattern: ^[a-zA-Z0-9]+$ type: string identificationNumberDescription: description: The business identification number description. This is required when identificationNumberType is "other". example: Social Security Number minLength: 1 type: string identificationNumberType: description: The business identification number type. Please refer to [identification number types](/concepts/onboarding/verification-profile) for the list of valid types. example: ein minLength: 1 type: string incorporatedOn: description: The date string in YYYY-MM-DD format example: '2026-01-01' type: string isDao: description: Whether the business is a decentralized autonomous organization (DAO). example: false type: boolean legalName: description: The business legal name. example: Acme Corporation Inc. minLength: 1 type: string licenseNumber: description: License or registration number issued by the regulatory authority. Required together with the other regulator fields when `regulatedActivities` includes `money_services`. example: MSB-123456789 maxLength: 200 minLength: 1 type: string moneyServicesDescription: description: The business money services description. This is required when regulatedActivities contains "money_services". example: The business engages in money services minLength: 1 type: string naicsCode: description: The business NAICS code. Please refer to NAICS codes for the list of valid codes. example: '511210' minLength: 1 type: string operatesInProhibitedCountries: description: Whether the business operates in prohibited countries. example: false type: boolean participatesInRegulatedFinancialActivity: type: boolean primarySourceOfFunds: description: The business primary source of funds enum: - business_loans - grants - inter_company_funds - investment_proceeds - legal_settlement - owners_capital - pension_retirement - sale_of_assets - sales_of_goods_and_services - third_party_funds - treasury_reserves example: sales_of_goods_and_services type: string primarySourceOfFundsDescription: description: The business primary source of funds description. example: Revenue from software licensing and consulting services minLength: 1 type: string registrationNumber: description: Company registration number (state registry, Companies House, etc.), separate from the tax identifier in `identificationNumber`. example: C1234567 maxLength: 100 minLength: 1 type: string regulatedActivities: description: The business regulated activities. example: - none_of_the_above items: description: The business regulated activity enum: - adult_entertainment - gambling - hold_client_funds - investment_services - lending_banking - marijuana_or_related_services - money_services - operate_foreign_exchange_virtual_currencies_brokerage_otc - pharmaceuticals - precious_metals_precious_stones_jewelry - safe_deposit_box_rentals - third_party_payment_processing - nicotine_tobacco_or_related_services - weapons_firearms_and_explosives - none_of_the_above example: money_services type: string minItems: 1 type: array regulatedActivitiesDescription: description: The business regulated activities description. This is required when regulatedActivities contains any value other than "none_of_the_above". example: The business engages in money services minLength: 1 type: string regulatedFinancialActivityDescription: description: The business regulated financial activity description. This is required when participatesInRegulatedFinancialActivity is true. example: The business engages in money services minLength: 1 type: string regulatoryAuthorityCountry: description: ISO-3166 alpha-3 country of the primary regulatory authority. Required together with `regulatoryAuthorityName` and `licenseNumber` when `regulatedActivities` includes `money_services`. example: USA type: string regulatoryAuthorityName: description: Name of the primary regulatory authority. Required together with the other regulator fields when `regulatedActivities` includes `money_services`. example: Financial Crimes Enforcement Network (FinCEN) maxLength: 500 minLength: 1 type: string totalAssetsUsd: description: Total business assets in USD as a decimal string (e.g. "2500000.00"). When this value is at or above the audited-financials threshold, `hasAuditedFinancialStatementsAttested` must be true. example: '2500000.00' type: string tradeName: description: The business trade name. example: Acme Corp minLength: 1 type: string website: description: The business website URL. Must be a real http(s) website; a social media profile URL is acceptable. `https://` is added when the scheme is omitted. Optional - if omitted, a document with documentType `proof_of_nature_of_business_document` must be uploaded instead to satisfy verification. example: https://acmecorp.example.com maxLength: 2048 type: string required: - legalName - tradeName - entityType - description - naicsCode - incorporatedOn - identificationNumberType - identificationNumber - estimatedAnnualRevenueInUsd - expectedMonthlyPaymentsInUsd - accountPurpose - primarySourceOfFunds - primarySourceOfFundsDescription - isDao - regulatedActivities - participatesInRegulatedFinancialActivity - operatesInProhibitedCountries type: object email: description: The business customer's email address. example: contact@acmecorp.example.com format: email maxLength: 254 type: string enabledVerificationProfiles: description: Restricts which verification profile families this customer may onboard through. Must be a subset of the families enabled on your application; supplying one that is not enabled is rejected with a 422. Omit the field to inherit the application's setting. example: - a - c items: enum: - a - b - c - d type: string minItems: 1 type: array ipAddress: description: The IP address the customer used to sign up. Required by some verification providers. example: 203.0.113.4 type: string meta: additionalProperties: type: string description: Additional metadata associated with the customer type: object phone: description: The business customer's phone number in E.164 format. example: '+14155551234' pattern: ^\+(?:[0-9]){6,14}[0-9]$ type: string type: description: The customer type. enum: - business example: business type: string required: - type - email - phone - addresses - businessInformation title: Business Customer Create type: object required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CustomerResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Create a Customer /v2/customer/kyc-link: post: description: Create a customer via the hosted onboarding link flow. Returns a KYC link and its expiry. operationId: postV2CustomerKycLink parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCustomerKycLinkDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/GenerateKycUrlResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Create Customer via Link x-doc-path: - v2 - customer - kyc /v2/customer/{id}: get: description: Get information about a customer by their ID operationId: getV2CustomerById parameters: - description: Customer ID in: path name: id required: true schema: example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/CustomerResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Get a customer by ID patch: description: Update a customer by ID. Individual and business customers can be updated during onboarding. A field is locked once a verification profile that is pending, approved or terminally rejected has completed the criterion the field supplies; locked fields return 400 with a pointer per field. Business customers may add verification profiles and supply the fields those profiles add. operationId: patchV2CustomerById parameters: - description: Customer ID in: path name: id required: true schema: example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string requestBody: content: application/json: schema: oneOf: - properties: address: description: The address of the customer. Required if personalInformation is provided. example: city: Chicago country: USA line1: 233 South Wacker Drive line2: Suite 4700 postalCode: '60606' state: IL properties: city: description: The city name example: Chicago maxLength: 100 minLength: 1 type: string country: description: The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string line1: description: The first line of the street address example: 233 South Wacker Drive maxLength: 100 minLength: 1 type: string line2: description: The second line of the street address (apartment, suite, etc.) example: Suite 4700 maxLength: 100 type: string postalCode: description: The postal or ZIP code. Required for countries that use postal codes example: '60606' type: string state: description: The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: IL type: string required: - line1 - city - country type: object addresses: description: The customer's addresses. Individual customers support exactly one residential address. Provide either this field or the deprecated `address` field, not both. example: - address: city: Chicago country: USA line1: 233 South Wacker Drive line2: Suite 4700 postalCode: '60606' state: IL type: residential items: properties: address: properties: city: description: The city name example: Chicago maxLength: 100 minLength: 1 type: string country: description: The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string line1: description: The first line of the street address example: 233 South Wacker Drive maxLength: 100 minLength: 1 type: string line2: description: The second line of the street address (apartment, suite, etc.) example: Suite 4700 maxLength: 100 type: string postalCode: description: The postal or ZIP code. Required for countries that use postal codes example: '60606' type: string state: description: The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: IL type: string required: - line1 - city - country type: object type: enum: - residential - registered - operating type: string x-enumNames: - residential - registered - operating required: - type - address type: object type: array enabledVerificationProfiles: description: Restricts which verification profile families this customer may onboard through. Must be a subset of the families enabled on your application; supplying one that is not enabled is rejected with a 422. Omit the field to inherit the application's setting. example: - a - c items: enum: - a - b - c - d type: string minItems: 1 type: array ipAddress: description: The IP address the customer used to sign up. Required by some verification providers. example: 203.0.113.4 type: string meta: additionalProperties: type: string description: The customer metadata example: key: value type: object personalExpectedActivity: description: The individual customer's expected transaction activity. Only accepted on individual customers. properties: expectedCounterpartyTypes: description: The types of counterparties transactions are expected to involve. example: - domestic_individual - foreign_business items: enum: - domestic_individual - foreign_individual - domestic_business - foreign_business - financial_institution - government_entity - nonprofit - self type: string minItems: 1 type: array expectedGeographies: description: The ISO3166-1 Alpha-3 country codes transactions are expected to involve. See [Country Codes](/concepts/reference/supported-countries). example: - MEX - USA items: type: string maxItems: 10 minItems: 1 type: array expectedMonthlyTransactionCount: description: The expected number of transactions per month, as a bucket range. enum: - less_than_5 - 5_15 - 16_50 - 51_200 - 200_plus example: 16_50 type: string transactionFrequency: description: How often transactions are expected to occur. enum: - daily - weekly - biweekly - monthly - quarterly example: monthly type: string title: Personal Expected Activity type: object personalInformation: description: Personal information including tax identification details for individual customers. When any tax identification field is provided, all tax identification fields (number, type, country) and address are required. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference. properties: accountPurpose: description: The purpose of the account. Required for EEA-resident individuals before they can be submitted for verification. enum: - personal_or_living_expenses - payments_to_friends_or_family_abroad - receive_salary - receive_payment_for_freelancing - protect_wealth - purchase_goods_and_services - charitable_donations - ecommerce_retail_payments - investment_purposes - operating_a_company - other example: receive_salary type: string accountPurposeDescription: description: A free-text description of the account purpose. Required when `accountPurpose` is `other`. minLength: 1 type: string actingAsIntermediary: description: Whether the customer is acting as an intermediary on behalf of a third party. Required by some verification providers. example: false type: boolean countryOfBirth: description: The ISO3166-1 Alpha-3 country code of the country where the customer was born. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string employmentStatus: description: The customer's employment status. Required by some verification providers. enum: - employed - homemaker - retired - self_employed - student - unemployed example: employed type: string expectedMonthlyPayments: description: The expected monthly payment volume in USD, as a bucket range. Required by some verification providers. enum: - 0_4999 - 5000_9999 - 10000_49999 - 50000_plus example: 5000_9999 type: string gender: description: The gender of the customer. Required by some verification providers. enum: - male - female - other example: male type: string middleName: description: The customer's middle name. Required for some verification flows. example: James maxLength: 255 minLength: 1 type: string nationality: description: The ISO3166-1 Alpha-3 country code of the customer's nationality. Required by some verification providers. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string occupationSocCode: description: The customer's occupation as a 6-digit Standard Occupational Classification (SOC) code, validated against the supported occupation list. Required for some verification flows. example: '151252' maxLength: 20 minLength: 1 type: string residencyCountry: description: The ISO3166-1 Alpha-3 country code of the customer's country of residency. Often satisfied by the address country, but some verification providers require it as a separate attribute. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string sourceOfFunds: description: The customer's primary source of funds. Required by some verification providers. enum: - company_funds - ecommerce_reseller - gambling_proceeds - gifts - government_benefits - inheritance - investments_loans - pension_retirement - salary - sale_of_assets_real_estate - savings - someone_elses_funds example: salary type: string x-enumNames: - company_funds - ecommerce_reseller - gambling_proceeds - gifts - government_benefits - inheritance - investments_loans - pension_retirement - salary - sale_of_assets_real_estate - savings - someone_elses_funds stateOfBirth: description: The subdivision code of the state/province where the customer was born, without the country prefix (e.g. `JAL`, not `MX-JAL`). Requires `countryOfBirth`. Required by some verification providers. example: JAL maxLength: 10 minLength: 1 type: string taxIdentificationNumber: description: The tax identification number. Required when providing tax identification information. Only alphanumeric characters (letters and numbers) are accepted - omit separators such as dashes or spaces (e.g. send "123456789", not "123-45-6789"). example: '123456789' minLength: 1 pattern: ^[a-zA-Z0-9]+$ type: string taxIdentificationNumberCountry: description: The ISO3166-1 Alpha-3 country code for the tax identification number. Required when providing tax identification information. See [Country Codes](/concepts/reference/supported-countries). example: USA minLength: 1 type: string taxIdentificationNumberDescription: description: Description of the tax identification number. Required when type is `other` type: string taxIdentificationNumberType: description: The type of tax identification number of the customer. Required when providing tax identification information. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference. example: ssn minLength: 1 type: string type: object title: Individual Customer Update type: object - example: addresses: - city: Monterrey country: MEX line1: Av. Constitución 2050 line2: Piso 4 postalCode: '64000' state: NLE type: operating businessExpectedActivity: expectedCounterpartyTypes: - domestic_business expectedGeographies: - MEX - USA expectedMonthlyTransactionCount: 51_200 transactionFrequency: weekly businessInformation: registrationNumber: N-2019045821 enabledVerificationProfiles: - a - d ipAddress: 189.203.41.17 meta: crmId: '4412' properties: addresses: description: Addresses to replace. Each entry replaces the stored address of the same type; types not sent are unchanged. items: description: The business customer's address. example: city: Chicago country: USA line1: 123 Main Street line2: Suite 100 postalCode: '60601' state: IL type: registered properties: city: description: The city name example: Chicago maxLength: 100 minLength: 1 type: string country: description: The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string line1: description: The first line of the street address example: 233 South Wacker Drive maxLength: 100 minLength: 1 type: string line2: description: The second line of the street address (apartment, suite, etc.) example: Suite 4700 maxLength: 100 type: string postalCode: description: The postal or ZIP code. Required for countries that use postal codes example: '60606' type: string state: description: The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: IL type: string type: enum: - operating - registered type: string required: - line1 - city - country - type type: object maxItems: 2 minItems: 1 type: array businessExpectedActivity: description: The business customer's expected transaction activity. Only accepted on business customers. properties: expectedCounterpartyTypes: description: The types of counterparties transactions are expected to involve. example: - domestic_individual - foreign_business items: enum: - domestic_individual - foreign_individual - domestic_business - foreign_business - financial_institution - government_entity - nonprofit - self type: string minItems: 1 type: array expectedGeographies: description: The ISO3166-1 Alpha-3 country codes transactions are expected to involve. See [Country Codes](/concepts/reference/supported-countries). example: - MEX - USA items: type: string maxItems: 10 minItems: 1 type: array expectedMonthlyTransactionCount: description: The expected number of transactions per month, as a bucket range. enum: - less_than_5 - 5_15 - 16_50 - 51_200 - 200_plus example: 16_50 type: string transactionFrequency: description: How often transactions are expected to occur. enum: - daily - weekly - biweekly - monthly - quarterly example: monthly type: string title: Business Expected Activity type: object businessInformation: description: Business information including identification number and all other relevant information to onboard the business customer. See [Business Verification Criteria](/concepts/onboarding/verification-profile). properties: accountPurpose: description: The business account purpose enum: - charitable_donations - ecommerce_retail_payments - investment_purposes - payments_to_friends_or_family_abroad - payroll - personal_or_living_expenses - protect_wealth - purchase_goods_and_services - receive_payments_for_goods_and_services - tax_optimization - third_party_money_transmission - treasury_management - other example: investment_purposes type: string accountPurposeDescription: description: The business account purpose description. This is required when accountPurpose is "other". example: Business checking account minLength: 1 nullable: true type: string complianceScreeningExplanation: description: The business compliance screening explanation. This is required when regulatedActivities contains "money_services". example: The business complies with all applicable regulations minLength: 1 nullable: true type: string description: description: The business description. example: Acme Corporation provides enterprise software solutions for supply chain management and logistics optimization. maxLength: 1000 minLength: 1 type: string entityType: description: The business entity type. enum: - cooperative - corporation - llc - partnership - sole_proprietorship - trust - other example: corporation type: string entityTypeDescription: description: The business entity type description. This is required when entityType is "other". example: Limited Liability Partnership minLength: 1 nullable: true type: string estimatedAnnualRevenueInUsd: description: The business estimated annual revenue in USD. Please refer to [estimated annual revenue in USD](/concepts/onboarding/verification-profile) for the list of valid ranges. enum: - 0_99999 - 100000_999999 - 1000000_9999999 - 10000000_49999999 - 50000000_249999999 - 250000000_plus example: 1000000_9999999 type: string expectedMonthlyPaymentsInUsd: description: The business expected monthly payments in USD. Please refer to [expected monthly payments in USD](/concepts/onboarding/verification-profile) for the list of valid ranges. example: '50000' type: string hasAuditedFinancialStatementsAttested: description: Must be true when `totalAssetsUsd` is at or above the audited-financials threshold (PD-16), confirming readiness to supply audited financial statements during verification. example: true nullable: true type: boolean identificationNumber: description: The business tax or primary identification number (e.g. EIN). Distinct from `registrationNumber`. Only alphanumeric characters (letters and numbers) are accepted - omit separators such as dashes or spaces (e.g. send "123456789", not "12-3456789"). example: '123456789' maxLength: 100 minLength: 1 pattern: ^[a-zA-Z0-9]+$ type: string identificationNumberDescription: description: The business identification number description. This is required when identificationNumberType is "other". example: Social Security Number minLength: 1 nullable: true type: string identificationNumberType: description: The business identification number type. Please refer to [identification number types](/concepts/onboarding/verification-profile) for the list of valid types. example: ein minLength: 1 type: string incorporatedOn: description: The date string in YYYY-MM-DD format example: '2026-01-01' type: string isDao: description: Whether the business is a decentralized autonomous organization (DAO). example: false type: boolean legalName: description: The business legal name. example: Acme Corporation Inc. minLength: 1 type: string licenseNumber: description: License or registration number issued by the regulatory authority. Required together with the other regulator fields when `regulatedActivities` includes `money_services`. example: MSB-123456789 maxLength: 200 minLength: 1 nullable: true type: string moneyServicesDescription: description: The business money services description. This is required when regulatedActivities contains "money_services". example: The business engages in money services minLength: 1 nullable: true type: string naicsCode: description: The business NAICS code. Please refer to NAICS codes for the list of valid codes. example: '511210' minLength: 1 type: string operatesInProhibitedCountries: description: Whether the business operates in prohibited countries. example: false type: boolean participatesInRegulatedFinancialActivity: type: boolean primarySourceOfFunds: description: The business primary source of funds enum: - business_loans - grants - inter_company_funds - investment_proceeds - legal_settlement - owners_capital - pension_retirement - sale_of_assets - sales_of_goods_and_services - third_party_funds - treasury_reserves example: sales_of_goods_and_services type: string primarySourceOfFundsDescription: description: The business primary source of funds description. example: Revenue from software licensing and consulting services minLength: 1 type: string registrationNumber: description: Company registration number (state registry, Companies House, etc.), separate from the tax identifier in `identificationNumber`. example: C1234567 maxLength: 100 minLength: 1 type: string regulatedActivities: description: The business regulated activities. example: - none_of_the_above items: description: The business regulated activity enum: - adult_entertainment - gambling - hold_client_funds - investment_services - lending_banking - marijuana_or_related_services - money_services - operate_foreign_exchange_virtual_currencies_brokerage_otc - pharmaceuticals - precious_metals_precious_stones_jewelry - safe_deposit_box_rentals - third_party_payment_processing - nicotine_tobacco_or_related_services - weapons_firearms_and_explosives - none_of_the_above example: money_services type: string minItems: 1 type: array regulatedActivitiesDescription: description: The business regulated activities description. This is required when regulatedActivities contains any value other than "none_of_the_above". example: The business engages in money services minLength: 1 nullable: true type: string regulatedFinancialActivityDescription: description: The business regulated financial activity description. This is required when participatesInRegulatedFinancialActivity is true. example: The business engages in money services minLength: 1 nullable: true type: string regulatoryAuthorityCountry: description: ISO-3166 alpha-3 country of the primary regulatory authority. Required together with `regulatoryAuthorityName` and `licenseNumber` when `regulatedActivities` includes `money_services`. example: USA nullable: true type: string regulatoryAuthorityName: description: Name of the primary regulatory authority. Required together with the other regulator fields when `regulatedActivities` includes `money_services`. example: Financial Crimes Enforcement Network (FinCEN) maxLength: 500 minLength: 1 nullable: true type: string totalAssetsUsd: description: Total business assets in USD as a decimal string (e.g. "2500000.00"). When this value is at or above the audited-financials threshold, `hasAuditedFinancialStatementsAttested` must be true. example: '2500000.00' nullable: true type: string tradeName: description: The business trade name. example: Acme Corp minLength: 1 type: string website: description: The business website URL. Must be a real http(s) website; a social media profile URL is acceptable. `https://` is added when the scheme is omitted. Optional - if omitted, a document with documentType `proof_of_nature_of_business_document` must be uploaded instead to satisfy verification. example: https://acmecorp.example.com maxLength: 2048 nullable: true type: string required: - entityTypeDescription - website - identificationNumberDescription - totalAssetsUsd - hasAuditedFinancialStatementsAttested - regulatoryAuthorityCountry - regulatoryAuthorityName - licenseNumber - accountPurposeDescription - regulatedActivitiesDescription - regulatedFinancialActivityDescription - moneyServicesDescription - complianceScreeningExplanation type: object email: {} enabledVerificationProfiles: description: Restricts which verification profile families this customer may onboard through. Must be a subset of the families enabled on your application; supplying one that is not enabled is rejected with a 422. Omit the field to inherit the application's setting. example: - a - c items: enum: - a - b - c - d type: string minItems: 1 type: array ipAddress: description: The IP address the customer used to sign up. Required by some verification providers. example: 203.0.113.4 type: string meta: additionalProperties: type: string description: Additional metadata associated with the customer example: crmId: '4412' type: object phone: {} type: description: Optional. Accepted so a client can echo the create shape; it cannot change the customer type. enum: - business example: business type: string title: Business Customer Update type: object required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CustomerResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Update a Customer by ID /v2/customer/{id}/face-verification-link: post: description: Generate a face verification link for a customer. operationId: postV2CustomerByIdFaceVerificationLink parameters: - description: Customer ID in: path name: id required: true schema: example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string responses: '201': content: application/json: schema: $ref: '#/components/schemas/GenerateFaceVerificationLinkResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Face Verification Link x-doc-path: - v2 - enhanced-due-diligence - face-verification-link /v2/customer/{id}/kyc-link: post: description: 'Regenerate a hosted KYC link for an existing customer. Only customers created via the onboarding link flow are supported. Supplying `enabledVerificationProfiles` **updates the customer**: the narrowing is persisted before the link is minted, so the hosted questionnaire and the profiles the customer is evaluated against cannot diverge.' operationId: postV2CustomerByIdKycLink parameters: - description: Customer ID in: path name: id required: true schema: example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string requestBody: content: application/json: schema: default: {} properties: enabledVerificationProfiles: description: Restricts which verification profile families this customer may onboard through. Must be a subset of the families enabled on your application; supplying one that is not enabled is rejected with a 422. Omit the field to inherit the application's setting. example: - a - c items: enum: - a - b - c - d type: string minItems: 1 type: array type: object required: false responses: '201': content: application/json: schema: $ref: '#/components/schemas/GenerateKycUrlResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Regenerate KYC Link x-doc-path: - v2 - customer - kyc /v2/customer/{id}/otp-send: post: description: Send an OTP code to a customer's contact information. operationId: postV2CustomerByIdOtpSend parameters: - description: Customer ID in: path name: id required: true schema: example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SendCustomerVerificationCodeDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SendVerificationCodeResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Send Verification Code x-doc-path: - v2 - enhanced-due-diligence - send-verification-code /v2/customer/{id}/otp-verify: post: description: Verify an OTP code for customer's contact information. operationId: postV2CustomerByIdOtpVerify parameters: - description: Customer ID in: path name: id required: true schema: example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/VerifyCustomerVerificationCodeDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/VerifyCustomerVerificationCodeResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Verify Verification Code x-doc-path: - v2 - enhanced-due-diligence - verify-verification-code /v2/customer/{id}/submit-verification: post: description: Submit a customer for verification. operationId: postV2CustomerByIdSubmitVerification parameters: - description: Customer ID in: path name: id required: true schema: example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/SubmitVerificationResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Submit Verification x-doc-path: - v2 - identity - submit-verification /v2/customer/{id}/tos-link: post: description: Create a TOS link for a customer. operationId: postV2CustomerByIdTosLink parameters: - description: Customer ID in: path name: id required: true schema: example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string responses: '201': content: application/json: schema: $ref: '#/components/schemas/GenerateTosLinkResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Create TOS Link x-doc-path: - v2 - enhanced-due-diligence - tos /v2/document: post: description: Upload a document for a customer. operationId: postV2Document parameters: [] requestBody: content: multipart/form-data: schema: oneOf: - description: Upload documents for individual customers. Supports identity documents (with country and side) and other documents (liveness report, tax forms, source of funds). example: country: USA description: Passport photo page documentType: passport file: (binary) side: front target: customer targetId: customer_66c4168d418a410eae282b83883bdc39 oneOf: - description: Upload identity documents for individual customers. Requires country of issuance and optionally the document side (front/back). properties: country: description: The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string description: description: Optional description or notes about the document example: Front side of driver's license type: string documentType: description: ID documents for individual customers. See [Document Guideline](/concepts/onboarding/identification-types) for requirements. enum: - passport - drivers - id_card - residence_permit - br_digital_drivers - br_digital_id example: passport type: string file: description: 'The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 8MB. Minimum file size: 10KB.' format: binary type: string side: description: The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents. enum: - front - back example: front type: string target: description: The target entity for which the document is being uploaded enum: - customer example: customer type: string targetId: description: The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string required: - targetId - file - country - target - documentType title: ID Document type: object - description: Upload non-ID documents for individual customers, such as liveness report, tax forms, or source-of-funds documentation. properties: description: description: Optional description or notes about the document example: Front side of driver's license type: string documentType: description: Non-ID documents for individual customers. enum: - proof_of_address_document - liveness_report_document - w8_ben_document - source_of_funds_document example: proof_of_address_document type: string file: description: 'The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 8MB. Minimum file size: 10KB.' format: binary type: string target: description: The target entity for which the document is being uploaded enum: - customer example: customer type: string targetId: description: The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string required: - targetId - file - target - documentType title: Other Document type: object title: Individual - description: Upload company documents for business customers, such as incorporation certificates, shareholder registries, or proof of address. example: description: Certificate of incorporation documentType: incorporation_cert_document file: (binary) target: customer targetId: customer_66c4168d418a410eae282b83883bdc39 properties: description: description: Optional description or notes about the document example: Front side of driver's license type: string documentType: description: Company documents for business customers. See [Business Document Guideline](/concepts/onboarding/identification-types) for requirements. enum: - proof_of_address_document - incorporation_cert_document - incorporation_articles_document - shareholder_registry_document - directors_registry_document - w8_ben_e_document - corporate_resolution_document - bank_statement_document - financial_statements_document - source_of_funds_document - regulated_activity_document - flow_of_funds_document - proof_of_nature_of_business_document example: incorporation_cert_document type: string file: description: 'The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 8MB. Minimum file size: 10KB.' format: binary type: string target: description: The target entity for which the document is being uploaded enum: - customer example: customer type: string targetId: description: The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string required: - targetId - file - target - documentType title: Business type: object - description: Upload documents for business representatives. Supports identity documents (with country and side) and proof of address. example: country: USA description: Passport photo page documentType: passport file: (binary) side: front target: business_representative targetId: business_representative_66c4168d418a410eae282b83883bdc39 oneOf: - description: Upload an ID document for a business representative. properties: country: description: The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string description: description: Optional description or notes about the document example: Front side of driver's license type: string documentType: description: ID documents for business representatives. See [Document Guideline](/concepts/onboarding/identification-types) for requirements. enum: - passport - drivers - id_card - residence_permit - br_digital_drivers - br_digital_id example: passport type: string file: description: 'The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 8MB. Minimum file size: 10KB.' format: binary type: string side: description: The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents. enum: - front - back example: front type: string target: description: The target entity for which the document is being uploaded enum: - business_representative example: business_representative type: string targetId: description: The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string required: - targetId - file - country - target - documentType title: ID Document type: object - description: Upload other documents for business representatives. properties: description: description: Optional description or notes about the document example: Front side of driver's license type: string documentType: description: Other documents for business representatives. enum: - proof_of_address_document - liveness_report_document - w9_document - w8_ben_document - source_of_funds_document example: proof_of_address_document type: string file: description: 'The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 8MB. Minimum file size: 10KB.' format: binary type: string target: description: The target entity for which the document is being uploaded enum: - business_representative example: business_representative type: string targetId: description: The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string required: - targetId - file - target - documentType title: Other Document type: object title: UBO - description: Upload supporting documents for transfers/payouts (e.g., invoices, contracts). Documents are uploaded first before linking to a transfer later. example: description: Invoice for third-party payment file: (binary) target: transfer properties: description: description: Optional description or notes about the document example: Invoice for third-party payment type: string file: description: 'The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 8MB. Minimum file size: 10KB.' format: binary type: string target: description: The target entity for which the document is being uploaded enum: - transfer example: transfer type: string required: - target - file title: Transfer type: object required: true responses: '201': content: application/json: schema: oneOf: - description: Response containing an uploaded document for an individual customer. example: country: USA createdAt: '2025-12-31T10:30:00.000Z' description: Passport photo page documentType: passport fileName: passport_front_20250101.pdf fileSize: 2048576 id: documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 mimeType: application/pdf side: front target: customer targetId: customer_66c4168d418a410eae282b83883bdc39 oneOf: - description: Response for an ID document uploaded for an individual customer. properties: country: description: The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA) example: USA type: string createdAt: description: The date and time the document was created example: '2025-12-31T10:30:00.000Z' type: string description: description: The description of the document example: Passport photo page type: string documentType: description: The type of the document enum: - drivers - passport - id_card - residence_permit - br_digital_drivers - br_digital_id example: passport type: string fileName: description: The name of the document file example: passport_front_20250101.pdf type: string fileSize: description: The size of the document in bytes example: 2048576 type: number id: description: The unique identifier of the document example: documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string mimeType: description: The MIME type of the document file example: application/pdf type: string side: description: The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents. enum: - front - back example: front type: string target: description: The target entity for which the document is being uploaded enum: - customer example: customer type: string targetId: description: The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 type: string required: - id - targetId - createdAt - fileName - fileSize - mimeType - description - target - documentType - country - side title: ID Document type: object - description: 'Response for a non-identity individual-customer document: proof_of_address_document, liveness_report_document, w8_ben_document, or source_of_funds_document.' properties: country: description: Country associated with the document when one was resolved for the upload example: DEU type: string createdAt: description: The date and time the document was created example: '2025-12-31T10:30:00.000Z' type: string description: description: The description of the document example: Passport photo page type: string documentType: description: Non-ID document type (liveness report, tax form, or source-of-funds declaration) enum: - passport - drivers - id_card - residence_permit - br_digital_drivers - br_digital_id - proof_of_address_document - liveness_report_document - w8_ben_document - source_of_funds_document example: proof_of_address_document type: string fileName: description: The name of the document file example: passport_front_20250101.pdf type: string fileSize: description: The size of the document in bytes example: 2048576 type: number id: description: The unique identifier of the document example: documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string mimeType: description: The MIME type of the document file example: application/pdf type: string side: description: Document side, if applicable enum: - front - back example: null type: string target: description: The target entity for which the document is being uploaded enum: - customer example: customer type: string targetId: description: The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 type: string required: - id - targetId - createdAt - fileName - fileSize - mimeType - description - target - documentType - country - side title: Other Document type: object title: Individual - description: Response containing an uploaded company document for a business customer. example: createdAt: '2025-12-31T10:30:00.000Z' description: Certificate of incorporation documentType: incorporation_cert_document fileName: incorporation_cert.pdf fileSize: 1024000 id: documentFile_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7 mimeType: application/pdf target: customer targetId: customer_66c4168d418a410eae282b83883bdc39 properties: createdAt: description: The date and time the document was created example: '2025-12-31T10:30:00.000Z' type: string description: description: The description of the document example: Passport photo page type: string documentType: description: The type of the document enum: - proof_of_address_document - incorporation_cert_document - incorporation_articles_document - shareholder_registry_document - directors_registry_document - w8_ben_e_document - corporate_resolution_document - bank_statement_document - financial_statements_document - source_of_funds_document - regulated_activity_document - flow_of_funds_document - proof_of_nature_of_business_document example: incorporation_cert_document type: string fileName: description: The name of the document file example: passport_front_20250101.pdf type: string fileSize: description: The size of the document in bytes example: 2048576 type: number id: description: The unique identifier of the document example: documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string mimeType: description: The MIME type of the document file example: application/pdf type: string target: description: The target entity for which the document is being uploaded enum: - customer example: customer type: string targetId: description: The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 type: string required: - id - targetId - createdAt - fileName - fileSize - mimeType - description - target - documentType title: Business Customer Document type: object - description: Response containing an uploaded document for a business representative (identity document, proof of address, or liveness report). example: country: USA createdAt: '2025-12-31T10:30:00.000Z' description: Passport photo page documentType: passport fileName: passport_front_20250101.pdf fileSize: 2048576 id: documentFile_c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8 mimeType: application/pdf side: front target: business_representative targetId: business_representative_66c4168d418a410eae282b83883bdc39 oneOf: - description: Response for an ID document uploaded for a business representative. properties: country: description: The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA) example: USA type: string createdAt: description: The date and time the document was created example: '2025-12-31T10:30:00.000Z' type: string description: description: The description of the document example: Passport photo page type: string documentType: description: The type of the document enum: - drivers - passport - id_card - residence_permit - br_digital_drivers - br_digital_id example: passport type: string fileName: description: The name of the document file example: passport_front_20250101.pdf type: string fileSize: description: The size of the document in bytes example: 2048576 type: number id: description: The unique identifier of the document example: documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string mimeType: description: The MIME type of the document file example: application/pdf type: string side: description: The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents. enum: - front - back example: front type: string target: enum: - business_representative type: string targetId: description: The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 type: string required: - id - targetId - createdAt - fileName - fileSize - mimeType - description - target - documentType - country - side title: ID Document type: object - description: Response for other documents uploaded for business representatives. properties: createdAt: description: The date and time the document was created example: '2025-12-31T10:30:00.000Z' type: string description: description: The description of the document example: Passport photo page type: string documentType: description: The type of the document enum: - passport - drivers - id_card - residence_permit - br_digital_drivers - br_digital_id - proof_of_address_document - liveness_report_document - w9_document - w8_ben_document - source_of_funds_document example: proof_of_address_document type: string fileName: description: The name of the document file example: passport_front_20250101.pdf type: string fileSize: description: The size of the document in bytes example: 2048576 type: number id: description: The unique identifier of the document example: documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string mimeType: description: The MIME type of the document file example: application/pdf type: string target: description: The target entity for which the document is being uploaded enum: - business_representative example: business_representative type: string targetId: description: The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 type: string required: - id - targetId - createdAt - fileName - fileSize - mimeType - description - target - documentType title: Other Document type: object title: Business Representative Document - description: Response for a supporting document uploaded for a transfer. example: fileSize: 2048576 id: document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 mimeType: application/pdf originalFilename: invoice_2025.pdf target: transfer uploadedAt: '2025-12-31T10:30:00.000Z' properties: fileSize: description: The size of the document in bytes example: 2048576 type: number id: description: The unique identifier of the uploaded document example: document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string mimeType: description: The MIME type of the document file example: application/pdf type: string originalFilename: description: The original filename of the uploaded document example: invoice_2025.pdf type: string target: description: The target entity for which the document was uploaded enum: - transfer example: transfer type: string uploadedAt: description: The date and time the document was uploaded example: '2025-12-31T10:30:00.000Z' oneOf: - type: string - {} required: - target - id - originalFilename - mimeType - fileSize - uploadedAt title: Transfer type: object description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Upload Document /v2/events: get: description: List events for the authenticated application, with optional filtering by webhook endpoint, event type, delivery status, and creation date range. operationId: getV2Events parameters: - in: query name: '' required: true schema: properties: createdEnd: description: ISO 8601 upper bound on event creation time (inclusive). example: '2026-12-31T23:59:59Z' format: date-time type: string createdStart: description: ISO 8601 lower bound on event creation time (inclusive). example: '2026-01-01T00:00:00Z' format: date-time type: string limit: default: '10' description: 'Number of items per page (default: 10)' example: 10 type: string page: default: '1' description: 'Page number of the list (default: 1)' example: 1 type: string status: description: Filter to events whose delivery is in this status. enum: - queued - delivering - delivered - failed example: delivered type: string x-enumNames: - QUEUED - DELIVERING - DELIVERED - FAILED type: description: Filter by event type. Supports wildcard suffix (e.g. "payment.*" matches all payment events). example: payment.* type: string webhookEndpointId: description: Filter to events that have a delivery for this webhook endpoint. example: webhook_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string required: - page - limit type: object responses: '200': content: application/json: schema: properties: data: description: Array of event presentations items: properties: createdAt: description: ISO 8601 timestamp when the event was created. example: '2026-01-01T00:00:00.000Z' type: string delivery: description: The most recent delivery for this event, or the one matching the webhookEndpointId/status filter if provided. Null if this event has no deliveries. nullable: true properties: attemptsUsed: description: Number of delivery attempts made so far. example: 1 type: number deliveredAt: description: ISO 8601 timestamp when the event was successfully delivered, or null if not yet delivered. example: '2026-01-01T00:05:00.000Z' nullable: true type: string id: description: The unique identifier of the delivery. example: eventDelivery_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string latestAttempt: description: The most recent delivery attempt for this delivery, or null if no attempt has been made yet. nullable: true properties: responseCode: description: HTTP status code returned by the endpoint, or null if no response was received. example: 200 nullable: true type: number success: description: Whether this attempt was delivered successfully. example: true type: boolean type: description: The kind of delivery attempt. enum: - original - replay - retry example: original type: string x-enumNames: - ORIGINAL - REPLAY - RETRY required: - type - success - responseCode type: object status: description: The current status of this delivery. enum: - queued - delivering - delivered - failed example: delivered type: string x-enumNames: - QUEUED - DELIVERING - DELIVERED - FAILED webhookEndpointId: description: The unique identifier of the webhook endpoint this delivery targets. example: webhook_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string required: - id - webhookEndpointId - status - attemptsUsed - deliveredAt - latestAttempt type: object id: description: The unique identifier of the event. example: event_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string sequence: description: Monotonically increasing sequence number for ordering events, or null if not assigned. example: 3 nullable: true type: number type: description: The type of the event. enum: - '*' - customer.* - transfer.* - document.* - service.* - customer.created - customer.pending - customer.approved - customer.rejected - transfer.created - transfer.pendingFunding - transfer.pendingReview - transfer.fundsReceived - transfer.processing - transfer.succeeded - transfer.returned - transfer.pendingRefundInformation - transfer.failed - transfer.canceled - transfer.refunded - transfer.unexpectedError - transfer.failedPrecondition - transfer.expired - transfer.unfunded - transfer.processingRefund - transfer.refundFailed - document.pending - document.processing - document.verified - document.rejected - service.pending - service.processing - service.succeeded - service.failed - service.cancelled example: transfer.succeeded type: string x-enumNames: - ALL - ALL_CUSTOMER - ALL_TRANSFER - ALL_DOCUMENT - ALL_SERVICE - CREATE_CUSTOMER - PENDING_CUSTOMER - APPROVE_CUSTOMER - REJECT_CUSTOMER - CREATE_TRANSFER - PENDING_FUNDING_TRANSFER - PENDING_REVIEW_TRANSFER - FUNDS_RECEIVED_TRANSFER - PROCESSING_TRANSFER - SUCCESSFUL_TRANSFER - RETURNED_TRANSFER - PENDING_REFUND_INFORMATION_TRANSFER - FAILED_TRANSFER - CANCELLED_TRANSFER - REFUNDED_TRANSFER - UNEXPECTED_ERROR_TRANSFER - FAILED_PRECONDITION_TRANSFER - EXPIRED_TRANSFER - UNFUNDED_TRANSFER - PROCESSING_REFUND_TRANSFER - REFUND_FAILED_TRANSFER - PENDING_DOCUMENT - PROCESSING_DOCUMENT - VERIFIED_DOCUMENT - REJECTED_DOCUMENT - PENDING_SERVICE - PROCESSING_SERVICE - SUCCESSFUL_SERVICE - FAILED_SERVICE - CANCELLED_SERVICE required: - id - type - createdAt - sequence - delivery type: object type: array hasNext: description: Whether there is a next page example: false type: boolean hasPrevious: description: Whether there is a previous page example: false type: boolean limit: description: Number of items per page example: 10 exclusiveMaximum: false exclusiveMinimum: false maximum: 100 minimum: 1 type: number page: description: Current page number example: 1 type: number total: description: Total number of items example: 1 type: number totalPages: description: Total number of pages example: 1 type: number required: - page - limit - total - totalPages - hasNext - hasPrevious - data type: object description: A paginated list of events. '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: List Events V2 /v2/events/replay/{eventDeliveryId}: post: description: Redeliver an event to its webhook endpoint by the ID of a prior delivery attempt. operationId: postV2EventsReplayByEventDeliveryId parameters: - in: path name: eventDeliveryId required: true schema: type: string responses: '201': description: The replay is queued for delivery. No content is returned; poll the event to observe the new attempt. '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Replay an Event Delivery V2 /v2/events/{id}: get: description: Retrieve an event by its ID. operationId: getV2EventsById parameters: - in: path name: id required: true schema: type: string responses: '200': content: application/json: schema: properties: attempts: description: Delivery attempts across the deliveries of this event items: properties: attemptedAt: description: ISO 8601 timestamp when this attempt was made. example: '2026-01-01T00:05:00.000Z' type: string id: description: The unique identifier of the delivery attempt. example: atmpt_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string latencyMs: description: Round-trip latency of this attempt in milliseconds, or null if no response was received. example: 128 nullable: true type: number responseBody: description: Response body returned by the endpoint, or null if no response was received. example: OK nullable: true type: string responseCode: description: HTTP status code returned by the endpoint, or null if no response was received. example: 200 nullable: true type: number success: description: Whether this attempt was delivered successfully. example: true type: boolean type: description: The kind of delivery attempt. enum: - original - replay - retry example: original type: string x-enumNames: - ORIGINAL - REPLAY - RETRY required: - id - type - attemptedAt - success - responseCode - responseBody - latencyMs type: object type: array createdAt: description: ISO 8601 timestamp when the event was created. example: '2026-01-01T00:00:00.000Z' type: string deliveries: description: Deliveries of this event, one per subscribed endpoint items: properties: attemptsUsed: description: Number of delivery attempts made so far. example: 1 type: number deliveredAt: description: ISO 8601 timestamp when the event was successfully delivered, or null if not yet delivered. example: '2026-01-01T00:05:00.000Z' nullable: true type: string id: description: The unique identifier of the delivery. example: eventDelivery_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string latestAttempt: description: The most recent delivery attempt for this delivery, or null if no attempt has been made yet. nullable: true properties: responseCode: description: HTTP status code returned by the endpoint, or null if no response was received. example: 200 nullable: true type: number success: description: Whether this attempt was delivered successfully. example: true type: boolean type: description: The kind of delivery attempt. enum: - original - replay - retry example: original type: string x-enumNames: - ORIGINAL - REPLAY - RETRY required: - type - success - responseCode type: object status: description: The current status of this delivery. enum: - queued - delivering - delivered - failed example: delivered type: string x-enumNames: - QUEUED - DELIVERING - DELIVERED - FAILED webhookEndpointId: description: The unique identifier of the webhook endpoint this delivery targets. example: webhook_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string required: - id - webhookEndpointId - status - attemptsUsed - deliveredAt - latestAttempt type: object type: array id: description: The unique identifier of the event. example: event_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string sequence: description: Monotonically increasing sequence number for ordering events, or null if not assigned. example: 3 nullable: true type: number type: description: The type of the event. enum: - '*' - customer.* - transfer.* - document.* - service.* - customer.created - customer.pending - customer.approved - customer.rejected - transfer.created - transfer.pendingFunding - transfer.pendingReview - transfer.fundsReceived - transfer.processing - transfer.succeeded - transfer.returned - transfer.pendingRefundInformation - transfer.failed - transfer.canceled - transfer.refunded - transfer.unexpectedError - transfer.failedPrecondition - transfer.expired - transfer.unfunded - transfer.processingRefund - transfer.refundFailed - document.pending - document.processing - document.verified - document.rejected - service.pending - service.processing - service.succeeded - service.failed - service.cancelled example: transfer.succeeded type: string x-enumNames: - ALL - ALL_CUSTOMER - ALL_TRANSFER - ALL_DOCUMENT - ALL_SERVICE - CREATE_CUSTOMER - PENDING_CUSTOMER - APPROVE_CUSTOMER - REJECT_CUSTOMER - CREATE_TRANSFER - PENDING_FUNDING_TRANSFER - PENDING_REVIEW_TRANSFER - FUNDS_RECEIVED_TRANSFER - PROCESSING_TRANSFER - SUCCESSFUL_TRANSFER - RETURNED_TRANSFER - PENDING_REFUND_INFORMATION_TRANSFER - FAILED_TRANSFER - CANCELLED_TRANSFER - REFUNDED_TRANSFER - UNEXPECTED_ERROR_TRANSFER - FAILED_PRECONDITION_TRANSFER - EXPIRED_TRANSFER - UNFUNDED_TRANSFER - PROCESSING_REFUND_TRANSFER - REFUND_FAILED_TRANSFER - PENDING_DOCUMENT - PROCESSING_DOCUMENT - VERIFIED_DOCUMENT - REJECTED_DOCUMENT - PENDING_SERVICE - PROCESSING_SERVICE - SUCCESSFUL_SERVICE - FAILED_SERVICE - CANCELLED_SERVICE required: - id - type - createdAt - sequence - deliveries - attempts type: object description: The requested event, with its deliveries and delivery attempts. '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Get an Event V2 /v2/offloader-wallet: get: description: List all offloader wallets operationId: getV2OffloaderWallet parameters: - description: 'Page number of the list (default: 1)' in: query name: page required: true schema: default: '1' example: 1 type: string - description: 'Number of items per page (default: 10)' in: query name: limit required: true schema: default: '10' example: 10 type: string - description: Filter offloader wallets by customer ID. Only wallets belonging to this customer will be returned. in: query name: customerId required: false schema: example: customer_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListOffloaderWalletsResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: List offloader wallets post: description: Create a new offloader wallet. operationId: postV2OffloaderWallet parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateOffloaderWalletRequestDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/OffloaderWalletResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Create an offloader wallet /v2/offloader-wallet/{id}: get: description: Get an offloader wallet by id operationId: getV2OffloaderWalletById parameters: - in: path name: id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/OffloaderWalletResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Get an offloader wallet patch: description: Update an offloader wallet by id operationId: patchV2OffloaderWalletById parameters: - in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateOffloaderWalletRequestDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/OffloaderWalletResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Update an offloader wallet /v2/quote: get: description: List quotes for the application. Repeat a currency parameter to match any supplied value; source and destination filters combine. operationId: getV2Quote parameters: - description: 'Page number of the list (default: 1)' in: query name: page required: true schema: default: '1' example: 1 type: string - description: 'Number of items per page (default: 10)' in: query name: limit required: true schema: default: '10' example: 10 type: string - description: Filter quotes by customer ID. in: query name: customerId required: false schema: example: customer_3faa484998f44cfead9668608b9ee1f5 pattern: ^customer_[a-z0-9]+$ type: string - description: Filter quotes by status. in: query name: status required: false schema: enum: - active - used - expired example: active type: string - description: Filter by one or more source currencies. Repeat the query parameter for multiple values. explode: true in: query name: sourceCurrency required: false schema: items: enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn type: string type: array style: form - description: Filter by one or more destination currencies. Repeat the query parameter for multiple values. explode: true in: query name: destinationCurrency required: false schema: items: enum: - usdc - usdt - eurc - usd - eur - brl - mxn - mxn type: string type: array style: form responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListQuotesResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: List Quotes post: description: Create a locked exchange rate quote. The quote is valid for the specified duration and can be used once to create a transfer. operationId: postV2Quote parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateQuoteRequestDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateQuoteResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Create a Quote /v2/quote/{id}: get: description: Retrieve a single quote by its ID. operationId: getV2QuoteById parameters: - description: The unique quote ID. in: path name: id required: true schema: example: quote_d243ab2b1de4447d8a046d87fefe58cf pattern: ^quote_[a-z0-9]+$ type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GetQuoteResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Get a Quote put: description: Mark an active quote as used or expired. Only active quotes can be updated. operationId: putV2QuoteById parameters: - description: The unique quote ID. in: path name: id required: true schema: example: quote_d243ab2b1de4447d8a046d87fefe58cf pattern: ^quote_[a-z0-9]+$ type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateQuoteStatusDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/GetQuoteResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Update Quote Status /v2/sandbox/customer/{id}/advance: post: description: Sandbox only. Reports a simulated verification outcome; sandbox never calls the verification providers. Approved approves every verification profile the customer has (A, and C and D where they apply), so the customer can use every route those profiles open; rejected rejects them all. Pass profile to advance profile A only. Customers onboarded through the hosted KYC link are advanced the same way. Advancing to the current outcome changes nothing; a rejected customer cannot be approved (422). operationId: postV2SandboxCustomerByIdAdvance parameters: - in: path name: id required: true schema: type: string requestBody: content: application/json: schema: properties: outcome: description: The verification outcome the provider reports for the customer. enum: - approved - rejected example: approved type: string profile: description: Advance only this profile A (kyc_profile_a for individuals, kyb_profile_a for businesses). Omit it to advance every profile the customer has. enum: - kyc_profile_a - kyb_profile_a example: kyc_profile_a type: string required: - outcome type: object required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CustomerResponseDto' description: '' '202': description: Identity verification passed and the provider customer creation is queued; profile A stays pending until the provider has created the customer. '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '409': content: application/json: examples: Customer not available on this route: summary: Customer not available on this route value: code: customer/onboarding-v3-managed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: This customer cannot be used with this route. status: 409 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Conflict - the customer cannot be used with this route '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Advance a sandbox customer /v2/sandbox/faucet: post: description: 'Sandbox only. Mints SPHEREUSDC, the sandbox test stablecoin, to the given address on a test network (ethereum is Sepolia, sol is Solana Devnet). The mint is submitted asynchronously: poll GET /v2/sandbox/faucet/{id} for the tx hash. Send an Idempotency-Key header to make retries safe: the same key returns the same mint, and reusing a key with different parameters is rejected with 409. Limits: 10 mints per hour per application, at most 1000 per mint, and a wallet balance cap of 10000 (409 when a mint would exceed it).' operationId: postV2SandboxFaucet parameters: - description: 'Caller idempotency key (1 to 128 characters: letters, digits, "_", ".", ":" or "-"). Scoped to the application.' in: header name: Idempotency-Key required: false schema: type: string requestBody: content: application/json: schema: properties: address: description: Wallet address that receives the tokens. example: '0xdEc79ba951875fc930F5309181d5b71b821E97FE' maxLength: 255 minLength: 1 type: string amount: description: Amount of SPHEREUSDC in human units, as a decimal string. Defaults to 1000; at most 1000 per request. A mint that would take the wallet above 10000 SPHEREUSDC, counting mints still pending, is refused with 409. example: '1000' pattern: ^\d+(\.\d+)?$ type: string network: description: 'Test network to mint on: ethereum (Sepolia) or sol (Solana Devnet).' enum: - ethereum - sol example: ethereum type: string required: - network - address type: object required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/FaucetMintResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Mint test tokens /v2/sandbox/faucet/{id}: get: description: Sandbox only. Returns the mint with its current status; txHash is set once the mint is on chain. Only mints created by the calling application are visible. operationId: getV2SandboxFaucetById parameters: - in: path name: id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/FaucetMintResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Retrieve a test token mint /v2/sandbox/transfer/{id}/advance: post: description: Sandbox only. Moves a transfer to the given status through the same status pipeline production uses. The matching transfer.* webhook is delivered when webhooks are enabled for the application; undeliverable has no webhook event. Advancing to the current status is a no-op that returns the transfer unchanged; a transition the lifecycle does not allow is rejected with 422. operationId: postV2SandboxTransferByIdAdvance parameters: - in: path name: id required: true schema: type: string requestBody: content: application/json: schema: properties: status: description: The status to advance the transfer to. enum: - pendingFunding - pendingReview - fundsReceived - processing - succeeded - undeliverable - returned - processingRefund - refundFailed - pendingRefundInformation - failed - canceled - refunded - unexpectedError - failedPrecondition - expired - unfunded example: succeeded type: string x-enumNames: - PENDING_FUNDING - PENDING_REVIEW - FUNDS_RECEIVED - PROCESSING - SUCCEEDED - UNDELIVERABLE - RETURNED - PROCESSING_REFUND - REFUND_FAILED - PENDING_REFUND_INFO - FAILED - CANCELED - REFUNDED - UNEXPECTED_ERROR - FAILED_PRECONDITION - EXPIRED - UNFUNDED required: - status type: object required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/GetTransferResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Advance a sandbox transfer /v2/transfer: get: description: List all transfers operationId: getV2Transfer parameters: - description: 'Page number of the list (default: 1)' in: query name: page required: true schema: default: '1' example: 1 type: string - description: 'Number of items per page (default: 10)' in: query name: limit required: true schema: default: '10' example: 10 type: string - description: Query by Customer ID. in: query name: customer required: false schema: example: customer_123abc... type: string - description: Query by Payout status. See [Transfer Lifecycle](/concepts/transfers/lifecycle) for status definitions. in: query name: status required: false schema: enum: - pendingFunding - pendingReview - fundsReceived - processing - succeeded - undeliverable - returned - processingRefund - refundFailed - pendingRefundInformation - failed - canceled - refunded - unexpectedError - failedPrecondition - expired - unfunded example: succeeded type: string x-enumNames: - PENDING_FUNDING - PENDING_REVIEW - FUNDS_RECEIVED - PROCESSING - SUCCEEDED - UNDELIVERABLE - RETURNED - PROCESSING_REFUND - REFUND_FAILED - PENDING_REFUND_INFO - FAILED - CANCELED - REFUNDED - UNEXPECTED_ERROR - FAILED_PRECONDITION - EXPIRED - UNFUNDED - description: Query by Payout type. in: query name: type required: false schema: enum: - offRamp - onChain - onRamp - microdeposit - unmatchedDeposit - fiatToFiat example: onRamp type: string x-enumNames: - OffRamp - OnChain - OnRamp - Microdeposit - UnmatchedDeposit - FiatToFiat - description: 'Comma-separated sort fields. Prefix with "-" for descending, "+" (or no prefix) for ascending. Allowed fields: created, updated, status, type, amount. Example: "type,-created".' in: query name: sort required: true schema: default: '-created' example: '-created' type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListTransfersResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: List Transfers post: description: Create a new transfer. operationId: postV2Transfer parameters: [] requestBody: content: application/json: schema: oneOf: - properties: customer: description: The customer's ID. example: customer_1234567890 pattern: ^customer_[a-z0-9]+$ type: string destination: properties: id: description: The payment instrument ID (wallet or bank account). example: wallet_1234567890abcdef1234567890abcdef12345678 type: string type: description: 'The payment instrument type: wallet or bank_account.' enum: - bank_account - wallet example: wallet type: string required: - type - id type: object documentId: description: ID of a pre-uploaded supporting document (from POST /v2/document with target `transfer`). Required for third-party transfers on certain routes. A transfer is considered third-party when the destination bank account owner is not the customer themselves (i.e. the bank account relationship is not `self`). The document should evidence the purpose of the transfer - for example, an invoice, contract, payment agreement, or proof of services rendered. example: document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 minLength: 1 pattern: ^document_[a-z0-9]+$ type: string externalId: description: Integrator-defined external reference. The value is not stored as unique. example: merchant_ref_123 type: string paymentDescription: description: A free-text description of the payment purpose. Required for third-party off-ramp transfers (where the destination bank account owner relationship is not `self`). Max 500 characters. example: INV-2026-004 - Q1 software services maxLength: 500 minLength: 1 type: string paymentReason: description: The reason for the payment. Required for SWIFT transfers, BRL transfers, and for third-party off-ramp transfers (where the destination bank account owner relationship is not `self`). enum: - personal - investment - real_estate - tax - loan - bills - reimbursement - professional_services - family_support - education - rent - donation - gift - insurance - medical - savings - travel - mortgage - fine - dividend - agriculture - import_export - art - other example: professional_services type: string quoteId: description: The quote ID from a previously created quote. The transfer uses the locked exchange rate, currency, and network from the quote. example: quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string referenceSide: {} returnAddress: description: Crypto address where funds are returned on failed transactions. Must be 1-255 characters and valid for the source network. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string source: properties: id: description: The payment instrument ID (wallet or bank account). example: wallet_1234567890abcdef1234567890abcdef12345678 type: string type: description: 'The payment instrument type: wallet or bank_account.' enum: - bank_account - wallet example: wallet type: string required: - type - id type: object required: - customer - quoteId - source - destination title: Transfer with Quote type: object - description: 'Standard floating-rate transfer. For BRL (PIX) transfers: `referenceSide` may be omitted or set to `source`, but `destination` is not supported; only `polygon`, `ethereum`, `base`, and `tron` wallet networks are supported (not `sol`); `integratorFixedFee` is not allowed - use `integratorBpsFeeRate` instead. See [BRL/PIX transfer constraints](/concepts/transfers/overview#brlpix-transfer-constraints) for current transfer limits.' properties: amount: description: 'The transfer amount, interpreted according to `referenceSide`: source amount to send when `referenceSide` is `source`, or destination amount to receive when `referenceSide` is `destination`. Defaults to source amount when `referenceSide` is omitted. Must have exactly 2 decimal places. Transfer limits are set dynamically based on due diligence and may change over time - see [BRL/PIX transfer constraints](/concepts/transfers/overview#brlpix-transfer-constraints) for current BRL limits.' example: '100.00' type: string customer: description: The customer's ID. example: customer_1234567890 pattern: ^customer_[a-z0-9]+$ type: string destination: oneOf: - description: The destination of an `On-ramp` transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: currency: description: The destination currency for an `On-ramp` transfer. This should be the currency of the wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string id: description: The destination wallet ID. example: wallet_1234567890abcdef1234567890abcdef12345678 pattern: ^wallet_[a-z0-9]+$ type: string network: description: The destination network of the customer's wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - ethereum - arbitrum - polygon - base - avalanche - tron example: sol type: string type: description: 'The destination type: wallet.' enum: - wallet example: wallet type: string required: - type - id - currency - network title: Destination Wallet type: object - description: The destination bank account for transfers. properties: achReference: description: Reference sent to the receiving institution with ACH transfers, 1-10 characters. example: REF123 maxLength: 10 minLength: 1 type: string currency: description: 'The destination currency: [usd, eur, brl, mxn]. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).' enum: - usd - eur - brl example: usd type: string id: description: The destination bank account ID. example: bank_account_123abc... type: string network: description: 'The destination network: [wire, ach, achPush, achPull, achSameDay, swift, sepa, pix, spei]. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).' enum: - ach - wire - sepa - pix - swift example: ach type: string sepaReference: description: Reference sent to the receiving institution with SEPA transfers, 6-140 characters. example: INV-2024-001 maxLength: 140 minLength: 6 type: string type: description: 'The destination type: bank_account.' enum: - bank_account example: bank_account type: string wireMessage: description: Message sent to the receiving institution with wire transfers, 1-105 characters. example: 'Invoice #1024' maxLength: 105 minLength: 1 type: string required: - type - id - currency - network title: Destination Bank Account type: object documentId: description: ID of a pre-uploaded supporting document (from POST /v2/document with target `transfer`). Required for third-party transfers on certain routes. A transfer is considered third-party when the destination bank account owner is not the customer themselves (i.e. the bank account relationship is not `self`). The document should evidence the purpose of the transfer - for example, an invoice, contract, payment agreement, or proof of services rendered. example: document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 minLength: 1 pattern: ^document_[a-z0-9]+$ type: string expectedProvider: description: Provider returned by the receipt preview. Creation fails if route selection changed, so the caller can refresh the preview before retrying. enum: - bridge - lumx - symmetry_arcadia - symmetry_titan type: string externalId: description: Integrator-defined external reference. The value is not stored as unique. example: merchant_ref_123 type: string integratorBpsFeeRate: description: The integrator BPS fee rate as an integer string (1 bps = 0.01%). This is the only fee mechanism supported for BRL transfers. example: '20' pattern: ^\d+$ type: string integratorFixedFee: description: The integrator fixed fee amount in source currency. Must have exactly 2 decimal places. Not supported for BRL transfers - use integratorBpsFeeRate instead. example: '2.00' type: string paymentDescription: description: A free-text description of the payment purpose. Required for third-party off-ramp transfers (where the destination bank account owner relationship is not `self`). Max 500 characters. example: INV-2026-004 - Q1 software services maxLength: 500 minLength: 1 type: string paymentReason: description: The reason for the payment. Required for SWIFT transfers, BRL transfers, and for third-party off-ramp transfers (where the destination bank account owner relationship is not `self`). enum: - personal - investment - real_estate - tax - loan - bills - reimbursement - professional_services - family_support - education - rent - donation - gift - insurance - medical - savings - travel - mortgage - fine - dividend - agriculture - import_export - art - other example: professional_services type: string quoteId: {} referenceSide: description: Controls whether `amount` is interpreted as the source amount to send or the destination amount to receive. Defaults to `source` when omitted. enum: - source - destination example: destination type: string returnAddress: description: Crypto address where funds are returned on failed transactions. Must be 1-255 characters and valid for the source network. example: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97' type: string source: oneOf: - description: The source of an `Off-ramp` transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: currency: description: The source currency for an `Off-ramp` transfer. This should be the currency of the wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string id: description: The source wallet ID. example: wallet_1234567890abcdef1234567890abcdef12345678 pattern: ^wallet_[a-z0-9]+$ type: string network: description: The source network of the customer's wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - ethereum - arbitrum - polygon - base - avalanche - tron example: sol type: string type: description: 'The source type: wallet.' enum: - wallet example: wallet type: string required: - type - id - currency - network title: Source Wallet type: object - description: The source of an `On-ramp` transfer. properties: currency: description: The source currency for an `On-ramp` transfer. This should be the currency of the bank account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usd - eur - brl - mxn example: usd type: string id: description: The source bank account ID. example: bank_account_1234567890 pattern: ^bankAccount_[a-z0-9]+$ type: string network: description: The source network of the bank account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach - wire - sepa - pix - swift - spei example: ach type: string type: description: 'The source type: bank_account.' enum: - bank_account example: bank_account type: string required: - type - id - currency - network title: Source Bank Account type: object required: - amount - customer - source - destination title: Transfer type: object required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateTransferResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Create a Transfer /v2/transfer/{id}: delete: description: Cancel a specific transfer. operationId: deleteV2TransferById parameters: - in: path name: id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/CancelTransferResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Cancel a Transfer get: description: Retrieve a specific transfer operationId: getV2TransferById parameters: - description: The payout ID. in: path name: id required: true schema: example: payout_d243ab2b1de4447d8a046d87fefe58cf type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GetTransferResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Retrieve a Transfer /v2/virtual-account: get: description: List all active virtual accounts for the authenticated application. operationId: getV2VirtualAccount parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListVirtualAccountsResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: List Virtual Accounts post: description: Create a new virtual account that converts incoming fiat deposits to crypto. operationId: postV2VirtualAccount parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateVirtualAccountRequestDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/VirtualAccountResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Create a Virtual Account /v2/virtual-account/{virtualAccountId}: get: description: Retrieve a virtual account by its ID. operationId: getV2VirtualAccountByVirtualAccountId parameters: - in: path name: virtualAccountId required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/VirtualAccountResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Get a Virtual Account patch: description: Update the destination, network, or fee configuration of a virtual account. operationId: patchV2VirtualAccountByVirtualAccountId parameters: - in: path name: virtualAccountId required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateVirtualAccountRequestDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/VirtualAccountResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Update a Virtual Account /v2/virtual-account/{virtualAccountId}/deactivate: patch: description: Deactivate a virtual account so it no longer accepts deposits. operationId: patchV2VirtualAccountByVirtualAccountIdDeactivate parameters: - in: path name: virtualAccountId required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/VirtualAccountResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Deactivate a Virtual Account /v2/virtual-account/{virtualAccountId}/reactivate: patch: description: Reactivate a previously deactivated virtual account. operationId: patchV2VirtualAccountByVirtualAccountIdReactivate parameters: - in: path name: virtualAccountId required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/VirtualAccountResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Reactivate a Virtual Account /v2/virtual-account/{virtualAccountId}/transfer: get: deprecated: true description: 'List the transfer history for a specific virtual account. Deprecated: the main `GET /v2/transfer` endpoint already returns virtual account transfers and will support filtering to the same effect.' operationId: getV2VirtualAccountByVirtualAccountIdTransfer parameters: - in: path name: virtualAccountId required: true schema: type: string responses: '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: List Virtual Account Transfers /v2/wallet: get: description: List all wallets with pagination. Optionally filter by customer. operationId: getV2Wallet parameters: - description: 'Page number of the list (default: 1)' in: query name: page required: true schema: default: '1' example: 1 type: string - description: 'Number of items per page (default: 10)' in: query name: limit required: true schema: default: '10' example: 10 type: string - description: Filter by customer ID in: query name: customerId required: false schema: example: customer_66c4168d418a410eae282b83883bdc39 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/WalletListResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: List Wallets post: description: Create a new wallet and associate it with a customer. operationId: postV2Wallet parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateWalletDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/WalletResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Create a Wallet /v2/wallet/{id}: delete: description: Delete a wallet by its ID operationId: deleteV2WalletById parameters: - description: The wallet ID in: path name: id required: true schema: example: wallet_ce745ef7f3df4b9a8bff1301ce24b045 minLength: 1 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/DeleteWalletResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Delete a Wallet get: description: Get information about a wallet by its ID operationId: getV2WalletById parameters: - description: The wallet ID in: path name: id required: true schema: example: wallet_ce745ef7f3df4b9a8bff1301ce24b045 minLength: 1 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/WalletResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Get a Wallet /v2/webhook-endpoints: get: description: List all webhook endpoints for the authenticated application, with optional filtering by status and subscribed event types. operationId: getV2WebhookEndpoints parameters: - in: query name: '' required: true schema: properties: limit: default: '10' description: 'Number of items per page (default: 10)' example: 10 type: string page: default: '1' description: 'Page number of the list (default: 1)' example: 1 type: string status: description: Filter endpoints by state. enum: - enabled - errored - disabled - deleted example: enabled type: string x-enumNames: - ENABLED - ERRORED - DISABLED - DELETED subscribedEvents: description: Comma-separated list of event types. Returns endpoints subscribed to at least one of them. example: payment.succeeded,payment.failed type: string required: - page - limit type: object responses: '200': content: application/json: schema: properties: data: description: Array of webhook endpoint presentations items: properties: apiVersion: description: API version date string this endpoint was configured with, or null if not set. example: '2026-04-01' nullable: true type: string createdAt: description: ISO 8601 timestamp when the endpoint was created. example: '2026-01-01T00:00:00.000Z' type: string description: description: Human-readable description of this webhook endpoint, or null if not set. example: Production payment events handler nullable: true type: string id: description: The unique identifier of the webhook endpoint. example: webhook_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string metadata: description: Arbitrary key-value metadata attached to this endpoint, or null if not set. example: environment: prod team: payments nullable: true status: description: The current state of this endpoint. enum: - enabled - errored - disabled - deleted example: enabled type: string x-enumNames: - ENABLED - ERRORED - DISABLED - DELETED subscribedEvents: description: List of event types this endpoint receives. example: - customer.created - transfer.succeeded items: enum: - '*' - customer.* - transfer.* - document.* - service.* - customer.created - customer.pending - customer.approved - customer.rejected - transfer.created - transfer.pendingFunding - transfer.pendingReview - transfer.fundsReceived - transfer.processing - transfer.succeeded - transfer.returned - transfer.pendingRefundInformation - transfer.failed - transfer.canceled - transfer.refunded - transfer.unexpectedError - transfer.failedPrecondition - transfer.expired - transfer.unfunded - transfer.processingRefund - transfer.refundFailed - document.pending - document.processing - document.verified - document.rejected - service.pending - service.processing - service.succeeded - service.failed - service.cancelled type: string x-enumNames: - ALL - ALL_CUSTOMER - ALL_TRANSFER - ALL_DOCUMENT - ALL_SERVICE - CREATE_CUSTOMER - PENDING_CUSTOMER - APPROVE_CUSTOMER - REJECT_CUSTOMER - CREATE_TRANSFER - PENDING_FUNDING_TRANSFER - PENDING_REVIEW_TRANSFER - FUNDS_RECEIVED_TRANSFER - PROCESSING_TRANSFER - SUCCESSFUL_TRANSFER - RETURNED_TRANSFER - PENDING_REFUND_INFORMATION_TRANSFER - FAILED_TRANSFER - CANCELLED_TRANSFER - REFUNDED_TRANSFER - UNEXPECTED_ERROR_TRANSFER - FAILED_PRECONDITION_TRANSFER - EXPIRED_TRANSFER - UNFUNDED_TRANSFER - PROCESSING_REFUND_TRANSFER - REFUND_FAILED_TRANSFER - PENDING_DOCUMENT - PROCESSING_DOCUMENT - VERIFIED_DOCUMENT - REJECTED_DOCUMENT - PENDING_SERVICE - PROCESSING_SERVICE - SUCCESSFUL_SERVICE - FAILED_SERVICE - CANCELLED_SERVICE type: array updatedAt: description: ISO 8601 timestamp when the endpoint was last updated. example: '2026-01-01T00:00:00.000Z' type: string url: description: The HTTPS URL events are delivered to. example: https://example.com/webhooks/sphere type: string required: - id - url - subscribedEvents - status - apiVersion - description - metadata - createdAt - updatedAt type: object type: array hasNext: description: Whether there is a next page example: false type: boolean hasPrevious: description: Whether there is a previous page example: false type: boolean limit: description: Number of items per page example: 10 exclusiveMaximum: false exclusiveMinimum: false maximum: 100 minimum: 1 type: number page: description: Current page number example: 1 type: number total: description: Total number of items example: 1 type: number totalPages: description: Total number of pages example: 1 type: number required: - page - limit - total - totalPages - hasNext - hasPrevious - data type: object description: A paginated list of webhook endpoints. '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: List Webhook Endpoints V2 post: description: Register a new webhook endpoint to receive event deliveries for the specified subscribed events. operationId: postV2WebhookEndpoints parameters: [] requestBody: content: application/json: schema: properties: apiVersion: description: API version date string provided by the client. example: '2026-04-01' type: string description: description: Human-readable description of this webhook endpoint. example: Production payment events handler maxLength: 500 type: string metadata: additionalProperties: {} description: Arbitrary key-value metadata to attach to this endpoint. example: environment: prod team: payments type: object subscribedEvents: description: List of event types this endpoint should receive. example: - customer.created - transfer.succeeded items: type: string minItems: 1 type: array url: description: The HTTPS URL to deliver webhook events to. example: https://example.com/webhooks/sphere format: uri maxLength: 2048 type: string required: - url - subscribedEvents - apiVersion type: object required: true responses: '201': content: application/json: schema: properties: apiVersion: description: API version date string this endpoint was configured with, or null if not set. example: '2026-04-01' nullable: true type: string createdAt: description: ISO 8601 timestamp when the endpoint was created. example: '2026-01-01T00:00:00.000Z' type: string description: description: Human-readable description of this webhook endpoint, or null if not set. example: Production payment events handler nullable: true type: string id: description: The unique identifier of the webhook endpoint. example: webhook_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string metadata: description: Arbitrary key-value metadata attached to this endpoint, or null if not set. example: environment: prod team: payments nullable: true secret: description: Signing secret for this endpoint. Returned only on creation and never retrievable afterwards. example: whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string status: description: The current state of this endpoint. enum: - enabled - errored - disabled - deleted example: enabled type: string x-enumNames: - ENABLED - ERRORED - DISABLED - DELETED subscribedEvents: description: List of event types this endpoint receives. example: - customer.created - transfer.succeeded items: enum: - '*' - customer.* - transfer.* - document.* - service.* - customer.created - customer.pending - customer.approved - customer.rejected - transfer.created - transfer.pendingFunding - transfer.pendingReview - transfer.fundsReceived - transfer.processing - transfer.succeeded - transfer.returned - transfer.pendingRefundInformation - transfer.failed - transfer.canceled - transfer.refunded - transfer.unexpectedError - transfer.failedPrecondition - transfer.expired - transfer.unfunded - transfer.processingRefund - transfer.refundFailed - document.pending - document.processing - document.verified - document.rejected - service.pending - service.processing - service.succeeded - service.failed - service.cancelled type: string x-enumNames: - ALL - ALL_CUSTOMER - ALL_TRANSFER - ALL_DOCUMENT - ALL_SERVICE - CREATE_CUSTOMER - PENDING_CUSTOMER - APPROVE_CUSTOMER - REJECT_CUSTOMER - CREATE_TRANSFER - PENDING_FUNDING_TRANSFER - PENDING_REVIEW_TRANSFER - FUNDS_RECEIVED_TRANSFER - PROCESSING_TRANSFER - SUCCESSFUL_TRANSFER - RETURNED_TRANSFER - PENDING_REFUND_INFORMATION_TRANSFER - FAILED_TRANSFER - CANCELLED_TRANSFER - REFUNDED_TRANSFER - UNEXPECTED_ERROR_TRANSFER - FAILED_PRECONDITION_TRANSFER - EXPIRED_TRANSFER - UNFUNDED_TRANSFER - PROCESSING_REFUND_TRANSFER - REFUND_FAILED_TRANSFER - PENDING_DOCUMENT - PROCESSING_DOCUMENT - VERIFIED_DOCUMENT - REJECTED_DOCUMENT - PENDING_SERVICE - PROCESSING_SERVICE - SUCCESSFUL_SERVICE - FAILED_SERVICE - CANCELLED_SERVICE type: array updatedAt: description: ISO 8601 timestamp when the endpoint was last updated. example: '2026-01-01T00:00:00.000Z' type: string url: description: The HTTPS URL events are delivered to. example: https://example.com/webhooks/sphere type: string required: - id - url - subscribedEvents - status - apiVersion - description - metadata - createdAt - updatedAt - secret type: object description: The created webhook endpoint, including the signing secret. The secret is returned only here and cannot be retrieved again. '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Create a Webhook Endpoint V2 /v2/webhook-endpoints/{id}: delete: description: Delete a webhook endpoint by its ID. Future events will no longer be delivered to it. operationId: deleteV2WebhookEndpointsById parameters: - in: path name: id required: true schema: type: string responses: '204': description: The webhook endpoint is deleted. No content is returned. '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Delete a Webhook Endpoint V2 get: description: Retrieve a webhook endpoint by its ID. operationId: getV2WebhookEndpointsById parameters: - in: path name: id required: true schema: type: string responses: '200': content: application/json: schema: properties: apiVersion: description: API version date string this endpoint was configured with, or null if not set. example: '2026-04-01' nullable: true type: string createdAt: description: ISO 8601 timestamp when the endpoint was created. example: '2026-01-01T00:00:00.000Z' type: string description: description: Human-readable description of this webhook endpoint, or null if not set. example: Production payment events handler nullable: true type: string id: description: The unique identifier of the webhook endpoint. example: webhook_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string metadata: description: Arbitrary key-value metadata attached to this endpoint, or null if not set. example: environment: prod team: payments nullable: true status: description: The current state of this endpoint. enum: - enabled - errored - disabled - deleted example: enabled type: string x-enumNames: - ENABLED - ERRORED - DISABLED - DELETED subscribedEvents: description: List of event types this endpoint receives. example: - customer.created - transfer.succeeded items: enum: - '*' - customer.* - transfer.* - document.* - service.* - customer.created - customer.pending - customer.approved - customer.rejected - transfer.created - transfer.pendingFunding - transfer.pendingReview - transfer.fundsReceived - transfer.processing - transfer.succeeded - transfer.returned - transfer.pendingRefundInformation - transfer.failed - transfer.canceled - transfer.refunded - transfer.unexpectedError - transfer.failedPrecondition - transfer.expired - transfer.unfunded - transfer.processingRefund - transfer.refundFailed - document.pending - document.processing - document.verified - document.rejected - service.pending - service.processing - service.succeeded - service.failed - service.cancelled type: string x-enumNames: - ALL - ALL_CUSTOMER - ALL_TRANSFER - ALL_DOCUMENT - ALL_SERVICE - CREATE_CUSTOMER - PENDING_CUSTOMER - APPROVE_CUSTOMER - REJECT_CUSTOMER - CREATE_TRANSFER - PENDING_FUNDING_TRANSFER - PENDING_REVIEW_TRANSFER - FUNDS_RECEIVED_TRANSFER - PROCESSING_TRANSFER - SUCCESSFUL_TRANSFER - RETURNED_TRANSFER - PENDING_REFUND_INFORMATION_TRANSFER - FAILED_TRANSFER - CANCELLED_TRANSFER - REFUNDED_TRANSFER - UNEXPECTED_ERROR_TRANSFER - FAILED_PRECONDITION_TRANSFER - EXPIRED_TRANSFER - UNFUNDED_TRANSFER - PROCESSING_REFUND_TRANSFER - REFUND_FAILED_TRANSFER - PENDING_DOCUMENT - PROCESSING_DOCUMENT - VERIFIED_DOCUMENT - REJECTED_DOCUMENT - PENDING_SERVICE - PROCESSING_SERVICE - SUCCESSFUL_SERVICE - FAILED_SERVICE - CANCELLED_SERVICE type: array updatedAt: description: ISO 8601 timestamp when the endpoint was last updated. example: '2026-01-01T00:00:00.000Z' type: string url: description: The HTTPS URL events are delivered to. example: https://example.com/webhooks/sphere type: string required: - id - url - subscribedEvents - status - apiVersion - description - metadata - createdAt - updatedAt type: object description: The requested webhook endpoint. '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error summary: Get a Webhook Endpoint V2 security: - bearer: [] servers: - description: Production url: https://api.spherepay.co tags: []