# Issue a Token Source: https://developer.fin.com/api-reference/authentication/issue-a-token POST /v1/oauth/token Generate an access token using client credentials Grab your `client_id` and `client_secret` from the [API Keys](https://orchestration.fin.com/api-keys) section of the [Orchestration Dashboard](https://orchestration.fin.com/) * The TTLs returned from this API are actually the time that the token will expire; i.e. not validity in number of seconds since creation. * The timestamps, i.e. TTLs returned from this endpoint are NOT in ISO 8601 format. Rather it is in the format `YYYY-MM-DD HH:MM:SS+00`. # Refresh a Token Source: https://developer.fin.com/api-reference/authentication/refresh-a-token POST /v1/oauth/refresh-token Generate a new token pair based on a refresh token. Exchanges a `refresh_token` received from the [Issue Token](/api-reference/authentication/issue-a-token) endpoint for a new pair of `access_token` and `refresh_token` * The TTLs returned from this API are actually the time that the token will expire; i.e. not validity in number of seconds since creation. * The timestamps, i.e. TTLs returned from this endpoint are NOT in ISO 8601 format. Rather it is in the format `YYYY-MM-DD HH:MM:SS+00`. # Fetch Prefunded Balance Source: https://developer.fin.com/api-reference/balances/fetch-prefunded-balance GET /v1/wallet/balances Retrieve the current prefunded wallet balances To enable prefundable wallets, you must first reach out to the fin.com team to enable wallets for you for both **sandbox** and **production** # Create Beneficiary Source: https://developer.fin.com/api-reference/beneficiaries/create-beneficiary-v3 POST /v3/beneficiaries Create a new beneficiary for payments and transfers. Supports bank accounts and e-wallets as destination types. * The beneficiary will be ready for transactions only when its `status` is `APPROVED` and `active` is true. * Check all the supported fiat and crypto rails and currencies, along with the valid combinations, in [Supported rails and currencies](https://developer.fin.com/guides/others/supported-rails-and-currencies). * The rails and currencies of `deposit_instruction` and `refund_instruction` have to be the same. * The available rails and currencies depend on the configuration set up for you. Contact support to know more. * `receiver_meta_data.intermediary_routing_number` is required for SWIFT payouts. * USD ACH payouts are coming soon. When `settlement_config.auto_settlement` is `true`, send funds with a maximum of two decimal places. Anything beyond two decimal places is not counted during conversion. ## De-Duplication Logic | Destination Type | Fields Checked | | ---------------- | ------------------------------------------------------------------------------------------ | | Bank Account | `bank_account.scheme`, `bank_account.number`, `bank_routing.scheme`, `bank_routing.number` | | E-Wallet | `e_wallet.scheme`, `e_wallet.number` | # Fetch Beneficiary Details Source: https://developer.fin.com/api-reference/beneficiaries/fetch-beneficiary-details-v2 GET /v2/beneficiaries/details Retrieve detailed information for a specific beneficiary. Returns structured data for bank accounts, e-wallets, and external crypto wallet destinations. # List Available Countries Source: https://developer.fin.com/api-reference/beneficiaries/list-available-countries GET /v1/beneficiaries/countries Retrieve a list of countries supported for beneficiary creation with available payment methods and phone validation rules # List Bank Branch Identifiers Source: https://developer.fin.com/api-reference/beneficiaries/list-bank-branch-identifiers GET /v1/beneficiaries/methods/{method_id}/branches Retrieve a list of available branches for a specific bank or payment method # List Bank Identifiers Source: https://developer.fin.com/api-reference/beneficiaries/list-bank-identifiers GET /v1/beneficiaries/methods Retrieve a list of available banks or e-wallet providers for a specific country and method type # List Beneficiaries For a Customer Source: https://developer.fin.com/api-reference/beneficiaries/list-beneficiaries-for-a-customer GET /v1/customers/{customer_id}/beneficiaries Retrieve all beneficiaries associated with a specific customer # Update Beneficiary Active Status Source: https://developer.fin.com/api-reference/beneficiaries/update-beneficiary-active-status PATCH /v1/beneficiaries Update the active status of a beneficiary to enable or disable it # Upload Beneficiary Documents Source: https://developer.fin.com/api-reference/beneficiaries/upload-beneficiary-documents POST /v1/beneficiaries/{beneficiary_id}/documents Upload one or more documents for a specific beneficiary using multipart/form-data ## Allowed File Types * `PDF` * `JPG` / `JPEG` * `PNG` # List Account Purposes Source: https://developer.fin.com/api-reference/catalogue/list-account-purposes GET /v1/purposes Retrieve a list of available account purposes # List Generic Country Codes Source: https://developer.fin.com/api-reference/catalogue/list-countries GET /v1/countries Retrieve a list of country specific codes following ISO 3166-1 alpha-3 standard Retrieve a list of country specific codes following ISO 3166-1 alpha-3 standard. # List Industries Source: https://developer.fin.com/api-reference/catalogue/list-industries GET /v1/industries Retrieve a list of available industries This endpoint is used for the deprecated V1 business customer creation flow only. It is not applicable for Create Business Customer. # List Occupations Source: https://developer.fin.com/api-reference/catalogue/list-occupations GET /v1/occupations Retrieve a list of available occupations # List Source of Funds Source: https://developer.fin.com/api-reference/catalogue/list-source-of-funds GET /v1/source-of-funds Retrieve a list of available source of funds # List Source of Wealth Source: https://developer.fin.com/api-reference/catalogue/list-source-of-wealth GET /v1/source-of-wealth Retrieve a list of available source of wealth options # List Subdivision Codes: ISO 3166-1 alpha-2 Source: https://developer.fin.com/api-reference/catalogue/list-subdivisions GET /v1/countries/{country_code}/subdivisions Retrieve a list of subdivision codes for a specific country following ISO 3166-2 standard # List Transaction Purposes Source: https://developer.fin.com/api-reference/catalogue/list-transaction-purposes GET /v1/transaction-purposes Retrieve a list of available transaction purposes # Create a crypto payment quote Source: https://developer.fin.com/api-reference/crypto-orchestration/create-a-crypto-payment-quote POST /v1/transit/quote Generate a fee estimation quote for a transit payment The quote has a limited validity period indicated by `expire_at`. Request a new quote if it has expired. ## Quote Request by Integration * `settlement_via`: `MARKET_ORDER` or `ONE_TO_ONE` * `rebalance_fee`: `true` or `false` * `developer_fee`: not applicable Check out the supported rails, chains, fee rebalancing, and settlement configuration combinations for Bybit [here](/guides/crypto-orchestration/integration-types/bybit#chains-rails-and-constraints). * `settlement_via`: `ONE_TO_ONE` * `rebalance_fee`: `true` or `false` * `developer_fee`: optional, supports `fixed` and `percentage` fields Check out the supported rails, chains, fee rebalancing, and settlement configuration combinations for Kraken [here](/guides/crypto-orchestration/integration-types/kraken#chains-rails-and-constraints). * `settlement_via`: `FEE_RETENTION` * `rebalance_fee`: `false` * `developer_fee`: optional, supports `fixed` and `percentage` fields Check out the supported rails, chains, fee rebalancing, and settlement configuration combinations for Pass Through [here](/guides/crypto-orchestration/integration-types/pass-through#chains-rails-and-constraints). * `settlement_via`: `ONE_TO_ONE` * `rebalance_fee`: `true` or `false` * `developer_fee`: optional, supports `fixed` and `percentage` fields ## Rebalance Fee Behavior | Value | Effect | | :------ | :------------------------------------------------------------------------------ | | `true` | Fees absorbed into order amount. `total_order_amount` equals `order_amount`. | | `false` | Fees added on top. `total_order_amount` equals `order_amount` plus `total_fee`. | # Create a Payment Source: https://developer.fin.com/api-reference/crypto-orchestration/create-a-payment POST /v1/transit/payment Create a new payment order for a supported integration type (ByBit, Kraken, OKX, Pass Through) Creates a payment order through the ByBit integration for USDT to PYUSD conversion. The payment flow supports QR code and e-commerce payment types with automatic settlement to a specified wallet address. **Conditional Field Rules:** * Either `order_info.order_amount` or `order_info.quote_id` must be provided, but **not both**. * When `order_info.quote_id` is not provided, `order_info.order_amount` and the `fin` object are required. * When `order_info.quote_id` is provided, `order_info.order_amount` and the `fin` object must **not** be included. * Providing both results in a `422` error. **Provider Error Codes:** The `428` response code is a placeholder. When errors occur from the payment provider (ByBit), the original status code will be forwarded. # Fetch a Payment Source: https://developer.fin.com/api-reference/crypto-orchestration/fetch-a-payment GET /v1/transit/payment/{payment_id} Retrieve payment details by payment ID ## Payment Status Values * **PAY\_INIT**: Payment initialized * **PAY\_PROCESS**: Payment is being processed * **PAY\_SUCCESS**: Payment completed successfully * **PAY\_FAILED**: Payment failed * **PAY\_TIMEOUT**: Payment timed out * **PAY\_CANCEL**: Payment was cancelled * **SETTLEMENT\_INIT**: Settlement process started * **SETTLEMENT\_SUCCESS**: Settlement completed successfully * **SETTLEMENT\_HOLD**: Transaction on hold due to insufficient rebalancing funds * **SETTLEMENT\_FAILED**: Settlement failed after 3 retry attempts The `settlement_info` field will be `null` until `PAY_SUCCESS`. The `payment_time` will be `0` until `PAY_SUCCESS`. # Attach Documents to Associated Party Source: https://developer.fin.com/api-reference/customers/attach-documents-to-associated-party-v2 POST /v2/customers/{customer_id}/associated-parties/individual/attach Attach identifying documents and address documents for one or more associated parties of a business customer. Replaces the v1 proof_of_identity / proof_of_address structure with separate identifying_documents and address_documents arrays, allowing multiple ID documents per party. * Upload files first using [Upload document](https://developer.fin.com/api-reference/customers/upload-document) to obtain URIs, then reference them here. * The `associated_party_id` for each party is returned in the [Get Customer Details V2](https://developer.fin.com/api-reference/customers/get-customer-details-v2) response. ## Identity Document Side Requirements | Type | Sides Required | | ------------------ | --------------------- | | `PASSPORT` | No (single image) | | `NATIONAL_ID` | Yes: `FRONT` + `BACK` | | `DRIVERS_LICENSE` | Yes: `FRONT` + `BACK` | | `RESIDENCE_PERMIT` | No (single image) | # Attach Documents to Business Customer Source: https://developer.fin.com/api-reference/customers/attach-documents-to-business-customer-v2 POST /v2/customers/{customer_id}/business/attach Attach formation, ownership, and supporting documents to an existing business customer. Documents are categorised into three arrays: formation_documents, ownership_documents, and supporting_documents, replacing the v1 ownership_structure / company_details / legal_presence structure. * Upload files first using the [Upload document](https://developer.fin.com/api-reference/customers/upload-document) endpoint to obtain URIs, then reference them here. * Parse `tos_policies_value` from the `tos_policies_url` returned by `POST /v2/customers/business` and include it in this request. ## Document Type Reference See [Entity-wise document requirement](https://developer.fin.com/guides/compliance-and-regulatory/entity-wise-document-requirement) for all valid `type` values per category and entity type. # Attach Documents to Individual Customer Source: https://developer.fin.com/api-reference/customers/attach-documents-to-individual-customer-v2 POST /v2/customers/{customer_id}/individual/attach Attach identifying and address documents to an existing v2 individual customer. Replaces the v1 proof_of_identity / proof_of_address structure with separate identifying_documents and address_documents arrays. Documents are processed asynchronously. * Upload files first using the [Upload document](https://developer.fin.com/api-reference/customers/upload-document) endpoint to obtain the URIs needed for the `files` arrays, then reference them here. * The `tos_policies_value` should be parsed from the `tos_policies_url` query parameter returned from the Create Individual Customer V2 endpoint. ## Prerequisites The customer must satisfy `customer_type = INDIVIDUAL`, `api_version = v2`, and a `customer_status` of `INCOMPLETE` or `ACTION_REQUIRED`. Any other state returns `403`. Only one attach can be in flight per customer; a second concurrent attach returns `409`. ## Identity Document Side Requirements | Type | Files | Sides | | ------------------ | ----- | -------------------------- | | `PASSPORT` | 1 | Side optional | | `NATIONAL_ID` | 2 | One `FRONT` and one `BACK` | | `DRIVERS_LICENSE` | 2 | One `FRONT` and one `BACK` | | `RESIDENCE_PERMIT` | 2 | One `FRONT` and one `BACK` | | `SELFIE` | 1 | Side optional | ## Key Rules * At most one non-SELFIE document may be included in `identifying_documents`. To switch the primary document type, re-attach with the new type. * `state` is required when `type` is `DRIVERS_LICENSE` and `country` is `USA`. It is optional for a `DRIVERS_LICENSE` issued elsewhere, and forbidden for `PASSPORT`, `NATIONAL_ID`, and `RESIDENCE_PERMIT`. * Exactly one `address_documents` entry is required. * File URIs must be unique across the entire request (SELFIE files excluded) and must belong to this customer. * A `SELFIE` entry may be required depending on your client configuration. When required, include exactly one `SELFIE` entry carrying at least one file. # Create Business Customer Source: https://developer.fin.com/api-reference/customers/create-business-customer-v2 POST /v2/customers/business Create a new business customer with full KYB profile, associated parties (UBOs/directors), compliance data, and optionally holding structure and public listing details. ## Important Requirements * **Email Address**: Must be all lowercase or you will receive a validation error * **RELIANCE Verification**: If you attempt to use `RELIANCE` verification type but it's not enabled for your client, you will receive a 423 error with message: "RELIANCE is not available for your client" * **Non-ASCII characters**: If any input field contains non-ASCII characters, you must provide a transliterated (Latin) value in the corresponding `_en` field (e.g., `legal_name_en`, `street_line_1_en`, `first_name_en`) * **Third-party Fund Usage**: The `third_party_fund_usage` field indicates whether this customer will be moving other people's money * **Ownership Percentages**: The total ownership percentages of all associated parties must add up to more than 0 and less than 100 * **Reference Data**: `purpose_id`, `source_of_fund_ids` and `source_of_wealth_ids` are integer foreign keys — fetch valid values from [List Account Purposes](https://developer.fin.com/api-reference/catalogue/list-account-purposes) , [List Source of Funds](https://developer.fin.com/api-reference/catalogue/list-source-of-funds) and [List Source of Wealth](https://developer.fin.com/api-reference/catalogue/list-source-of-wealth) * **subdivision\_code**: Pass the ISO 3166-2 code. For example for CA, pass US-CA. # Create Individual Customer Source: https://developer.fin.com/api-reference/customers/create-individual-customer-v2 POST /v2/customers/individual Create a new individual customer with verification details, basic info, address, and financial profile. Only English (Latin) characters are allowed as inputs for all fields. If any field contains non-ASCII characters, provide a transliterated (Latin) value in the corresponding `_en` field (e.g., `first_name_en`, `street_line_1_en`). ## Important Requirements * **Email Address**: Must be all lowercase or you will receive a validation error * **RELIANCE Verification**: If you attempt to use `RELIANCE` verification type but it's not enabled for your client, you will receive a 423 error with message: "RELIANCE is not available for your client" * **Address country**: `address.country` must match `basic_info.country_of_residence` * **Reference Data**: `occupation_id`, `purpose_id`, and `source_of_fund_ids` are integer foreign keys. Fetch valid values from [List Occupations](https://developer.fin.com/api-reference/catalogue/list-occupations), [List Account Purposes](https://developer.fin.com/api-reference/catalogue/list-account-purposes), and [List Source of Funds](https://developer.fin.com/api-reference/catalogue/list-source-of-funds) * **subdivision\_code**: Pass the ISO 3166-2 code. For example for CA, pass US-CA. # Get Customer Capabilities Source: https://developer.fin.com/api-reference/customers/get-customer-capabilities GET /v2/customers/{customer_id}/capabilities Returns the on-ramp and off-ramp capabilities available for a customer, including the supported rails and their activation status for each currency and corridor. # Get Customer Details Source: https://developer.fin.com/api-reference/customers/get-customer-details-v2 GET /v2/customers/{customer_id} Retrieve detailed information for a specific customer Use this endpoint to fetch business customer details. For individual customer details, use [Get Customer Details](https://developer.fin.com/api-reference/customers/get-customer-details). # List Customers Source: https://developer.fin.com/api-reference/customers/list-customers-v2 GET /v2/customers Retrieve a list of customers filtered by type # Patch Customer RFI Source: https://developer.fin.com/api-reference/customers/patch-customer-rfi PATCH /v1/customers/{customer_id} Submit an RFI response for an individual or business customer. You must pass only the fields and documents specified in the RFI. Submitting data that was not requested will trigger an error. Only submit the fields explicitly listed in the RFI. Sending unrequested fields will result in an error. The request body accepts the same fields as the following endpoints: * Attach Documents to Individual Customer * Attach Documents to Business Customer * Attach Documents to Associated Party # Upload Document Source: https://developer.fin.com/api-reference/customers/upload-document POST /v1/customers/upload Upload customer documents using multipart/form-data. Files can be uploaded with arbitrary field names (e.g., poa, poi, passport, file1, etc.) ## Allowed File Types * `PDF` * `JPG` / `JPEG` * `PNG` Files should be uploaded as separate form fields with arbitrary names. You can use any field name for files (e.g., `passport`, `poa`, `poi`, `file1`, `document1`, etc.). The field name you use will be returned as the key in the response. # Calculate Exchange Rates Source: https://developer.fin.com/api-reference/fees-and-fx-rates/calculate-exchange-rates POST /v1/fee-calculation Calculate exchange rates and applicable fees for a transaction. Pass either `source_amount` or `destination_amount`. Use `beneficiary_id` instead of `destination_currency` to get developer-fee-aware calculations. # Fetch Exchange Rates Source: https://developer.fin.com/api-reference/fees-and-fx-rates/fetch-exchange-rates GET /v1/fx-rate Retrieve exchange rates for a specific country or currency. Provide either `country_code` or `currency_code`, but not both. # Create a Transfer Source: https://developer.fin.com/api-reference/transactions/create-a-transfer POST /v1/transactions/transfer-payout Initiate a transfer payout to a beneficiary. **Validation Rules:** - Minimum amount: 500 cents (5.00 in major currency units) - Attachments array is optional, but if provided must contain at least one item This endpoint can only be used with beneficiaries created with `auto_settlement` set to `false`. # Create a Transfer V2 Source: https://developer.fin.com/api-reference/transactions/create-a-transfer-v2 POST /v2/transactions/transfer-payout Initiate a transfer payout to a beneficiary. **Validation Rules:** - Send exactly one of `source_amount` or `destination_amount`, never both - `source_amount` minimum: 500 cents (5.00 in major currency units) - Attachments array is optional, but if provided must contain at least one item This endpoint can only be used with beneficiaries created with `auto_settlement` set to `false`. ## What changed from V1 | **V1** | **V2** | | :------------ | :---------------------------------------------------------------------- | | `amount` | Replaced by `source_amount` and `destination_amount`. Send exactly one. | | Not available | `source_currency`, either `USD` or `USDC`. | | Not available | `deduct_from`, either `PREFUNDED_BALANCE` or `LIQUIDATION_ADDRESS`. | V2 lets you fix either end of the transfer. Send `source_amount` to debit a known amount and let the beneficiary receive whatever it converts to, or send `destination_amount` to guarantee what the beneficiary receives and let the debit float. Sending both is rejected. `deduct_from` decides where the money comes from. Only `PREFUNDED_BALANCE` transfers are eligible for refunds if they fail. The response is unchanged from V1. V1 remains available at `POST /v1/transactions/transfer-payout`. Transfers created on V2 must be settled with [Settle a Transfer V2](/api-reference/transactions/settle-a-transfer-v2). # Create Quote Source: https://developer.fin.com/api-reference/transactions/create-quote POST /v2/transactions/quote Returns fee and receivable amount estimations for a crypto withdrawal from a Fin.com internal wallet to a customer's external crypto wallet. The source wallet and destination wallet must share the same blockchain rail and currency. For example, if the source wallet is on POLYGON with USDC, the beneficiary's destination wallet must also be on POLYGON with USDC. # Execute Batch Transfer Source: https://developer.fin.com/api-reference/transactions/execute-batch-transfer POST /v1/batch/transactions/commit Execute multiple transfer payouts in a single batch operation. This endpoint can only be used with beneficiaries created with `auto_settlement` set to `false`. **Amount Specification:** * Each transaction must include exactly one of `source_amount` or `destination_amount` (not both) * `source_amount`: Minimum 500 cents (e.g. 500 = \$5.00) * Only `PREFUNDED_BALANCE` transactions are eligible for refunds if they fail # Execute Quote Source: https://developer.fin.com/api-reference/transactions/execute-quote POST /v2/transactions Executes a quote returned from the Create Quote endpoint, initiating a crypto withdrawal to the beneficiary's external wallet. # Fetch Batch Details Source: https://developer.fin.com/api-reference/transactions/fetch-batch-details GET /v1/batch/transactions/commit/{batch_id} Retrieve detailed information about a batch transaction including all items and their statuses # Fetch Transaction Details Source: https://developer.fin.com/api-reference/transactions/fetch-transaction-details-v2 GET /v2/transactions/{transaction_id} Returns full details for a transaction by ID, including status, amounts, fees, and settlement data. The populated fields vary based on the transaction type. # List Beneficiary Transactions Source: https://developer.fin.com/api-reference/transactions/list-beneficiary-transactions GET /v1/beneficiaries/{beneficiary_id}/transactions Retrieve a paginated list of all transactions for a specific beneficiary # List Customer Transactions Source: https://developer.fin.com/api-reference/transactions/list-customer-transactions GET /v2/transactions Returns a paginated list of transactions for a customer, optionally filtered by transaction type. ``` GET /v2/transactions?customer_id=765d498e-a267-4154-9d2f-9e411a0b50dd&type=CRYPTO_WITHDRAWAL¤t_page=1&per_page=10 ``` # Settle a Transfer Source: https://developer.fin.com/api-reference/transactions/settle-a-transfer POST /v1/transactions/transfer-payout/settle Settle a previously created transfer payout # Settle a Transfer V2 Source: https://developer.fin.com/api-reference/transactions/settle-a-transfer-v2 POST /v2/transactions/transfer-payout/settle Settle a transfer payout created with `POST /v2/transactions/transfer-payout`. ## What changed from V1 The request and response are identical to V1. Only the path differs. Use this endpoint to settle transfers created with [Create a Transfer V2](/api-reference/transactions/create-a-transfer-v2). V1 remains available at `POST /v1/transactions/transfer-payout/settle` for transfers created on V1. # Upload Beneficiary Documents Source: https://developer.fin.com/api-reference/transactions/upload-beneficiary-documents POST /v1/beneficiaries/{beneficiary_id}/documents Upload one or more documents for a specific beneficiary using multipart/form-data ## Allowed File Types * `PDF` * `JPG` / `JPEG` * `PNG` # Create Virtual Account Source: https://developer.fin.com/api-reference/virtual-accounts/create-virtual-account-v3 POST /v3/customers/{customer_id}/virtual-accounts Create a virtual bank account for a specific customer to convert fiat deposits to crypto. The `customer_id` path parameter identifies the customer for whom the virtual account is being created. V3 adds `source.bank` so you can choose the banking partner that issues the account, and returns the destination and banking partner on the create response. * Check all the supported fiat and crypto rails and currencies, along with the valid combinations, in [Supported rails and currencies](https://developer.fin.com/guides/others/supported-rails-and-currencies). * The available rails and currencies depend on the configuration set up for you. Contact support to know more. ## What changed from V2 | Change | Detail | | :------------------ | :------------------------------------------------------------------------------------------------------------------------------ | | `source.bank` added | Required. Selects the banking partner that issues the account. | | Response body | Now returns `deposit_instructions`, `destination`, and `bank`. `customer_id` and `created_at` are no longer returned on create. | Virtual Account V2 has been retired and is no longer documented. V3 replaces it. ## Choosing a banking partner `source.bank` selects the banking partner that issues the virtual account and receives the customer's fiat deposit. The accepted values are `SSB` and `PORTAGE`. ## Duplicate accounts A customer can hold only one virtual account per source currency and rail. Requesting one that already exists returns `422` with the colliding `customer_id` and `source` in `errors`, along with the `virtual_account_id` of the existing account. Use that account instead of retrying the create call. # Fetch Virtual Account Transactions Source: https://developer.fin.com/api-reference/virtual-accounts/fetch-virtual-account-transactions GET /v1/virtual-account/{virtual_account_id}/transactions Retrieve a paginated list of all transactions for a specific virtual account # Get Virtual Account Details Source: https://developer.fin.com/api-reference/virtual-accounts/get-virtual-account-details GET /v3/customers/{customer_id}/virtual-accounts/{va_id} Retrieve the full record for a single virtual account, including the deposit instructions the customer funds the account with and the crypto destination the deposits settle to. # List Virtual Accounts Source: https://developer.fin.com/api-reference/virtual-accounts/list-virtual-accounts-v3 GET /v3/customers/{customer_id}/virtual-accounts Retrieve a paginated list of all virtual accounts belonging to a specific customer. # Batch Transaction Item Status Source: https://developer.fin.com/api-reference/webhooks/batch-transaction-item-status WEBHOOK batch.transaction.item.status Triggered when a batch transaction item's status changes after committing a batch. # Beneficiary Created Source: https://developer.fin.com/api-reference/webhooks/beneficiary-created WEBHOOK beneficiary.created Triggered when a new beneficiary is created in the system. # Beneficiary Liquidation Deposit Source: https://developer.fin.com/api-reference/webhooks/beneficiary-liquidation-deposit WEBHOOK beneficiary.liquidation.deposit Triggered when any transfer hits a beneficiary's liquidation address. # Beneficiary Status Source: https://developer.fin.com/api-reference/webhooks/beneficiary-status WEBHOOK beneficiary.status Triggered when a beneficiary's status changes. # Customer Created Source: https://developer.fin.com/api-reference/webhooks/customer-created WEBHOOK customer.created Triggered when a customer is successfully created. # Customer RFI Source: https://developer.fin.com/api-reference/webhooks/customer-rfi WEBHOOK customer.rfi Triggered when the compliance team requests additional information or documents from a customer. Sets the customer status to ACTION_REQUIRED. The payload includes a structured list of what is missing, invalid, or expired, scoped to either the customer or a specific associated party. # Customer Status Source: https://developer.fin.com/api-reference/webhooks/customer-status WEBHOOK customer.status Triggered when a customer's status changes during verification. # Transaction Status Source: https://developer.fin.com/api-reference/webhooks/transaction-status WEBHOOK transaction.status Triggered when a transaction's status changes. # Transit Payment Status Source: https://developer.fin.com/api-reference/webhooks/transit-payment-status WEBHOOK transit.payment.status Triggered when a transit payment's status changes through the payment and settlement flow. # Virtual Account Created V2 Source: https://developer.fin.com/api-reference/webhooks/virtual-account-created-v2 WEBHOOK virtual_account.created.v2 Triggered when a new V2 virtual account is created for a customer. # Virtual Account Status V2 Source: https://developer.fin.com/api-reference/webhooks/virtual-account-status-v2 WEBHOOK virtual_account.status.v2 Triggered when a V2 virtual account’s status changes. # December 31, 2025 Source: https://developer.fin.com/changelogs/2025-12-31 Changelog for December 31, 2025 ## ✨ New Features 1. **FX Rate Validity**\ The global [FX Rate API](/api-reference/fees-and-fx-rates/fetch-exchange-rates) now returns the validity and expiration. (i.e. when the rate will change next) 2. **FX Rate Locking in Single Transfers**\ The [Create a Transfer](/api-reference/transactions/create-a-transfer) API now returns a `quotation` key with the destination currency, amount and developer fee. 3. **FX Rate Locking in Batch Transfers**\ The [Batch Transfer](/api-reference/transactions/execute-batch-transfer) API now transparently quotes the fx rates and developer fees 4. **Fee Calculation API**\ We introduced the [Fee Calculation](/api-reference/fees-and-fx-rates/calculate-exchange-rates) API 5. **Webhook for Liquidation Address Deposit Events**\ We introduced the [`beneficiary.liquidation.deposit` webhook](/api-reference/webhooks/beneficiary-liquidation-deposit) that gets triggered whenever a transaction hits the liquidation address of a beneficiary. 6. **Duplicate Beneficiaries No Longer Allowed**\ Attempting to create a beneficiary with duplicate bank information will result in a HTTP `409 Conflict` response. 7. **Off-ramp Transaction List**\ You can now [List Transactions for a Beneficiary](/api-reference/transactions/list-beneficiary-transactions). 8. **Orchestration Dashboard Now Shows Balance**\ Check it out on the [Dashboard itself](https://orchestration.fin.com/). 9. **Email Notification if Prefunded Balance Goes Below Threshold** ## 🛠️ Improvements 1. **Improved Beneficiary Details API** Documentation is progress. ## 🐞 Bug Fixes 1. **Fix: Business Customer Creation Stability**\ API now gives readable errors when attempting to create a Business customer where the associated parties own more than 100% of the business. ## ⚠️ Breaking Changes 1. **FX Rate API No Longer Returns Country Code**\ The global [FX Rate API](/api-reference/fees-and-fx-rates/fetch-exchange-rates) no longer returns the country code in its response. # January 02, 2026 Source: https://developer.fin.com/changelogs/2026-01-02 Changelog for January 02, 2026 ## ✨ New Features * **FX Rate Locking:** Introduced a lock period for exchange rates to ensure price stability during transactions. * **Fee Calculator API:** Launched the [`/v1/fee-calculation`](/api-reference/fees-and-fx-rates/calculate-exchange-rates) endpoint to estimate costs before initiating transfers. * **Liquidation Deposit Webhook:** Introduced the `beneficiary.liquidation.deposit` webhook, which triggers when a deposit is made to a beneficiary's liquidation address. ## 🛠️ Improvements * **Beneficiary Details v2:** Upgraded to a more structured and detailed format that supports richer metadata. * **Flexible FX Query Parameters:** The FX rate endpoint now supports both `country_code` and `currency_code` as valid query parameters. * **FX Response Metadata:** Added `valid_from` and `valid_till` (UTC) to the FX response to indicate rate validity windows. * **Transaction Quotation Visibility:** Payout and batch payout responses now include a `quotation` object detailing the exchange rate, destination amount, and developer fees. * **Orchestration Dashboard Updates:** Developers with prefunded balance capabilities can now view their `fin-ledger` balance directly in the dashboard. * **Automated Balance Alerts:** Implemented email notifications to alert developers when prefunded balances fall below a minimum threshold. ## 🐞 Bug Fixes * **Duplicate Beneficiary Prevention:** The system now prevents the creation of beneficiaries with duplicate bank information. ## ⚠️ Breaking Changes * **Transaction Type Renaming:** The field `transaction_type` has been renamed from `DEBIT` to `OFFRAMP`. # January 09, 2026 Source: https://developer.fin.com/changelogs/2026-01-09 Changelog for January 09, 2026 ## ✨ New Features * **Transaction Detail by ID:** Launched a new API to fetch specific transaction details using a `transaction_id`. * **Virtual Account Transaction History:** Developers can now retrieve transaction lists associated with a specific `virtual_account_id`. * **Batch Item Status Webhook:** Introduced the `batch.transaction.item.status` webhook to track items as they enter the processing queue. ## 🛠️ Improvements * **Immediate Batch IDs:** The `transaction_id` is now available in the Batch Details response immediately following a Batch Create call. * **Enhanced Conflict Responses:** When a duplicate beneficiary is detected, the `409 Conflict` error now returns the existing `beneficiary_id`. ## 🐞 Bug Fixes * **Strict Country Code Validation:** Added mandatory ISO alpha-3 validation for beneficiary country codes. # January 19, 2026 Source: https://developer.fin.com/changelogs/2026-01-19 Changelog for January 19, 2026 ## 🛠️ Improvements * **Fee Guarantee Timestamp:** Added the `valid_till` field to the Fee Calculation response to specify the rate guarantee window. * **Batch Context in Transactions:** Transaction detail responses now include a `batch_info` object if the transaction was part of a batch payout. * **Flexible Document Uploads:** The customer upload system now supports arbitrary file field names (e.g., `poa`, `poi`)\[. * **New Customer Statuses:** Introduced `QUEUED` (sent to processor) and `REINITIATE` (requires new document upload) statuses for customer verification. ## 🐞 Bug Fixes * **USA Capability Validation:** Added a restriction to prevent USA beneficiary creation for customers who do not have USD capabilities enabled. # January 25, 2026 Source: https://developer.fin.com/changelogs/2026-01-25 Changelog for January 25, 2026 ## ✨ New Features 1. **Granular Transaction Webhooks** We have expanded our webhook notifications to provide better visibility into the transaction lifecycle. In addition to `COMPLETED`, you will now receive real-time updates for the following statuses: * **INITIATED**: The transaction request has been successfully received. * **PROCESSING**: The transaction is currently being handled by our core systems. * **IN\_COMPLIANCE**: The transaction is undergoing standard regulatory and compliance review. * **FAILED**: The transaction could not be completed. ## 🛠️ Improvements 1. **System Traceability & Reliability** We have implemented comprehensive internal logging for all transaction lifecycle events. This includes enhanced HTTP logging for communications with external applications and improved tracking for incoming on-ramp and off-ramp webhooks, ensuring faster resolution of edge-case issues and higher system uptime. ## 🐞 Bug Fixes 1. **Minimum Transaction Amount Validation** To ensure processing efficiency, a mandatory minimum check of **500 cents** has been implemented for: * Batch transaction creation requests. * Individual payout request creation flows. # February 03, 2026 Source: https://developer.fin.com/changelogs/2026-02-03 Changelog for February 03, 2026 ## ✨ New Features * **Auto Refund for Prefunded Balances:** Failed transactions using the `PREFUNDED` wallet type are now eligible for automatic refunds. ## 🛠️ Improvements * **Granular Webhook Statuses:** Expanded transaction webhooks to include `INITIATED`, `PROCESSING`, `IN_COMPLIANCE`, `FAILED`, and `REFUNDED`. * **Status Definitions:** The `REFUNDED` status specifically indicates a successful return of funds to a prefunded wallet. ## 🐞 Bug Fixes * **Minimum Transaction Value:** Implemented a mandatory 500-cent minimum check for all batch and payout transaction flows. # February 10, 2026 Source: https://developer.fin.com/changelogs/2026-02-10 Changelog for February 10, 2026 ## ✨ New Features * **Flexible Business Customer Creation:** The `business_trade_name` field is now optional when creating business customers via the `/customers/business` endpoint. * **Zero Ownership Percentage Support:** Associate parties can now have a `percentage_of_ownership` of 0 when creating business customers. * **Zero Monthly Volume Allowed:** Both individual and business customer creation now accept `monthly_volume` values of 0. * **Independent Phone Validation:** Phone number validation is now separated from the customer and beneficiary's country of residence for improved flexibility across `/customers/individual`, `/customers/business`, and `/v2/beneficiaries` endpoints. * **Orchestration Dashboard - Customer & Beneficiary Module:** New UI module for managing customers and beneficiaries, including customer creation (individual and business), document upload and attachment, customer details view with transactions and beneficiaries, TOS acceptance, beneficiary creation and management with field-level validations, and beneficiary details sidebar view. ## 🛠️ Improvements * **Transaction Simulation Fixed:** Resolved issues with transaction simulation for `OFF_RAMP` transactions in the Sandbox environment via `/transactions/simulation`. ## 🐞 Bug Fixes * **Orchestration Dashboard - Duplicate Branch Entry:** Removed duplicate "branch" entry for India (IND) from the branches API response. * **Orchestration Dashboard - Missing Business Name:** Fixed missing `business_name` field in API response for business-type beneficiaries. * **Orchestration Dashboard - E-Wallet Field Population:** Resolved empty values for `number`, `bank_name`, and `scheme` fields in e-wallet beneficiary details API. * **Phone Number Validation - GBR:** Corrected phone number validation for Great Britain (GBR) to properly accept 10-character phone numbers instead of incorrectly requiring 7-20 characters. * **Bank Account Validation - GBR:** Implemented proper bank account number validation for Great Britain when creating beneficiaries. * **OAuth Token Authentication:** Fixed 401 error in `/v1/oauth/token` endpoint for new users with valid `client_id` and `secret` credentials. * **Address Validation Error:** Resolved "Internal Server Error" when `street_line_1` starts with a number without a space after it. * **Relationship Remarks Validation:** Fixed incorrect validation error for `relationship_remarks` field when `relationship` is set to "OTHER" during beneficiary creation. * **Duplicate State Entry:** Removed duplicate state entry for Dhaka, Bangladesh. * **Get Methods API Case Sensitivity:** Standardized parameter handling in "Get methods" API to accept both lowercase "swift" and uppercase "SWIFT". * **API Key Creation Errors:** Resolved "Internal Server error" on first attempt and "Forbidden" error on second attempt when new users try to create API keys. # February 11, 2026 Source: https://developer.fin.com/changelogs/2026-02-11 Changelog for February 11, 2026 ## ✨ New Features * **Beneficiary Document Upload:** Added new `/v1/beneficiaries/{beneficiaryId}/documents` endpoint supporting document uploads against beneficiaries via multipart/form-data content type. * **Transaction Attachments Support:** The `/v1/transactions/transfer-payout` endpoint now supports an optional `attachments` array field for including document references with transfers. Each attachment object contains `remark` (description/note) and `uri` (document reference) fields. Multiple attachments can be included per transfer, and URIs should reference previously uploaded documents via the beneficiary documents endpoint for improved traceability. # February 16, 2026 Source: https://developer.fin.com/changelogs/2026-02-16 Changelog for February 16, 2026 ## ✨ New Features 1. **Destination Amount Support in Batch Transfers** The [Batch Transfer](/api-reference/transactions/execute-batch-transfer) API now supports `destination_amount` as an alternative to `source_amount`, ensuring the recipient receives the exact amount specified. Exactly one field must be provided per transaction item—not both. > **Note:** All amounts (whether `destination_amount` or `source_amount`) must be provided in minor units. 2. **GBR Bank Account Number Validation** New validation has been implemented for GBR bank account numbers when creating a beneficiary. The updated pattern `^[0-9]{4,9}$` applies to both LOCAL and SWIFT schemes. ## 🐞 Bug Fixes 1. **Fix: SWIFT Beneficiary Syncing** Resolved an issue with SWIFT beneficiary syncing. # April 13, 2026 Source: https://developer.fin.com/changelogs/2026-04-13 Changelog for April 13, 2026 ## ✨ New Features ### Customers 1. **New Endpoint: `GET /v2/customers`** List customers with the same filtering and pagination as V1. The V1 endpoint remains available. 2. **New Endpoint: `GET /v2/customers/{customer_id}`** Retrieve customer details with new fields not available in V1. The response now includes `rejection_reason` (populated when `customer_status` is `REJECTED` or `ACTION_REQUIRED`) and `request_for_information` (populated when `customer_status` is `ACTION_REQUIRED`). These fields give developers structured visibility into why a customer was rejected or what action is needed, without requiring a separate API call or webhook. 3. **New Endpoint: `POST /v2/customers/business`** Create a business customer with a significantly expanded KYB profile. Key additions over V1 include: * `industry_codes` — accepts NAICS 2022 6-digit codes instead of the V1 `business_industry_id` integer * `tax_info[]` array — replaces the single `tax_id` string, supporting multiple tax documents per country * `holding_structure` — captures corporate shareholders and foreign branch registrations * `public_listings` — stock exchange details for publicly traded companies * `compliance` — full AML/KYC program details including risk profile, regulated activity, and sanctions screening * `source_of_fund_ids` and `source_of_wealth_ids` — accept arrays instead of a single integer, ordered by contribution size * `_en` transliteration fields — for non-ASCII business names and addresses * Granular volume fields: `expected_monthly_deposits_usd`, `expected_monthly_withdrawals_usd`, `expected_transaction_value_usd`, and `expected_monthly_transaction_count` replace the single `monthly_volume` field The V1 `POST /v1/customers/business` endpoint remains available. Returns `201` on success (V1 returns `200`). 4. **New Endpoint: `POST /v2/customers/{customer_id}/business/attach`** Attach documents to a V2 business customer. Documents are organized into three categories: `formation_documents`, `ownership_documents`, and `supporting_documents`. This replaces the V1 structure of `ownership_structure`, `company_details`, and `legal_presence`. The `customer_id` is now a path parameter instead of a request body field. 5. **New Endpoint: `POST /v2/customers/{customer_id}/associated-parties/individual/attach`** Attach identity and address documents for associated parties of a V2 business customer. Replaces `proof_of_identity` and `proof_of_address` with `identifying_documents` and `address_documents` arrays, allowing multiple identity documents per party. 6. **New Endpoint: `PATCH /v1/customers/{customer_id}`** Unified endpoint for responding to RFI requests across all customer types and API versions. Submit only the fields and documents specified in the `customer.rfi` webhook. Sending unrequested fields will trigger an error. The request body accepts the same field structures used by the customer creation and document attachment endpoints (both V1 and V2). This single endpoint replaces the need for separate PATCH calls per document category. ### Beneficiaries 7. **New Endpoint: `POST /v3/beneficiaries`** Create a beneficiary with a required `counter_party` field (`FIRST_PARTY` or `THIRD_PARTY`). The `occupation_remarks` field is no longer required in `receiver_meta_data`. The response returns `beneficiary_id` directly instead of `id` and `status`. The beneficiary is ready for transactions only when its `status` reaches `ACTIVE` (delivered via the `beneficiary.status` webhook). ### Virtual Accounts 8. **New Endpoint: `POST /v2/customers/virtual-account`** Create a virtual account with a restructured request body. Key changes from V1: * `customer_id` is no longer in the request body (inferred from auth context) * Uses `destination.wallet`, `destination.currency`, `destination.rail` instead of flat fields * Uses `source.currency` and `source.rail` instead of `source_currency` and `source_rail` * Accepts both `developer_fee.percentage` and `developer_fee.fixed` instead of only `developer_fee_percentage` * The account starts in `PROCESSING` status. `deposit_instructions` will be null until the account becomes `ACTIVE`. 9. **New Endpoint: `GET /v2/customers/virtual-account`** List virtual accounts with the same filtering as V1. The response adds `developer_fee_fixed`, `rfi`, `bank_country`, `account_type`, and `bank_code` fields. The `status` enum is expanded to include `PROCESSING`, `IN_COMPLIANCE`, `REQUEST_FOR_INFORMATION`, `ACTIVE`, `INACTIVE`, and `DECLINED`. ### Catalogue 10. **New Endpoint: `GET /v1/source-of-wealth`** Retrieve a list of source of wealth options. Accepts `type` (`INDIVIDUAL` or `BUSINESS`) as a required query parameter. Used by `POST /v2/customers/business` via the `source_of_wealth_ids` field. ### Webhooks 11. **New Webhook: `customer.rfi`** Fires when the compliance team requests additional documents or data from a customer. Sets the customer status to `ACTION_REQUIRED`. The payload includes a structured `request_for_information` array describing exactly which sections, document types, and fields are `MISSING`, `EXPIRED`, or `INVALID`. Scoped to either the customer or a specific associated party. Can also fire after a customer is already `APPROVED`. | Customer Type | Section Values | | ------------------- | -------------------------------------------------------------------- | | Individual | `proof_of_identity`, `proof_of_address`, `tos_policies_value` | | Business V1 | `company_details`, `ownership_structure`, `legal_presence` | | Business V2 | `formation_documents`, `ownership_documents`, `supporting_documents` | | Associated Party V1 | `proof_of_identity`, `proof_of_address` | | Associated Party V2 | `identifying_documents`, `tax_info`, `address_documents` | 12. **New Webhook: `virtual_account.created.v2`** Fires when a V2 virtual account is created. The account starts in `PROCESSING` status with `deposit_instructions` set to null. Includes a `developer_fee_fixed` field and an `rfi` object (null initially). 13. **New Webhook: `virtual_account.status.v2`** Fires when a V2 virtual account status changes. Possible values: `PROCESSING`, `IN_COMPLIANCE`, `REQUEST_FOR_INFORMATION`, `ACTIVE`, `INACTIVE`, `DECLINED`. The payload includes `deposit_instructions` (populated once active), `developer_fee_fixed`, `developer_fee_percent`, and `rfi`. ## 🛠️ Improvements ### Customers 1. **V2 Customer Status Names** Three customer status values have been renamed in V2 endpoints and webhooks. V1 status names remain unchanged for V1 created customers. | Status | V1 Name | V2 Name | | --------------------- | ------------ | ----------------- | | Awaiting processing | `QUEUED` | `PROCESSING` | | Paused for compliance | `ON_HOLD` | `IN_COMPLIANCE` | | Action needed | `REINITIATE` | `ACTION_REQUIRED` | The status values you receive are determined by which version of the Get Customer Details endpoint you call, not which version was used to create the customer. A business customer created via `POST /v1/customers/business` will return V2 status names when retrieved via `GET /v2/customers/{customer_id}`, and vice versa. 2. **V1 entity\_type enum: `PRIVATE_LIMITED` removed** The `PRIVATE_LIMITED` value has been removed from the `entity_type` enum in `POST /v2/customers/business`. It remains available in V1. 3. **Identity document types expanded** The `ProofOfIdentity` schema now includes `RESIDENCE_PERMIT` and `PERMANENT_RESIDENCY_ID` as accepted types. `PERMANENT_RESIDENCY_ID` is only supported for USA residents and will be rejected for non-USA residents. 4. **`GET /v1/industries` scoped to V1 only** The List Industries catalogue endpoint now applies only to `POST /v1/customers/business`. The V2 business customer endpoint uses `industry_codes` (NAICS 6-digit codes) instead. ### Beneficiaries 5. **`counter_party` field added to `POST /v2/beneficiaries`** An optional `counter_party` field (`FIRST_PARTY` or `THIRD_PARTY`) has been added to the existing V2 Create Beneficiary endpoint. 6. **`status` and `counter_party` fields added to `GET /v2/beneficiaries/details`** The Fetch Beneficiary Details V2 response now includes a `status` field with values `PROCESSING`, `ACTIVE`, `INACTIVE`, or `REJECTED`, and a `counter_party` field with values `FIRST_PARTY` or `THIRD_PARTY`. 7. **`beneficiary.status` webhook now includes `status` field** The `beneficiary.status` webhook payload now includes a `status` field (`PROCESSING`, `ACTIVE`, `INACTIVE`, `REJECTED`) alongside the existing `active` boolean. The webhook now fires for all four status transitions. # April 20, 2026 Source: https://developer.fin.com/changelogs/2026-04-20 API Migration Guide — deprecation deadline May 20, 2026 **Deprecation Notice:** The endpoints listed below will be deprecated on **May 20, 2026**. Please migrate to the new versions before this date to avoid service disruption. ## API Migration Guide This guide outlines the endpoints scheduled for deprecation, their replacements, and the key behavioral changes you need to be aware of when migrating. Each section includes direct links to the relevant API reference for both the deprecated and new endpoints. *** ## Endpoint Migration Reference ### Customers | Resource | Deprecated Endpoint | New Endpoint | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Create business customer | `POST /v1/customers/business` — [reference](/api-reference/customers/create-business-customer) | `POST /v2/customers/business` — [reference](/api-reference/customers/create-business-customer-v2) | | Attach business documents | `POST /v1/customers/business/attach` — [reference](/api-reference/customers/attach-documents-to-business-customer) | `POST /v2/customers/{customer_id}/business/attach` — [reference](/api-reference/customers/attach-documents-to-business-customer-v2) | | Attach document to associated party | `POST /v1/customers/associated-parties/individual/attach` — [reference](/api-reference/customers/attach-document-to-associated-party) | `POST /v2/customers/{customer_id}/associated-parties/individual/attach` — [reference](/api-reference/customers/attach-documents-to-associated-party-v2) | | List customers | `GET /v1/customers` — [reference](/api-reference/customers/list-customers) | `GET /v2/customers` — [reference](/api-reference/customers/list-customers-v2) | | Get business customer details | `GET /v1/customers/{customer_id}` | `GET /v2/customers/{customer_id}` — [reference](/api-reference/customers/get-customer-details-v2) | ### Beneficiaries | Resource | Deprecated Endpoint | New Endpoint | | ----------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------- | | Create beneficiary | `POST /v2/beneficiaries` | `POST /v3/beneficiaries` — [reference](/api-reference/beneficiaries/create-beneficiary-v3) | | Get beneficiary details | `GET /v1/beneficiaries/details` | `GET /v2/beneficiaries/details` — [reference](/api-reference/beneficiaries/fetch-beneficiary-details-v2) | The new beneficiary details endpoint adds visibility into the `status` and `counter_party` fields. ### Virtual Accounts | Resource | Deprecated Endpoint | New Endpoint | | ---------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------ | | Create virtual account | `POST /v1/customers/virtual-account` — [reference](/api-reference/virtual-accounts/create-virtual-account) | `POST /v2/customers/virtual-account` | | List virtual accounts | `GET /v1/customers/virtual-account` | `GET /v2/customers/virtual-account` | *** ## What's Changed ### 1. New Status Values for Business Customers (v2) The v2 business customer API introduces clearer, more descriptive status values. If you have logic that branches on customer status, you'll need to update it. | Legacy Status (v1) | New Status (v2) | | ------------------ | ----------------- | | `QUEUED` | `PROCESSING` | | `ON_HOLD` | `IN_COMPLIANCE` | | `REINITIATE` | `ACTION_REQUIRED` | **Versioning rules:** * **Business customers** — Use v2 for both creation and retrieval. * **Individual customers** — Continue using v1 for both creation and retrieval. ### 2. Request for Information (RFI) Management A new `request_for_information` object has been introduced on the business customer resource to streamline RFI handling. To respond to or update an RFI, use: ``` PATCH /v1/customers/{customer_id} ``` This is the canonical way to manage RFIs going forward — no separate workflow is required. ### 3. Capabilities Moved to a Dedicated Endpoint The `capabilities` object has been **removed** from the v2 customer details response. To fetch a customer's capabilities, use the new dedicated endpoint: ``` GET /v2/customers/{customer_id}/capabilities ``` This keeps customer detail responses lighter and lets you fetch capability data only when you actually need it. ### 4. New Beneficiary Status Values Beneficiaries now expose a more granular status lifecycle so you can clearly determine transaction eligibility: | Status | Description | Eligible for Transactions? | | ------------ | ------------------------------------------------------- | -------------------------- | | `PROCESSING` | The beneficiary is being prepared and is not yet ready. | No | | `ACTIVE` | The beneficiary is fully set up and ready to use. | Yes | | `INACTIVE` | The beneficiary is currently disabled. | No | | `REJECTED` | Beneficiary failed validation. | No | Make sure your transaction-initiation logic checks for `ACTIVE` before attempting to send funds to a beneficiary. *** ## Migration Checklist Use this list to track your migration work before **May 20, 2026**: * Update all business customer create and fetch calls to v2. * Map legacy customer statuses (`QUEUED`, `ON_HOLD`, `REINITIATE`) to their new values in your codebase. * Implement the `PATCH /v1/customers/{customer_id}` flow for RFI handling. * Update document attachment calls to use the new `{customer_id}`-scoped paths. * Update customer list and detail integrations to v2. * Move any capabilities-dependent logic to `GET /v2/customers/{customer_id}/capabilities`. * Update beneficiary creation calls to v3 and fetch calls to v2. * Handle the new beneficiary statuses (`PROCESSING`, `ACTIVE`, `INACTIVE`, `REJECTED`) — gate transactions on `ACTIVE`. * Update virtual account create and list calls to v2. * Verify individual customer flows remain on v1 (no change required). * Complete migration before **May 20, 2026**. # May 01, 2026 Source: https://developer.fin.com/changelogs/2026-05-01 Changelog for May 01, 2026 ## ✨ New Features ### Country Codes 1. **New Postal Code Object in `GET /v1/countries`** Each country object in the response now includes a `postal_code` object with two fields: * `required` — boolean indicating whether a postal code is mandatory for that country * `regex` — validation pattern for the expected postal code format; `null` for countries where postal codes are not applicable ## 🛠️ Improvements ### Customers 1. **Postal Code Validation on Submission** Address fields that include a postal code are now validated against the `regex` pattern of the specified country at the time of submission. Invalid formats are rejected with a descriptive error, reducing the likelihood of triggering a Request for Information (RFI) due to malformed address data. ## 🐞 Bug Fixes ### Customers 1. **Business Customer Onboarding Flow Stability** Resolved issues affecting the onboarding flow for certain business entity types. Affected entity types now progress through onboarding steps correctly without unexpected errors or stalled states. # June 10, 2026 Source: https://developer.fin.com/changelogs/2026-06-10 Changelog for June 10, 2026 ## ✨ New Features ### Pay-ins 1. **New Endpoint: `POST /v2/transactions/pay-ins`** Create a pay-in instruction for a customer. The customer makes a fiat payment before expiry using the returned deposit instructions and mandatory reference code, and receives USDC in their specified destination wallet. * `currency` — source currency. Currently supports `MXN` only. * `destination.rail` — blockchain rail for the destination wallet. Supports `POLYGON` and `SOLANA`. * `destination.currency` — destination currency. Currently supports `USDC` only. * `developer_fee` — optional object to apply a fixed and/or percentage fee to the pay-in. * `deposit_instruction` — returned in the response. Contains either `bank_details` (with CLABE, SPEI rail, and reference code) or `checkout_details`, depending on the `type` field. * `expire_at` — timestamp after which the pay-in can no longer be paid. * `X-Idempotency-Key` header is required on all requests. Pay-in instructions require separate configuration. Contact support to enable this feature for your account. 2. **New Endpoint: `GET /v2/transactions/pay-ins`** Returns a paginated list of pay-ins. Each item includes `id`, `status`, `source_amount`, `source_amount_in_major`, `currency`, and `created_at`. Supports `current_page` and `per_page` query parameters (max 100 per page). 3. **New Endpoint: `GET /v2/transactions/pay-ins/{payin_id}`** Returns full details for a single pay-in by ID, including status, amounts, fees, exchange rate, destination wallet, and deposit instructions. The `transaction_id` field is `null` until the pay-in is processed and a transaction is created. Pay-in statuses: `PENDING`, `PROCESSING`, `COMPLETED`, `EXPIRED`, `FAILED`. # June 16, 2026 Source: https://developer.fin.com/changelogs/2026-06-16 Changelog for June 16, 2026 ## ✨ New Features ### Customers 1. **New Endpoint: `POST /v2/customers/individual`** Create an individual customer with verification details, basic info, address, and financial profile. The customer is created in the `INCOMPLETE` state; attach documents next using `POST /v2/customers/{customer_id}/individual/attach`. The response returns `customer_id` and a `tos_policies_url`. Key fields and behaviors: * `basic_info.tax_info` — array of tax documents, each with `country_code`, `document_type`, and `document_id`. Each entry must have a unique `document_id`. * `basic_info` — also accepts `middle_name`, `secondary_nationality`, and `gender` (`MALE`, `FEMALE`), alongside `first_name`, `last_name`, `dob`, `email`, `phone`, `country_of_residence`, and `primary_nationality`. * `financial_profile.employment_status` — one of `EMPLOYED`, `SELF_EMPLOYED`, `RETIRED`, `STUDENT`, `UNEMPLOYED`. * `financial_profile` — uses `occupation_id`, `purpose_id`, `source_of_fund_ids` (array of integer foreign keys), and `monthly_volume_usd`. * `address.subdivision_code` — ISO 3166-2 code (for example, `US-CA`). `address.country` must match `basic_info.country_of_residence`. * `_en` companions — when a field contains non-ASCII characters, provide a transliterated value in the matching `_en` field (for example, `first_name_en`, `street_line_1_en`). The V1 endpoint `POST /v1/customers/individual` remains available. In V2, the single `basic_info.tin` field is replaced by the `tax_info` array: | V1 Field | V2 Field | | ---------------- | ----------------------- | | `basic_info.tin` | `basic_info.tax_info[]` | 2. **New Endpoint: `POST /v2/customers/{customer_id}/individual/attach`** Attach identifying and address documents to an existing V2 individual customer. The customer ID is now a path parameter, and documents are grouped into typed arrays. Documents are processed asynchronously — a `200` response means the request was validated and queued, and the customer moves to `PROCESSING` once processing completes. Key fields and behaviors: * `identifying_documents` — supported `type` values are `PASSPORT`, `NATIONAL_ID`, `DRIVERS_LICENSE`, `RESIDENCE_PERMIT`, and `SELFIE`. At most one non-SELFIE document may be included per request. * `NATIONAL_ID`, `DRIVERS_LICENSE`, `RESIDENCE_PERMIT` — require two files, one `FRONT` and one `BACK`. `PASSPORT` and `SELFIE` take a single file. * `state` — document issuing state (max 64 characters), required when `type` is `DRIVERS_LICENSE` and `country` is `USA`. * `address_documents` — exactly one entry, with a `type` of `UTILITY_BILL`, `GOVERNMENT_LETTER`, or `BANK_STATEMENT`. Its `country` must match the customer's `country_of_residence`. * File URIs must be unique across the entire request and must belong to the customer. Only one attach can be in flight per customer; a concurrent attach returns `409`. The V1 endpoint `POST /v1/customers/individual/attach` remains available. In V2, the single proof objects are replaced by typed document arrays, and `customer_id` moves from the body to the path: | V1 Field | V2 Field | | -------------------- | ------------------------------ | | `proof_of_identity` | `identifying_documents[]` | | `proof_of_address` | `address_documents[]` | | `customer_id` (body) | `customer_id` (path parameter) | # July 14, 2026 Source: https://developer.fin.com/changelogs/2026-07-14 Changelog for July 14, 2026 ## 🛠️ Improvements ### Crypto Orchestration 1. **`status` Field Added to [Get Customer Wallets](https://developer.fin.com/api-reference/customers/get-customer-wallets)** `GET /v2/customers/{customer_id}/wallets` responses now include a `status` field (`PENDING`, `ACTIVE`, `INACTIVE`) on each wallet object, reflecting the same asynchronous provisioning state introduced by the new Create Customer Wallets endpoint. `address` is `null` until the wallet finishes provisioning. ### Payment Instructions 1. **Pay-in Endpoints Temporarily Unavailable** `POST /v2/transactions/pay-ins`, `GET /v2/transactions/pay-ins`, and `GET /v2/transactions/pay-ins/{payin_id}` are temporarily unavailable. They are expected to return in the first week of August 2026. ## ✨ New Features ### Virtual Accounts 1. **Additional Fiat Currencies and Rails on** [Create Virtual Account V2](https://developer.fin.com/api-reference/virtual-accounts/create-virtual-account-v2)`POST /v2/customers/{customer_id}/virtual-accounts` now accepts `EUR` and `MXN` in `source.currency` (previously `USD` only), and `FEDNOW`, `SEPA`, and `SPEI` in `source.rail` (previously `ACH`, `SWIFT`, and `FEDWIRE` only). The endpoint description has also been updated to describe general fiat-to-crypto conversion rather than USD-to-USDC specifically. ### Crypto Orchestration **New Endpoint:** [**Create Customer Wallets**](https://developer.fin.com/api-reference/customers/create-customer-wallets)`POST /v2/customers/{customer_id}/wallets` Provision one or more crypto wallets for a customer in a single request. Specify one or more `rail`/`currency` pairs in the `wallets[]` array; each requested wallet is created asynchronously and starts with a status of `PENDING`, moving to `ACTIVE` (or `INACTIVE`) once the wallet address has been issued. Poll `GET /v2/customers/{customer_id}/wallets` to check on status. * Returns a `409` if any requested `rail`/`currency` pair already exists for the customer, listing the colliding pairs in the response * Currently supports `POLYGON` → `USDC`, `ETHEREUM` → `USDC`, and `SOLANA` → `USDC` # August 16, 2026 Source: https://developer.fin.com/changelogs/2026-08-16 Changelog for August 16, 2026 ## 🛠️ Improvements ### Crypto Orchestration 1. **Additional Rails and Tokens on** [Create Customer Wallets](https://developer.fin.com/api-reference/customers/create-customer-wallets) `POST /v2/customers/{customer_id}/wallets` now provisions wallets on `BASE` in addition to `ETHEREUM`, `POLYGON`, and `SOLANA`, and supports native and stablecoin tokens beyond `USDC`. | Rail | Currencies | | ---------- | ----------------------------------------------- | | `BASE` | `ETH`, `USDC`, `EURC` | | `ETHEREUM` | `ETH`, `USDC`, `USDT`, `EURC` | | `POLYGON` | `MATIC`, `USDC`, `USDT` | | `SOLANA` | `SOL`, `USDC`, `EURC`, `PYUSD`, `USDT`, `USDPT` | Previously, each rail supported `USDC` only. Requests specifying a token that is not available on the selected rail are failed. ### Virtual Accounts 1. **Additional Crypto Tokens and Networks on** [Create Virtual Account V2](https://developer.fin.com/api-reference/virtual-accounts/create-virtual-account-v2) `POST /v2/customers/{customer_id}/virtual-accounts` now accepts `USDT` and `EURC` in `destination.currency` (previously `USDC` only), and `ETHEREUM`, `SOLANA`, and `BASE` in `destination.rail` (previously `POLYGON` only). * Availability depends on the token, the network, and the `source.rail`. See [Supported rails and currencies](https://developer.fin.com/guides/others/supported-rails-and-currencies) for the valid combinations. * The `destination.wallet` address format now depends on the selected rail. `ETHEREUM`, `BASE`, and `POLYGON` use hexadecimal addresses, and `SOLANA` uses base58. ### Beneficiaries 1. **Additional Crypto Tokens and Networks for Bank and E-Wallet Beneficiaries on** [Create Beneficiary V3](https://developer.fin.com/api-reference/beneficiaries/create-beneficiary-v3) `POST /v3/beneficiaries` now accepts `USDT` and `EURC` in `deposit_instruction.currency` and `refund_instruction.currency` (previously `USDC` only), and `ETHEREUM`, `SOLANA`, and `BASE` in `deposit_instruction.rail` and `refund_instruction.rail` (previously `POLYGON` only). * The `currency` and `rail` of `deposit_instruction` and `refund_instruction` must match. * Available rails and currencies depend on the configuration set up for your account. Contact support to confirm what is enabled for you. 2. **Additional Chains and Tokens for External Crypto Wallet Beneficiaries** On the External Crypto Wallet beneficiary type, `destination_wallet.rail` now accepts `BASE` alongside `POLYGON`, `ETHEREUM`, and `SOLANA`. `destination_wallet.currency` now accepts `ETH`, `SOL`, `MATIC`, `USDT`, `EURC`, `PYUSD`, and `USDPT` alongside `USDC`. * Not every token is available on every chain. `USDPT` is available on `SOLANA` only. # September 9, 2026 Source: https://developer.fin.com/changelogs/2026-09-09 Changelog for September 9, 2026 **Deprecations:** Everything listed under Deprecations and Removals below is deprecated and no longer documented. The V1 customer, beneficiary, virtual account, and transaction endpoints reached their stated deprecation date of September 1, 2026. Migrate to the replacements before your next release. ## ✨ New Features ### Virtual Accounts 1. **New Endpoint: `POST /v3/customers/{customer_id}/virtual-accounts`** [Create Virtual Account](/api-reference/virtual-accounts/create-virtual-account-v3) issues a virtual account for a customer and now lets you choose the banking partner that receives the fiat deposit. * `source.bank` — required. Accepts `SSB` and `PORTAGE`. The banks available to you depend on your configuration, and not every bank supports every source rail. * The create response now returns `deposit_instructions`, `destination`, and `bank`. `customer_id` and `created_at` are no longer returned on create. 2. **New Endpoint: `GET /v3/customers/{customer_id}/virtual-accounts`** [List Virtual Accounts](/api-reference/virtual-accounts/list-virtual-accounts-v3) returns a paginated list of every virtual account belonging to a customer. 3. **New Endpoint: `GET /v3/customers/{customer_id}/virtual-accounts/{va_id}`** [Get Virtual Account Details](/api-reference/virtual-accounts/get-virtual-account-details) returns the full record for a single virtual account, including the deposit instructions the customer funds it with and the crypto destination the deposits settle to. There is no earlier equivalent for this endpoint. ### Beneficiaries 1. **New Field: `intermediary_routing_number`** [Create Beneficiary](/api-reference/beneficiaries/create-beneficiary-v3) accepts `receiver_meta_data.intermediary_routing_number`, the routing number of an intermediary bank when a payout has to be routed through one before it reaches the beneficiary bank. This field is required for SWIFT payouts. ## 🛠️ Improvements ### Beneficiaries 1. **Request Examples Split by Rail** The bank beneficiary example on [Create Beneficiary](/api-reference/beneficiaries/create-beneficiary-v3) has been replaced with two examples: a local rail example using `bank_account.scheme` `LOCAL` with a `FEDWIRE` routing number, and an international rail example using `bank_account.scheme` `SWIFT` with a SWIFT BIC. Both examples now use the `ETHEREUM` rail for `deposit_instruction` and `refund_instruction`. 2. **USD ACH Payouts Coming Soon** USD ACH payouts are not yet available. This is now stated on [Create Beneficiary](/api-reference/beneficiaries/create-beneficiary-v3). ### Supported Currencies and Rails 1. **`EURC` Removed From Currency Enums** `EURC` is no longer accepted and has been removed from the currency enums on the following endpoints. `USDC` and `USDT` are unaffected. * [Create Beneficiary](/api-reference/beneficiaries/create-beneficiary-v3) — `deposit_instruction.currency`, `refund_instruction.currency`, and the external crypto wallet token list * [Create Virtual Account](/api-reference/virtual-accounts/create-virtual-account-v3) — `destination.currency` * Create Customer Wallets — `currency` 2. **`FEDNOW` and `SEPA` Removed From Virtual Account Source Rails** `source.rail` on [Create Virtual Account](/api-reference/virtual-accounts/create-virtual-account-v3) now accepts `ACH`, `SWIFT`, `FEDWIRE`, and `SPEI`. `FEDNOW` and `SEPA` have been removed. 3. **Capabilities Response Examples Updated** The response examples on [Get Customer Capabilities](/api-reference/customers/get-customer-capabilities) no longer include `EURC` tokens, the `FEDNOW` on-ramp rail, or `SEPA` off-ramp routes. ## 🗑️ Deprecations and Removals 1. **Endpoints Deprecated and Removed After the September 1, 2026 Deprecation Date** | Resource | Removed endpoint | Replacement | | --------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Create individual customer | `POST /v1/customers/individual` | `POST /v2/customers/individual` — [reference](/api-reference/customers/create-individual-customer-v2) | | Attach individual documents | `POST /v1/customers/individual/attach` | `POST /v2/customers/{customer_id}/individual/attach` — [reference](/api-reference/customers/attach-documents-to-individual-customer-v2) | | Get customer details | `GET /v1/customers/{customer_id}` | `GET /v2/customers/{customer_id}` — [reference](/api-reference/customers/get-customer-details-v2) | | Create beneficiary | `POST /v2/beneficiaries` | `POST /v3/beneficiaries` — [reference](/api-reference/beneficiaries/create-beneficiary-v3) | | Create virtual account | `POST /v2/customers/{customer_id}/virtual-accounts` | `POST /v3/customers/{customer_id}/virtual-accounts` — [reference](/api-reference/virtual-accounts/create-virtual-account-v3) | | List virtual accounts | `GET /v2/customers/{customer_id}/virtual-accounts` | `GET /v3/customers/{customer_id}/virtual-accounts` — [reference](/api-reference/virtual-accounts/list-virtual-accounts-v3) | | Fetch transaction details | `GET /v1/transactions/{transaction_id}` | `GET /v2/transactions/{transaction_id}` — [reference](/api-reference/transactions/fetch-transaction-details-v2) | `PATCH /v1/customers/{customer_id}` — [Patch Customer RFI](/api-reference/customers/patch-customer-rfi) is unaffected and remains available. 2. **V1 Virtual Account Webhooks Deprecated** The `virtual_account.created` and `virtual_account.status` events are deprecated and no longer documented. Subscribe to the `.v2` events instead, which carry the same fields plus `rfi` and `developer_fee_fixed`. | Deprecated event | Replacement | | ------------------------- | ---------------------------------------------------------------------------------------------- | | `virtual_account.created` | `virtual_account.created.v2` — [reference](/api-reference/webhooks/virtual-account-created-v2) | | `virtual_account.status` | `virtual_account.status.v2` — [reference](/api-reference/webhooks/virtual-account-status-v2) | Both event names have been removed from the `type` enum on the webhook event envelope. The `status` values differ between the two versions: the deprecated events returned `ACTIVE`, `INACTIVE`, and `SUSPENDED`, while the `.v2` events return `PROCESSING`, `IN_COMPLIANCE`, `REQUEST_FOR_INFORMATION`, `ACTIVE`, `INACTIVE`, and `DECLINED`. All other webhook events are unaffected. # FAQs Source: https://developer.fin.com/faqs/index FAQs regarding API integration, sandbox testing, technical capabilities, and others. Contact [sales@fin.com](mailto:sales@fin.com) to get sandbox keys. Visit [orchestration.fin.com](https://orchestration.fin.com) and submit the registered email Sign Up Screen Enter the One-Time Password (OTP) sent to your registered contact method to verify your identity. Once verified, you will be automatically redirected to your account dashboard. Navigate to the **API Keys** menu to issue your initial set of keys and begin exploring our API collection. Check our [entity-wise document requirements](/guides/compliance/entity-wise-document-requirement). Check our [individual customer document requirements](/guides/compliance/individual-identifying-documents). Virtual accounts are available in the following currencies and payment rails, subject to the risk classification of the customer's country of residence: * **USD (ACH & FedWire)** - Individuals & Businesses * **USD (SWIFT)** - Individuals & Businesses * **MXN (SPEI) -** Individuals & Businesses To know more, check our [payin coverage](/guides/pricing-and-coverage/coverage-and-capabilities). While the beneficiary was created successfully, you should have also received a `liquidation_address` in the response. For **USD payouts**, the Transfer API and Batch API are **not applicable** for local routes. If the beneficiary has `auto_settlement: false` with country `USA` and currency `USD`, using those APIs will result in this error. The Transfer/Batch APIs can only be used for USD SWIFT in specific cases where Fin maintains an underlying prefunding with the banking partner. **All USD local payouts must go through the `liquidation_address`.** You need to send **USDC on Polygon** (the currently supported currency and rail, with more being added) to the `liquidation_address`. This automatically triggers a liquidation address drain, which initiates a payout to the end bank account. You will also receive a `transaction.status` webhook when funds are received by Fin at the liquidation address. Liquidation Address Flow # Bank account & routing number validation rules Source: https://developer.fin.com/guides/beneficiaries/bank-account-and-routing-validation-rules Allowed values for bank account and routing schemes when creating a beneficiary. Allowed values for bank account and routing schemes when creating a beneficiary. These specifications are regularly updated — refer to the [release notes](/changelogs) for the latest changes. All ENUM values must be provided in **ALL CAPS** when making API calls. ### Required when values | Value | Meaning | | :------------ | :------------------------------------------------------- | | `always` | Required regardless of the bank account scheme used | | `local` | Required only when `bank_account.scheme` is `LOCAL` | | `swift` | Required only when `bank_account.scheme` is `SWIFT` | | `conditional` | Required based on the payment type (ACH vs wire for USA) | | `null` | Optional — include if available | **Allowed currencies:** `AUD`, `USD` **Bank account** | Field | Value | | :----------- | :--------------- | | Schemes | `LOCAL`, `SWIFT` | | Number regex | `^[0-9]{4,9}$` | **Bank routing** | Scheme | Regex | Required when | | :------------------ | :-------------------------------------------- | :------------ | | `BSB` | `^[0-9]{6}$` | `local` | | `SWIFT` | `^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$` | `swift` | | `BANK_IDENTIFIER` | `^[1-9]\d*$` | `always` | | `BRANCH_IDENTIFIER` | `^[1-9]\d*$` | `conditional` | ```json Local theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "AUS", "currency": "AUD", "account_holder": { "type": "INDIVIDUAL", "first_name": "Afroja", "last_name": "Akter", "email": "afroja@example.com", "phone": "+61412345678" }, "bank_account": { "bank_name": "Commonwealth Bank of Australia", "number": "123456789", "scheme": "LOCAL", "type": "SAVINGS" }, "bank_address": { "street_line_1": "Ground Floor Tower 1, 201 Sussex Street", "city": "Sydney", "state": "AU-SA", "postcode": "2000", "country": "AUS" }, "account_holder_address": { "street_line_1": "42 Wallaby Way", "city": "Queensland", "state": "AU-SA", "postcode": "2000", "country": "AUS" }, "receiver_meta_data": { "nationality": "AUS", "transaction_purpose_id": 1, "transaction_purpose_remarks": "Send to Family & Friends", "occupation_id": 504, "occupation_remarks": "Software quality assurance analyst and tester", "relationship": "FAMILY_MEMBER", "relationship_remarks": "Family & Friends" }, "bank_routing": [ { "scheme": "BSB", "number": 123456 }, { "scheme": "BANK_IDENTIFIER", "number": 120 } ], "developer_fee": { "fixed": 1.25, "percentage": 0.45 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": false } } ``` ```json SWIFT theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "AUS", "currency": "USD", "account_holder": { "type": "INDIVIDUAL", "first_name": "Michael", "last_name": "Connor", "email": "michael.oconnor@example.com", "phone": "+61412345678" }, "bank_account": { "bank_name": "Commonwealth Bank of Australia", "number": "123456789", "scheme": "SWIFT", "type": "SAVINGS" }, "bank_address": { "street_line_1": "Ground Floor Tower 1, 201 Sussex Street", "city": "Sydney", "state": "AU-SA", "postcode": "2000", "country": "AUS" }, "account_holder_address": { "street_line_1": "42 Wallaby Way", "city": "Queensland", "state": "AU-SA", "postcode": "2000", "country": "AUS" }, "receiver_meta_data": { "nationality": "AUS", "transaction_purpose_id": 1, "transaction_purpose_remarks": "Send to Family & Friends", "occupation_id": 504, "occupation_remarks": "Software quality assurance analyst and tester", "relationship": "FAMILY_MEMBER", "relationship_remarks": "Family & Friends" }, "bank_routing": [ { "scheme": "BANK_IDENTIFIER", "number": 3503 }, { "scheme": "SWIFT", "number": "DBSSSGSG001" } ], "developer_fee": { "fixed": 1.25, "percentage": 0.45 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": false } } ``` **Allowed currencies:** `BDT` **Bank account** | Field | Value | | :----------- | :-------------- | | Schemes | `LOCAL` | | Number regex | `^[0-9]{6,20}$` | **Bank routing** | Scheme | Regex | Required when | | :------------------ | :----------- | :------------ | | `BANK_IDENTIFIER` | `^[1-9]\d*$` | `always` | | `BRANCH_IDENTIFIER` | `^[1-9]\d*$` | `conditional` | ```json Local bank theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "BGD", "currency": "BDT", "account_holder": { "type": "INDIVIDUAL", "first_name": "Afroja", "last_name": "Akter", "email": "afro@email.com", "phone": "+8801688502814" }, "bank_account": { "bank_name": "BRAC Bank Limited", "number": "1234567890123456", "scheme": "LOCAL", "type": "SAVINGS" }, "bank_routing": [ { "scheme": "BANK_IDENTIFIER", "number": 161 }, { "scheme": "BRANCH_IDENTIFIER", "number": 125 } ], "bank_address": { "street_line_1": "BRAC Bank Tower, 75 Mohakhali", "city": "Dhaka", "state": "BD-03", "postcode": "1212", "country": "BGD" }, "account_holder_address": { "street_line_1": "42 Dhanmondi Road", "city": "Dhaka", "state": "BD-03", "postcode": "1205", "country": "BGD" }, "receiver_meta_data": { "nationality": "BGD", "transaction_purpose_id": 6, "transaction_purpose_remarks": "Education expenses", "occupation_id": 210, "occupation_remarks": "Software Engineer", "relationship": "FAMILY_MEMBER" }, "developer_fee": { "fixed": 2.50, "percentage": 10.5 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x1234567890123456789012345678901234567890", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": true } } ``` ```json E-wallet (bKash) theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "BGD", "currency": "BDT", "account_holder": { "type": "INDIVIDUAL", "first_name": "Fahmi", "last_name": "Testbenvtwo", "email": "fahmitestbenv2ewallet@email.com", "phone": "+8801688502814" }, "account_holder_address": { "street_line_1": "42 Chamelibag Shantinagar", "city": "Dhaka", "state": "BD-13-13", "postcode": "1217", "country": "BGD" }, "receiver_meta_data": { "nationality": "BGD", "transaction_purpose_id": 1, "transaction_purpose_remarks": "Education expenses", "occupation_id": 2, "occupation_remarks": "Software Engineer", "relationship": "FRIEND" }, "e_wallet": { "number": "+8801688502814", "scheme": "BKASH" }, "developer_fee": { "fixed": 1.55, "percentage": 0.48 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0xabcdef1234567890abcdef1234567890abcdef12", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": false } } ``` **Allowed currencies:** `CAD` **Bank account** | Field | Value | | :----------- | :-------------- | | Schemes | `LOCAL` | | Number regex | `^[0-9]{7,12}$` | **Bank routing** | Scheme | Regex | Required when | | :------------------ | :----------- | :------------ | | `BRANCH_CODE` | `^[0-9]{3}$` | `null` | | `TRANSIT_NUMBER` | `^[0-9]{5}$` | `local` | | `BANK_IDENTIFIER` | `^[1-9]\d*$` | `always` | | `BRANCH_IDENTIFIER` | `^[1-9]\d*$` | `conditional` | ```json Local theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "CAN", "currency": "CAD", "account_holder": { "type": "INDIVIDUAL", "first_name": "Liz", "last_name": "Tomford", "email": "liztomford@email.com", "phone": "+12345678910" }, "bank_account": { "bank_name": "Royal Bank of Canada", "number": "123456789", "scheme": "LOCAL", "type": "SAVINGS" }, "bank_address": { "street_line_1": "Ground Floor Tower 1, 201 Sussex Street", "city": "Alberta", "state": "CA-BC", "postcode": "2000", "country": "CAN" }, "account_holder_address": { "street_line_1": "42 Wallaby Way", "city": "Vancouver", "state": "CA-BC", "postcode": "4554", "country": "CAN" }, "receiver_meta_data": { "nationality": "USA", "transaction_purpose_id": 1, "transaction_purpose_remarks": "Send to Family & Friends", "occupation_id": 504, "occupation_remarks": "Software quality assurance analyst and tester", "relationship": "FAMILY_MEMBER", "relationship_remarks": "Family & Friends" }, "bank_routing": [ { "scheme": "BANK_IDENTIFIER", "number": 163 }, { "scheme": "TRANSIT_NUMBER", "number": 50201 } ], "developer_fee": { "fixed": 1.25, "percentage": 0.45 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": false } } ``` **Allowed currencies:** `EUR` for all EUR-supported countries in this region **Bank account** | Field | Value | | :----------- | :---------------------------- | | Schemes | `LOCAL` | | Number regex | `^[A-Z0-9]{8}([A-Z0-9]{3})?$` | **Bank routing** | Scheme | Regex | Required when | | :------------------ | :---------------------------------- | :------------ | | `IBAN` | `^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$` | `always` | | `BANK_IDENTIFIER` | `^[1-9]\d*$` | `always` | | `BRANCH_IDENTIFIER` | `^[1-9]\d*$` | `conditional` | ```json Local theme={null} { "customer_id": "{{customer_id}}", "counter_party": "FIRST_PARTY", "country": "FRA", "currency": "EUR", "account_holder": { "type": "INDIVIDUAL", "first_name": "Camille", "last_name": "Fontaine", "email": "camille.fontaine@orange.fr", "phone": "+33612345678" }, "bank_account": { "bank_name": "BNP Paribas", "number": "30004007648", "scheme": "LOCAL", "type": "SAVINGS" }, "bank_address": { "street_line_1": "16 Boulevard des Italiens", "city": "Paris", "state": "FR-75", "postcode": "75009", "country": "FRA" }, "account_holder_address": { "street_line_1": "24 Rue de Rivoli", "city": "Paris", "state": "FR-75", "postcode": "75004", "country": "FRA" }, "receiver_meta_data": { "nationality": "FRA", "occupation_id": 504, "transaction_purpose_id": 1, "transaction_purpose_remarks": "Personal remittance for living expenses and family support", "relationship": "EMPLOYEE", "relationship_remarks": "Individual beneficiary" }, "bank_routing": [ { "scheme": "IBAN", "number": "FR7630004007540001957675085" }, { "scheme": "BANK_IDENTIFIER", "number": 1918 } ], "developer_fee": { "fixed": 0, "percentage": 0 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x9c3d57fa82b401e7d2087ab36c1f8e3d20a647b1", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": false } } ``` ```json SWIFT theme={null} { "customer_id": "{{customer_id}}", "country": "FRA", "currency": "USD", "account_holder": { "type": "BUSINESS", "business_name": "Lumiere Tech Solutions SAS", "email": "comptabilite@lumieretech.fr", "phone": "+33140298765" }, "bank_account": { "bank_name": "Societe Generale", "number": "30102578492", "scheme": "SWIFT", "type": "CHECKING" }, "bank_address": { "street_line_1": "29 Boulevard Haussmann", "city": "Paris", "state": "FR-75", "postcode": "75009", "country": "FRA" }, "account_holder_address": { "street_line_1": "12 Rue du Faubourg Saint-Antoine", "city": "Paris", "state": "FR-75", "postcode": "75012", "country": "FRA" }, "receiver_meta_data": { "nationality": "FRA", "transaction_purpose_id": 15, "transaction_purpose_remarks": "Payment for B2B software services and technology consulting exports", "relationship": "CUSTOMER", "relationship_remarks": "Corporate beneficiary" }, "bank_routing": [ { "scheme": "SWIFT", "number": "SOGEFRPPXXX" }, { "scheme": "BANK_IDENTIFIER", "number": 1918 } ], "developer_fee": { "fixed": 0, "percentage": 0 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0xf4a823cd91e756b30d18ec47f2b0d3e85a91c027", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": false } } ``` **Allowed currencies:** `GBP`, `USD` **Bank account** | Field | Value | | :------------------- | :---------------------------------- | | Schemes | `LOCAL`, `SWIFT` | | Number regex (local) | `^[A-Z0-9]{8}([A-Z0-9]{3})?$` | | Number regex (IBAN) | `^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$` | **Bank routing** | Scheme | Regex | Required when | | :------------------ | :-------------------------------------------- | :------------ | | `SWIFT` | `^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$` | `swift` | | `IBAN` | `^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$` | `always` | | `BANK_IDENTIFIER` | `^[1-9]\d*$` | `always` | | `BRANCH_IDENTIFIER` | `^[1-9]\d*$` | `conditional` | ```json Local theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "GBR", "currency": "GBP", "account_holder": { "type": "INDIVIDUAL", "first_name": "Michael", "last_name": "Connor", "email": "michael.oconnor@example.com", "phone": "+447912345678" }, "bank_account": { "bank_name": "Barclays Bank UK", "number": "12345678", "scheme": "LOCAL", "type": "SAVINGS" }, "bank_address": { "street_line_1": "1 Churchill Place", "city": "London", "state": "GB-ABE", "postcode": "E14 5HP", "country": "GBR" }, "account_holder_address": { "street_line_1": "22 Baker Street", "city": "London", "state": "GB-ABE", "postcode": "W1U 3BW", "country": "GBR" }, "receiver_meta_data": { "nationality": "GBR", "transaction_purpose_id": 1, "transaction_purpose_remarks": "Send to Family & Friends", "occupation_id": 504, "occupation_remarks": "Software quality assurance analyst and tester", "relationship": "FAMILY_MEMBER", "relationship_remarks": "Family & Friends" }, "bank_routing": [ { "scheme": "IBAN", "number": "NW11BKGB2LXXX1223456" }, { "scheme": "BANK_IDENTIFIER", "number": 274 } ], "developer_fee": { "fixed": 1.25, "percentage": 0.45 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": false } } ``` ```json SWIFT theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "GBR", "currency": "USD", "account_holder": { "type": "INDIVIDUAL", "first_name": "Michael", "last_name": "Connor", "email": "michael.oconnor@example.com", "phone": "+447912345678" }, "bank_account": { "bank_name": "Barclays Bank UK", "number": "12345678", "scheme": "SWIFT", "type": "SAVINGS" }, "bank_address": { "street_line_1": "1 Churchill Place", "city": "London", "state": "GB-ABE", "postcode": "E14 5HP", "country": "GBR" }, "account_holder_address": { "street_line_1": "22 Baker Street", "city": "London", "state": "GB-ABE", "postcode": "W1U 3BW", "country": "GBR" }, "receiver_meta_data": { "nationality": "GBR", "transaction_purpose_id": 1, "transaction_purpose_remarks": "Send to Family & Friends", "occupation_id": 504, "occupation_remarks": "Software quality assurance analyst and tester", "relationship": "FAMILY_MEMBER", "relationship_remarks": "Family & Friends" }, "bank_routing": [ { "scheme": "BANK_IDENTIFIER", "number": 3501 }, { "scheme": "IBAN", "number": "NW11BKGB2LXXX1223456" }, { "scheme": "SWIFT", "number": "BARCGB22XXX" } ], "developer_fee": { "fixed": 1.25, "percentage": 0.45 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": false } } ``` **Allowed currencies:** `INR`, `USD` **Bank account** | Field | Value | | :----------- | :--------------- | | Schemes | `LOCAL`, `SWIFT` | | Number regex | `^[0-9]{6,18}$` | **Bank routing** | Scheme | Regex | Required when | | :------------------ | :-------------------------------------------- | :------------ | | `IFSC` | `^[A-Za-z]{4}0[A-Za-z0-9]{6}$` | `always` | | `SWIFT` | `^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$` | `swift` | | `BANK_IDENTIFIER` | `^[1-9]\d*$` | `always` | | `BRANCH_IDENTIFIER` | `^[1-9]\d*$` | `conditional` | ```json Local theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "IND", "currency": "INR", "account_holder": { "type": "INDIVIDUAL", "first_name": "Michael", "last_name": "Connor", "email": "michael.oconnor@example.com", "phone": "+919876543210" }, "bank_account": { "bank_name": "State Bank of India", "number": "12345678901", "scheme": "LOCAL", "type": "CHECKING" }, "bank_address": { "street_line_1": "SBI Tower, Bandra Kurla Complex", "city": "Mumbai", "state": "IN-AP", "postcode": "400051", "country": "IND" }, "account_holder_address": { "street_line_1": "42 Marine Drive", "city": "Mumbai", "state": "IN-AP", "postcode": "400002", "country": "IND" }, "receiver_meta_data": { "nationality": "IND", "transaction_purpose_id": 4, "transaction_purpose_remarks": "Send to Family & Friends", "occupation_id": 504, "occupation_remarks": "Software quality assurance analyst and tester", "relationship": "FAMILY_MEMBER", "relationship_remarks": "Family & Friends" }, "bank_routing": [ { "scheme": "BRANCH_IDENTIFIER", "number": 30690 }, // [!code ++] { // [!code ++] "scheme": "IFSC", "number": "ABCD0A1B2C3" }, { "scheme": "BANK_IDENTIFIER", "number": 1800 } ], "developer_fee": { "fixed": 1.25, "percentage": 0.45 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": true } } ``` ```json SWIFT theme={null} { "customer_id": "{{customer_id}}", "country": "IND", "currency": "USD", "account_holder": { "type": "BUSINESS", "business_name": "Zenith Exports Private Limited", "email": "finance@zenithexports.in", "phone": "+912240867531" }, "bank_account": { "bank_name": "ICICI Bank", "number": "628374910234567", "scheme": "SWIFT", "type": "CHECKING" }, "bank_address": { "street_line_1": "ICICI Bank Tower, Bandra Kurla Complex", "city": "Mumbai", "state": "IN-MH", "postcode": "400051", "country": "IND" }, "account_holder_address": { "street_line_1": "Plot 7, MIDC Industrial Area, Andheri East", "city": "Mumbai", "state": "IN-MH", "postcode": "400093", "country": "IND" }, "receiver_meta_data": { "nationality": "IND", "transaction_purpose_id": 13, "transaction_purpose_remarks": "Payment for export of manufactured goods", "relationship": "CUSTOMER", "relationship_remarks": "Corporate beneficiary" }, "bank_routing": [ { "scheme": "IFSC", "number": "ICIC0000021" }, { "scheme": "SWIFT", "number": "ICICINBBMUM" }, { "scheme": "BANK_IDENTIFIER", "number": 3855 } ], "developer_fee": { "fixed": 0, "percentage": 0 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0xb2d894f13c67a501e8d409bc27f3e82d1054a8c9", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": false } } ``` **Allowed currencies:** `JPY` **Bank account** | Field | Value | | :----------- | :----------- | | Schemes | `LOCAL` | | Number regex | `^[0-9]{7}$` | **Bank routing** | Scheme | Regex | Required when | | :------------------ | :----------- | :------------ | | `BANK_CODE` | `^[0-9]{4}$` | `always` | | `BANK_IDENTIFIER` | `^[1-9]\d*$` | `always` | | `BRANCH_IDENTIFIER` | `^[1-9]\d*$` | `conditional` | ```json Local theme={null} { "routing_scheme": "BANK_CODE", "routing_value": "<4-digit bank code>", "bank_identifier": "", "branch_identifier": "" } ``` **Allowed currencies:** `MXN` **Bank account** | Field | Value | | :----------- | :--------- | | Schemes | `LOCAL` | | Number regex | `^\d{18}$` | **Bank routing** | Scheme | Regex | Required when | | :------ | :--------- | :------------ | | `CLABE` | `^\d{18}$` | `local` | * Only **first-party payouts** are currently supported for MXN. Third-party payouts are not available at this time. * `auto_settlement` must be `true` for MXN payouts. ```json Local theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "MEX", "currency": "MXN", "account_holder": { "type": "BUSINESS", "business_name": "Acme Corp", "email": "contact@acmecorp.com", "phone": "+525512345678" }, "bank_account": { "bank_name": "STP", "number": "646180402301253739", "scheme": "LOCAL", "type": "CHECKING" }, "bank_routing": [ { "scheme": "CLABE", "number": "646180402301253739" } ], "bank_address": { "street_line_1": "Paseo de la Reforma 510", "city": "Ciudad de Mexico", "state": "MX-CMX", "postcode": "06600", "country": "MEX" }, "account_holder_address": { "street_line_1": "Avenida Insurgentes Sur 123", "city": "Ciudad de Mexico", "state": "MX-CMX", "postcode": "01000", "country": "MEX" }, "receiver_meta_data": { "nationality": "USA", "transaction_purpose_id": 1, "transaction_purpose_remarks": "Education expenses", "occupation_id": 2, "occupation_remarks": "Software Engineer", "relationship": "FAMILY_MEMBER" }, "developer_fee": { "fixed": 0, "percentage": 0 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": true } } ``` **Allowed currencies:** `NPR` **Bank account** | Field | Value | | :----------- | :-------------- | | Schemes | `LOCAL` | | Number regex | `^[0-9]{8,20}$` | **Bank routing** | Scheme | Regex | Required when | | :------------------ | :----------- | :------------ | | `BANK_IDENTIFIER` | `^[1-9]\d*$` | `always` | | `BRANCH_IDENTIFIER` | `^[1-9]\d*$` | `conditional` | ```json Local theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "NPL", "currency": "NPR", "account_holder": { "type": "INDIVIDUAL", "first_name": "Michael", "last_name": "Connor", "email": "michael.oconnor@example.com", "phone": "+9779801234567" }, "bank_account": { "bank_name": "Nabil Bank Limited", "number": "00123456789", "scheme": "LOCAL", "type": "CHECKING" }, "bank_address": { "street_line_1": "Durbarmarg", "city": "Kathmandu", "state": "NP-2", "postcode": "44600", "country": "NPL" }, "account_holder_address": { "street_line_1": "Thamel", "city": "Kathmandu", "state": "NP-2", "postcode": "44600", "country": "NPL" }, "receiver_meta_data": { "nationality": "NPL", "transaction_purpose_id": 7, "occupation_id": 15, "relationship": "FAMILY_MEMBER", "relationship_remarks": "Family & Friends" }, "bank_routing": [ { "scheme": "BANK_IDENTIFIER", "number": "1768" } ], "developer_fee": { "fixed": 1.25, "percentage": 0.45 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": false } } ``` **Allowed currencies:** `PKR` **Bank account** | Field | Value | | :----------- | :----------------- | | Schemes | `LOCAL` | | Number regex | `^PK[0-9A-Z]{22}$` | **Bank routing** | Scheme | Regex | Required when | | :------------------ | :----------- | :------------ | | `BANK_IDENTIFIER` | `^[1-9]\d*$` | `always` | | `BRANCH_IDENTIFIER` | `^[1-9]\d*$` | `conditional` | ```json Local theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "PAK", "currency": "PKR", "account_holder": { "type": "INDIVIDUAL", "first_name": "Michael", "last_name": "OConnor", "email": "michael.oconnor@example.com", "phone": "+923001234567" }, "bank_account": { "bank_name": "Habib Bank Limited", "number": "PK36HABB1234567890123456", "scheme": "LOCAL", "type": "CHECKING" }, "bank_address": { "street_line_1": "Habib Bank Plaza", "city": "Karachi", "state": "PK-SD", "postcode": "74400", "country": "PAK" }, "account_holder_address": { "street_line_1": "42 Clifton Road", "city": "Karachi", "state": "PK-SD", "postcode": "74400", "country": "PAK" }, "receiver_meta_data": { "nationality": "PAK", "transaction_purpose_id": 2, "transaction_purpose_remarks": "Send to Family & Friends", "occupation_id": 504, "occupation_remarks": "Software quality assurance analyst and tester", "relationship": "FAMILY_MEMBER", "relationship_remarks": "Family & Friends" }, "bank_routing": [ { "scheme": "BANK_IDENTIFIER", "number": 1778 } ], "developer_fee": { "fixed": 1.25, "percentage": 0.45 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": true } } ``` **Allowed currencies:** `PHP` **Bank account** | Field | Value | | :----------- | :-------------- | | Schemes | `LOCAL` | | Number regex | `^[0-9]{8,16}$` | **Bank routing** | Scheme | Regex | Required when | | :------------------ | :----------- | :------------ | | `BANK_IDENTIFIER` | `^[1-9]\d*$` | `always` | | `BRANCH_IDENTIFIER` | `^[1-9]\d*$` | `conditional` | ```json Local theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "PHL", "currency": "PHP", "account_holder": { "type": "INDIVIDUAL", "first_name": "Michael", "last_name": "OConnor", "email": "michael.oconnor@example.com", "phone": "+639171234567" }, "bank_account": { "bank_name": "Bank of the Philippine Islands", "number": "1234567890", "scheme": "LOCAL", "type": "SAVINGS" }, "bank_address": { "street_line_1": "BPI Buendia Branch", "city": "Makati City", "state": "PH-03", "postcode": "1200", "country": "PHL" }, "account_holder_address": { "street_line_1": "42 Ayala Avenue", "city": "Makati City", "state": "PH-03", "postcode": "1200", "country": "PHL" }, "receiver_meta_data": { "nationality": "PHL", "transaction_purpose_id": 3, "transaction_purpose_remarks": "Send to Family & Friends", "occupation_id": 500, "occupation_remarks": "Software quality assurance analyst and tester", "relationship": "FAMILY_MEMBER", "relationship_remarks": "Family & Friends" }, "bank_routing": [ { "scheme": "BANK_IDENTIFIER", "number": 1770 } ], "developer_fee": { "fixed": 1.25, "percentage": 0.45 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": false } } ``` **Allowed currencies:** `SGD`, `USD` **Bank account** | Field | Value | | :----------- | :--------------- | | Schemes | `LOCAL`, `SWIFT` | | Number regex | `^[0-9]{7,11}$` | **Bank routing** | Scheme | Regex | Required when | | :------------------ | :-------------------------------------------- | :------------ | | `SWIFT` | `^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$` | `swift` | | `BANK_IDENTIFIER` | `^[1-9]\d*$` | `always` | | `BRANCH_IDENTIFIER` | `^[1-9]\d*$` | `conditional` | ```json Local theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "SGP", "currency": "SGD", "account_holder": { "type": "INDIVIDUAL", "first_name": "Michael", "last_name": "Connor", "email": "michael.oconnor@example.com", "phone": "+6591234567" }, "bank_account": { "bank_name": "DBS Bank", "number": "1234567890", "scheme": "LOCAL", "type": "SAVINGS" }, "bank_address": { "street_line_1": "12 Marina Boulevard", "city": "Singapore", "state": "SG-02", "postcode": "018982", "country": "SGP" }, "account_holder_address": { "street_line_1": "5 Shenton Way", "city": "Singapore", "state": "SG-02", "postcode": "068808", "country": "SGP" }, "receiver_meta_data": { "nationality": "SGP", "transaction_purpose_id": 1, "transaction_purpose_remarks": "Send to Family & Friends", "occupation_id": 504, "occupation_remarks": "Software quality assurance analyst and tester", "relationship": "FAMILY_MEMBER", "relationship_remarks": "Family & Friends" }, "bank_routing": [ { "scheme": "BANK_IDENTIFIER", "number": 1782 } ], "developer_fee": { "fixed": 1.25, "percentage": 0.45 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": true } } ``` ```json SWIFT theme={null} { "customer_id": "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9", "counter_party": "FIRST_PARTY", "country": "SGP", "currency": "USD", "account_holder": { "type": "INDIVIDUAL", "first_name": "Michael", "last_name": "Connor", "email": "michael.oconnor@example.com", "phone": "+6591234567" }, "bank_account": { "bank_name": "DBS Bank", "number": "1234567890", "scheme": "SWIFT", "type": "SAVINGS" }, "bank_address": { "street_line_1": "12 Marina Boulevard", "city": "Singapore", "state": "SG-02", "postcode": "018982", "country": "SGP" }, "account_holder_address": { "street_line_1": "5 Shenton Way", "city": "Singapore", "state": "SG-02", "postcode": "068808", "country": "SGP" }, "receiver_meta_data": { "nationality": "SGP", "transaction_purpose_id": 1, "transaction_purpose_remarks": "Send to Family & Friends", "occupation_id": 504, "occupation_remarks": "Software quality assurance analyst and tester", "relationship": "FAMILY_MEMBER", "relationship_remarks": "Family & Friends" }, "bank_routing": [ { "scheme": "SWIFT", "number": "DBSSSGSG" }, { "scheme": "BANK_IDENTIFIER", "number": 3499 } ], "developer_fee": { "fixed": 1.25, "percentage": 0.45 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": false } } ``` **Allowed currencies:** `USD` **Bank account** | Field | Value | | :------------ | :-------------------- | | Schemes | `LOCAL`, `SWIFT` | | Number regex | `^[0-9]{4,17}$` | | Account types | `CHECKING`, `SAVINGS` | **Bank routing** | Scheme | Regex | Required when | | :---------------- | :-------------------------------------------- | :------------ | | `ACH` | `^[0-9]{9}$` | `conditional` | | `FEDWIRE` | `^[0-9]{9}$` | `conditional` | | `SWIFT` | `^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$` | `swift` | | `BANK_IDENTIFIER` | `^[0-9]{1}$` | `always` | ```json Local (ACH) theme={null} { "customer_id": "8e08ca88-df60-41e7-b1ed-ff8f95480ff0", "counter_party": "FIRST_PARTY", "country": "USA", "currency": "USD", "account_holder": { "type": "BUSINESS", "business_name": "Rivertel", "email": "rivertel@rivertel.com", "phone": "+1041555526" }, "bank_account": { "bank_name": "Column NA - Brex", "number": "202063425871811", "scheme": "LOCAL", "type": "CHECKING" }, "bank_address": { "street_line_1": "7409 37th Ave Ste 403", "city": "Jackson Heights", "state": "US-CA", "postcode": "11372", "country": "USA" }, "account_holder_address": { "street_line_1": "7409 37th Ave Ste 403", "city": "Jackson Heights", "state": "US-CA", "postcode": "11372", "country": "USA" }, "receiver_meta_data": { "nationality": "USA", "transaction_purpose_id": 15, "transaction_purpose_remarks": "Business payment", "relationship": "FAMILY_MEMBER", "relationship_remarks": "Corporate beneficiary" }, "bank_routing": [ { "scheme": "ACH", "number": "121145349" }, { "scheme": "BANK_IDENTIFIER", "number": "1" } ], "developer_fee": { "fixed": null, "percentage": 0.65 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x838c562c55c4e515417ea15b852ffa2bded9b990", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": false } } ``` ```json SWIFT theme={null} { "customer_id": "{{customer_id}}", "counter_party": "FIRST_PARTY", "country": "USA", "currency": "USD", "account_holder": { "type": "BUSINESS", "business_name": "Meridian Cargo Solutions LLC", "email": "accounts@meridiancargosolutions.com", "phone": "+17189042371" }, "bank_account": { "bank_name": "Column NA - Brex", "number": "787212236285345", "scheme": "SWIFT", "type": "CHECKING" }, "bank_address": { "street_line_1": "1 Letterman Drive A Suite A4-700", "city": "San Francisco", "state": "US-CA", "postcode": "94129", "country": "USA" }, "account_holder_address": { "street_line_1": "8437 170th St", "city": "Jamaica", "state": "US-NY", "postcode": "11432", "country": "USA" }, "receiver_meta_data": { "nationality": "USA", "transaction_purpose_id": 14, "transaction_purpose_remarks": "International trade payment for logistics and freight services", "relationship": "FRIEND", "relationship_remarks": "Corporate beneficiary" }, "bank_routing": [ { "scheme": "ACH", "number": "121145349" }, { "scheme": "SWIFT", "number": "CLNOUS66BRX" }, { "scheme": "BANK_IDENTIFIER", "number": 3498 } ], "developer_fee": { "fixed": 0, "percentage": 0 }, "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" }, "refund_instruction": { "wallet_address": "0x4e9ce36e442e55ecd9025b9a6e0d88485d628a67", "currency": "USDC", "rail": "POLYGON" }, "settlement_config": { "auto_settlement": true } } ``` # Beneficiary Onboarding Guide Source: https://developer.fin.com/guides/beneficiaries/beneficiary-onboarding A beneficiary is a destination account (bank or e-wallet) that receives payouts on behalf of your customer. This guide walks you through onboarding a beneficiary using the latest API versions. *** ## Before You Start | Prerequisite | Detail | | ----------------- | --------------------------------------------------------- | | Bearer token | Issued via `POST /v1/oauth/token` | | Approved customer | Customer `customer_status` must be `APPROVED` | | Reference data | Country, bank, and branch identifiers (covered in Step 1) | *** ## Onboarding Flow Beneficiary Onboarding Flow 1 *** ## Step 1: Fetch Reference Data Three catalogue endpoints feed into beneficiary creation. These are V1-only and no newer versions exist. ### 1a. List Supported Countries ```text theme={null} GET /v1/beneficiaries/countries ``` Returns every payout-eligible country with supported methods and phone validation rules. ```json theme={null} { "data": [ { "id": 4, "code": "AUS", "name": "Australia", "currency_code": "AUD", "phone": { "code": "+61", "min_length": 9, "max_length": 9 }, "available_methods": ["BANK"], "flag": "https://flagcdn.com/au.svg" } ] } ``` **What you need from this:** `code` (ISO alpha-3) → maps to `country` and `currency` in the create call. `available_methods` tells you whether to build a bank form or e-wallet form. ### 1b. List Bank / E-Wallet Identifiers ```text theme={null} GET /v1/beneficiaries/methods?method=BANK&scheme=LOCAL¤cy=BDT&country_code=BGD ``` | Parameter | Required | Values | | -------------- | -------- | ----------------------------------- | | `method` | Yes | `BANK` or `E_WALLET` | | `scheme` | Yes | `LOCAL` or `SWIFT` | | `currency` | Yes | Destination currency (from Step 1a) | | `country_code` | Yes | ISO alpha-3 (from Step 1a) | ```json theme={null} { "data": [ { "id": 160, "name": "AB BANK", "method": "BANK", "has_branch": true }, { "id": 161, "name": "EASTERN BANK LTD.", "method": "BANK", "has_branch": true } ] } ``` **What you need from this:** `id` → used as `bank_routing[].number` with scheme `BANK_IDENTIFIER`. Check `has_branch`. If `true`, proceed to 1c. ### 1c. List Branch Identifiers (conditional) Only call this if `has_branch` is `true` from Step 1b. ```text theme={null} GET /v1/beneficiaries/methods/{method_id}/branches ``` ```json theme={null} { "data": [ { "id": 21513, "name": "BANANI", "branch_code": "020157391" } ] } ``` **What you need from this:** `id` → used as `bank_routing[].number` with scheme `BRANCH_IDENTIFIER`. *** ## Step 2: Create the Beneficiary ```text theme={null} POST /v3/beneficiaries ``` This is the primary creation endpoint. The payload has a fixed common section plus a polymorphic destination section (bank or e-wallet). ### Request Structure ```text theme={null} { // ── Common (always required) ────────────────── customer_id // uuid, must be APPROVED country // ISO alpha-3 currency // e.g. "BDT" counter_party // "FIRST_PARTY" or "THIRD_PARTY" account_holder // who gets paid (Individual or Business) account_holder_address // their address receiver_meta_data // purpose, relationship, nationality developer_fee // your markup deposit_instruction // how funds arrive (USDC / POLYGON) refund_instruction // where refunds go // ── Destination (one of) ────────────────────── bank_account + bank_routing + bank_address // Bank path e_wallet // E-Wallet path // ── Optional ────────────────────────────────── settlement_config // settlement method (true or false) } ``` ### Counter Party The `counter_party` field declares the relationship between the customer and the beneficiary receiving the payout. | Value | Meaning | Example | | ------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `FIRST_PARTY` | The customer is paying themselves. The beneficiary is the same entity as the customer. | A business withdrawing funds to its own bank account in another country | | `THIRD_PARTY` | The customer is paying someone else. The beneficiary is a different individual or entity. | A business paying a supplier, employee, or freelancer | This field is required in V3 and drives compliance screening. Third-party payouts may be subject to additional checks depending on the corridor. ### Account Holder The `account_holder` object is polymorphic based on `type`. **Individual:** ```json theme={null} { "type": "INDIVIDUAL", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+8801912244626" } ``` **Business:** ```json theme={null} { "type": "BUSINESS", "business_name": "Fin.com", "email": "contact@fin.com", "phone": "+8801912244626" } ``` ### Account Holder Address ```json theme={null} { "account_holder_address": { "street_line_1": "Road 11", "city": "Dhaka", "state": "BD-13", "postcode": "1212", "country": "BGD" } } ``` `state` uses ISO 3166-2 subdivision codes. Fetch valid values from `GET /v1/countries/{country_code}/subdivisions`. ### Receiver Metadata ```json theme={null} { "receiver_meta_data": { "transaction_purpose_id": 1, "transaction_purpose_remarks": null, "occupation_id": 5, "occupation_remarks": "Software Engineer", "relationship": "FAMILY_MEMBER", "relationship_remarks": "Family & Friends", "nationality": "AUS", "govt_id_number": "JG1121316A", "govt_id_issue_date": "2024-12-30", "govt_id_expire_date": "2027-12-30" } } ``` `transaction_purpose_id` → fetch from `GET /v1/transaction-purposes?type=INDIVIDUAL` or `?type=BUSINESS`. `occupation_id` → fetch from `GET /v1/occupations`. **Relationship values by account holder type:** Relationship enums varies by the sender and receiver types. Lern more about [sender and beneficiary relationship](/guides/beneficiaries/sender-and-receiver-relationships). ### Developer Fee Your markup on each payout through this beneficiary. ```json theme={null} { "developer_fee": { "fixed": 0.02, "percentage": 0.01 } } ``` Both components are applied: total fee = `fixed` + (`percentage` × payout amount). ### Deposit & Refund Instructions **Deposit instruction** defines how source funds arrive: ```json theme={null} { "deposit_instruction": { "currency": "USDC", "rail": "POLYGON" } } ``` **Refund instruction** defines where failed payouts are returned: ```json theme={null} { "refund_instruction": { "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F", "currency": "USDC", "rail": "POLYGON" } } ``` ### Settlement Config (optional) ```json theme={null} { "settlement_config": { "auto_settlement": true } } ``` Fin.com offers two settlement methods for payouts: **Automatic settlement** (`auto_settlement: true`): Fin.com initiates the fiat payout automatically when crypto is received in the beneficiary's liquidation address. **Programmatic settlement** (`auto_settlement: false`): You trigger the payout yourself using the [Settle a Transfer](https://developer.fin.com/api-reference/transactions/settle-a-transfer) endpoint or the [Execute Batch Transfer](https://developer.fin.com/api-reference/transactions/execute-batch-transfer) endpoint. #### Programmatic settlement with prefunded balance If you maintain prefunded balances with Fin.com, you must always trigger payouts programmatically. Use either the [Settle a Transfer](https://developer.fin.com/api-reference/transactions/settle-a-transfer) endpoint or the [Execute Batch Transfer](https://developer.fin.com/api-reference/transactions/execute-batch-transfer) endpoint. This applies regardless of the beneficiary's `auto_settlement` value (`true` or `false`). #### Programmatic settlement without a prefunded balance Set `auto_settlement` to `false` for the beneficiary. Fin.com will hold the crypto in the liquidation address until you trigger the payout using either the [Settle a Transfer](https://developer.fin.com/api-reference/transactions/settle-a-transfer) endpoint or the [Execute Batch Transfer](https://developer.fin.com/api-reference/transactions/execute-batch-transfer) endpoint. Learn more about [Funding & Balances](/guides/move-money/funding-your-balance). Pre-funding is required for all local currency payouts (e.g., BDT, INR, EUR). *** ### Destination: Bank Account Add three fields: `bank_account`, `bank_routing`, and `bank_address`. **bank\_account:** ```json theme={null} { "bank_account": { "bank_name": "Eastern Bank Ltd.", "number": "1234572211", "scheme": "LOCAL", "type": "SAVINGS" } } ``` | Field | Values | | -------- | --------------------- | | `scheme` | `LOCAL`, `SWIFT` | | `type` | `CHECKING`, `SAVINGS` | **bank\_routing:** An array. Most corridors need multiple routing entries. ```json theme={null} { "bank_routing": [ { "scheme": "SWIFT", "number": "CLNOUS66BRX" }, { "scheme": "BANK_IDENTIFIER", "number": 160 }, { "scheme": "BRANCH_IDENTIFIER", "number": 8 } ] } ``` | Scheme | When to use | | ------------------- | ------------------------------------------------------ | | `SWIFT` | International transfers (BIC/SWIFT code) | | `ACH` | US domestic ACH routing number | | `WIRE` | US domestic Fedwire routing number | | `IBAN` | Europe, Middle East (IBAN) | | `BSB` | Australia (Bank/State/Branch code) | | `IFSC` | India (IFSC code) | | `BANK_IDENTIFIER` | Use `id` from `/v1/beneficiaries/methods` | | `BRANCH_IDENTIFIER` | Use `id` from `/v1/beneficiaries/methods/:id/branches` | | `BANK_CODE` | Country-specific bank code | | `BRANCH_CODE` | Country-specific branch code | | `TRANSIT_NUMBER` | Canada transit number | **bank\_address:** ```json theme={null} { "bank_address": { "street_line_1": "Ground Floor Tower 1, Road no 11", "city": "Dhaka", "state": "BD-13", "postcode": "1212", "country": "BGD" } } ``` *** ### Destination: E-Wallet Replace the three bank fields with a single `e_wallet` object. ```json theme={null} { "e_wallet": { "scheme": "BKASH", "number": "+8801688502814" } } ``` `scheme` values come from the `name` field in the [List Bank Identfier](https://developer.fin.com/api-reference/beneficiaries/list-bank-identifiers) response. Select `E_WALLET` in query parameter to get the list of E-Wallets. *** ### Response ```json theme={null} { "data": { "beneficiary_id": "0254b433-e47d-412e-844b-b735c4bbba74" } } ``` Store this `beneficiary_id`. You'll need it for payouts, document uploads, and detail lookups. *** ### De-Duplication Rules Fin rejects duplicate beneficiaries with a `409 Conflict`. Uniqueness is determined by: | Destination | Fields checked | | ----------- | --------------------------------------------------------------------------------------------- | | Bank | `bank_account.scheme` + `bank_account.number` + `bank_routing.scheme` + `bank_routing.number` | | E-Wallet | `e_wallet.scheme` + `e_wallet.number` | The `409` response includes the existing `beneficiary_id` so you can reuse it instead of creating a new one. *** ### Country-Specific Validation | Country | Rule | | ------- | ---------------------------------------------------------------------------------- | | GBR | Bank account number must match `^[0-9]{4,9}$` for both `LOCAL` and `SWIFT` schemes | *** ## Step 3: Upload Documents (Optional) ```text theme={null} POST /v1/beneficiaries/{beneficiary_id}/documents ``` Multipart form-data. Use arbitrary field names. Allowed types: **PDF**, **JPG/JPEG**, **PNG**. ```json theme={null} { "data": { "files": [ { "invoice1": "/wKbvfH5E_Invoice.pdf" }, { "invoice2": "/XUOdWacK_Invoice.jpg" } ] } } ``` The returned URIs can be attached to transfer payouts later via the `attachments` array in [Create a Transfer](https://developer.fin.com/api-reference/transactions/create-a-transfer) payload. *** ## Step 4: Verify & Confirm ### Fetch Beneficiary Details ```text theme={null} GET /v3/beneficiaries/details?customer_id={id}&beneficiary_id={id} ``` Confirm the beneficiary was created correctly. The response includes the full record with all fields you submitted plus system-generated values. Key fields to verify: | Field | What to check | | ----------------------------------------- | ------------------------------------------------------------------ | | `active` | Boolean. Controlled by you via `PATCH /v1/beneficiaries`. | | `status` | Enum. Controlled by Fin's internal validation. | | `deposit_instruction.liquidation_address` | System-assigned. This is where you send USDC to trigger a payout. | | `bank_routing[].name` | System-resolved bank/branch names from the identifiers you passed. | ### Eligibility for Transactions A beneficiary can receive payouts **only** when both conditions are met: | Field | Required value | Controlled by | | -------- | -------------- | ----------------------------------- | | `active` | `true` | You (via `PATCH /v1/beneficiaries`) | | `status` | `ACTIVE` | Fin (system-managed) | These are independent fields. `active` is your on/off switch. `status` reflects Fin's validation outcome. **`status` values:** | Status | Meaning | | ------------ | -------------------------------------- | | `PROCESSING` | Beneficiary is being validated by Fin | | `ACTIVE` | Fin validation passed | | `INACTIVE` | Fin has deactivated the beneficiary | | `REJECTED` | Fin validation failed. Cannot be used. | A newly created beneficiary starts in `PROCESSING` with `active = true`. Listen for the `beneficiary.status` webhook to know when Fin transitions it to `ACTIVE` or `REJECTED`. *** ## Managing Beneficiaries ### List All Beneficiaries for a Customer ```text theme={null} GET /v1/customers/{customer_id}/beneficiaries ``` Returns all beneficiaries (active and inactive) for the given customer. Useful for building a beneficiary picker in your UI. ### Deactivate / Reactivate ```text theme={null} PATCH /v1/beneficiaries ``` ```json theme={null} { "beneficiary_id": "0254b433-e47d-412e-844b-b735c4bbba74", "active": false } ``` This endpoint toggles the `active` flag only. It does not change `status`. Setting `active: false` makes the beneficiary ineligible for payouts even if `status` is `ACTIVE`. Set `active: true` to re-enable. > **Note:** If Fin has set `status` to `REJECTED` or `INACTIVE`, the beneficiary cannot transact regardless of the `active` flag. For `REJECTED` beneficiaries, create a new one instead. *** ## Webhooks Subscribe to these events to track beneficiary lifecycle changes asynchronously. | Event | Fires when | | --------------------------------- | ----------------------------------------------- | | `beneficiary.created` | A new beneficiary is created | | `beneficiary.status` | A beneficiary's status changes | | `beneficiary.liquidation.deposit` | USDC hits the beneficiary's liquidation address | All webhook payloads include HMAC signatures for verification. Learn how to [verify webhook signatures](/guides/webhooks/verifying-webhooks). ### beneficiary.created Triggered when a new beneficiary is created in the system. Use this to confirm the beneficiary was registered and to capture the `beneficiary_id` on your end. ```json theme={null} { "event": { "id": "85804b3a-bf18-4d87-94f3-f7c45e66868e", "type": "beneficiary.created", "event_reference_id": "4d715f20-f704-45e0-af56-19ade318e852", "created_at": "2025-12-10T10:36:18.279837Z", "sandbox_mode": true }, "data": { "beneficiary_id": "4d715f20-f704-45e0-af56-19ade318e852", "customer_id": "efb54adf-b7f4-4716-80e3-806e11f20b7b", "type": "INDIVIDUAL", "active": true } } ``` At this point the beneficiary's `status` is `PROCESSING`. Wait for the `beneficiary.status` webhook before attempting any payouts. ### beneficiary.status Triggered when a beneficiary's status changes. This is the primary webhook you should listen for to know when a beneficiary is ready to receive payments. **Status values:** | Status | Meaning | | ------------ | ----------------------------------------------------- | | `PROCESSING` | Beneficiary creation is in progress | | `ACTIVE` | Beneficiary is verified and ready to receive payments | | `INACTIVE` | Beneficiary has been deactivated | | `REJECTED` | Beneficiary was rejected during verification | **Common transitions:** | From | To | What it means | | ------------ | ---------- | ---------------------------------------------- | | `PROCESSING` | `ACTIVE` | Verification passed. You can now send payouts. | | `PROCESSING` | `REJECTED` | Verification failed. Create a new beneficiary. | | `ACTIVE` | `INACTIVE` | Beneficiary deactivated by Fin. | ### beneficiary.liquidation.deposit Fires when any transfer hits the liquidation address. Useful for confirming funds arrival before payout execution. ```json theme={null} { "data": { "beneficiary_id": "5b4ea7ee-9d40-44b3-b857-dd5a890b9313", "customer_id": "bea5a6c1-0611-44c6-8c29-a6608e76916c", "amount": 3, "liquidation_address": "0xade8141fd1aef58dc0a5365a32a6cfe95904c08f", "txn_hash": "0x7808238a69057600f0c8e291ffbfde87a74fb81b32fc583231352147770e2751", "type": "INDIVIDUAL", "active": true } } ``` *** ## Error Reference | Status | Cause | Action | | ------ | ----------------------- | --------------------------------------------------------- | | `400` | Field validation failed | Check `errors` array for field-level details | | `401` | Invalid / expired token | Re-authenticate via `POST /v1/oauth/token` | | `409` | Duplicate beneficiary | Use the returned `beneficiary_id` from the error response | | `422` | Request format error | Check required fields and data types | *** ## V3 vs V2: Key Differences ### Create Beneficiary | Aspect | V2 (`POST /v2/beneficiaries`) | V3 (`POST /v3/beneficiaries`) | | -------------------------------------------- | --------------------------------- | --------------------------------------- | | `customer_id` format | Free string (e.g., `cust_123456`) | UUID (strict) | | `counter_party` | Not supported | Required. `FIRST_PARTY` / `THIRD_PARTY` | | `occupation_remarks` in `receiver_meta_data` | Required | Optional | | Response body | `{ data: { id, status } }` | `{ data: { beneficiary_id } }` | | Response code | `200` | `200` | ### Fetch Beneficiary Details | Aspect | V2 (`GET /v2/beneficiaries/details`) | V3 (`GET /v3/beneficiaries/details`) | | ----------------------- | ------------------------------------ | ------------------------------------------------- | | `status` field | Not present | `PROCESSING` / `ACTIVE` / `INACTIVE` / `REJECTED` | | `counter_party` field | Not present | Present | | `bank_routing[].number` | Not returned (only `name`) | Returned alongside `name` | **Recommendation:** Use V3 for all new integrations. V2 remains available but lacks counter-party tracking and the explicit status field. *** ## What's Next With the beneficiary onboarded, you can: * **Send USDC to the beneficiary liquidation address** * **Send a single payout** → `POST /v1/transactions/transfer-payout` , if the settlement\_config is false. * **Send batch payouts** → `POST /v1/batch/transactions/commit` , if the settlement\_config is false. * **Preview fees** → `POST /v1/fee-calculation` (pass `beneficiary_id` for developer-fee-aware calculations) * **Check FX rates** → `GET /v1/fx-rate?currency_code={code}` # Sender & Receiver Relationships Source: https://developer.fin.com/guides/beneficiaries/sender-and-receiver-relationships Understanding relationship types between senders and beneficiaries for compliant transactions When creating a beneficiary and initiating a transaction, it's essential to accurately specify the relationship between the sender and the receiver. This information is required for compliance, regulatory reporting, and fraud prevention purposes. The relationship between the beneficiary and sender is **mandatory** for processing transactions. Providing accurate relationship information helps ensure smooth transaction processing and compliance with international financial regulations. ## Relationship Categories Relationships are categorized based on whether the sender and receiver are **businesses** or **individuals**: * **B** = Business entity * **I** = Individual person This creates four distinct relationship categories: 1. **B2I** - Business to Individual 2. **B2B** - Business to Business 3. **I2B** - Individual to Business 4. **I2I** - Individual to Individual *** ## Business to Individual (B2I) When a business is sending funds to an individual, use one of the following relationship types: | Relationship | Description | | --------------- | ---------------------------------------------------------------------------------- | | `EMPLOYEE` | For payments to employees such as salaries, wages, bonuses, or reimbursements | | `FREELANCER` | For payments to independent contractors or freelance workers for services rendered | | `GIG_WORKER` | For payments to gig economy workers (e.g., delivery drivers, task-based workers) | | `AFFILIATE` | For payments to affiliate marketers or partners in your affiliate program | | `CUSTOMER` | For payments to customers such as refunds, rewards, or cashback | | `FAMILY_MEMBER` | When a business owner is sending funds to their family member | | `FRIEND` | When a business owner is sending funds to a friend | | `SELF` | When a business owner is transferring funds to their personal account | | `OTHER` | For any relationship not covered by the above categories | When using `OTHER` as the relationship value, you **must** provide the `relationship_remarks` field with a clear explanation of the actual relationship. Failing to do so may result in transaction delays or rejections. ### B2I Use Cases Use `EMPLOYEE` for regular payroll, bonuses, commissions, or expense reimbursements to full-time or part-time employees. Use `FREELANCER` for payments to independent contractors, consultants, or freelance professionals. Use `GIG_WORKER` for platform-based or task-specific workers. Use `CUSTOMER` for refunds, loyalty rewards, cash-back payments, or settlement of customer disputes. Use `AFFILIATE` for commission payments to affiliate partners, referral bonuses, or performance-based incentives. *** ## Business to Business (B2B) When a business is sending funds to another business entity, use one of the following relationship types: | Relationship | Description | | -------------------- | --------------------------------------------------------------------------------- | | `SUPPLIER` | For payments to suppliers for goods or raw materials | | `VENDOR` | For payments to vendors for products or inventory | | `SERVICE_PROVIDER` | For payments to service providers (e.g., SaaS, consulting, professional services) | | `MERCHANT` | For payments to merchants or retailers | | `CONTRACTOR` | For payments to business contractors or contracting firms | | `CUSTOMER` | For payments to business customers (e.g., refunds, rebates) | | `SUBSIDIARY` | For transfers to a subsidiary or controlled entity | | `PARENT_COMPANY` | For transfers to the parent company or holding company | | `AFFILIATE_BUSINESS` | For payments to affiliated businesses or sister companies | | `BANK_ACCOUNT` | For transfers to your own business bank account | | `OTHER` | For any business relationship not covered by the above categories | When using `OTHER` as the relationship value, you **must** provide the `relationship_remarks` field with a clear explanation of the actual relationship. Failing to do so may result in transaction delays or rejections. ### B2B Use Cases Use `SUPPLIER` for raw materials, `VENDOR` for finished goods or inventory, and `MERCHANT` for retail purchases. Use `SERVICE_PROVIDER` for payments to consultants, agencies, SaaS platforms, or any professional service organization. Use `SUBSIDIARY` for transfers to owned entities, `PARENT_COMPANY` for transfers to your holding company, and `AFFILIATE_BUSINESS` for sister companies or partnerships. Use `BANK_ACCOUNT` when moving funds between your own business accounts. *** ## Individual to Business (I2B) When an individual is sending funds to a business entity, use one of the following relationship types: | Relationship | Description | | ------------------ | ----------------------------------------------------------------------------------------- | | `MERCHANT` | For payments to merchants for purchases of goods or services | | `SERVICE_PROVIDER` | For payments to service providers (e.g., utilities, subscriptions, professional services) | | `SUPPLIER` | For payments to suppliers (typically for small business owners) | | `VENDOR` | For payments to vendors for products | | `BROKER` | For payments to brokers (e.g., insurance, real estate, investment) | | `EXCHANGE` | For payments to currency exchanges, crypto exchanges, or trading platforms | | `WALLET` | For payments to digital wallets or payment service providers | | `BANK_ACCOUNT` | For transfers to your own business bank account | | `OTHER` | For any relationship not covered by the above categories | When using `OTHER` as the relationship value, you **must** provide the `relationship_remarks` field with a clear explanation of the actual relationship. Failing to do so may result in transaction delays or rejections. ### I2B Use Cases Use `MERCHANT` for online or retail purchases, `SERVICE_PROVIDER` for subscription services, utilities, or professional services. Use `BROKER` for insurance premiums or investment services, `EXCHANGE` for currency or crypto trading, and `WALLET` for loading digital wallets. Individual business owners may use `SUPPLIER` or `VENDOR` when purchasing inventory or supplies, or `BANK_ACCOUNT` when funding their business account. *** ## Individual to Individual (I2I) When an individual is sending funds to another individual, use one of the following relationship types: | Relationship | Description | | --------------- | --------------------------------------------------------------------------- | | `FAMILY_MEMBER` | For transfers to family members (e.g., spouse, children, parents, siblings) | | `FRIEND` | For transfers to friends or acquaintances | | `SELF` | For transfers between your own accounts | | `OTHER` | For any relationship not covered by the above categories | When using `OTHER` as the relationship value, you **must** provide the `relationship_remarks` field with a clear explanation of the actual relationship. Failing to do so may result in transaction delays or rejections. ### I2I Use Cases Use `FAMILY_MEMBER` for remittances, allowances, gifts, or financial support to immediate or extended family members. Use `FRIEND` for splitting bills, repaying loans, or sending gifts to friends. Use `SELF` for transfers between your own accounts. *** ## The `OTHER` Relationship Type The `OTHER` relationship type serves as a catch-all for legitimate relationships that don't fit into the predefined categories. However, using `OTHER` requires additional documentation. ### Requirements When Using `OTHER` When you specify `OTHER` as the relationship type, you **must** include the `relationship_remarks` field in your API request. This field should contain: 1. **Clear description** - Explain the actual relationship in plain language 2. **Sufficient detail** - Provide enough context for compliance review 3. **Legitimate purpose** - Ensure the relationship and transaction purpose are lawful ### Examples of Valid `relationship_remarks` ```json Example 1: B2I Other theme={null} theme={null} { "relationship": "OTHER", "relationship_remarks": "Payment to independent brand ambassador for social media marketing campaign" } ``` ```json Example 2: B2B Other theme={null} theme={null} { "relationship": "OTHER", "relationship_remarks": "Payment to joint venture partner for shared project revenue distribution" } ``` ```json Example 3: I2B Other theme={null} theme={null} { "relationship": "OTHER", "relationship_remarks": "Payment to crowdfunding platform for investment in startup" } ``` ```json Example 4: I2I Other theme={null} theme={null} { "relationship": "OTHER", "relationship_remarks": "Payment to roommate for shared utility bills and rent contribution" } ``` **Best Practice**: Whenever possible, use the specific predefined relationship types rather than `OTHER`. This helps ensure faster transaction processing and reduces the likelihood of compliance holds. *** ## Quick Reference Table Here's a consolidated view of all relationship types across categories: | Category | Available Relationships | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **B2I** (Business to Individual) | `EMPLOYEE`, `FREELANCER`, `GIG_WORKER`, `AFFILIATE`, `CUSTOMER`, `FAMILY_MEMBER`, `FRIEND`, `SELF`, `OTHER` | | **B2B** (Business to Business) | `SUPPLIER`, `VENDOR`, `SERVICE_PROVIDER`, `MERCHANT`, `CONTRACTOR`, `CUSTOMER`, `SUBSIDIARY`, `PARENT_COMPANY`, `AFFILIATE_BUSINESS`, `BANK_ACCOUNT`, `OTHER` | | **I2B** (Individual to Business) | `MERCHANT`, `SERVICE_PROVIDER`, `SUPPLIER`, `VENDOR`, `BROKER`, `EXCHANGE`, `WALLET`, `BANK_ACCOUNT`, `OTHER` | | **I2I** (Individual to Individual) | `FAMILY_MEMBER`, `FRIEND`, `SELF`, `OTHER` | **Remember**: All ENUM values must be provided in **ALL CAPS** as shown in the table above. *** ## Need Help? If you're unsure which relationship type to use for your specific use case: 1. Review the descriptions and examples provided in this guide 2. Choose the most accurate predefined relationship type whenever possible 3. Use `OTHER` only when no predefined type accurately describes the relationship 4. When using `OTHER`, provide detailed and honest information in `relationship_remarks` 5. Contact our support team if you need clarification on specific scenarios For questions or support, please reach out to our team or consult your integration documentation. # Coverage & capabilities Source: https://developer.fin.com/guides/coverage/coverage-and-capabilities Fin.com supports payouts and payins (on-ramps and off-ramps) across several global corridors, and is moving fast to add new corridors and increase our reach. **As of August 2026, every flow has a stablecoin on one side.** There is no fiat to fiat corridor today. * A **payin** is always fiat to stablecoin. Your customer sends fiat to a virtual account and the value settles as stablecoin. * A **payout** is always stablecoin to fiat. You send stablecoin and the beneficiary receives local fiat or USD. For **non-USD payout currencies**, you are expected to pre-fund Fin.com in bulk rather than fund each transaction. See [Funding Your Balance](/guides/move-money/funding-your-balance). Virtual accounts are available in the following currencies and payment rails, subject to the risk classification of the customer's country of residence: * **USD (ACH, Fedwire & SWIFT)** - Individuals & Businesses * **MXN (SPEI) -** Individuals & Businesses ### Definitions **Prohibited:** Fin.com does not provide services to these countries, except in extraordinary circumstances such as pre-authorized regulatory or legal exemptions. **Restricted:** Fin.com does not provide services to these countries unless they are approved under specific, pre-authorized programs. Services are subject to enhanced oversight, heightened due diligence, and ongoing monitoring. **Enhanced Monitoring:** Fin.com may provide services to these countries, subject to enhanced oversight, heightened due diligence, and ongoing monitoring. **Not High Risk:** Fin.com provides services to these countries under standard compliance monitoring and control procedures. **Important notes:** 1. USD SWIFT pay-ins have no maximum limit. 2. Fin.com provides named USD virtual accounts only. We do not offer omnibus or pooled USD accounts. 3. MXN VAs and payouts require separate configuration. Please contact support if you want to enable these capabilities for your customers. 4. MXN VAs will be business-named accounts, not customer-named. | Country of Residence | Country Code | USD (\$) | MXN (₱) | | ----------------------------------------------------------------- | ------------ | ------------------- | ------------- | | Afghanistan | AFG | Prohibited | Prohibited | | Åland Islands | ALA | Not High Risk | Not High Risk | | Albania | ALB | Not High Risk | Not High Risk | | Algeria | DZA | Enhanced Monitoring | Prohibited | | American Samoa | ASM | Not High Risk | Not High Risk | | Andorra | AND | Not High Risk | Not High Risk | | Angola | AGO | Enhanced Monitoring | Prohibited | | Anguilla | AIA | Not High Risk | Not High Risk | | Antarctica | ATA | Not High Risk | Not High Risk | | Antigua and Barbuda | ATG | Not High Risk | Not High Risk | | Argentina | ARG | Not High Risk | Not High Risk | | Armenia | ARM | Enhanced Monitoring | Not High Risk | | Aruba | ABW | Not High Risk | Not High Risk | | Australia | AUS | Not High Risk | Not High Risk | | Austria | AUT | Not High Risk | Not High Risk | | Azerbaijan | AZE | Enhanced Monitoring | Not High Risk | | Bahamas | BHS | Enhanced Monitoring | Not High Risk | | Bahrain | BHR | Enhanced Monitoring | Not High Risk | | Bangladesh | BGD | Enhanced Monitoring | Not High Risk | | Barbados | BRB | Not High Risk | Not High Risk | | Belarus | BLR | Prohibited | Not High Risk | | Belgium | BEL | Not High Risk | Not High Risk | | Belize | BLZ | Not High Risk | Not High Risk | | Benin | BEN | Not High Risk | Not High Risk | | Bermuda | BMU | Enhanced Monitoring | Not High Risk | | Bhutan | BTN | Not High Risk | Not High Risk | | Bolivia | BOL | Enhanced Monitoring | Not High Risk | | Bonaire, Sint Eustatius and Saba | BES | Not High Risk | Not High Risk | | Bosnia and Herzegovina | BIH | Enhanced Monitoring | Not High Risk | | Botswana | BWA | Not High Risk | Not High Risk | | Bouvet Island | BVT | Not High Risk | Not High Risk | | Brazil | BRA | Not High Risk | Not High Risk | | British Indian Ocean Territory | IOT | Not High Risk | Not High Risk | | British Virgin Islands | VGB | Enhanced Monitoring | Not High Risk | | Brunei | BRN | Enhanced Monitoring | Not High Risk | | Bulgaria | BGR | Enhanced Monitoring | Prohibited | | Burkina Faso | BFA | Enhanced Monitoring | Prohibited | | Burundi | BDI | Not High Risk | Not High Risk | | Cabo Verde | CPV | Not High Risk | Not High Risk | | Cambodia | KHM | Enhanced Monitoring | Not High Risk | | Cameroon | CMR | Enhanced Monitoring | Prohibited | | Canada | CAN | Not High Risk | Not High Risk | | Cayman Islands | CYM | Not High Risk | Not High Risk | | Central African Republic | CAF | Prohibited | Not High Risk | | Chad | TCD | Not High Risk | Not High Risk | | Chile | CHL | Not High Risk | Not High Risk | | China | CHN | Not High Risk | Not High Risk | | Christmas Island | CXR | Not High Risk | Not High Risk | | Cocos (Keeling) Islands | CCK | Not High Risk | Not High Risk | | Colombia | COL | Not High Risk | Not High Risk | | Comoros | COM | Not High Risk | Not High Risk | | Cook Islands | COK | Enhanced Monitoring | Not High Risk | | Costa Rica | CRI | Enhanced Monitoring | Not High Risk | | Côte d'Ivoire | CIV | Enhanced Monitoring | Prohibited | | Croatia | HRV | Not High Risk | Prohibited | | Cuba | CUB | Prohibited | Not High Risk | | Curaçao | CUW | Not High Risk | Not High Risk | | Cyprus | CYP | Enhanced Monitoring | Not High Risk | | Czech Republic | CZE | Not High Risk | Not High Risk | | Democratic Republic of the Congo | COD | Prohibited | Prohibited | | Denmark | DNK | Not High Risk | Not High Risk | | Djibouti | DJI | Not High Risk | Not High Risk | | Dominica | DMA | Not High Risk | Not High Risk | | Dominican Republic | DOM | Not High Risk | Not High Risk | | Ecuador | ECU | Not High Risk | Not High Risk | | Egypt | EGY | Enhanced Monitoring | Not High Risk | | El Salvador | SLV | Enhanced Monitoring | Not High Risk | | Equatorial Guinea | GNQ | Not High Risk | Not High Risk | | Eritrea | ERI | Not High Risk | Not High Risk | | Estonia | EST | Not High Risk | Not High Risk | | Eswatini | SWZ | Not High Risk | Not High Risk | | Ethiopia | ETH | Not High Risk | Not High Risk | | Falkland Islands | FLK | Not High Risk | Not High Risk | | Faroe Islands | FRO | Not High Risk | Not High Risk | | Fiji | FJI | Not High Risk | Not High Risk | | Finland | FIN | Not High Risk | Not High Risk | | France | FRA | Not High Risk | Not High Risk | | French Guiana | GUF | Not High Risk | Not High Risk | | French Polynesia | PYF | Not High Risk | Not High Risk | | French Southern Territories | ATF | Not High Risk | Not High Risk | | Gabon | GAB | Not High Risk | Not High Risk | | Gambia | GMB | Not High Risk | Not High Risk | | Georgia | GEO | Not High Risk | Not High Risk | | Germany | DEU | Not High Risk | Not High Risk | | Ghana | GHA | Not High Risk | Not High Risk | | Gibraltar | GIB | Enhanced Monitoring | Not High Risk | | Greece | GRC | Enhanced Monitoring | Not High Risk | | Greenland | GRL | Not High Risk | Not High Risk | | Grenada | GRD | Not High Risk | Not High Risk | | Guadeloupe | GLP | Not High Risk | Not High Risk | | Guam | GUM | Not High Risk | Not High Risk | | Guatemala | GTM | Enhanced Monitoring | Not High Risk | | Guernsey | GGY | Enhanced Monitoring | Not High Risk | | Guinea | GIN | Not High Risk | Not High Risk | | Guinea-Bissau | GNB | Not High Risk | Not High Risk | | Guyana | GUY | Not High Risk | Not High Risk | | Haiti | HTI | Enhanced Monitoring | Prohibited | | Heard and McDonald Islands | HMD | Not High Risk | Not High Risk | | Holy See | VAT | Not High Risk | Not High Risk | | Honduras | HND | Enhanced Monitoring | Not High Risk | | Hong Kong | HKG | Not High Risk | Not High Risk | | Hungary | HUN | Not High Risk | Not High Risk | | Iceland | ISL | Not High Risk | Not High Risk | | India | IND | Not High Risk | Not High Risk | | Indonesia | IDN | Enhanced Monitoring | Not High Risk | | Iran | IRN | Prohibited | Prohibited | | Iraq | IRQ | Prohibited | Not High Risk | | Ireland | IRL | Not High Risk | Not High Risk | | Isle of Man | IMN | Enhanced Monitoring | Not High Risk | | Israel | ISR | Not High Risk | Not High Risk | | Italy | ITA | Not High Risk | Not High Risk | | Jamaica | JAM | Not High Risk | Not High Risk | | Japan | JPN | Not High Risk | Not High Risk | | Jersey | JEY | Enhanced Monitoring | Not High Risk | | Jordan | JOR | Enhanced Monitoring | Not High Risk | | Kazakhstan | KAZ | Enhanced Monitoring | Not High Risk | | Kenya | KEN | Enhanced Monitoring | Prohibited | | Kiribati | KIR | Not High Risk | Not High Risk | | Kosovo | XKX | Enhanced Monitoring | Not High Risk | | Kuwait | KWT | Enhanced Monitoring | Not High Risk | | Kyrgyzstan | KGZ | Not High Risk | Not High Risk | | Laos | LAO | Enhanced Monitoring | Not High Risk | | Latvia | LVA | Not High Risk | Not High Risk | | Lebanon | LBN | Enhanced Monitoring | Prohibited | | Lesotho | LSO | Not High Risk | Not High Risk | | Liberia | LBR | Prohibited | Not High Risk | | Libya | LBY | Prohibited | Not High Risk | | Liechtenstein | LIE | Enhanced Monitoring | Not High Risk | | Lithuania | LTU | Not High Risk | Not High Risk | | Luxembourg | LUX | Not High Risk | Not High Risk | | Macao | MAC | Not High Risk | Not High Risk | | Madagascar | MDG | Not High Risk | Not High Risk | | Malawi | MWI | Not High Risk | Not High Risk | | Malaysia | MYS | Enhanced Monitoring | Not High Risk | | Maldives | MDV | Not High Risk | Not High Risk | | Mali | MLI | Not High Risk | Prohibited | | Malta | MLT | Not High Risk | Not High Risk | | Marshall Islands | MHL | Not High Risk | Not High Risk | | Martinique | MTQ | Not High Risk | Not High Risk | | Mauritania | MRT | Not High Risk | Not High Risk | | Mauritius | MUS | Not High Risk | Not High Risk | | Mayotte | MYT | Not High Risk | Not High Risk | | Mexico | MEX | Not High Risk | Not High Risk | | Micronesia | FSM | Not High Risk | Not High Risk | | Moldova | MDA | Not High Risk | Not High Risk | | Monaco | MCO | Enhanced Monitoring | Prohibited | | Mongolia | MNG | Enhanced Monitoring | Not High Risk | | Montenegro | MNE | Not High Risk | Not High Risk | | Montserrat | MSR | Not High Risk | Not High Risk | | Morocco | MAR | Not High Risk | Not High Risk | | Mozambique | MOZ | Enhanced Monitoring | Prohibited | | Myanmar | MMR | Prohibited | Prohibited | | Namibia | NAM | Not High Risk | Prohibited | | Nauru | NRU | Not High Risk | Not High Risk | | Nepal | NPL | Enhanced Monitoring | Not High Risk | | Netherlands | NLD | Not High Risk | Not High Risk | | New Caledonia | NCL | Not High Risk | Not High Risk | | New Zealand | NZL | Not High Risk | Not High Risk | | Nicaragua | NIC | Enhanced Monitoring | Not High Risk | | Niger | NER | Not High Risk | Not High Risk | | Nigeria | NGA | Enhanced Monitoring | Prohibited | | Niue | NIU | Not High Risk | Not High Risk | | Norfolk Island | NFK | Not High Risk | Not High Risk | | North Korea | PRK | Prohibited | Prohibited | | North Macedonia | MKD | Not High Risk | Not High Risk | | Northern Mariana Islands | MNP | Restricted | Not High Risk | | Norway | NOR | Not High Risk | Not High Risk | | Oman | OMN | Enhanced Monitoring | Not High Risk | | Pakistan | PAK | Not High Risk | Not High Risk | | Palau | PLW | Not High Risk | Not High Risk | | Palestine - West Bank | PSE | Prohibited | Not High Risk | | Panama | PAN | Not High Risk | Not High Risk | | Papua New Guinea | PNG | Enhanced Monitoring | Not High Risk | | Paraguay | PRY | Enhanced Monitoring | Not High Risk | | Peru | PER | Not High Risk | Not High Risk | | Philippines | PHL | Enhanced Monitoring | Prohibited | | Pitcairn | PCN | Not High Risk | Not High Risk | | Poland | POL | Not High Risk | Not High Risk | | Portugal | PRT | Not High Risk | Not High Risk | | Puerto Rico | PRI | Not High Risk | Not High Risk | | Qatar | QAT | Not High Risk | Not High Risk | | Republic of the Congo | COG | Not High Risk | Not High Risk | | Réunion | REU | Not High Risk | Not High Risk | | Romania | ROU | Not High Risk | Not High Risk | | Russia | RUS | Prohibited | Prohibited | | Rwanda | RWA | Not High Risk | Not High Risk | | Saint Barthélemy | BLM | Not High Risk | Not High Risk | | Saint Helena | SHN | Not High Risk | Not High Risk | | Saint Kitts and Nevis | KNA | Not High Risk | Not High Risk | | Saint Lucia | LCA | Not High Risk | Not High Risk | | Saint Martin | MAF | Not High Risk | Not High Risk | | Saint Pierre & Miquelon | SPM | Not High Risk | Not High Risk | | Saint Vincent and the Grenadines | VCT | Not High Risk | Not High Risk | | Samoa | WSM | Not High Risk | Not High Risk | | San Marino | SMR | Not High Risk | Not High Risk | | São Tomé and Príncipe | STP | Not High Risk | Not High Risk | | Saudi Arabia | SAU | Prohibited | Not High Risk | | Senegal | SEN | Not High Risk | Not High Risk | | Serbia | SRB | Enhanced Monitoring | Not High Risk | | Seychelles | SYC | Not High Risk | Not High Risk | | Sierra Leone | SLE | Not High Risk | Not High Risk | | Singapore | SGP | Not High Risk | Not High Risk | | Sint Maarten | SXM | Not High Risk | Not High Risk | | Slovakia | SVK | Not High Risk | Not High Risk | | Slovenia | SVN | Not High Risk | Not High Risk | | Solomon Islands | SLB | Not High Risk | Not High Risk | | Somalia | SOM | Prohibited | Not High Risk | | South Africa | ZAF | Enhanced Monitoring | Prohibited | | South Georgia and South Sandwich Islands | SGS | Not High Risk | Not High Risk | | South Korea | KOR | Not High Risk | Not High Risk | | South Sudan | SSD | Enhanced Monitoring | Prohibited | | Spain | ESP | Not High Risk | Not High Risk | | Sri Lanka | LKA | Enhanced Monitoring | Not High Risk | | Sudan | SDN | Prohibited | Not High Risk | | Suriname | SUR | Not High Risk | Not High Risk | | Svalbard and Jan Mayen | SJM | Not High Risk | Not High Risk | | Sweden | SWE | Not High Risk | Not High Risk | | Switzerland | CHE | Not High Risk | Not High Risk | | Syria | SYR | Prohibited | Prohibited | | Taiwan | TWN | Not High Risk | Not High Risk | | Tajikistan | TJK | Not High Risk | Not High Risk | | Tanzania | TZA | Not High Risk | Prohibited | | Thailand | THA | Enhanced Monitoring | Not High Risk | | Timor-Leste | TLS | Not High Risk | Not High Risk | | Togo | TGO | Not High Risk | Not High Risk | | Tokelau | TKL | Not High Risk | Not High Risk | | Tonga | TON | Not High Risk | Not High Risk | | Trinidad and Tobago | TTO | Enhanced Monitoring | Not High Risk | | Tunisia | TUN | Enhanced Monitoring | Not High Risk | | Turkey | TUR | Not High Risk | Not High Risk | | Turkmenistan | TKM | Not High Risk | Not High Risk | | Turks and Caicos Islands | TCA | Not High Risk | Not High Risk | | Tuvalu | TUV | Not High Risk | Not High Risk | | Uganda | UGA | Enhanced Monitoring | Not High Risk | | Ukraine | UKR | Prohibited | Not High Risk | | Ukraine Regions (Crimea, Donetsk, Luhansk, Zaporizhzhia, Kherson) | N/A | Prohibited | Not High Risk | | United Arab Emirates | ARE | Not High Risk | Not High Risk | | United Kingdom | GBR | Not High Risk | Not High Risk | | United States | USA | Not supported | Not High Risk | | Uruguay | URY | Not High Risk | Not High Risk | | US Minor Outlying Islands | UMI | Restricted | Not High Risk | | US Virgin Islands | VIR | Not supported | Not High Risk | | Uzbekistan | UZB | Enhanced Monitoring | Not High Risk | | Vanuatu | VUT | Not High Risk | Not High Risk | | Venezuela | VEN | Prohibited | Prohibited | | Vietnam | VNM | Enhanced Monitoring | Prohibited | | Wallis and Futuna | WLF | Not High Risk | Not High Risk | | Western Sahara | ESH | Not High Risk | Not High Risk | | Yemen | YEM | Prohibited | Prohibited | | Zambia | ZMB | Not High Risk | Not High Risk | | Zimbabwe | ZWE | Prohibited | Not High Risk | Fin.com offers both local currency and USD SWIFT payout coverage across multiple countries/corridors. Refer to the table below for detailed availability. ### **Definitions:** **Yes:** These countries are available in production and can be configured for if not configured yet. **No:** These countries are not available in production. **On-Request:** These countries can be enabled in production upon request with an estimated transaction volume commitment. Fin.com partners with multiple banks to support different corridors. | Payout Country | Country Code | Payout Currency | Local Payout | USD SWIFT | Notes | | ---------------------------------------- | ------------ | --------------- | -------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | United States | USA | USD | Yes (Fedwire) | Yes | Limits: 10M/txn for Businesses | | Afghanistan | AFG | AFN | No | No | | | Åland Islands | ALA | EUR | No | Yes | | | Albania | ALB | ALL | No | Yes | | | Algeria | DZA | DZD | No | Yes | | | American Samoa | ASM | USD | No | Yes | | | Andorra | AND | EUR | No | Yes | | | Angola | AGO | AOA | No | Yes | | | Anguilla | AIA | XCD | No | Yes | | | Antarctica | ATA | USD | No | Yes | | | Antigua and Barbuda | ATG | XCD | No | Yes | | | Argentina | ARG | ARS | On-Request | Yes | Local payout: B2B, I2I; ARS 14,400 | | Armenia | ARM | AMD | No | Yes | | | Aruba | ABW | AWG | No | Yes | | | Australia | AUS | AUD | On-Request | Yes | Local payout: B2B, I2I; No limit | | Austria | AUT | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Azerbaijan | AZE | AZN | No | Yes | | | Bahamas | BHS | BSD | No | Yes | | | Bahrain | BHR | BHD | No | Yes | | | Bangladesh | BGD | BDT | Yes (Bank, Ewallet) | Yes | Local payout - Bank: B2I, I2I; No limit. Ewallet: B2I, I2I; BDT 250,000 | | Barbados | BRB | BBD | No | Yes | | | Belarus | BLR | BYN | No | No | | | Belgium | BEL | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Belize | BLZ | BZD | No | Yes | | | Benin | BEN | XOF | No | Yes | | | Bermuda | BMU | BMD | No | Yes | | | Bhutan | BTN | BTN | No | Yes | | | Bolivia | BOL | BOB | No | Yes | | | Bonaire, Sint Eustatius and Saba | BES | USD | No | Yes | | | Bosnia and Herzegovina | BIH | BAM | No | Yes | | | Botswana | BWA | BWP | No | Yes | | | Bouvet Island | BVT | NOK | No | Yes | | | Brazil | BRA | BRL | On-Request | Yes | Local payout: B2B, I2I; BRL 269,000 | | British Indian Ocean Territory | IOT | USD | No | Yes | | | British Virgin Islands | VGB | USD | No | Yes | | | Brunei Darussalam | BRN | BND | No | Yes | | | Bulgaria | BGR | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Burkina Faso | BFA | XOF | No | Yes | | | Burundi | BDI | BIF | No | Yes | | | Cabo Verde | CPV | CVE | No | Yes | | | Cambodia | KHM | KHR | No | Yes | | | Cameroon | CMR | XAF | No | Yes | | | Canada | CAN | CAD | On-Request | Yes | Local payout: B2B, I2I; No limit | | Cayman Islands | CYM | KYD | No | Yes | | | Central African Republic | CAF | XAF | No | No | | | Chad | TCD | XAF | No | Yes | | | Chile | CHL | CLP | On-Request | Yes | Local payout: B2B, I2I; USD 10,000 | | China | CHN | CNY | On-Request | Yes | Local payout: B2B, I2I; CNY 1,000,000 (same day/T+1); USD no limit | | Christmas Island | CXR | AUD | No | Yes | | | Cocos (Keeling) Islands | CCK | AUD | No | Yes | | | Colombia | COL | COP | On-Request | Yes | Local payout: B2B, I2I; USD 56,000 | | Comoros | COM | KMF | No | Yes | | | Congo (Republic) | COG | XAF | No | Yes | | | Cook Islands | COK | NZD | No | Yes | | | Costa Rica | CRI | CRC | No | Yes | | | Côte d'Ivoire | CIV | XOF | No | Yes | | | Croatia | HRV | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Cuba | CUB | CUP | No | No | | | Curacao | CUW | XCG | No | Yes | | | Cyprus | CYP | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Czechia | CZE | EUR | On-Request | Yes | Local payout: B2B, I2I; No limit | | Denmark | DNK | EUR | No | Yes | | | Djibouti | DJI | DJF | No | Yes | | | Dominica | DMA | XCD | No | Yes | | | Dominican Republic | DOM | DOP | No | Yes | | | DR Congo | COD | CDF | No | No | | | Ecuador | ECU | USD | No | Yes | | | Egypt | EGY | EGP | No | Yes | | | El Salvador | SLV | USD | No | Yes | | | Equatorial Guinea | GNQ | XAF | No | Yes | | | Eritrea | ERI | ERN | No | Yes | | | Estonia | EST | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Eswatini | SWZ | SZL | No | Yes | | | Ethiopia | ETH | ETB | No | Yes | | | Falkland Islands | FLK | FKP | No | Yes | | | Faroe Islands | FRO | DKK | No | Yes | | | Fiji | FJI | FJD | No | Yes | | | Finland | FIN | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | France | FRA | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | French Guiana | GUF | EUR | No | Yes | | | French Polynesia | PYF | XPF | No | Yes | | | French Southern Territories | ATF | EUR | No | Yes | | | Gabon | GAB | XAF | No | Yes | | | Gambia | GMB | GMD | No | Yes | | | Georgia | GEO | GEL | No | Yes | | | Germany | DEU | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Ghana | GHA | GHS | No | Yes | | | Gibraltar | GIB | GIP | No | Yes | | | Greece | GRC | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Greenland | GRL | DKK | No | Yes | | | Grenada | GRD | XCD | No | Yes | | | Guadeloupe | GLP | EUR | No | Yes | | | Guam | GUM | USD | No | Yes | | | Guatemala | GTM | GTQ | No | Yes | | | Guernsey | GGY | GBP | No | Yes | | | Guinea | GIN | GNF | No | Yes | | | Guinea-Bissau | GNB | XOF | No | Yes | | | Guyana | GUY | GYD | No | Yes | | | Haiti | HTI | HTG | No | Yes | | | Heard and McDonald Islands | HMD | AUD | No | Yes | | | Holy See | VAT | EUR | No | Yes | | | Honduras | HND | HNL | No | Yes | | | Hong Kong | HKG | HKD | No | Yes | | | Hungary | HUN | EUR | On-Request | Yes | Local payout: B2B, I2I; No limit | | Iceland | ISL | EUR | No | Yes | | | India | IND | INR | On-Request | Yes | Local payout: B2B, I2I; INR 1,500,000 | | Indonesia | IDN | IDR | On-Request | Yes | Local payout: B2B, I2I; IDR 100,000,000 | | Iran | IRN | IRR | No | No | | | Iraq | IRQ | IQD | No | No | | | Ireland | IRL | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Isle of Man | IMN | GBP | No | Yes | | | Israel | ISR | ILS | On-Request | Yes | Local payout: B2B, I2I; ILS 25,000 | | Italy | ITA | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Jamaica | JAM | JMD | No | Yes | | | Japan | JPN | JPY | On-Request | Yes | Local payout: B2B, I2I; JPY 1,000,000 | | Jersey | JEY | GBP | No | Yes | | | Jordan | JOR | JOD | No | Yes | | | Kazakhstan | KAZ | KZT | No | Yes | | | Kenya | KEN | KES | No | Yes | | | Kiribati | KIR | AUD | No | Yes | | | Kosovo | XKX | EUR | No | Yes | | | Kuwait | KWT | KWD | No | Yes | | | Kyrgyzstan | KGZ | KGS | No | Yes | | | Laos | LAO | LAK | No | Yes | | | Latvia | LVA | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Lebanon | LBN | LBP | No | Yes | | | Lesotho | LSO | LSL | No | Yes | | | Liberia | LBR | LRD | No | No | | | Libya | LBY | LYD | No | No | | | Liechtenstein | LIE | EUR | No | Yes | | | Lithuania | LTU | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Luxembourg | LUX | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Macao | MAC | MOP | No | Yes | | | Madagascar | MDG | MGA | No | Yes | | | Malawi | MWI | MWK | No | Yes | | | Malaysia | MYS | MYR | On-Request | Yes | Local payout: B2B, I2I; MYR 1,000,000 | | Maldives | MDV | MVR | No | Yes | | | Mali | MLI | XOF | No | Yes | | | Malta | MLT | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Marshall Islands | MHL | USD | No | Yes | | | Martinique | MTQ | EUR | No | Yes | | | Mauritania | MRT | MRU | No | Yes | | | Mauritius | MUS | MUR | No | Yes | | | Mayotte | MYT | EUR | No | Yes | | | Mexico | MEX | MXN | On-Request (SPEI) | Yes | | | Micronesia | FSM | USD | No | Yes | | | Moldova | MDA | MDL | No | Yes | | | Monaco | MCO | EUR | No | Yes | | | Mongolia | MNG | MNT | No | Yes | | | Montenegro | MNE | EUR | No | Yes | | | Montserrat | MSR | XCD | No | Yes | | | Morocco | MAR | MAD | No | Yes | | | Mozambique | MOZ | MZN | No | Yes | | | Myanmar | MMR | MMK | No | No | | | Namibia | NAM | NAD | No | Yes | | | Nauru | NRU | AUD | No | Yes | | | Nepal | NPL | NPR | On-Request | Yes | Local payout: B2B, I2I; No limit | | Netherlands | NLD | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | New Caledonia | NCL | XPF | No | Yes | | | New Zealand | NZL | NZD | No | Yes | | | Nicaragua | NIC | NIO | No | Yes | | | Niger | NER | XOF | No | Yes | | | Nigeria | NGA | NGN | No | Yes | | | Niue | NIU | NZD | No | Yes | | | Norfolk Island | NFK | AUD | No | Yes | | | North Korea | PRK | KPW | No | No | | | North Macedonia | MKD | MKD | No | Yes | | | Northern Mariana Islands | MNP | USD | No | Yes | | | Norway | NOR | EUR | No | Yes | | | Oman | OMN | OMR | No | Yes | | | Pakistan | PAK | PKR | Yes | Yes | Local payout: B2I, I2I; PKR 1,600,000 | | Palau | PLW | USD | No | Yes | | | Palestine | PSE | ILS | No | No | | | Panama | PAN | PAB | No | Yes | | | Papua New Guinea | PNG | PGK | No | Yes | | | Paraguay | PRY | PYG | No | Yes | | | Peru | PER | PEN | On-Request | Yes | Local payout: B2B, I2I; USD 100,000 | | Philippines | PHL | PHP | On-Request (Bank, Ewallet) | Yes | Local payout - Bank: B2B, I2I; PHP 1,000,000; USD 10,000 (higher via RFI). Ewallet: B2I, I2I; PHP 500,000 (GCash); PHP 50,000 (other wallets) | | Pitcairn | PCN | NZD | No | Yes | | | Poland | POL | EUR | On-Request | Yes | Local payout: B2B, I2I; PLN 99,999 (RTP); PLN 999,999 (ACH); PLN 1,000,000+ (RTGS) | | Portugal | PRT | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Puerto Rico | PRI | USD | No | Yes | | | Qatar | QAT | QAR | No | Yes | | | Réunion | REU | EUR | No | Yes | | | Romania | ROU | EUR | On-Request | Yes | Local payout: B2B, I2I; RON 439,000 | | Russia | RUS | RUB | No | No | | | Rwanda | RWA | RWF | No | Yes | | | Saint Barthélemy | BLM | EUR | No | Yes | | | Saint Helena | SHN | SHP | No | Yes | | | Saint Kitts and Nevis | KNA | XCD | No | Yes | | | Saint Lucia | LCA | XCD | No | Yes | | | Saint Martin | MAF | EUR | No | Yes | | | Saint Pierre & Miquelon | SPM | EUR | No | Yes | | | Saint Vincent and the Grenadines | VCT | XCD | No | Yes | | | Samoa | WSM | WST | No | Yes | | | San Marino | SMR | EUR | No | Yes | | | Sao Tome and Principe | STP | STN | No | Yes | | | Saudi Arabia | SAU | SAR | No | No | | | Senegal | SEN | XOF | No | Yes | | | Serbia | SRB | RSD | No | Yes | | | Seychelles | SYC | SCR | No | Yes | | | Sierra Leone | SLE | SLE | No | Yes | | | Singapore | SGP | SGD | On-Request | Yes | Local payout: B2B, I2I; SGD 200,000 | | Sint Maarten | SXM | XCG | No | Yes | | | Slovakia | SVK | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Slovenia | SVN | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Solomon Islands | SLB | SBD | No | Yes | | | Somalia | SOM | SOS | No | No | | | South Africa | ZAF | ZAR | No | Yes | | | South Georgia and South Sandwich Islands | SGS | GBP | No | Yes | | | South Korea | KOR | KRW | On-Request | Yes | Local payout: B2B, I2I; No limit | | South Sudan | SSD | SSP | No | Yes | | | Spain | ESP | EUR | On-Request | Yes | Local payout: B2B, I2I; EUR 100,000 (SEPA Instant); EUR 1,000,000 (SEPA CT) | | Sri Lanka | LKA | LKR | No | Yes | | | Sudan | SDN | SDG | No | No | | | Suriname | SUR | SRD | No | Yes | | | Svalbard and Jan Mayen | SJM | NOK | No | Yes | | | Sweden | SWE | EUR | No | Yes | | | Switzerland | CHE | EUR | On-Request | Yes | Local payout: B2B, I2I; No limit | | Syria | SYR | SYP | No | No | | | Taiwan | TWN | TWD | No | Yes | | | Tajikistan | TJK | TJS | No | Yes | | | Tanzania | TZA | TZS | No | Yes | | | Thailand | THA | THB | No | Yes | | | Timor-Leste | TLS | USD | No | Yes | | | Togo | TGO | XOF | No | Yes | | | Tokelau | TKL | NZD | No | Yes | | | Tonga | TON | TOP | No | Yes | | | Trinidad and Tobago | TTO | TTD | No | Yes | | | Tunisia | TUN | TND | No | Yes | | | Turkey | TUR | TRY | On-Request | Yes | Local payout: B2B, I2I; No limit | | Turkmenistan | TKM | TMT | No | Yes | | | Turks and Caicos Islands | TCA | USD | No | Yes | | | Tuvalu | TUV | AUD | No | Yes | | | Uganda | UGA | UGX | No | Yes | | | Ukraine | UKR | UAH | No | No | | | United Arab Emirates | ARE | AED | On-Request | Yes | Local payout: B2B, I2I; USD 10,000 | | United Kingdom (EURO) | GBR | EUR | On-Request | Yes | Local payout: B2B, I2I; GBP 1,000,000 (FPS); EUR 100,000 instant / 1,000,000 CT | | United Kingdom (GBP) | GBR | GBP | On-Request | Yes | Local payout: B2B, I2I; GBP 1,000,000 (FPS); EUR 100,000 instant / 1,000,000 CT | | Uruguay | URY | UYU | No | Yes | | | US Minor Outlying Islands | UMI | USD | No | Yes | | | US Virgin Islands | VIR | USD | No | Yes | | | Uzbekistan | UZB | UZS | No | Yes | | | Vanuatu | VUT | VUV | No | Yes | | | Venezuela | VEN | VES | No | No | | | Viet Nam | VNM | VND | No | Yes | | | Wallis and Futuna | WLF | XPF | No | Yes | | | Western Sahara | ESH | MAD | No | Yes | | | Yemen | YEM | YER | No | No | | | Zambia | ZMB | ZMW | No | Yes | | | Zimbabwe | ZWE | ZWG | No | No | | **Important notes:** 1. Fin.com does not support pay-in or pay-out features via physical cash. However, we enable pay-outs through mobile money and e-wallets in specific regions, such as Bangladesh and the Philippines, to ensure localized digital payouts. 2. USD SWIFT payouts have no maximum transaction limits. ## Banking Infrastructure and Partner Networks We use local banking and partner networks to provide the best pricing, reliability, and execution. # Supported rails and currencies Source: https://developer.fin.com/guides/coverage/supported-rails-and-currencies Stablecoin and blockchain network pairs, fiat rails and currencies, and the supported combinations for on-ramp (Payin) and off-ramp (Payout) transfers. Fin.com routes stablecoin transfers across multiple blockchain networks and settles fiat through a range of payment rails. A transfer is only valid when the token and network you specify form a supported pair, and when the rail you use supports that pair in the direction you need. ## Stablecoins by network | Stablecoins | Ethereum | Polygon | | :---------- | :---------- | :---------- | | **USDC** | ✅ | ✅ | | **USDT** | Coming soon | Coming soon | ## Fiat currencies and rails | Rail | Currency | Coverage | Payin | Payout | | :------ | :------- | :------------ | :---- | :---------- | | ACH | USD | US Domestic | ✅ | Coming soon | | Fedwire | USD | US Domestic | ✅ | ✅ | | SWIFT | USD | International | ✅ | ✅ | | SPEI | MXN | MX Domestic | ✅ | ✅ | | Local | BDT | BD Domestic | | ✅ | | Local | PKR | PK Domestic | | ✅ | ## Supported combinations ### Payin: fiat to crypto | Rail | Currency | USDC | USDT (Coming soon) | | :------ | :------- | :---------------- | :----------------- | | ACH | USD | Ethereum, Polygon | Ethereum, Polygon | | Fedwire | USD | Ethereum, Polygon | Ethereum, Polygon | | SWIFT | USD | Ethereum, Polygon | Ethereum, Polygon | | SPEI | MXN | Solana, Polygon | Polygon | ### Payout: crypto to fiat | Rail | Currency | USDC | USDT (Coming soon) | | :---------------- | :------- | :---------------- | :----------------- | | ACH (Coming soon) | USD | Ethereum, Polygon | Ethereum, Polygon | | Fedwire | USD | Ethereum, Polygon | Ethereum, Polygon | | SWIFT | USD | Ethereum, Polygon | Ethereum, Polygon | | SPEI | MXN | Solana, Polygon | Polygon | | Local | BDT | Ethereum, Polygon | Ethereum, Polygon | | Local | PKR | Ethereum, Polygon | Ethereum, Polygon | **Notes on the combination tables** * **Local**: Payouts only. Minimums and settlement times vary by destination country. * For the **Local payout** rails listed above, we route each transfer to the most efficient rail available. The rail varies based on the destination bank. ## Direction Every token and network pair in the network matrix supports both directions: * Fiat to crypto (Payin) * Crypto to fiat (Payout) Confirm the rail in the combination tables before building against a pair. ## Conversion rate Fin.com applies a fixed **1:1 conversion rate** for **USDC/USDT-to-USD** or **EURC-to-EUR** transactions. For all other assets, conversion rates are variable and subject to real-time market fluctuations. ## Requesting additional coverage For integration requirements involving tokens, networks, or rails not listed above, reach out to your account manager or contact our team in your dedicated Slack channel. # Definition of Statuses Source: https://developer.fin.com/guides/crypto-orchestration/definition-of-statuses | Status | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | PAY\_INIT | The order has been created | | PAY\_PROCESS | The customer has attempted to make the payment. | | PAY\_SUCCESS | Fin has received the `order_amount` and Fin has received it | | PAY\_FAILED | The customer attempted to pay but it failed | | PAY\_TIMEOUT | The order has expired and the customer has not paid | | SETTLEMENT\_INIT | Payment has been received and Fin has started the settlement process | | SETTLEMENT\_SUCCESS | Fin has successfully settled to the destination | | SETTLEMENT\_HOLD | Fin has put the transaction on a hold due to multiple reasons (read below) | | SETTLEMENT\_FAILED | Fin has failed after 3 retry attempts \[The likelihood of SETTLEMENT\_FAILED is negligible, except in the event of a technical issue] | ### Reasons why order status can be "`SETTLEMENT_HOLD`" 1. **Insufficient funds in developer rebalance wallet:** The order is on a `rebalance_fee` = `true` and the developers rebalance wallets with Fin doesn't have enough balance to rebalance that particular transaction. The moment the developer funds their rebalance wallet transaction will initiate again and eventually be processed (`SETTLEMENT_SUCCESS`) 2. **Rare scenario:** Fin doesn't have enough gas for the transaction in its gas tank. # ByBit Source: https://developer.fin.com/guides/crypto-orchestration/integration-types/bybit The ByBit integration allows a developer to enable a ByBit user to use their [ByBit Pay](https://www.bybit.com/en/bybitpay/) balance to deposit in their desired platform / wallet address. Check the use cases that it can serve [here](/guides/crypto-orchestration/introduction). The supported sources and destinations can be found below along with important integration information. Learn key terminologies for a better implementation ## Chains, rails, and constraints | **Supported Source Currency** | **Supported Source Rail** | **Supported Destination Currency** | **Supported Destination Rail** | **Quote Estimation** | **Minimum Order Limit** | **Maximum Order Limit** | **Estimated Settlement Time (once deposit received)** | **Settlement Configuration (**`settlment_via`**)** | Fee rebalancing capability (`rebalance_fee`) | | :---------------------------- | :------------------------ | :--------------------------------- | :----------------------------- | :------------------- | :---------------------- | :---------------------- | :---------------------------------------------------- | :------------------------------------------------- | ------------------------------------------------------ | | USDC | BYBIT | USDC | SOLANA | ✅ | 3 | Not applicable yet | \~ 3 mins | `ONE_TO_ONE` | `true` / `false` | | USDC | BYBIT | USDC | ETHEREUM | ✅ | 7 | Not applicable yet | \~ 3 mins | `ONE_TO_ONE` | `true` / `false` | | USDC | BYBIT | USDC | BASE | ✅ | 3 | Not applicable yet | \~ 3 mins | `ONE_TO_ONE` | `true` / `false` | | USDT | BYBIT | PYUSD | SOLANA | ✅ | 3 | Not applicable yet | \~ 3 mins | `MARKET_ORDER` | Has to be always `true` (in roadmap for full support) | For routes where "Fee rebalancing capability" & "Quote estimation" is limited. Fin can enable both upon request of the Developer or Fin will enable themselves if it is in the roadmap. Please send request in your dedicated communication group. ## ByBit Quote creation: The quote endpoint requires a few key action for different settlement configuration at the moment ```json highlight={11} focus={11} theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/transit/quote \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "order_amount": "100.00", "integration_type": "BYBIT", "settlement_config": { "settlement_via": "MARKET_ORDER", "rebalance_fee": true, "destination_details": { "wallet_address": "SOLANA_WALLET_ADDRESS", "currency": "USDC", "rail": "SOLANA" } } } ' ``` To get a quote using `settlement_via ` = `MARKET_ORDER` , `rebalance_fee` has to be `true` . We are in the processing of adding support for `false` as well. ## ByBit Order creation: The only required fields in different cases has been share below, more cases to be added as there are more use cases within ByBit that Fin supports. ```json theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/transit/payment \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "integration_type": "BYBIT", "order_info": { "payment_type": "E_COMMERCE", "merchant_trade_no": "841e4ba2-1234-5678-9abc-a2a45de7bd00", "order_amount": "100.00", "currency": "USDT", "currency_type": "crypto", "order_expire_time": 3600, "goods": [ { "shopping_name": "test good1", "mcc_code": "1520", "goods_name": "test1", "goods_detail": "First product" } ], "env": { "terminal_type": "APP", "device": "iPhone 15", "browser_version": "iOS 17.0 Safari", "ip": "192.168.0.1" }, }, "fin": { "settlement_config": { "settlement_via": "MARKET_ORDER", "destination_details": { "wallet_address": "Ox....", "currency": "PYUSD", "rail": "SOLANA" } } } } ``` ```json theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/transit/payment \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "integration_type": "BYBIT", "order_info": { "quote_id": "4081fa09-7761-42b6-8f66-24beae1a2ca5", "payment_type": "E_COMMERCE", "merchant_trade_no": "841e4ba2-1234-5678-9abc-a2a45de7bd00", "currency_type": "crypto", "goods": [ { "shopping_name": "test good1", "mcc_code": "1520", "goods_name": "test1", "goods_detail": "First product" } ], "env": { "terminal_type": "APP", "device": "iPhone 15", "browser_version": "iOS 17.0 Safari", "ip": "192.168.0.1" }, } } ``` If `quote_id` is provided then `order_amount` & `fin` object **cannot be provided**. Hence if the `quote_id` is not provided then `order_amount` & `fin` object is **mandatory.** ## Definitions of parameters: Parameters are ByBit specific, hence please find the definitions of those parameters in the APIs below in the table below. | Param name | Definition | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `merchant_trade_no` | UUID from the developer side for a particular order | | `order_expire_time` | (Optional) By default the order will be valid for 1 hour. A developer can put their custom time range. The minimum order expire time is 10 mins | | `goods` | In ByBit when something is being paid for it is attributed to a good. We need the goods information within this object | | `goods.mcc` | Universal Merchant Category Codes, can be found [here](https://www.iso.org/standard/79450.html) | | `goods.goods_name` | Name of the good that is being paid for | | `goods.goods_detail` | Detail of the good that is being paid for | | `env` | **Needs to be accurate**. Details about the customers environment, this requires information regarding the users device information | | `env.terminal_type` | `APP / WEB / WAP / MINIAPP` - where is the customer initiating the payment from | | `env.device` | Device name of the customer | | `env.browser_version` | Browser version of the customer where the web view is being loaded | | `env.ip` | Customers IP | ## Response Differences for ByBit | Integration Type | Response Field | | :--------------- | :----------------------- | | BYBIT | `data.provider_response` | # Kraken Source: https://developer.fin.com/guides/crypto-orchestration/integration-types/kraken The Kraken integration allows a developer to allow a [Krak](https://www.kraken.com/krak/payments) user to deposit funds from their [Krak](https://www.kraken.com/krak/payments) app to their desired destination wallet address. ## Chains, rails, and constraints | **Supported Source Currency** | **Supported Source Rail** | **Supported Destination Currency** | **Supported Destination Rail** | **Quote Estimation** | **Minimum Order Limit** | **Maximum Order Limit** | **Estimated Settlement Time (once deposit received)** | **Settlement Configuration (**`settlment_via`**)** | Fee rebalancing capability (`rebalance_fee`) | | :---------------------------- | :------------------------ | :--------------------------------- | :----------------------------- | :------------------- | :---------------------- | :---------------------- | :---------------------------------------------------- | :------------------------------------------------- | :------------------------------------------- | | ANY ASSET (Read below) | KRAKEN | PYUSD | SOLANA | ✅ | TBA | TBA | TBA | `ONE_TO_ONE` | `true` / `false` | ### Payment settlement with automatic asset conversion When you create a payment request, you specify the destination asset and amount you want to receive. The paying customer does not need to hold that exact asset in their account. If the customer's account contains a different asset, the payment provider automatically converts it at the point of payment and settles the exact amount you requested in your chosen destination asset. The conversion spread is borne by the customer, not by you. This means you always receive exactly what you asked for, regardless of what the customer holds. ### Example You create a payment request for **100 PYUSD**. | Step | What happens | | :--- | :------------------------------------------------------------------------------------------------------------------- | | 1 | Your system calls the Create Order API with `destination.currency:PYUSD` and `order_amount: 100`. | | 2 | The customer opens the payment link in their app. Their account holds **150 USDC** and **0.002 BTC**, with no PYUSD. | | 3 | The customer selects USDC as their funding source and confirms. | | 4 | The payment provider converts \~100 PYUSD worth of USDC → PYUSD internally, applying a conversion spread. | | 5 | You receive **100 USDC**. The customer's USDC balance is debited for the equivalent amount plus the spread. | ### What this means for your integration * You do not need to know or care what assets your customers hold. * Always request in your preferred settlement asset. The conversion layer sits entirely on the payment provider's side. * Conversion fees are the customer's responsibility and are shown to them before they confirm. Note: The customer can fund the payment from any supported asset in their account, including fiat currencies, stablecoins, and cryptocurrencies. The full list of supported assets depends on the payment provider's availability in the customer's region. ## Kraken Quote creation For Kraken the quote creation body should look like this ```json highlight={6,13-16} focus={6,13-16} theme={null} curl --request GET \ --url https://sandbox.api.fin.com/v1/transit/quote \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "order_amount": "100.00", "integration_type": "KRAKEN", "settlement_config": { "settlement_via": "ONE_TO_ONE", "rebalance_fee": false, "destination_details": { "wallet_address": "....", "currency": "USDC", "rail": "SOLANA" } }, "developer_fee": { "fixed": "0.15", "percentage": "2.5" } } ' ``` ## Kraken Order creation ```json theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/transit/payment \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "integration_type": "KRAKEN", "order_info": { "merchant_trade_no": "841e4ba2-...-a2a45de7bd00", "order_amount": "100.00", "currency": "PYUSD", "rail": "SOLANA", "currency_type": "crypto" }, "fin": { "settlement_config": { "settlement_via": "ONE_TO_ONE", "destination_details": { "wallet_address": "....", "currency": "PYUSD", "rail": "SOLANA" }, "developer_fee": { "fixed": "0.15", "percentage": "2.5" } } } } ' ``` ```json theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/transit/payment \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "integration_type": "KRAKEN", "order_info": { "merchant_trade_no": "841e4ba2-...-a2a45de7bd00", "quote_id": "76e8bcc0-a6b4-41f7-...-76cfbe910fe3", "currency": "PYUSD", "rail": "SOLANA", "currency_type": "crypto" } } ' ``` `order_info.currency & rail` has to be the same as `destination_detail.currency & rail` this is done to keep the requests symmetric. As mentioned under the above "Payment settlement with automatic conversion" headline, the user is not required to hold the `order_info.currency` . This is just a Fin API convention. # OKX Source: https://developer.fin.com/guides/crypto-orchestration/integration-types/okx The OKX integration allows a developer to enable an OKX user to deposit funds from their OKX Pay balance to a destination wallet address. | **Supported Source Currency** | **Supported Source Rail** | **Supported Destination Currency** | **Supported Destination Rail** | **Quote Estimation** | **Minimum Order Limit** | **Maximum Order Limit** | **Estimated Settlement Time (once deposit received)** | **Settlement Configuration (**`settlement_via`**)** | Fee rebalancing capability (`rebalance_fee`) | | :---------------------------- | :------------------------ | :--------------------------------- | :----------------------------- | :------------------- | :---------------------- | :---------------------- | :---------------------------------------------------- | :-------------------------------------------------- | :------------------------------------------- | | ANY ASSET | OKX | USDC | SOLANA | ✅ | TBA | TBA | TBA | `ONE_TO_ONE` | `true` / `false` | Only USDC on SOLANA is supported in milestone-1. ## OKX Quote creation ```json theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/transit/quote \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "order_amount": "100.00", "integration_type": "OKX", "settlement_config": { "settlement_via": "ONE_TO_ONE", "rebalance_fee": false, "destination_details": { "wallet_address": "....", "currency": "USDC", "rail": "SOLANA" } }, "developer_fee": { "fixed": "0.15", "percentage": "2.5" } } ' ``` When `rebalance_fee` is `false`, the settled amount equals `order_amount` minus `total_fee` (gas fee + developer fee + payment fee + conversion fee + withdrawal fee). ## OKX Order creation ```json theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/transit/payment \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "integration_type": "OKX", "order_info": { "merchant_name": "MESH Shop", "merchant_trade_no": "841e4ba2-...-a2a45de7bd00", "order_amount": "100.00", "currency": "USDC", "rail": "SOLANA", "currency_type": "crypto", "redirection_url": "" }, "fin": { "settlement_config": { "settlement_via": "ONE_TO_ONE", "destination_details": { "wallet_address": "....", "currency": "USDC", "rail": "SOLANA" } }, "developer_fee": { "fixed": "0.15", "percentage": "2.5" } } } ' ``` ```json theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/transit/payment \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "integration_type": "OKX", "order_info": { "merchant_trade_no": "841e4ba2-...-a2a45de7bd00", "quote_id": "FIN_PROVIDED_QUOTE_ID", "currency": "USDC", "rail": "SOLANA", "currency_type": "crypto" } } ' ``` If `quote_id` is provided then `order_amount` and the `fin` object **cannot be provided**. If `quote_id` is not provided then `order_amount` and the `fin` object are **mandatory**. Providing both results in a `422` error. `order_info.currency` and `order_info.rail` must match `destination_details.currency` and `destination_details.rail`. This is a Fin API convention: the customer is not required to hold the `order_info.currency` in their OKX account. ## Response Differences for OKX | Integration Type | Response Field | | :--------------- | :----------------------- | | OKX | `data.provider_response` | The `provider_response` object contains: | Field | Description | | :-------------- | :----------------------------------------------------- | | `pay_id` | OKX-generated payment ID | | `expire_time` | Unix timestamp when the payment link expires | | `create_time` | Unix timestamp when the order was created | | `checkout_link` | OKX QR-code deeplink for the payer to complete payment | # Pass through Source: https://developer.fin.com/guides/crypto-orchestration/integration-types/pass-through The pass-through use case is when a developer just want to allow their customers to deposit an asset from one source and receive in a destination wallet address. The developer also has the option to collect revenue within the flow as well. Check the use cases that it can serve [here](/guides/crypto-orchestration/introduction). ## Chains, rails, and constraints | **Supported Source Currency** | **Supported Source Rail** | **Supported Destination Currency** | **Supported Destination Rail** | **Quote Estimation** | **Minimum Order Limit** | **Maximum Order Limit** | **Estimated Settlement Time (once deposit received)** | **Settlement Configuration (**`settlment_via`**)** | Rebalance Configuration (`rebalance_fee`) | Default Order Expiry Time | | :---------------------------- | :------------------------ | :--------------------------------- | :----------------------------- | :------------------- | :---------------------- | :---------------------- | :---------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------ | ------------------------- | | BTC | BITCOIN | BTC | BITCOIN | ✅ | 0.00005 | Not applicable yet | \~ 1 hour | `FEE_RETENTION` | Has to be always `false`(in roadmap for full support) | 1 hour | | USDT | TRON | USDT | TRON | ✅ | 2 | Not applicable yet | \~ 3-5 mins | `FEE_RETENTION` | Has to be always `false` (in roadmap for full support) | 1 hour | | ETH | ETHEREUM | ETH | ETHEREUM | ✅ | 0.001 | Not applicable yet | \~ 3-5 mins | `FEE_RETENTION` | Has to be always `false` (in roadmap for full support) | 1 hour | For routes where "Fee rebalancing capability" & "Quote estimation" is limited. Fin can enable both upon request of the Developer or Fin will enable themselves if it is in the roadmap. Please send request in your dedicated communication group. ## Pass through quote creation: ```text highlight={11} focus={11} theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/transit/quote \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "order_amount": "100.00", "integration_type": "PASS_THROUGH", "settlement_config": { "settlement_via": "FEE_RETENTION", "rebalance_fee": false, "destination_details": { "wallet_address": "SOLANA_WALLET_ADDRESS", "currency": "ETH", "rail": "ETHEREUM" } }, "developer_fee": { "fixed": "0.5", "percentage": "1" } } ' ``` For `PASS_THROUGH`, `rebalance_fee` has to be **always** `false` . ## Pass through order creation: ```json theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/transit/payment \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "integration_type": "PASS_THROUGH", "order_info": { "external_customer_id": "dcfed3f9-46ad-407b-87ff-3bac7c9c4c38", "merchant_trade_no": "841e4ba2-1234-5678-9abc-a2a45de7bd00", "order_amount": "100.00", "currency": "USDT", "rail": "SOLANA", "currency_type": "crypto" }, "fin": { "settlement_config": { "settlement_via": "MARKET_ORDER", "destination_details": { "wallet_address": "Ox....", "currency": "PYUSD", "rail": "SOLANA" } }, "developer_fee": { "fixed": "0.5", "percentage": "1" } } } ' ``` ```json theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/transit/payment \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "integration_type": "PASS_THROUGH", "order_info": { "external_customer_id": "1a11c804-8a9b-425d-96a8-c0682f52ff04", "quote_id": "5831ce86-cd88-4aba-b1fd-32dcf6e1a030", "merchant_trade_no": "841e4ba2-1234-5678-9abc-a2a45de7bd00", "currency": "USDT", "rail": "SOLANA", "currency_type": "crypto" } } ' ``` `order_expiry_time` for `PASS_THROUGH` is configurable per developer but it has to be requested by the developer to Fin and Fin will configure it in their backend. ## Important Considerations ### **About External Customer ID** The external customer ID is required for the pass-through use case. When the same external customer ID is passed in multiple requests, the same deposit wallet address is issued for that customer. For each external customer ID, one wallet address is issued per currency and rail combination. If a wallet address doesn't exist for an external customer ID, Fin creates a new one and issues it for the order and keeps using it for future orders. ### Limits to order creation For a particular customer there can be only 1 order per currency & rail combination. **For example:** Customer 1 has an open order of 0.5 BTC.BITCOIN, the customer cannot create another BTC.BITCOIN order until the existing order **expires** / **fails** / **processed** The default order expiry can be found above. ## Response Difference for Integration Type | Integration Type | Response Field | | :--------------- | :------------------------- | | PASS\_THROUGH | `data.deposit_instruction` | # Introduction - Fin Crypto Orchestration Source: https://developer.fin.com/guides/crypto-orchestration/introduction Fin provides payment infrastructure that lets platforms accept crypto deposits from multiple sources (exchange wallets, external wallets, and more) with built-in fee handling, token conversion, and multi-chain delivery. **This feature is only given upon Fin's compliance due diligence.** Three APIs power the entire flow: **Quote Estimation**, **Create Order**, and **Get Payment Details**. *** ## Payment Sources Fin currently supports three deposit sources, with more on the way. | Source | How It Works | Status | | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- | | **Bybit Pay** | User scans a QR code from their Bybit account. Funds are deducted and routed through Fin to the destination wallet. | Live | | **Kraken Pay** | User pays from their Kraken account. Same flow as Bybit Pay: funds route through Fin to the destination. | Integrating | | **External Wallet** | User sends from any wallet (exchange, dApp, hardware, or mobile). Fin receives the deposit, deducts a fee, and forwards to the destination wallet. | Live | | **Clipper** | Additional exchange payment source. | Coming Soon | *** ## Use Cases ### 1. Prediction Market Deposits A prediction market platform wants to let users deposit funds directly from their exchange accounts or external wallets. **What the user does:** * Opens the deposit flow on the platform * Selects Bybit Pay, Kraken Pay, or pays from an external wallet * Confirms the transaction **What happens under the hood:** 1. Platform calls the **Quote Estimation API** to get the conversion rate and fees for the deposit amount. 2. User confirms. Platform calls the **Create Order API** to initiate the transaction. 3. For exchange pay (Bybit/Kraken): user scans a QR code to authorize payment from their exchange account. For external wallets: user sends to a provided deposit address. 4. Fin receives the funds, deducts the platform fee, and credits the destination wallet. 5. Platform calls **Get Payment Details API** to confirm settlement and update the user's balance. **Supported tokens and chains:** * Pay with USDC → receive USDC on Solana, Base, or Ethereum * Pay with USDC → receive USDC on Polygon * Additional tokens and chains can be added based on platform requirements *** ### 2. Multi-Chain Wallet Top-Ups A platform wants to let users top up their account balance with a range of tokens across different chains. **What the user does:** * Initiates a deposit on the platform * Chooses their preferred token and payment method * Sends funds from any external wallet **What happens under the hood:** 1. **Quote Estimation API** returns the rate, fee, and expected delivery amount for the selected token pair. 2. **Create Order API** generates the deposit address or QR code. 3. User sends funds. Fin receives the deposit, handles any conversion, deducts the fee, and delivers to the destination wallet. 4. **Get Payment Details API** confirms the transaction status. **Supported tokens and chains:** * Bitcoin on the Bitcoin network * ETH on Ethereum * USDT on Tron * USDC on Solana, Base, Ethereum *** ### 3. Cross-Token Deposits A platform accepts a specific token (e.g., PYUSD), but users hold a different token (e.g., USDT on Bybit). **What the user does:** * Initiates a deposit * Pays with USDT from Bybit Pay * Receives PYUSD in their platform wallet **What happens under the hood:** 1. **Quote Estimation API** returns the USDT → PYUSD conversion rate and fees. 2. **Create Order API** initiates the order and generates the Bybit Pay QR code. 3. User scans the QR code. USDT is deducted from their Bybit Pay account. 4. Fin converts USDT to PYUSD, deducts the fee, and deposits PYUSD into the user's platform wallet. 5. **Get Payment Details API** confirms delivery. **Key point:** The user pays in whatever token they hold. The platform receives exactly the token it needs. Fin handles the conversion in between. *** ## API Overview | API | Purpose | | :---------------------- | :------------------------------------------------------------------------------------------------------------------- | | **Quote Estimation** | Returns the conversion rate, fees, and estimated delivery amount for a given token pair and amount. | | **Create Order** | Initiates the deposit transaction. Returns a QR code (for exchange pay) or a deposit address (for external wallets). | | **Get Payment Details** | Returns the current status of an order (pending, completed, or failed) along with transaction details. | *** ## Supported Assets | Token | Chains | | :---- | :------------------------------ | | USDC | Solana, Base, Ethereum, Polygon | | USDT | Tron | | ETH | Ethereum | | BTC | Bitcoin | | PYUSD | Solana | This is not an exhaustive list. Fin can add support for additional tokens and chains based on platform requirements. *** ## How Fees Work Fin deducts a platform-defined fee from each transaction before delivering funds to the destination wallet. The fee is surfaced to the user upfront via the Quote Estimation API, with no hidden costs. *** ## Integration Flow for receiving payments ```text theme={null} 1. User initiates deposit on your platform 2. Your backend calls Quote Estimation API → show rate + fees to user 3. User confirms → your backend calls Create Order API 4. User pays (QR scan or wallet transfer) 5. Fin receives funds → deducts fee → delivers to destination wallet 6. Your backend polls Get Payment Details API → updates user balance ``` # Legends & Concepts Source: https://developer.fin.com/guides/crypto-orchestration/legends-and-concepts Learn key concepts & terminologies to work with the Fin Crypto Orchestration Layer. | **Term** | **Definition** | | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | | **Currency** | Fin considers all forms of assets as a currency. USDC, USD, all are **currencies** to us | | **Rail** | Fin considers all forms of blockchains, fiat rails, and everything under the umbrella term `rail` | | **Integration type** | This indicates what kind of integration you want to use | | **Settlement via** | How you would like your funds to be settled to your end user | | **Rebalancing fees** | Subsidise the fees on behalf of your users by maintaining a rebalancing wallet address with Fin that will inject funds on each deposit | | **Developer fee** | Collection of fees on your users transactions | # Transit Payment Webhooks Source: https://developer.fin.com/guides/crypto-orchestration/transit-payment-webhooks Webhook payloads and statuses for transit payment events. ## Overview Fin sends `transit.payment.status` webhook events to notify you of payment and settlement status changes. All webhook types share the same event structure. ## Event Structure Every webhook includes an `event` object and a `data` object: ```text theme={null} { "event": { "id": "UUID", // unique for every event "type": "transit.payment.status", // always the same "event_reference_id": "payment_id", // payment_id as reference "created_at": "2025-10-10T15:40:56Z" // UTC }, "data": { ... } } ``` ## Payment Status Webhooks Triggered when the payment status changes. **Statuses:** `PAY_INIT` | `PAY_PROCESS` | `PAY_TIMEOUT` | `PAY_CANCEL` | `PAY_SUCCESS` | `PAY_FAILED` ```text theme={null} { "event": { "id": "UUID", "type": "transit.payment.status", "event_reference_id": "payment_id", "created_at": "2025-10-10T15:40:56Z" }, "data": { "payment_id": "FIN_PROVIDED_UUID", "integration_type": "PASS_THROUGH", "status": "PAY_SUCCESS", "create_time": 1740748353, "quote_id": "FIN_PROVIDED_UUID", "payment_info": { "trx_hash": "", "pay_id": "...", "merchant_trade_no": "841e4ba2-...-a2a45de7bd00", "amount": "100", "status": "PAY_SUCCESS", "currency": "USDC", "rail": "SOLANA", "currency_type": "...", "expire_time": 1740751953, "payment_time": 1740748353 } } } ``` > **Note:** > > * `payment_info.trx_hash` is null or empty until `PAY_SUCCESS` > * `payment_info.pay_id` is null or empty for `integration_type: PASS_THROUGH` > * `payment_info.payment_time` is `0` until `PAY_SUCCESS` ## Settlement Status Webhooks Triggered when the settlement status changes, after a successful payment. **Statuses:** `SETTLEMENT_INIT` | `SETTLEMENT_SUCCESS` | `SETTLEMENT_HOLD` | `SETTLEMENT_FAILED` ```text theme={null} { "event": { "id": "UUID", "type": "transit.payment.status", "event_reference_id": "payment_id", "created_at": "2025-10-10T15:40:56Z" }, "data": { "payment_id": "FIN_PROVIDED_UUID", "integration_type": "PASS_THROUGH", "status": "SETTLEMENT_INIT", "create_time": 1740748353, "quote_id": "FIN_PROVIDED_UUID", "payment_info": { "trx_hash": "", "pay_id": "...", "merchant_trade_no": "841e4ba2-...-a2a45de7bd00", "amount": "100", "status": "PAY_SUCCESS", "currency": "BTC", "rail": "BITCOIN", "currency_type": "crypto", "expire_time": 1740751953, "payment_time": 1740748353 }, "settlement_info": { "settlement_via": "FEE_RETENTION", "wallet_address": "....", "currency": "BTC", "rail": "BITCOIN", "amount": "100", "trx_hash": "0x580...", "settle_time": 1740748353, "status": "SETTLEMENT_INIT", "retry_attempts": 0 } } } ``` > **Note:** > > * `settlement_info` is null until `PAY_SUCCESS` > * `settlement_info.settle_time` is `0` until `SETTLEMENT_SUCCESS` > * `data.payment_info.trx_hash` is the on-chain deposit hash > * `data.settlement_info.trx_hash` is the on-chain settlement transaction hash ## Status Flow ```text theme={null} PAY_INIT → PAY_PROCESS → PAY_SUCCESS → SETTLEMENT_INIT → SETTLEMENT_SUCCESS ↘ PAY_TIMEOUT ↘ SETTLEMENT_HOLD ↘ PAY_CANCEL ↘ SETTLEMENT_FAILED ↘ PAY_FAILED ``` # Business Industry Codes Source: https://developer.fin.com/guides/customers-and-compliance/business-industry-codes | **NAICS Code** | **Industry Description** | | :------------- | :------------------------------------------------------------------------------------------------------------------- | | 111110 | Soybean Farming | | 111120 | Oilseed Except Soybean Farming | | 111130 | Dry Pea And Bean Farming | | 111140 | Wheat Farming | | 111150 | Corn Farming | | 111160 | Rice Farming | | 111191 | Oilseed And Grain Combination Farming | | 111199 | All Other Grain Farming | | 111211 | Potato Farming | | 111219 | Other Vegetable Except Potato And Melon Farming | | 111310 | Orange Groves | | 111320 | Citrus Except Orange Groves | | 111331 | Apple Orchards | | 111332 | Grape Vineyards | | 111333 | Strawberry Farming | | 111334 | Berry Except Strawberry Farming | | 111335 | Tree Nut Farming | | 111336 | Fruit And Tree Nut Combination Farming | | 111339 | Other Noncitrus Fruit Farming | | 111411 | Mushroom Production | | 111419 | Other Food Crops Grown Under Cover | | 111421 | Nursery And Tree Production | | 111422 | Floriculture Production | | 111910 | Tobacco Farming | | 111920 | Cotton Farming | | 111930 | Sugarcane Farming | | 111940 | Hay Farming | | 111991 | Sugar Beet Farming | | 111992 | Peanut Farming | | 111998 | All Other Miscellaneous Crop Farming | | 112111 | Beef Cattle Ranching And Farming | | 112112 | Cattle Feedlots | | 112120 | Dairy Cattle And Milk Production | | 112210 | Hog And Pig Farming | | 112310 | Chicken Egg Production | | 112320 | Broilers And Other Meat Type Chicken Production | | 112330 | Turkey Production | | 112340 | Poultry Hatcheries | | 112390 | Other Poultry Production | | 112410 | Sheep Farming | | 112420 | Goat Farming | | 112511 | Finfish Farming And Fish Hatcheries | | 112512 | Shellfish Farming | | 112519 | Other Aquaculture | | 112910 | Apiculture | | 112920 | Horses And Other Equine Production | | 112930 | Fur Bearing Animal And Rabbit Production | | 112990 | All Other Animal Production | | 113110 | Timber Tract Operations | | 113210 | Forest Nurseries And Gathering Of Forest Products | | 113310 | Logging | | 114111 | Finfish Fishing | | 114112 | Shellfish Fishing | | 114119 | Other Marine Fishing | | 114210 | Hunting And Trapping | | 115111 | Cotton Ginning | | 115112 | Soil Preparation Planting And Cultivating | | 115113 | Crop Harvesting Primarily By Machine | | 115114 | Postharvest Crop Activities Except Cotton Ginning | | 115115 | Farm Labor Contractors And Crew Leaders | | 115116 | Farm Management Services | | 115210 | Support Activities For Animal Production | | 115310 | Support Activities For Forestry | | 211120 | Crude Petroleum Extraction | | 211130 | Natural Gas Extraction | | 212114 | Surface Coal Mining | | 212115 | Underground Coal Mining | | 212210 | Iron Ore Mining | | 212220 | Gold Ore And Silver Ore Mining | | 212230 | Copper Nickel Lead And Zinc Mining | | 212290 | Other Metal Ore Mining | | 212311 | Dimension Stone Mining And Quarrying | | 212312 | Crushed And Broken Limestone Mining And Quarrying | | 212313 | Crushed And Broken Granite Mining And Quarrying | | 212319 | Other Crushed And Broken Stone Mining And Quarrying | | 212321 | Construction Sand And Gravel Mining | | 212322 | Industrial Sand Mining | | 212323 | Kaolin Clay And Ceramic And Refractory Minerals Mining | | 212390 | Other Nonmetallic Mineral Mining And Quarrying | | 213111 | Drilling Oil And Gas Wells | | 213112 | Support Activities For Oil And Gas Operations | | 213113 | Support Activities For Coal Mining | | 213114 | Support Activities For Metal Mining | | 213115 | Support Activities For Nonmetallic Minerals Except Fuels Mining | | 221111 | Hydroelectric Power Generation | | 221112 | Fossil Fuel Electric Power Generation | | 221113 | Nuclear Electric Power Generation | | 221114 | Solar Electric Power Generation | | 221115 | Wind Electric Power Generation | | 221116 | Geothermal Electric Power Generation | | 221117 | Biomass Electric Power Generation | | 221118 | Other Electric Power Generation | | 221121 | Electric Bulk Power Transmission And Control | | 221122 | Electric Power Distribution | | 221210 | Natural Gas Distribution | | 221310 | Water Supply And Irrigation Systems | | 221320 | Sewage Treatment Facilities | | 221330 | Steam And Air Conditioning Supply | | 236115 | New Single Family Housing Construction Except For Sale Builders | | 236116 | New Multifamily Housing Construction Except For Sale Builders | | 236117 | New Housing For Sale Builders | | 236118 | Residential Remodelers | | 236210 | Industrial Building Construction | | 236220 | Commercial And Institutional Building Construction | | 237110 | Water And Sewer Line And Related Structures Construction | | 237120 | Oil And Gas Pipeline And Related Structures Construction | | 237130 | Power And Communication Line And Related Structures Construction | | 237210 | Land Subdivision | | 237310 | Highway Street And Bridge Construction | | 237990 | Other Heavy And Civil Engineering Construction | | 238110 | Poured Concrete Foundation And Structure Contractors | | 238111 | Residential Poured Concrete Foundation And Structure Contractors | | 238112 | Non Residential Poured Concrete Foundation And Structure Contractors | | 238121 | Residential Structural Steel And Precast Concrete Contractors | | 238122 | Non Residential Structural Steel And Precast Concrete Contractors | | 238131 | Residential Framing Contractors | | 238132 | Non Residential Framing Contractors | | 238140 | Masonry Contractors | | 238141 | Residential Masonry Contractors | | 238142 | Non Residential Masonry Contractors | | 238151 | Residential Glass And Glazing Contractors | | 238152 | Non Residential Glass And Glazing Contractors | | 238160 | Roofing Contractors | | 238161 | Residential Roofing Contractors | | 238162 | Non Residential Roofing Contractors | | 238171 | Residential Siding Contractors | | 238172 | Non Residential Siding Contractors | | 238191 | Residential Other Foundation Structure And Building Exterior Contractors | | 238192 | Non Residential Other Foundation Structure And Building Exterior Contractors | | 238210 | Electrical Contractors And Other Wiring Installation Contractors | | 238211 | Residential Electrical Contractors And Other Wiring Installation Contractors | | 238212 | Non Residential Electrical Contractors And Other Wiring Installation Contractors | | 238220 | Plumbing Heating And Air Conditioning Contractors | | 238221 | Residential Plumbing Heating And Air Conditioning Contractors | | 238222 | Non Residential Plumbing Heating And Air Conditioning Contractors | | 238291 | Residential Other Building Equipment Contractors | | 238292 | Non Residential Other Building Equipment Contractors | | 238311 | Residential Drywall And Insulation Contractors | | 238312 | Non Residential Drywall And Insulation Contractors | | 238321 | Residential Painting And Wall Covering Contractors | | 238322 | Non Residential Painting And Wall Covering Contractors | | 238331 | Residential Flooring Contractors | | 238332 | Non Residential Flooring Contractors | | 238341 | Residential Tile And Terrazzo Contractors | | 238342 | Non Residential Tile And Terrazzo Contractors | | 238350 | Finish Carpentry Contractors | | 238351 | Residential Finish Carpentry Contractors | | 238352 | Non Residential Finish Carpentry Contractors | | 238391 | Residential Other Building Finishing Contractors | | 238392 | Non Residential Other Building Finishing Contractors | | 238911 | Residential Site Preparation Contractors | | 238912 | Non Residential Site Preparation Contractors | | 238990 | All Other Specialty Trade Contractors | | 238991 | Residential All Other Specialty Trade Contractors | | 238992 | Non Residential All Other Specialty Trade Contractors | | 311111 | Dog And Cat Food Manufacturing | | 311119 | Other Animal Food Manufacturing | | 311211 | Flour Milling | | 311212 | Rice Milling | | 311213 | Malt Manufacturing | | 311221 | Wet Corn Milling And Starch Manufacturing | | 311224 | Soybean And Other Oilseed Processing | | 311225 | Fats And Oils Refining And Blending | | 311230 | Breakfast Cereal Manufacturing | | 311313 | Beet Sugar Manufacturing | | 311314 | Cane Sugar Manufacturing | | 311340 | Nonchocolate Confectionery Manufacturing | | 311351 | Chocolate And Confectionery Manufacturing From Cacao Beans | | 311352 | Confectionery Manufacturing From Purchased Chocolate | | 311411 | Frozen Fruit Juice And Vegetable Manufacturing | | 311412 | Frozen Specialty Food Manufacturing | | 311421 | Fruit And Vegetable Canning | | 311422 | Specialty Canning | | 311423 | Dried And Dehydrated Food Manufacturing | | 311511 | Fluid Milk Manufacturing | | 311512 | Creamery Butter Manufacturing | | 311513 | Cheese Manufacturing | | 311514 | Dry Condensed And Evaporated Dairy Product Manufacturing | | 311520 | Ice Cream And Frozen Dessert Manufacturing | | 311611 | Animal Except Poultry Slaughtering | | 311612 | Meat Processed From Carcasses | | 311613 | Rendering And Meat Byproduct Processing | | 311615 | Poultry Processing | | 311710 | Seafood Product Preparation And Packaging | | 311811 | Retail Bakeries | | 311812 | Commercial Bakeries | | 311813 | Frozen Cakes Pies And Other Pastries Manufacturing | | 311821 | Cookie And Cracker Manufacturing | | 311824 | Dry Pasta Dough And Flour Mixes Manufacturing From Purchased Flour | | 311830 | Tortilla Manufacturing | | 311911 | Roasted Nuts And Peanut Butter Manufacturing | | 311919 | Other Snack Food Manufacturing | | 311920 | Coffee And Tea Manufacturing | | 311930 | Flavoring Syrup And Concentrate Manufacturing | | 311941 | Mayonnaise Dressing And Other Prepared Sauce Manufacturing | | 311942 | Spice And Extract Manufacturing | | 311991 | Perishable Prepared Food Manufacturing | | 311999 | All Other Miscellaneous Food Manufacturing | | 312111 | Soft Drink Manufacturing | | 312112 | Bottled Water Manufacturing | | 312113 | Ice Manufacturing | | 312120 | Breweries | | 312130 | Wineries | | 312140 | Distilleries | | 312230 | Tobacco Manufacturing | | 313110 | Fiber Yarn And Thread Mills | | 313210 | Broadwoven Fabric Mills | | 313220 | Narrow Fabric Mills And Schiffli Machine Embroidery | | 313230 | Nonwoven Fabric Mills | | 313240 | Knit Fabric Mills | | 313310 | Textile And Fabric Finishing Mills | | 313320 | Fabric Coating Mills | | 314110 | Carpet And Rug Mills | | 314120 | Curtain And Linen Mills | | 314910 | Textile Bag And Canvas Mills | | 314994 | Rope Cordage Twine Tire Cord And Tire Fabric Mills | | 314999 | All Other Miscellaneous Textile Product Mills | | 315120 | Apparel Knitting Mills | | 315210 | Cut And Sew Apparel Contractors | | 315250 | Cut And Sew Apparel Manufacturing Except Contractors | | 315990 | Apparel Accessories And Other Apparel Manufacturing | | 316110 | Leather And Hide Tanning And Finishing | | 316210 | Footwear Manufacturing | | 316990 | Other Leather And Allied Product Manufacturing | | 321113 | Sawmills | | 321114 | Wood Preservation | | 321211 | Hardwood Veneer And Plywood Manufacturing | | 321212 | Softwood Veneer And Plywood Manufacturing | | 321215 | Engineered Wood Member Manufacturing | | 321219 | Reconstituted Wood Product Manufacturing | | 321911 | Wood Window And Door Manufacturing | | 321912 | Cut Stock Resawing Lumber And Planing | | 321918 | Other Millwork Including Flooring | | 321920 | Wood Container And Pallet Manufacturing | | 321991 | Manufactured Home Mobile Home Manufacturing | | 321992 | Prefabricated Wood Building Manufacturing | | 321999 | All Other Miscellaneous Wood Product Manufacturing | | 322110 | Pulp Mills | | 322120 | Paper Mills | | 322130 | Paperboard Mills | | 322211 | Corrugated And Solid Fiber Box Manufacturing | | 322212 | Folding Paperboard Box Manufacturing | | 322219 | Other Paperboard Container Manufacturing | | 322220 | Paper Bag And Coated And Treated Paper Manufacturing | | 322230 | Stationery Product Manufacturing | | 322291 | Sanitary Paper Product Manufacturing | | 322299 | All Other Converted Paper Product Manufacturing | | 323111 | Commercial Printing Except Screen And Books | | 323113 | Commercial Screen Printing | | 323117 | Books Printing | | 323120 | Support Activities For Printing | | 324110 | Petroleum Refineries | | 324121 | Asphalt Paving Mixture And Block Manufacturing | | 324122 | Asphalt Shingle And Coating Materials Manufacturing | | 324191 | Petroleum Lubricating Oil And Grease Manufacturing | | 324199 | All Other Petroleum And Coal Products Manufacturing | | 325110 | Petrochemical Manufacturing | | 325120 | Industrial Gas Manufacturing | | 325130 | Synthetic Dye And Pigment Manufacturing | | 325180 | Other Basic Inorganic Chemical Manufacturing | | 325193 | Ethyl Alcohol Manufacturing | | 325194 | Cyclic Crude Intermediate And Gum And Wood Chemical Manufacturing | | 325199 | All Other Basic Organic Chemical Manufacturing | | 325211 | Plastics Material And Resin Manufacturing | | 325212 | Synthetic Rubber Manufacturing | | 325220 | Artificial And Synthetic Fibers And Filaments Manufacturing | | 325311 | Nitrogenous Fertilizer Manufacturing | | 325312 | Phosphatic Fertilizer Manufacturing | | 325314 | Fertilizer Mixing Only Manufacturing | | 325315 | Compost Manufacturing | | 325320 | Pesticide And Other Agricultural Chemical Manufacturing | | 325411 | Medicinal And Botanical Manufacturing | | 325412 | Pharmaceutical Preparation Manufacturing | | 325413 | In Vitro Diagnostic Substance Manufacturing | | 325414 | Biological Product Except Diagnostic Manufacturing | | 325510 | Paint And Coating Manufacturing | | 325520 | Adhesive Manufacturing | | 325611 | Soap And Other Detergent Manufacturing | | 325612 | Polish And Other Sanitation Good Manufacturing | | 325613 | Surface Active Agent Manufacturing | | 325620 | Toilet Preparation Manufacturing | | 325910 | Printing Ink Manufacturing | | 325920 | Explosives Manufacturing | | 325991 | Custom Compounding Of Purchased Resins | | 325992 | Photographic Film Paper Plate Chemical And Copy Toner Manufacturing | | 325998 | All Other Miscellaneous Chemical Product And Preparation Manufacturing | | 326111 | Plastics Bag And Pouch Manufacturing | | 326112 | Plastics Packaging Film And Sheet Including Laminated Manufacturing | | 326113 | Unlaminated Plastics Film And Sheet Except Packaging Manufacturing | | 326121 | Unlaminated Plastics Profile Shape Manufacturing | | 326122 | Plastics Pipe And Pipe Fitting Manufacturing | | 326130 | Laminated Plastics Plate Sheet Except Packaging And Shape Manufacturing | | 326140 | Polystyrene Foam Product Manufacturing | | 326150 | Urethane And Other Foam Product Except Polystyrene Manufacturing | | 326160 | Plastics Bottle Manufacturing | | 326191 | Plastics Plumbing Fixture Manufacturing | | 326199 | All Other Plastics Product Manufacturing | | 326211 | Tire Manufacturing Except Retreading | | 326212 | Tire Retreading | | 326220 | Rubber And Plastics Hoses And Belting Manufacturing | | 326291 | Rubber Product Manufacturing For Mechanical Use | | 326299 | All Other Rubber Product Manufacturing | | 327110 | Pottery Ceramics And Plumbing Fixture Manufacturing | | 327120 | Clay Building Material And Refractories Manufacturing | | 327211 | Flat Glass Manufacturing | | 327212 | Other Pressed And Blown Glass And Glassware Manufacturing | | 327213 | Glass Container Manufacturing | | 327215 | Glass Product Manufacturing Made Of Purchased Glass | | 327310 | Cement Manufacturing | | 327320 | Ready Mix Concrete Manufacturing | | 327331 | Concrete Block And Brick Manufacturing | | 327332 | Concrete Pipe Manufacturing | | 327390 | Other Concrete Product Manufacturing | | 327410 | Lime Manufacturing | | 327420 | Gypsum Product Manufacturing | | 327910 | Abrasive Product Manufacturing | | 327991 | Cut Stone And Stone Product Manufacturing | | 327992 | Ground Or Treated Mineral And Earth Manufacturing | | 327993 | Mineral Wool Manufacturing | | 327999 | All Other Miscellaneous Nonmetallic Mineral Product Manufacturing | | 331110 | Iron And Steel Mills And Ferroalloy Manufacturing | | 331210 | Iron And Steel Pipe And Tube Manufacturing From Purchased Steel | | 331221 | Rolled Steel Shape Manufacturing | | 331222 | Steel Wire Drawing | | 331313 | Alumina Refining And Primary Aluminum Production | | 331314 | Secondary Smelting And Alloying Of Aluminum | | 331315 | Aluminum Sheet Plate And Foil Manufacturing | | 331318 | Other Aluminum Rolling Drawing And Extruding | | 331410 | Nonferrous Metal Except Aluminum Smelting And Refining | | 331420 | Copper Rolling Drawing Extruding And Alloying | | 331491 | Nonferrous Metal Except Copper And Aluminum Rolling Drawing And Extruding | | 331492 | Secondary Smelting Refining And Alloying Of Nonferrous Metal Except Copper And Aluminum | | 331511 | Iron Foundries | | 331512 | Steel Investment Foundries | | 331513 | Steel Foundries Except Investment | | 331523 | Nonferrous Metal Die Casting Foundries | | 331524 | Aluminum Foundries Except Die Casting | | 331529 | Other Nonferrous Metal Foundries Except Die Casting | | 332111 | Iron And Steel Forging | | 332112 | Nonferrous Forging | | 332114 | Custom Roll Forming | | 332117 | Powder Metallurgy Part Manufacturing | | 332119 | Metal Crown Closure And Other Metal Stamping Except Automotive | | 332215 | Metal Kitchen Cookware Utensil Cutlery And Flatware Except Precious Manufacturing | | 332216 | Saw Blade And Handtool Manufacturing | | 332311 | Prefabricated Metal Building And Component Manufacturing | | 332312 | Fabricated Structural Metal Manufacturing | | 332313 | Plate Work Manufacturing | | 332321 | Metal Window And Door Manufacturing | | 332322 | Sheet Metal Work Manufacturing | | 332323 | Ornamental And Architectural Metal Work Manufacturing | | 332410 | Power Boiler And Heat Exchanger Manufacturing | | 332420 | Metal Tank Heavy Gauge Manufacturing | | 332431 | Metal Can Manufacturing | | 332439 | Other Metal Container Manufacturing | | 332510 | Hardware Manufacturing | | 332613 | Spring Manufacturing | | 332618 | Other Fabricated Wire Product Manufacturing | | 332710 | Machine Shops | | 332721 | Precision Turned Product Manufacturing | | 332722 | Bolt Nut Screw Rivet And Washer Manufacturing | | 332811 | Metal Heat Treating | | 332812 | Metal Coating Engraving Except Jewelry And Silverware And Allied Services To Manufacturers | | 332813 | Electroplating Plating Polishing Anodizing And Coloring | | 332911 | Industrial Valve Manufacturing | | 332912 | Fluid Power Valve And Hose Fitting Manufacturing | | 332913 | Plumbing Fixture Fitting And Trim Manufacturing | | 332919 | Other Metal Valve And Pipe Fitting Manufacturing | | 332991 | Ball And Roller Bearing Manufacturing | | 332992 | Small Arms Ammunition Manufacturing | | 332993 | Ammunition Except Small Arms Manufacturing | | 332994 | Small Arms Ordnance And Ordnance Accessories Manufacturing | | 332996 | Fabricated Pipe And Pipe Fitting Manufacturing | | 332999 | All Other Miscellaneous Fabricated Metal Product Manufacturing | | 333111 | Farm Machinery And Equipment Manufacturing | | 333112 | Lawn And Garden Tractor And Home Lawn And Garden Equipment Manufacturing | | 333120 | Construction Machinery Manufacturing | | 333131 | Mining Machinery And Equipment Manufacturing | | 333132 | Oil And Gas Field Machinery And Equipment Manufacturing | | 333241 | Food Product Machinery Manufacturing | | 333242 | Semiconductor Machinery Manufacturing | | 333243 | Sawmill Woodworking And Paper Machinery Manufacturing | | 333248 | All Other Industrial Machinery Manufacturing | | 333310 | Commercial And Service Industry Machinery Manufacturing | | 333413 | Industrial And Commercial Fan And Blower And Air Purification Equipment Manufacturing | | 333414 | Heating Equipment Except Warm Air Furnaces Manufacturing | | 333415 | Air Conditioning And Warm Air Heating Equipment And Commercial And Industrial Refrigeration Equipment Manufacturing | | 333511 | Industrial Mold Manufacturing | | 333514 | Special Die And Tool Die Set Jig And Fixture Manufacturing | | 333515 | Cutting Tool And Machine Tool Accessory Manufacturing | | 333517 | Machine Tool Manufacturing | | 333519 | Rolling Mill And Other Metalworking Machinery Manufacturing | | 333611 | Turbine And Turbine Generator Set Units Manufacturing | | 333612 | Speed Changer Industrial High Speed Drive And Gear Manufacturing | | 333613 | Mechanical Power Transmission Equipment Manufacturing | | 333618 | Other Engine Equipment Manufacturing | | 333912 | Air And Gas Compressor Manufacturing | | 333914 | Measuring Dispensing And Other Pumping Equipment Manufacturing | | 333921 | Elevator And Moving Stairway Manufacturing | | 333922 | Conveyor And Conveying Equipment Manufacturing | | 333923 | Overhead Traveling Crane Hoist And Monorail System Manufacturing | | 333924 | Industrial Truck Tractor Trailer And Stacker Machinery Manufacturing | | 333991 | Power Driven Handtool Manufacturing | | 333992 | Welding And Soldering Equipment Manufacturing | | 333993 | Packaging Machinery Manufacturing | | 333994 | Industrial Process Furnace And Oven Manufacturing | | 333995 | Fluid Power Cylinder And Actuator Manufacturing | | 333996 | Fluid Power Pump And Motor Manufacturing | | 333998 | All Other Miscellaneous General Purpose Machinery Manufacturing | | 334111 | Electronic Computer Manufacturing | | 334112 | Computer Storage Device Manufacturing | | 334118 | Computer Terminal And Other Computer Peripheral Equipment Manufacturing | | 334210 | Telephone Apparatus Manufacturing | | 334220 | Radio And Television Broadcasting And Wireless Communications Equipment Manufacturing | | 334290 | Other Communications Equipment Manufacturing | | 334310 | Audio And Video Equipment Manufacturing | | 334412 | Bare Printed Circuit Board Manufacturing | | 334413 | Semiconductor And Related Device Manufacturing | | 334416 | Capacitor Resistor Coil Transformer And Other Inductor Manufacturing | | 334417 | Electronic Connector Manufacturing | | 334418 | Printed Circuit Assembly Electronic Assembly Manufacturing | | 334419 | Other Electronic Component Manufacturing | | 334510 | Electromedical And Electrotherapeutic Apparatus Manufacturing | | 334511 | Search Detection Navigation Guidance Aeronautical And Nautical System And Instrument Manufacturing | | 334512 | Automatic Environmental Control Manufacturing For Residential Commercial And Appliance Use | | 334513 | Instruments And Related Products Manufacturing For Measuring Displaying And Controlling Industrial Process Variables | | 334514 | Totalizing Fluid Meter And Counting Device Manufacturing | | 334515 | Instrument Manufacturing For Measuring And Testing Electricity And Electrical Signals | | 334516 | Analytical Laboratory Instrument Manufacturing | | 334517 | Irradiation Apparatus Manufacturing | | 334519 | Other Measuring And Controlling Device Manufacturing | | 334610 | Manufacturing And Reproducing Magnetic And Optical Media | | 335131 | Residential Electric Lighting Fixture Manufacturing | | 335132 | Commercial Industrial And Institutional Electric Lighting Fixture Manufacturing | | 335139 | Electric Lamp Bulb And Other Lighting Equipment Manufacturing | | 335210 | Small Electrical Appliance Manufacturing | | 335220 | Major Household Appliance Manufacturing | | 335311 | Power Distribution And Specialty Transformer Manufacturing | | 335312 | Motor And Generator Manufacturing | | 335313 | Switchgear And Switchboard Apparatus Manufacturing | | 335314 | Relay And Industrial Control Manufacturing | | 335910 | Battery Manufacturing | | 335921 | Fiber Optic Cable Manufacturing | | 335929 | Other Communication And Energy Wire Manufacturing | | 335931 | Current Carrying Wiring Device Manufacturing | | 335932 | Noncurrent Carrying Wiring Device Manufacturing | | 335991 | Carbon And Graphite Product Manufacturing | | 335999 | All Other Miscellaneous Electrical Equipment And Component Manufacturing | | 336110 | Automobile And Light Duty Motor Vehicle Manufacturing | | 336120 | Heavy Duty Truck Manufacturing | | 336211 | Motor Vehicle Body Manufacturing | | 336212 | Truck Trailer Manufacturing | | 336213 | Motor Home Manufacturing | | 336214 | Travel Trailer And Camper Manufacturing | | 336310 | Motor Vehicle Gasoline Engine And Engine Parts Manufacturing | | 336320 | Motor Vehicle Electrical And Electronic Equipment Manufacturing | | 336330 | Motor Vehicle Steering And Suspension Components Except Spring Manufacturing | | 336340 | Motor Vehicle Brake System Manufacturing | | 336350 | Motor Vehicle Transmission And Power Train Parts Manufacturing | | 336360 | Motor Vehicle Seating And Interior Trim Manufacturing | | 336370 | Motor Vehicle Metal Stamping | | 336390 | Other Motor Vehicle Parts Manufacturing | | 336411 | Aircraft Manufacturing | | 336412 | Aircraft Engine And Engine Parts Manufacturing | | 336413 | Other Aircraft Parts And Auxiliary Equipment Manufacturing | | 336414 | Guided Missile And Space Vehicle Manufacturing | | 336415 | Guided Missile And Space Vehicle Propulsion Unit And Propulsion Unit Parts Manufacturing | | 336419 | Other Guided Missile And Space Vehicle Parts And Auxiliary Equipment Manufacturing | | 336510 | Railroad Rolling Stock Manufacturing | | 336611 | Ship Building And Repairing | | 336612 | Boat Building | | 336991 | Motorcycle Bicycle And Parts Manufacturing | | 336992 | Military Armored Vehicle Tank And Tank Component Manufacturing | | 336999 | All Other Transportation Equipment Manufacturing | | 337110 | Wood Kitchen Cabinet And Countertop Manufacturing | | 337121 | Upholstered Household Furniture Manufacturing | | 337122 | Nonupholstered Wood Household Furniture Manufacturing | | 337126 | Household Furniture Except Wood And Upholstered Manufacturing | | 337127 | Institutional Furniture Manufacturing | | 337211 | Wood Office Furniture Manufacturing | | 337212 | Custom Architectural Woodwork And Millwork Manufacturing | | 337214 | Office Furniture Except Wood Manufacturing | | 337215 | Showcase Partition Shelving And Locker Manufacturing | | 337910 | Mattress Manufacturing | | 337920 | Blind And Shade Manufacturing | | 339112 | Surgical And Medical Instrument Manufacturing | | 339113 | Surgical Appliance And Supplies Manufacturing | | 339114 | Dental Equipment And Supplies Manufacturing | | 339115 | Ophthalmic Goods Manufacturing | | 339116 | Dental Laboratories | | 339910 | Jewelry And Silverware Manufacturing | | 339920 | Sporting And Athletic Goods Manufacturing | | 339930 | Doll Toy And Game Manufacturing | | 339940 | Office Supplies Except Paper Manufacturing | | 339950 | Sign Manufacturing | | 339991 | Gasket Packing And Sealing Device Manufacturing | | 339992 | Musical Instrument Manufacturing | | 339993 | Fastener Button Needle And Pin Manufacturing | | 339994 | Broom Brush And Mop Manufacturing | | 339995 | Burial Casket Manufacturing | | 339999 | All Other Miscellaneous Manufacturing | | 423110 | Automobile And Other Motor Vehicle Merchant Wholesalers | | 423120 | Motor Vehicle Supplies And New Parts Merchant Wholesalers | | 423130 | Tire And Tube Merchant Wholesalers | | 423140 | Motor Vehicle Parts Used Merchant Wholesalers | | 423210 | Furniture Merchant Wholesalers | | 423220 | Home Furnishing Merchant Wholesalers | | 423310 | Lumber Plywood Millwork And Wood Panel Merchant Wholesalers | | 423320 | Brick Stone And Related Construction Material Merchant Wholesalers | | 423330 | Roofing Siding And Insulation Material Merchant Wholesalers | | 423390 | Other Construction Material Merchant Wholesalers | | 423410 | Photographic Equipment And Supplies Merchant Wholesalers | | 423420 | Office Equipment Merchant Wholesalers | | 423430 | Computer And Computer Peripheral Equipment And Software Merchant Wholesalers | | 423440 | Other Commercial Equipment Merchant Wholesalers | | 423450 | Medical Dental And Hospital Equipment And Supplies Merchant Wholesalers | | 423460 | Ophthalmic Goods Merchant Wholesalers | | 423490 | Other Professional Equipment And Supplies Merchant Wholesalers | | 423510 | Metal Service Centers And Other Metal Merchant Wholesalers | | 423520 | Coal And Other Mineral And Ore Merchant Wholesalers | | 423610 | Electrical Apparatus And Equipment Wiring Supplies And Related Equipment Merchant Wholesalers | | 423620 | Household Appliances Electric Housewares And Consumer Electronics Merchant Wholesalers | | 423690 | Other Electronic Parts And Equipment Merchant Wholesalers | | 423710 | Hardware Merchant Wholesalers | | 423720 | Plumbing And Heating Equipment And Supplies Hydronics Merchant Wholesalers | | 423730 | Warm Air Heating And Air Conditioning Equipment And Supplies Merchant Wholesalers | | 423740 | Refrigeration Equipment And Supplies Merchant Wholesalers | | 423810 | Construction And Mining Except Oil Well Machinery And Equipment Merchant Wholesalers | | 423820 | Farm And Garden Machinery And Equipment Merchant Wholesalers | | 423830 | Industrial Machinery And Equipment Merchant Wholesalers | | 423840 | Industrial Supplies Merchant Wholesalers | | 423850 | Service Establishment Equipment And Supplies Merchant Wholesalers | | 423860 | Transportation Equipment And Supplies Except Motor Vehicle Merchant Wholesalers | | 423910 | Sporting And Recreational Goods And Supplies Merchant Wholesalers | | 423920 | Toy And Hobby Goods And Supplies Merchant Wholesalers | | 423930 | Recyclable Material Merchant Wholesalers | | 423940 | Jewelry Watch Precious Stone And Precious Metal Merchant Wholesalers | | 423990 | Other Miscellaneous Durable Goods Merchant Wholesalers | | 424110 | Printing And Writing Paper Merchant Wholesalers | | 424120 | Stationery And Office Supplies Merchant Wholesalers | | 424130 | Industrial And Personal Service Paper Merchant Wholesalers | | 424210 | Drugs And Druggists Sundries Merchant Wholesalers | | 424310 | Piece Goods Notions And Other Dry Goods Merchant Wholesalers | | 424340 | Footwear Merchant Wholesalers | | 424350 | Clothing And Clothing Accessories Merchant Wholesalers | | 424410 | General Line Grocery Merchant Wholesalers | | 424420 | Packaged Frozen Food Merchant Wholesalers | | 424430 | Dairy Product Except Dried Or Canned Merchant Wholesalers | | 424440 | Poultry And Poultry Product Merchant Wholesalers | | 424450 | Confectionery Merchant Wholesalers | | 424460 | Fish And Seafood Merchant Wholesalers | | 424470 | Meat And Meat Product Merchant Wholesalers | | 424480 | Fresh Fruit And Vegetable Merchant Wholesalers | | 424490 | Other Grocery And Related Products Merchant Wholesalers | | 424510 | Grain And Field Bean Merchant Wholesalers | | 424520 | Livestock Merchant Wholesalers | | 424590 | Other Farm Product Raw Material Merchant Wholesalers | | 424610 | Plastics Materials And Basic Forms And Shapes Merchant Wholesalers | | 424690 | Other Chemical And Allied Products Merchant Wholesalers | | 424710 | Petroleum Bulk Stations And Terminals | | 424720 | Petroleum And Petroleum Products Merchant Wholesalers Except Bulk Stations And Terminals | | 424810 | Beer And Ale Merchant Wholesalers | | 424820 | Wine And Distilled Alcoholic Beverage Merchant Wholesalers | | 424910 | Farm Supplies Merchant Wholesalers | | 424920 | Book Periodical And Newspaper Merchant Wholesalers | | 424930 | Flower Nursery Stock And Florists Supplies Merchant Wholesalers | | 424940 | Tobacco Product And Electronic Cigarette Merchant Wholesalers | | 424950 | Paint Varnish And Supplies Merchant Wholesalers | | 424990 | Other Miscellaneous Nondurable Goods Merchant Wholesalers | | 425120 | Wholesale Trade Agents And Brokers | | 441110 | New Car Dealers | | 441120 | Used Car Dealers | | 441210 | Recreational Vehicle Dealers | | 441222 | Boat Dealers | | 441227 | Motorcycle ATV And All Other Motor Vehicle Dealers | | 441330 | Automotive Parts And Accessories Retailers | | 441340 | Tire Dealers | | 444110 | Home Centers | | 444120 | Paint And Wallpaper Retailers | | 444140 | Hardware Retailers | | 444180 | Other Building Material Dealers | | 444230 | Outdoor Power Equipment Retailers | | 444240 | Nursery Garden Center And Farm Supply Retailers | | 445110 | Supermarkets And Other Grocery Retailers Except Convenience Retailers | | 445131 | Convenience Retailers | | 445132 | Vending Machine Operators | | 445230 | Fruit And Vegetable Retailers | | 445240 | Meat Retailers | | 445250 | Fish And Seafood Retailers | | 445291 | Baked Goods Retailers | | 445292 | Confectionery And Nut Retailers | | 445298 | All Other Specialty Food Retailers | | 445320 | Beer Wine And Liquor Retailers | | 449110 | Furniture Retailers | | 449121 | Floor Covering Retailers | | 449122 | Window Treatment Retailers | | 449129 | All Other Home Furnishings Retailers | | 449210 | Electronics And Appliance Retailers | | 454113 | Mail Order Houses | | 454390 | Other Direct Selling Establishments | | 455110 | Department Stores | | 455211 | Warehouse Clubs And Supercenters | | 455219 | All Other General Merchandise Retailers | | 456110 | Pharmacies And Drug Retailers | | 456120 | Cosmetics Beauty Supplies And Perfume Retailers | | 456130 | Optical Goods Retailers | | 456191 | Food Health Supplement Retailers | | 456199 | All Other Health And Personal Care Retailers | | 457110 | Gasoline Stations With Convenience Stores | | 457120 | Other Gasoline Stations | | 457210 | Fuel Dealers | | 458110 | Clothing And Clothing Accessories Retailers | | 458210 | Shoe Retailers | | 458310 | Jewelry Retailers | | 458320 | Luggage And Leather Goods Retailers | | 459110 | Sporting Goods Retailers | | 459120 | Hobby Toy And Game Retailers | | 459130 | Sewing Needlework And Piece Goods Retailers | | 459140 | Musical Instrument And Supplies Retailers | | 459210 | Book Retailers And News Dealers | | 459310 | Florists | | 459410 | Office Supplies And Stationery Retailers | | 459420 | Gift Novelty And Souvenir Retailers | | 459510 | Used Merchandise Retailers | | 459910 | Pet And Pet Supplies Retailers | | 459920 | Art Dealers | | 459930 | Manufactured Mobile Home Dealers | | 459991 | Tobacco Electronic Cigarette And Other Smoking Supplies Retailers | | 459999 | All Other Miscellaneous Retailers | | 481111 | Scheduled Passenger Air Transportation | | 481112 | Scheduled Freight Air Transportation | | 481211 | Nonscheduled Chartered Passenger Air Transportation | | 481212 | Nonscheduled Chartered Freight Air Transportation | | 481219 | Other Nonscheduled Air Transportation | | 482111 | Line Haul Railroads | | 482112 | Short Line Railroads | | 483111 | Deep Sea Freight Transportation | | 483112 | Deep Sea Passenger Transportation | | 483113 | Coastal And Great Lakes Freight Transportation | | 483114 | Coastal And Great Lakes Passenger Transportation | | 483211 | Inland Water Freight Transportation | | 483212 | Inland Water Passenger Transportation | | 484110 | General Freight Trucking Local | | 484121 | General Freight Trucking Long Distance Truckload | | 484122 | General Freight Trucking Long Distance Less Than Truckload | | 484210 | Used Household And Office Goods Moving | | 484220 | Specialized Freight Except Used Goods Trucking Local | | 484230 | Specialized Freight Except Used Goods Trucking Long Distance | | 485111 | Mixed Mode Transit Systems | | 485112 | Commuter Rail Systems | | 485113 | Bus And Other Motor Vehicle Transit Systems | | 485119 | Other Urban Transit Systems | | 485210 | Interurban And Rural Bus Transportation | | 485310 | Taxi And Ridesharing Services | | 485320 | Limousine Service | | 485410 | School And Employee Bus Transportation | | 485510 | Charter Bus Industry | | 485991 | Special Needs Transportation | | 485999 | All Other Transit And Ground Passenger Transportation | | 486110 | Pipeline Transportation Of Crude Oil | | 486210 | Pipeline Transportation Of Natural Gas | | 486910 | Pipeline Transportation Of Refined Petroleum Products | | 486990 | All Other Pipeline Transportation | | 487110 | Scenic And Sightseeing Transportation Land | | 487210 | Scenic And Sightseeing Transportation Water | | 487990 | Scenic And Sightseeing Transportation Other | | 488111 | Air Traffic Control | | 488119 | Other Airport Operations | | 488190 | Other Support Activities For Air Transportation | | 488210 | Support Activities For Rail Transportation | | 488310 | Port And Harbor Operations | | 488320 | Marine Cargo Handling | | 488330 | Navigational Services To Shipping | | 488390 | Other Support Activities For Water Transportation | | 488410 | Motor Vehicle Towing | | 488490 | Other Support Activities For Road Transportation | | 488510 | Freight Transportation Arrangement | | 488991 | Packing And Crating | | 488999 | All Other Support Activities For Transportation | | 491110 | Postal Service | | 492110 | Couriers And Express Delivery Services | | 492210 | Local Messengers And Local Delivery | | 493110 | General Warehousing And Storage | | 493120 | Refrigerated Warehousing And Storage | | 493130 | Farm Product Warehousing And Storage | | 493190 | Other Warehousing And Storage | | 512110 | Motion Picture And Video Production | | 512120 | Motion Picture And Video Distribution | | 512131 | Motion Picture Theaters Except Drive Ins | | 512132 | Drive In Motion Picture Theaters | | 512191 | Teleproduction And Other Postproduction Services | | 512199 | Other Motion Picture And Video Industries | | 512230 | Music Publishers | | 512240 | Sound Recording Studios | | 512250 | Record Production And Distribution | | 512290 | Other Sound Recording Industries | | 513110 | Newspaper Publishers | | 513120 | Periodical Publishers | | 513130 | Book Publishers | | 513140 | Directory And Mailing List Publishers | | 513191 | Greeting Card Publishers | | 513199 | All Other Publishers | | 513210 | Software Publishers | | 515210 | Cable And Other Subscription Programming | | 516110 | Radio Broadcasting Stations | | 516120 | Television Broadcasting Stations | | 516210 | Media Streaming Distribution Services Social Networks And Other Media Networks And Content Providers | | 517111 | Wired Telecommunications Carriers | | 517112 | Wireless Telecommunications Carriers Except Satellite | | 517121 | Telecommunications Resellers | | 517410 | Satellite Telecommunications | | 517810 | All Other Telecommunications | | 518210 | Computing Infrastructure Providers Data Processing Web Hosting And Related Services | | 519210 | Libraries And Archives | | 519290 | Web Search Portals And All Other Information Services | | 522110 | Commercial Banking | | 522130 | Credit Unions | | 522180 | Savings Institutions And Other Depository Credit Intermediation | | 522210 | Credit Card Issuing | | 522220 | Sales Financing | | 522291 | Consumer Lending | | 522292 | Real Estate Credit | | 522298 | All Other Nondepository Credit Intermediation | | 522299 | International Secondary Market And All Other Nondepository Credit Intermediation | | 522310 | Mortgage And Nonmortgage Loan Brokers | | 522390 | Other Activities Related To Credit Intermediation | | 523150 | Investment Banking And Securities Intermediation | | 523160 | Commodity Contracts Intermediation | | 523910 | Miscellaneous Intermediation | | 523940 | Portfolio Management And Investment Advice | | 523999 | Miscellaneous Financial Investment Activities | | 524113 | Direct Life Insurance Carriers | | 524114 | Direct Health And Medical Insurance Carriers | | 524126 | Direct Property And Casualty Insurance Carriers | | 524127 | Direct Title Insurance Carriers | | 524128 | Other Direct Insurance Except Life Health And Medical Carriers | | 524130 | Reinsurance Carriers | | 524210 | Insurance Agencies And Brokerages | | 524291 | Claims Adjusting | | 524292 | Pharmacy Benefit Management And Other Third Party Administration Of Insurance And Pension Funds | | 524298 | All Other Insurance Related Activities | | 525110 | Pension Funds | | 525120 | Health And Welfare Funds | | 525190 | Other Insurance Funds | | 525910 | Open End Investment Funds | | 525920 | Trusts Estates And Agency Accounts | | 525990 | Other Financial Vehicles | | 531110 | Lessors Of Residential Buildings And Dwellings | | 531120 | Lessors Of Nonresidential Buildings Except Miniwarehouses | | 531130 | Lessors Of Miniwarehouses And Self Storage Units | | 531190 | Lessors Of Other Real Estate Property | | 531210 | Offices Of Real Estate Agents And Brokers | | 531311 | Residential Property Managers | | 531312 | Nonresidential Property Managers | | 531320 | Offices Of Real Estate Appraisers | | 531390 | Other Activities Related To Real Estate | | 532111 | Passenger Car Rental | | 532112 | Passenger Car Leasing | | 532120 | Truck Utility Trailer And RV Recreational Vehicle Rental And Leasing | | 532210 | Consumer Electronics And Appliances Rental | | 532281 | Formal Wear And Costume Rental | | 532282 | Video Tape And Disc Rental | | 532283 | Home Health Equipment Rental | | 532284 | Recreational Goods Rental | | 532289 | All Other Consumer Goods Rental | | 532310 | General Rental Centers | | 532411 | Commercial Air Rail And Water Transportation Equipment Rental And Leasing | | 532412 | Construction Mining And Forestry Machinery And Equipment Rental And Leasing | | 532420 | Office Machinery And Equipment Rental And Leasing | | 532490 | Other Commercial And Industrial Machinery And Equipment Rental And Leasing | | 533110 | Lessors Of Nonfinancial Intangible Assets Except Copyrighted Works | | 541110 | Offices Of Lawyers | | 541191 | Title Abstract And Settlement Offices | | 541199 | All Other Legal Services | | 541211 | Offices Of Certified Public Accountants | | 541213 | Tax Preparation Services | | 541214 | Payroll Services | | 541219 | Other Accounting Services | | 541310 | Architectural Services | | 541320 | Landscape Architectural Services | | 541330 | Engineering Services | | 541340 | Drafting Services | | 541350 | Building Inspection Services | | 541360 | Geophysical Surveying And Mapping Services | | 541370 | Surveying And Mapping Except Geophysical Services | | 541380 | Testing Laboratories And Services | | 541410 | Interior Design Services | | 541420 | Industrial Design Services | | 541430 | Graphic Design Services | | 541490 | Other Specialized Design Services | | 541511 | Custom Computer Programming Services | | 541512 | Computer Systems Design Services | | 541513 | Computer Facilities Management Services | | 541519 | Other Computer Related Services | | 541611 | Administrative Management And General Management Consulting Services | | 541612 | Human Resources Consulting Services | | 541613 | Marketing Consulting Services | | 541614 | Process Physical Distribution And Logistics Consulting Services | | 541618 | Other Management Consulting Services | | 541620 | Environmental Consulting Services | | 541690 | Other Scientific And Technical Consulting Services | | 541713 | Research And Development In Nanotechnology | | 541714 | Research And Development In Biotechnology Except Nanobiotechnology | | 541715 | Research And Development In The Physical Engineering And Life Sciences Except Nanotechnology And Biotechnology | | 541720 | Research And Development In The Social Sciences And Humanities | | 541810 | Advertising Agencies | | 541820 | Public Relations Agencies | | 541830 | Media Buying Agencies | | 541840 | Media Representatives | | 541850 | Indoor And Outdoor Display Advertising | | 541860 | Direct Mail Advertising | | 541870 | Advertising Material Distribution Services | | 541890 | Other Services Related To Advertising | | 541910 | Marketing Research And Public Opinion Polling | | 541921 | Photography Studios Portrait | | 541922 | Commercial Photography | | 541930 | Translation And Interpretation Services | | 541940 | Veterinary Services | | 541990 | All Other Professional Scientific And Technical Services | | 551111 | Offices Of Bank Holding Companies | | 551112 | Offices Of Other Holding Companies | | 551114 | Corporate Subsidiary And Regional Managing Offices | | 561110 | Office Administrative Services | | 561210 | Facilities Support Services | | 561311 | Employment Placement Agencies | | 561312 | Executive Search Services | | 561320 | Temporary Help Services | | 561330 | Professional Employer Organizations | | 561410 | Document Preparation Services | | 561421 | Telephone Answering Services | | 561422 | Telemarketing Bureaus And Other Contact Centers | | 561431 | Private Mail Centers | | 561439 | Other Business Service Centers Including Copy Shops | | 561440 | Collection Agencies | | 561450 | Credit Bureaus | | 561491 | Repossession Services | | 561492 | Court Reporting And Stenotype Services | | 561499 | All Other Business Support Services | | 561510 | Travel Agencies | | 561520 | Tour Operators | | 561591 | Convention And Visitors Bureaus | | 561599 | All Other Travel Arrangement And Reservation Services | | 561611 | Investigation And Personal Background Check Services | | 561612 | Security Guards And Patrol Services | | 561613 | Armored Car Services | | 561621 | Security Systems Services Except Locksmiths | | 561622 | Locksmiths | | 561710 | Exterminating And Pest Control Services | | 561720 | Janitorial Services | | 561730 | Landscaping Services | | 561740 | Carpet And Upholstery Cleaning Services | | 561790 | Other Services To Buildings And Dwellings | | 561910 | Packaging And Labeling Services | | 561920 | Convention And Trade Show Organizers | | 561990 | All Other Support Services | | 562111 | Solid Waste Collection | | 562112 | Hazardous Waste Collection | | 562119 | Other Waste Collection | | 562211 | Hazardous Waste Treatment And Disposal | | 562212 | Solid Waste Landfill | | 562213 | Solid Waste Combustors And Incinerators | | 562219 | Other Nonhazardous Waste Treatment And Disposal | | 562910 | Remediation Services | | 562920 | Materials Recovery Facilities | | 562991 | Septic Tank And Related Services | | 562998 | All Other Miscellaneous Waste Management Services | | 611110 | Elementary And Secondary Schools | | 611210 | Junior Colleges | | 611310 | Colleges Universities And Professional Schools | | 611410 | Business And Secretarial Schools | | 611420 | Computer Training | | 611430 | Professional And Management Development Training | | 611511 | Cosmetology And Barber Schools | | 611512 | Flight Training | | 611513 | Apprenticeship Training | | 611519 | Other Technical And Trade Schools | | 611610 | Fine Arts Schools | | 611620 | Sports And Recreation Instruction | | 611630 | Language Schools | | 611691 | Exam Preparation And Tutoring | | 611692 | Automobile Driving Schools | | 611699 | All Other Miscellaneous Schools And Instruction | | 611710 | Educational Support Services | | 621111 | Offices Of Physicians Except Mental Health Specialists | | 621112 | Offices Of Physicians Mental Health Specialists | | 621210 | Offices Of Dentists | | 621310 | Offices Of Chiropractors | | 621320 | Offices Of Optometrists | | 621330 | Offices Of Mental Health Practitioners Except Physicians | | 621340 | Offices Of Physical Occupational And Speech Therapists And Audiologists | | 621391 | Offices Of Podiatrists | | 621399 | Offices Of All Other Miscellaneous Health Practitioners | | 621410 | Family Planning Centers | | 621420 | Outpatient Mental Health And Substance Abuse Centers | | 621491 | HMO Medical Centers | | 621492 | Kidney Dialysis Centers | | 621493 | Freestanding Ambulatory Surgical And Emergency Centers | | 621498 | All Other Outpatient Care Centers | | 621511 | Medical Laboratories | | 621512 | Diagnostic Imaging Centers | | 621610 | Home Health Care Services | | 621910 | Ambulance Services | | 621991 | Blood And Organ Banks | | 621999 | All Other Miscellaneous Ambulatory Health Care Services | | 622110 | General Medical And Surgical Hospitals | | 622210 | Psychiatric And Substance Abuse Hospitals | | 622310 | Specialty Except Psychiatric And Substance Abuse Hospitals | | 623110 | Nursing Care Facilities Skilled Nursing Facilities | | 623210 | Residential Intellectual And Developmental Disability Facilities | | 623220 | Residential Mental Health And Substance Abuse Facilities | | 623311 | Continuing Care Retirement Communities | | 623312 | Assisted Living Facilities For The Elderly | | 623990 | Other Residential Care Facilities | | 624110 | Child And Youth Services | | 624120 | Services For The Elderly And Persons With Disabilities | | 624190 | Other Individual And Family Services | | 624210 | Community Food Services | | 624221 | Temporary Shelters | | 624229 | Other Community Housing Services | | 624230 | Emergency And Other Relief Services | | 624310 | Vocational Rehabilitation Services | | 624410 | Child Care Services | | 711110 | Theater Companies And Dinner Theaters | | 711120 | Dance Companies | | 711130 | Musical Groups And Artists | | 711190 | Other Performing Arts Companies | | 711211 | Sports Teams And Clubs | | 711212 | Racetracks | | 711219 | Other Spectator Sports | | 711310 | Promoters Of Performing Arts Sports And Similar Events With Facilities | | 711320 | Promoters Of Performing Arts Sports And Similar Events Without Facilities | | 711410 | Agents And Managers For Artists Athletes Entertainers And Other Public Figures | | 711510 | Independent Artists Writers And Performers | | 712110 | Museums | | 712120 | Historical Sites | | 712130 | Zoos And Botanical Gardens | | 712190 | Nature Parks And Other Similar Institutions | | 713110 | Amusement And Theme Parks | | 713120 | Amusement Arcades | | 713210 | Casinos Except Casino Hotels | | 713290 | Other Gambling Industries | | 713910 | Golf Courses And Country Clubs | | 713920 | Skiing Facilities | | 713930 | Marinas | | 713940 | Fitness And Recreational Sports Centers | | 713950 | Bowling Centers | | 713990 | All Other Amusement And Recreation Industries | | 721110 | Hotels Except Casino Hotels And Motels | | 721120 | Casino Hotels | | 721191 | Bed And Breakfast Inns | | 721199 | All Other Traveler Accommodation | | 721211 | RV Recreational Vehicle Parks And Campgrounds | | 721214 | Recreational And Vacation Camps Except Campgrounds | | 721310 | Rooming And Boarding Houses Dormitories And Workers Camps | | 722310 | Food Service Contractors | | 722320 | Caterers | | 722330 | Mobile Food Services | | 722410 | Drinking Places Alcoholic Beverages | | 722511 | Full Service Restaurants | | 722513 | Limited Service Restaurants | | 722514 | Cafeterias Grill Buffets And Buffets | | 722515 | Snack And Nonalcoholic Beverage Bars | | 811111 | General Automotive Repair | | 811114 | Specialized Automotive Repair | | 811121 | Automotive Body Paint And Interior Repair And Maintenance | | 811122 | Automotive Glass Replacement Shops | | 811191 | Automotive Oil Change And Lubrication Shops | | 811192 | Car Washes | | 811198 | All Other Automotive Repair And Maintenance | | 811210 | Electronic And Precision Equipment Repair And Maintenance | | 811310 | Commercial And Industrial Machinery And Equipment Except Automotive And Electronic Repair And Maintenance | | 811411 | Home And Garden Equipment Repair And Maintenance | | 811412 | Appliance Repair And Maintenance | | 811420 | Reupholstery And Furniture Repair | | 811430 | Footwear And Leather Goods Repair | | 811490 | Other Personal And Household Goods Repair And Maintenance | | 812111 | Barber Shops | | 812112 | Beauty Salons | | 812113 | Nail Salons | | 812191 | Diet And Weight Reducing Centers | | 812199 | Other Personal Care Services | | 812210 | Funeral Homes And Funeral Services | | 812220 | Cemeteries And Crematories | | 812310 | Coin Operated Laundries And Drycleaners | | 812320 | Drycleaning And Laundry Services Except Coin Operated | | 812331 | Linen Supply | | 812332 | Industrial Launderers | | 812910 | Pet Care Except Veterinary Services | | 812921 | Photofinishing Laboratories Except One Hour | | 812922 | One Hour Photofinishing | | 812930 | Parking Lots And Garages | | 812990 | All Other Personal Services | | 813110 | Religious Organizations | | 813211 | Grantmaking Foundations | | 813212 | Voluntary Health Organizations | | 813219 | Other Grantmaking And Giving Services | | 813311 | Human Rights Organizations | | 813312 | Environment Conservation And Wildlife Organizations | | 813319 | Other Social Advocacy Organizations | | 813410 | Civic And Social Organizations | | 813910 | Business Associations | | 813920 | Professional Organizations | | 813930 | Labor Unions And Similar Labor Organizations | | 813940 | Political Organizations | | 813990 | Other Similar Organizations Except Business Professional Labor And Political Organizations | | 814110 | Private Households | | 921110 | Executive Offices | | 921120 | Legislative Bodies | | 921130 | Public Finance Activities | | 921140 | Executive And Legislative Offices Combined | | 921150 | American Indian And Alaska Native Tribal Governments | | 921190 | Other General Government Support | | 922110 | Courts | | 922120 | Police Protection | | 922130 | Legal Counsel And Prosecution | | 922140 | Correctional Institutions | | 922150 | Parole Offices And Probation Offices | | 922160 | Fire Protection | | 922190 | Other Justice Public Order And Safety Activities | | 923110 | Administration Of Education Programs | | 923120 | Administration Of Public Health Programs | | 923130 | Administration Of Human Resource Programs Except Education Public Health And Veterans Affairs Programs | | 923140 | Administration Of Veterans Affairs | | 924110 | Administration Of Air And Water Resource And Solid Waste Management Programs | | 924120 | Administration Of Conservation Programs | | 925110 | Administration Of Housing Programs | | 925120 | Administration Of Urban Planning And Community And Rural Development | | 926110 | Administration Of General Economic Programs | | 926120 | Regulation And Administration Of Transportation Programs | | 926130 | Regulation And Administration Of Communications Electric Gas And Other Utilities | | 926140 | Regulation Of Agricultural Marketing And Commodities | | 926150 | Regulation Licensing And Inspection Of Miscellaneous Commercial Sectors | | 927110 | Space Research And Technology | | 928110 | National Security | | 928120 | International Affairs |

# Business Tax ID documents by region Source: https://developer.fin.com/guides/customers-and-compliance/business-tax-id-documents-by-region The following lists tax ID types that Fin.com will accept for businesses by region. Pass `OTHER` for the countries not listed below. | Region | Identification Type | | :----------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- | | **Aruba** - (`ABW`) | `CN` - Census Number | | **Afghanistan** - (`AFG`) | `TIN` - Tax Identification Number | | **Angola** - (`AGO`) | `NIF` - Número de Identificação Fiscal | | **Albania** - (`ALB`) | `NIPT` - Numri i Identifikimit për Personin e Tatueshëm | | **Andorra** - (`AND`) | `NRT` - Número de Registre Tributari | | **United Arab Emirates** - (`ARE`) | `TRN` - Tax Registration Number | | **Argentina** - (`ARG`) | `CUIT` - Clave Única de Identificación Tributaria | | **Armenia** - (`ARM`) | `TIN` - Tax Identification Number | | **Australia** - (`AUS`) | `ABN` - Australian Business Number | | **Australia** - (`AUS`) | `ACN` - Australian Company Number | | **Australia** - (`AUS`) | `ARBN` - Australian Registered Body Number | | **Austria** - (`AUT`) | `FN` - Firmenbuchnummer | | **Austria** - (`AUT`) | `UID` - Umsatzsteuer-Identifikationsnummer | | **Azerbaijan** - (`AZE`) | `VOEN` - Vergi Ödəyicisinin Eyniləşdirmə Nömrəsi | | **Belgium** - (`BEL`) | `BCE` - Banque-Carrefour des Entreprises | | **Belgium** - (`BEL`) | `KBO` - Kruispuntbank van Ondernemingen | | **Bangladesh** - (`BGD`) | `BIN` - Business Identification Number | | **Bangladesh** - (`BGD`) | `VAT` - Value Added Tax Number | | **Bulgaria** - (`BGR`) | `UIC` - Unified Identification Code | | **Bahrain** - (`BHR`) | `CRN` - Company/Commercial Registration Number | | **Bahamas** - (`BHS`) | `TIN` - Tax Identification Number | | **Bosnia and Herzegovina** - (`BIH`) | `ID_BROJ` - ID Broj (Identification Number) | | **Belize** - (`BLZ`) | `TIN` - Tax Identification Number | | **Bermuda** - (`BMU`) | `CRN` - Company/Commercial Registration Number | | **Bolivia (Plurinational State of)** - (`BOL`) | `NIT` - Número de Identificación Tributaria | | **Bolivia (Plurinational State of)** - (`BOL`) | `VAT` - Value Added Tax Number | | **Brazil** - (`BRA`) | `CNPJ` - Cadastro Nacional da Pessoa Jurídica | | **Brazil** - (`BRA`) | `VAT` - Value Added Tax Number | | **Barbados** - (`BRB`) | `TIN` - Tax Identification Number | | **Botswana** - (`BWA`) | `CRN` - Company/Commercial Registration Number | | **Canada** - (`CAN`) | `BIN` - Business Identification Number | | **Canada** - (`CAN`) | `VAT` - Value Added Tax Number | | **Switzerland** - (`CHE`) | `UID` - Unternehmens-Identifikationsnummer | | **Chile** - (`CHL`) | `RUT` - Registro Único Tributario | | **China** - (`CHN`) | `USC` - Unified Social Credit Code | | **Côte d'Ivoire** - (`CIV`) | `NIF` - Numéro d'Identification Fiscale | | **Cameroon** - (`CMR`) | `NIF` - Numéro d'Identification Fiscale | | **Cameroon** - (`CMR`) | `RCCM` - Registre du Commerce et du Crédit Mobilier | | **Colombia** - (`COL`) | `NIT` - Número de Identificación Tributaria | | **Colombia** - (`COL`) | `RUT` - Registro Único Tributario | | **Comoros** - (`COM`) | `NIF` - Numéro d'Identification Fiscale | | **Costa Rica** - (`CRI`) | `CEDULA_JURIDICA` - Cédula Jurídica | | **Curaçao** - (`CUW`) | `CRIB` - Central Registratie en Informatiebureau | | **Christmas Island** - (`CXR`) | `ABN` - Australian Business Number | | **Cayman Islands** - (`CYM`) | `CRN` - Company/Commercial Registration Number | | **Cyprus** - (`CYP`) | `CRN` - Company/Commercial Registration Number | | **Czechia** - (`CZE`) | `ICO` - Identifikační Číslo Organizace (Organization Identification Number) | | **Germany** - (`DEU`) | `UST_IDNR` - Umsatzsteuer-Identifikationsnummer | | **Germany** - (`DEU`) | `CRN` - Company/Commercial Registration Number | | **Dominica** - (`DMA`) | `TIN` - Tax Identification Number | | **Denmark** - (`DNK`) | `CVR` - Central Virksomhedsregister (Central Business Register) | | **Dominican Republic** - (`DOM`) | `RNC` - Registro Nacional de Contribuyentes (National Taxpayer Registry) | | **Algeria** - (`DZA`) | `NIF` - Numéro d'Identification Fiscale | | **Ecuador** - (`ECU`) | `RUC` - Registro Único de Contribuyentes | | **Egypt** - (`EGY`) | `TIN` - Tax Identification Number | | **Egypt** - (`EGY`) | `VAT` - Value Added Tax Number | | **Spain** - (`ESP`) | `NIF` - Numéro d'Identification Fiscale | | **Spain** - (`ESP`) | `CIF` - Código de Identificación Fiscal (Fiscal Identification Code) | | **Estonia** - (`EST`) | `RC` - Register Code | | **Ethiopia** - (`ETH`) | `TIN` - Tax Identification Number | | **Finland** - (`FIN`) | `Y_TUNNUS` - Business ID | | **Fiji** - (`FJI`) | `TIN` - Tax Identification Number | | **France** - (`FRA`) | `SIREN` - Système d'Identification du Répertoire des Entreprises (Enterprise Identification System) | | **France** - (`FRA`) | `SIRET` - Système d'Identification du Répertoire des Établissements (Establishment Identification System) | | **United Kingdom of Great Britain and Northern Ireland** - (`GBR`) | `CRN` - Company/Commercial Registration Number | | **United Kingdom of Great Britain and Northern Ireland** - (`GBR`) | `VAT` - Value Added Tax Number | | **Georgia** - (`GEO`) | `IC` - Identification Code | | **Ghana** - (`GHA`) | `TIN` - Tax Identification Number | | **Gibraltar** - (`GIB`) | `CRN` - Company/Commercial Registration Number | | **Greece** - (`GRC`) | `AOM` - Αριθμός Οικονομικής Μονάδας (Economic Unit Number) | | **Guatemala** - (`GTM`) | `NIT` - Número de Identificación Tributaria | | **Guatemala** - (`GTM`) | `VAT` - Value Added Tax Number | | **Hong Kong** - (`HKG`) | `BRN` - Business Registration Number | | **Honduras** - (`HND`) | `RTN` - Registro Tributario Nacional (National Tax Registry) | | **Croatia** - (`HRV`) | `OIB` - Osobni Identifikacijski Broj (Personal Identification Number) | | **Haiti** - (`HTI`) | `NIF` - Numéro d'Identification Fiscale | | **Hungary** - (`HUN`) | `TIN` - Tax Identification Number | | **Indonesia** - (`IDN`) | `NPWP` - Nomor Pokok Wajib Pajak (Taxpayer Identification Number) | | **Indonesia** - (`IDN`) | `VAT` - Value Added Tax Number | | **Isle of Man** - (`IMN`) | `CRN` - Company/Commercial Registration Number | | **India** - (`IND`) | `GSTIN` - Goods and Services Tax Identification Number | | **India** - (`IND`) | `CIN` - Corporate Identification Number | | **India** - (`IND`) | `PAN` - Personal Account Number | | **India** - (`IND`) | `VAT` - Value Added Tax Number | | **Ireland** - (`IRL`) | `CRO` - Company Registration Office Number | | **Iraq** - (`IRQ`) | `TIN` - Tax Identification Number | | **Iceland** - (`ISL`) | `ID` - Identification Number | | **Israel** - (`ISR`) | `CRN` - Company/Commercial Registration Number | | **Italy** - (`ITA`) | `PARTITA_IVA` - Partita IVA | | **Italy** - (`ITA`) | `CF` - Codice Fiscale | | **Jamaica** - (`JAM`) | `TRN` - Tax Registration Number | | **Jordan** - (`JOR`) | `TIN` - Tax Identification Number | | **Japan** - (`JPN`) | `HN` - Hojin Number (Corporate Number) | | **Kazakhstan** - (`KAZ`) | `BIN` - Business Identification Number | | **Kenya** - (`KEN`) | `PIN` - Personal Identification Number | | **Kenya** - (`KEN`) | `VAT` - Value Added Tax Number | | **Kyrgyzstan** - (`KGZ`) | `INN` - Идентификационный Номер Налогоплательщика (Taxpayer Identification Number) | | **Cambodia** - (`KHM`) | `TIN` - Tax Identification Number | | **Cambodia** - (`KHM`) | `VAT` - Value Added Tax Number | | **Saint Kitts and Nevis** - (`KNA`) | `TIN` - Tax Identification Number | | **Korea (Republic of)** - (`KOR`) | `BRN` - Business Registration Number | | **Kuwait** - (`KWT`) | `CRN` - Company/Commercial Registration Number | | **Lao People's Democratic Republic** - (`LAO`) | `TIN` - Tax Identification Number | | **Lebanon** - (`LBN`) | `CRN` - Company/Commercial Registration Number | | **Liberia** - (`LBR`) | `TIN` - Tax Identification Number | | **Saint Lucia** - (`LCA`) | `TIN` - Tax Identification Number | | **Sri Lanka** - (`LKA`) | `BRN` - Business Registration Number | | **Lithuania** - (`LTU`) | `CC` - Company Code | | **Luxembourg** - (`LUX`) | `MATRICULE` - | | **Latvia** - (`LVA`) | `RN` - Reģistrācijas Numurs (Registration Number) | | **Morocco** - (`MAR`) | `IF` - Identifiant Fiscal (Tax Identifier) | | **Monaco** - (`MCO`) | `CRN` - Company/Commercial Registration Number | | **Moldova (Republic of)** - (`MDA`) | `IDNO` - Identification Number of Organization | | **Madagascar** - (`MDG`) | `NIF` - Numéro d'Identification Fiscale | | **Mexico** - (`MEX`) | `RFC` - Registro Federal de Contribuyentes (Federal Taxpayer Registry) | | **Mexico** - (`MEX`) | `VAT` - Value Added Tax Number | | **Marshall Islands** - (`MHL`) | `EN` - Entity Number | | **North Macedonia** - (`MKD`) | `TIN` - Tax Identification Number | | **Malta** - (`MLT`) | `CRN` - Company/Commercial Registration Number | | **Malta** - (`MLT`) | `VAT` - Value Added Tax Number | | **Montenegro** - (`MNE`) | `CRN` - Company/Commercial Registration Number | | **Mozambique** - (`MOZ`) | `PIB` - Personal Identification of the Business | | **Mauritania** - (`MRT`) | `NIF` - Numéro d'Identification Fiscale | | **Mauritius** - (`MUS`) | `BRN` - Business Registration Number | | **Malawi** - (`MWI`) | `TPIN` - Taxpayer Identification Number | | **Malaysia** - (`MYS`) | `SSM` - Suruhanjaya Syarikat Malaysia | | **Malaysia** - (`MYS`) | `GSTIN` - Goods and Services Tax Identification Number | | **Namibia** - (`NAM`) | `VAT` - Value Added Tax Number | | **Nigeria** - (`NGA`) | `CAC` - Corporate Affairs Commission Registration Certificate number | | **Nigeria** - (`NGA`) | `TIN` - Tax Identification Number | | **Nigeria** - (`NGA`) | `VAT` - Value Added Tax Number | | **Nicaragua** - (`NIC`) | `RUC` - Registro Único de Contribuyentes | | **Netherlands** - (`NLD`) | `KVK` - Kamer van Koophandel | | **Netherlands** - (`NLD`) | `VAT` - Value Added Tax Number | | **Norway** - (`NOR`) | `ORGNR` - Organisasjonsnummer | | **Nepal** - (`NPL`) | `PAN` - Permanent Account Number | | **New Zealand** - (`NZL`) | `GST` - Goods and Services Tax Number | | **Oman** - (`OMN`) | `CRN` - Company/Commercial Registration Number | | **Panama** - (`PAN`) | `RUC` - Registro Único de Contribuyentes | | **Peru** - (`PER`) | `RUC` - Registro Único de Contribuyentes | | **Philippines** - (`PHL`) | `TIN` - Tax Identification Number | | **Pakistan** - (`PAK`) | `NTN` - National Tax Number | | **Poland** - (`POL`) | `NIP` - Numer Identyfikacji Podatkowej | | **Poland** - (`POL`) | `KRS` - Krajowy Rejestr Sądowy | | **Portugal** - (`PRT`) | `NIF` - Número de Identificação Fiscal | | **Portugal** - (`PRT`) | `NIPC` - Número de Identificação de Pessoa Coletiva | | **Qatar** - (`QAT`) | `CRN` - Company/Commercial Registration Number | | **Romania** - (`ROU`) | `CUI` - Cod Unic de Înregistrare | | **Russia** - (`RUS`) | `INN` - Individual Taxpayer Number | | **Russia** - (`RUS`) | `OGRN` - Primary State Registration Number | | **Saudi Arabia** - (`SAU`) | `CRN` - Company/Commercial Registration Number | | **Senegal** - (`SEN`) | `NINEA` - Numéro d’Identification Nationale des Entreprises et des Associations | | **Singapore** - (`SGP`) | `UEN` - Unique Entity Number | | **Slovakia** - (`SVK`) | `ICO` - Identifikačné Číslo Organizácie | | **Slovenia** - (`SVN`) | `MS` - Matična Številka | | **South Africa** - (`ZAF`) | `VAT` - Value Added Tax Number | | **South Africa** - (`ZAF`) | `TIN` - Tax Identification Number | | **Sweden** - (`SWE`) | `ORGNR` - Organisationsnummer | | **Switzerland** - (`CHE`) | `UID` - Unternehmens-Identifikationsnummer | | **Thailand** - (`THA`) | `TIN` - Tax Identification Number | | **Tunisia** - (`TUN`) | `MF` - Matricule Fiscale | | **Turkey** - (`TUR`) | `VKN` - Vergi Kimlik Numarası | | **Uganda** - (`UGA`) | `TIN` - Tax Identification Number | | **Ukraine** - (`UKR`) | `EDRPOU` - ЄДРПОУ (Unified State Register of Enterprises and Organizations of Ukraine) | | **United Arab Emirates** - (`ARE`) | `VAT` - Value Added Tax Number | | **United States** - (`USA`) | `EIN` - Employer Identification Number | | **Uruguay** - (`URY`) | `RUT` - Registro Único Tributario | | **Uzbekistan** - (`UZB`) | `INN` - Individual Taxpayer Number | | **Venezuela** - (`VEN`) | `RIF` - Registro de Información Fiscal | | **Vietnam** - (`VNM`) | `MST` - Mã số thuế (Tax Code) | | **Yemen** - (`YEM`) | `TIN` - Tax Identification Number | | **Zambia** - (`ZMB`) | `TPIN` - Taxpayer Identification Number | | **Zimbabwe** - (`ZWE`) | `BP` - Business Partner Number | # Entity-wise document requirement Source: https://developer.fin.com/guides/customers-and-compliance/entity-wise-document-requirement Depending on your entity type, you'll need to upload specific documents (or their local equivalents) to complete the profile. You can attach these using the [Attach Documents to Business Customer ](https://developer.fin.com/api-reference/customers/attach-documents-to-business-customer)endpoint. ## Document Requirements | Entity Type | Formation Documents | Ownership Documents | Supporting Documents | | ----------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **Limited Liability Company (LLC)** | Registration Document, Constitutional Document, Evidence of Directors and Controllers *(non-US only)* | Proof of Signatory Authority | Proof of Address, Proof of Source of Funds, Shareholder Register, Cert of Incumbency, E Signature Certificate | | **Corporation (Inc, Corp)** | Registration Document, Constitutional Document, Evidence of Directors and Controllers *(non-US only)* | Proof of Signatory Authority | Proof of Address, Proof of Source of Funds, Shareholder Register, Cert of Incumbency, E Signature Certificate | | **Partnership** | Registration Document, Constitutional Document | Proof of Signatory Authority | Proof of Address, Proof of Source of Funds, Shareholder Register, Cert of Incumbency, E Signature Certificate | | **Sole Proprietorship** | Proof of Nature of Business, Proof of Entity Name Change, Proof of Tax Identification | *None* | Proof of Address, Proof of Source of Funds | | **Private Foundation** | Registration Document, Constitutional Document | Proof of Signatory Authority | Proof of Address, Tax Exempt Entity Confirmation, Proof of Source of Wealth, Proof of Source of Funds, Cert of Incumbency, E Signature Certificate | | **Non-profit Organization** | Registration Document, Constitutional Document | Proof of Signatory Authority | Proof of Address, Tax Exempt Entity Confirmation, Proof of Source of Wealth, Proof of Source of Funds, Cert of Incumbency, E Signature Certificate | | **Publicly Listed Company** | Registration Document, Constitutional Document, Evidence of Directors and Controllers *(non-US only)* | Proof of Signatory Authority | Proof of Address, Proof of Source of Funds, Shareholder Register, Cert of Incumbency, E Signature Certificate | ## Document Definitions | Document name | Document API code | What to send ✈️ | What reviewers check 🔍 | What to avoid 🚫 | | :----------------------------------------- | :--------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Registration Document** | `REGISTRATION_DOCUMENT` | Certificate of incorporation, formation, or registration. Your country's equivalent works if it serves the same purpose (e.g. a trade license in some free zones). | • Exact legal name, character for character, matching the application and the public registry.
• Incorporation date, jurisdiction, registry stamp or registration number.
• Still current, not expired or superseded. | • Expired or superseded copies.
• Name changed after formation, official name-change document missing.
• Wrong local document type for your country. Ask us if unsure. | | **Constitutional Document** | `CONSTITUTIONAL_DOCUMENT` | Articles of association or organization, bylaws, an operating agreement, or a partnership agreement, whichever governs your entity type. | • Entity name matches the registration document exactly.
• Signatures where the document type carries them (digital is fine).
• All pages and schedules included. | • Draft or unsigned versions.
• Missing pages or schedules that list members and their interests. | | **Evidence of Directors and Controllers** | `EVIDENCE_OF_DIRECTORS_AND_CONTROLLERS` | Register of directors, registry extract, or certificate of incumbency showing all current directors. | • Every current director listed.
• Names spelled exactly as on the public register and in the application, including middle names and initials.
• The record is current. | • Outdated records that don't reflect current directors.
• A director in the application missing from the document, or vice versa.
• Spelling differences vs the public registry. | | **Proof of Tax Identification** | `PROOF_OF_TAX_IDENTIFICATION` | A tax filing or an official tax-authority letter showing the number. Sole proprietors: the individual tax return covering the business. | • The tax ID on the document matches the number entered in the application.
• The document shows the exact legal name.
• Issuing authority visible. | • The number on the document doesn't match the application. Fix the data, then resubmit.
• A letter addressed to a different name or entity. | | **Proof of Signatory Authority** | `PROOF_OF_SIGNATORY_AUTHORITY` | • An authorized-representative list, board resolution, or power of attorney naming who can act for the company, signed by a director.
• DAOs: the list of managers or persons able to legally bind the organization.
• Where person filling the DD questionnaire or operating Fin Dashboard is different from the Directors of UBOs, to provide a Board Resolution authorising the individual(s) the right to access and sign-offs on behalf of. | • The person operating this account is named, with role and scope of authority.
• Entity name on the document.
• Executed by a director or the governing body. | • The account admin isn't on the list.
• Unsigned lists, or authority granted by someone with no standing to grant it. | | **Shareholder Register** | `SHAREHOLDER_REGISTER` | • A share register, cap table, or shareholders' agreement: any official record listing the owners.
• Owned by another company? The same document for that company too. | • Your company's name on the face of the document.
• Every owner with an exact percentage, adding up to 100%.
• Dated and signed by a director. Cap tables from recognized platforms (Carta, AngelList) need no extra signature.
• Every middle layer of a holding structure has its own register.

Note: Keep real per-layer percentages on documents. Reviewers trace the chain and compute effective ownership themselves. A 'corrected' number matching no registry creates a query, not a shortcut. | • The document proves who the directors are but not who owns what percentage. This is the most common ownership rejection.
• A holding company in the chain with no register of its own.
• Outdated registers that don't reflect current shareholders. | | **Ownership Information** | `OWNERSHIP_INFORMATION` | • For DAOs and member structures: membership or token agreement, voting records, or governance framework showing who controls the organization. | • Members or token holders and their percentages, or the control mechanics if there are no percentages.
• Consistency with the governance you've described. | • Documents showing the governance process but not who actually controls.
• Self-declarations with nothing verifiable behind them. | | **Ownership Chart** | `OWNERSHIP_CHART` | • A one-page chart of the full ownership structure covering every entity layer, down to actual people. Required whenever another entity sits in your ownership chain, and always for funds.
• Document must indicate in % the ownership. Total must equals to 100% | • Each layer: entity legal name, country, and percentage held.
• Direct and indirect percentages sum to 100%; the chain ends at natural persons.
• The chart matches the share registers submitted. | • A chart that doesn't match the registers.
• Missing layers, or percentages that don't add up. | | **Cert of Incumbency** | `CERT_OF_INCUMBENCY` | • A recent certificate of incumbency issued by your registered agent. | • Current directors and officers, plus shareholders with percentages where the certificate carries them.
• Entity name and a recent issue date.
• Names match the register of directors exactly. | • Stale certificates.
• Names differing from the public register.
• Shareholders listed without percentages when the certificate is used as ownership evidence. | | **Proof of Address** | `PROOF_OF_ADDRESS` | • A utility bill, bank statement, or lease showing your company name and full address.
• Also acceptable: a government letter or a registry extract showing the address.

Note: Fully remote? Proof of a director's home address plus a short signed letter confirming remote operations. Ask us for the template. | • Issued within the last 90 days; a lease can be older if still active.
• Company legal name in full, complete address, issue date, and the issuer's name or logo, all visible.
• The address is where you actually operate. No PO boxes, virtual offices, or mail-forwarding addresses.
• The entire document visible, nothing cropped or blacked out. | • Registered-agent or virtual-office addresses. These are checked against known lists, and they fail.
• A document in a person's name instead of the company's.
• Redacted lines. Redaction reads as tampering.
• Older than 90 days. | | **Proof of Source of Funds** | `PROOF_OF_SOURCE_OF_FUNDS` | • The last three months of business bank statements, in the company name.
• Your latest financial statements or management accounts.
• A short note naming the actual accounts and institutions money comes from.

Note: Crypto-native business? Wallet ownership proof, on-chain transaction history, and exchange account statements all work as evidence. | • Statements in the company's registered name with real operating activity.
• Financial statements with notes and a breakdown of the major balance-sheet lines, plus who prepared them and on what basis.
• The story matches your declared revenue and the application. | • Personal-account statements, never accepted for a company application.
• Statements from a parent, sister, or other related company.
• Statements older than three months.
• Condensed one-page financial summaries.
• Vague one-liners (“business revenue”) with nothing behind them. | | **Proof of Source of Wealth** | `PROOF_OF_SOURCE_OF_WEALTH` | • A signed source-of-wealth declaration. Ask us for the template; free-form letters get sent back.
• Evidence matching your wealth type: payslips or contracts for salary, portfolio statements for investments, estate documents for inheritance.
• Foundations, charities, NPOs: annual reports. | • Signed by a named person with their role stated.
• Evidence consistent with the declared wealth story. | • Free-form letters instead of the template.
• Declarations with no supporting evidence behind them. | | **Proof of Nature of Business** | `PROOF_OF_NATURE_OF_BUSINESS` | • Two or three recent invoices or signed contracts; bills of lading where relevant.
• Brand-new company with no revenue? A business plan, pitch deck, or product demo instead. | • Invoices look real: payment details, branding, specific amounts.
• The activity shown matches what the application says you do. | • Generic round-number invoices. These trigger proof-of-payment requests.
• An invoice that can't be matched to a bank statement when asked.
• Evidence contradicting the stated activity. | | **Proof of Entity Name Change** | `PROOF_OF_ENTITY_NAME_CHANGE` | • The official name-change filing, or a trade-name / DBA registration linking your brand to the legal entity.
• Domain registration or a brand-to-entity agreement also helps. | • Old and new (or trading) name, the official filing, and its date.
• The connection between the website brand and the legal entity is clear. | • A brand on the website belonging to a different company, with nothing official connecting them.
• Informal explanations with no filing behind them. | | **Tax Exempt Entity Confirmation** | `TAX_EXEMPT_ENTITY_CONFIRMATION` | • Your tax-exemption determination letter or charity registration letter (the local equivalent is fine). | • Entity legal name, exemption or registration number, issuing authority. | • A letter issued to a related entity instead of the applicant.
• Lapsed registrations. | | **Marketing Materials** | `MARKETING_MATERIALS` | • Investment funds: prospectus, offering memorandum, or private placement memorandum.
• Other companies: decks or brochures that substantiate the business, when asked. | • Entity or fund name on the materials.
• Strategy and product consistent with the application. | • Materials describing a different product or entity than the one applying. | | **AML Comfort Letter** | `AML_COMFORT_LETTER` | • For investment funds: an AML attestation letter issued by the fund administrator. | • Issuer identity (the administrator), entity name, program scope (verification, monitoring, sanctions).
• Date and signature. | • Self-issued letters where an administrator's letter is required.
• Letters with no detail on the actual program. | | **E Signature Certificate** | `E_SIGNATURE_CERTIFICATE` | • The completion certificate from your signing platform (e.g. DocuSign) for electronically signed onboarding documents.
• Your Certificate of incorporation is acceptable for this | • Signer identity, reference to the signed document, completion timestamp. | • A signed PDF submitted without its certificate when one is required.
• A certificate that doesn't match the signed document. | | **Flow of Funds** | `FLOW_OF_FUNDS` | • A short structured note covering four things: where funds come from (which institutions), why you're transacting, who you pay, and where funds go, plus expected monthly volume.
• Moving money for third parties? Add a simple funds-flow diagram. | • Volume squares with your declared revenue. A gap between the two is the fastest way to a follow-up question.
• Counterparties fit the business you've described. | • Round guesses with no relationship to the financials submitted.
• Moving money for other businesses or people without telling us first. Accounts can't process undisclosed third-party funds. If your model pays out for others, talk to us before you build the flow. | | **Evidence of Good Standing** | `EVIDENCE_OF_GOOD_STANDING` | • A recent certificate of good standing from your registry. Usually requested when the registry can't be verified automatically. | • Entity legal name, jurisdiction, active status, recent issue date. | • Stale certificates.
• The entity shown as inactive or struck off. | | **Proof of Nature of Business License** | `PROOF_OF_NATURE_OF_BUSINESS_LICENSE` | • Regulated activity (payments, FX, crypto services, lending, gambling, holding client funds): your license or registration.
• Not regulated: a signed one-line statement confirming no money-services or virtual-asset registration applies to you. | • License in the exact legal name of the applying entity.
• Regulator, number, scope, and validity.
• The licensed activity matches the activity in the application. | • Regulated activity left undisclosed. This alone is grounds for rejection.
• A license held by a group company instead of the applying entity. | | **Proof of Nature of Business AML Policy** | `PROOF_OF_NATURE_OF_BUSINESS_AML_POLICY` | • Your AML policy. Required alongside the license whenever you conduct money-services or regulated activity. | • Entity name and a named responsible officer.
• Customer verification procedures, transaction monitoring, sanctions screening. | • Generic templates with no company specifics.
• A policy naming a different entity. | | **Proof of Account Purpose** | `PROOF_OF_ACCOUNT_PURPOSE` | • A clear narrative of how you'll use the account: payments, settlement, treasury, or operational flows.
• State upfront whether you'll create virtual accounts for your end customers. | • The purpose is consistent with your business model and your flow of funds.
• Substantiation where the purpose is higher-risk, such as paying out to third parties. | • A stated purpose that conflicts with the described model.
• Third-party payout intent left undisclosed. | # High Risk Activities Source: https://developer.fin.com/guides/customers-and-compliance/high-risk-activities Understanding disclosure requirements and prohibited activities for business customers ## Disclosure Requirements All business customers must disclose any high-risk activities during the onboarding process. This disclosure is essential for regulatory compliance and proper risk assessment. ### Activities Requiring Disclosure The following business activities are classified as high-risk and must be disclosed upfront: * **Money Services** - Check cashing, gift card sales, ATM operations, remittance services * **Lending or Banking Services** - Providing loans, credit, or banking products * **Foreign Exchange Operations** - Currency exchange, virtual currency brokerage, or over-the-counter trading * **Client Fund Management** - Holding funds on behalf of clients, including escrow services * **Third-Party Payment Processing** - Processing payments for other businesses or merchants Disclosure of these activities does not guarantee approval. Each case is evaluated individually based on regulatory requirements and risk factors. ## Prohibited Activities The following business activities are explicitly prohibited under Fin.com's Terms of Service and will result in account termination. ### Illegal or Harmful Activities * Unlawful or abusive activity * Unfair, predatory, or deceptive practices * Fraud or fraudulent schemes * Intellectual property infringement * Counterfeit or unauthorized goods ### Regulated Goods and Services * Weapons and firearms * Precious metals (gold, silver, etc.) * Jewelry and watches * Luxury goods * Pharmaceuticals * Tobacco products * Cannabis and cannabis-related products or services * Substances designed to mimic illegal drugs * Adult content and services ### Financial Services Restrictions * Investment or credit services (provided by customers to third parties via Fin.com) * Digital asset exchange services (provided by customers to third parties via Fin.com) * Money services businesses (provided by customers to third parties via Fin.com) * Money transmission services (provided by customers to third parties via Fin.com) * Check cashing services * Bail bonds * Safe deposit box rentals * Mixing services ### Gaming and Chance-Based Activities * Games of chance * Gambling operations * Sweepstakes * Lotteries * Unlawful prediction markets ### Other Prohibited Activities * Collections agencies * Multi-level marketing schemes * Any business that Fin.com determines poses elevated financial risk, legal liability, or violates payment services provider rules, card network rules, or banking partner policies ## Compliance Process During onboarding, our compliance team will review your business activities and documentation to ensure alignment with regulatory requirements and our risk policies. Complete and accurate disclosure helps expedite the approval process. If your business activities change after onboarding, you must notify Fin.com immediately to reassess your account status. ## Questions? If you're unsure whether your business activities require disclosure or fall under prohibited categories, please contact your account manager or reach out to [**compliance@fin.com**](mailto:compliance@fin.com) for guidance. # Individual Identifying documents Source: https://developer.fin.com/guides/customers-and-compliance/individual-identifying-documents Document requirements for individual customers and for the associated parties of a business customer. Fin.com verifies every natural person through two document categories: an **identifying document** that proves who they are, and an **address document** that proves where they live. This applies both to an individual customer and to each associated party (owner, director, or controlling person) of a business customer. Files must be uploaded first through the [Upload document](/api-reference/customers/upload-document) endpoint. The endpoint returns a URI that you then reference in the `files` array of the attach request. ## Where documents are submitted | Person | Endpoint | | :----------------------------- | :---------------------------------------------------------------------------------------------------------------- | | Individual customer | [Attach Documents to Individual Customer V2](/api-reference/customers/attach-documents-to-individual-customer-v2) | | Associated party of a business | [Attach Documents to Associated Party](/api-reference/customers/attach-documents-to-associated-party-v2) | ## Identifying documents Accepted government-issued identity documents, and the number of images each one needs: | Type | Description | Files | | :----------------- | :-------------------------- | :--------------------------------------------------------------- | | `PASSPORT` | Passport | 1 (side optional) | | `NATIONAL_ID` | National ID card | 2 (one `FRONT`, one `BACK`) | | `DRIVERS_LICENSE` | Driver's license | 2 (one `FRONT`, one `BACK`) | | `RESIDENCE_PERMIT` | Residence permit | Individual customer: 2 (`FRONT` and `BACK`). Associated party: 1 | | `SELFIE` | Live selfie of the customer | 1 (individual customer only) | Requirements that apply to every identifying document: * The document must not be expired. `expiry_date` must be a future date. * `number`, `country`, and `expiry_date` are required for all types except `SELFIE`. * `state` is required when `type` is `DRIVERS_LICENSE` and `country` is `USA`. It is optional for a license issued elsewhere and is not accepted for other document types. * Images must be clear, uncropped, and show the full document including any machine-readable zone. ## Recommended documents for USD SWIFT virtual accounts and payouts To issue USD SWIFT virtual accounts and enable USD SWIFT payouts for your customers, upload an identification document that matches the recommended type for its issuing country. While other accepted document types may pass basic verification, they might prevent virtual account issuance or payout features. | Issuing country | Recommended identifying documents | | :------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------- | | **Afghanistan** (`AFG`) | `PASSPORT` | | **Angola** (`AGO`) | `PASSPORT`, `NATIONAL_ID` | | **Anguilla** (`AIA`) | `PASSPORT` | | **Albania** (`ALB`) | `PASSPORT`, `NATIONAL_ID` | | **Andorra** (`AND`) | `PASSPORT` | | **United Arab Emirates** (`ARE`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Argentina** (`ARG`) | `PASSPORT`, `NATIONAL_ID` | | **Armenia** (`ARM`) | `PASSPORT`, `NATIONAL_ID` | | **American Samoa** (`ASM`) | `PASSPORT`, `NATIONAL_ID` | | **Antigua and Barbuda** (`ATG`) | `PASSPORT` | | **Australia** (`AUS`) | `PASSPORT`, `RESIDENCE_PERMIT` | | **Austria** (`AUT`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Azerbaijan** (`AZE`) | `PASSPORT`, `NATIONAL_ID` | | **Belgium** (`BEL`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Benin** (`BEN`) | `PASSPORT`, `NATIONAL_ID` | | **Burkina Faso** (`BFA`) | `PASSPORT`, `NATIONAL_ID` | | **Bangladesh** (`BGD`) | `PASSPORT`, `NATIONAL_ID` | | **Bulgaria** (`BGR`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Bahrain** (`BHR`) | `PASSPORT`, `NATIONAL_ID` | | **Bahamas** (`BHS`) | `PASSPORT` | | **Bosnia and Herzegovina** (`BIH`) | `PASSPORT`, `NATIONAL_ID` | | **Saint Barthélemy** (`BLM`) | `PASSPORT` | | **Belarus** (`BLR`) | `PASSPORT`, `NATIONAL_ID` | | **Belize** (`BLZ`) | `PASSPORT` | | **Bermuda** (`BMU`) | `PASSPORT`, `RESIDENCE_PERMIT` | | **Bolivia** (`BOL`) | `PASSPORT`, `NATIONAL_ID` | | **Brazil** (`BRA`) | `PASSPORT`, `DRIVERS_LICENSE`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Barbados** (`BRB`) | `PASSPORT`, `NATIONAL_ID` | | **Brunei Darussalam** (`BRN`) | `PASSPORT` | | **Bhutan** (`BTN`) | `PASSPORT` | | **Botswana** (`BWA`) | `PASSPORT`, `NATIONAL_ID` | | **Central African Republic** (`CAF`) | `PASSPORT` | | **Canada** (`CAN`) | `PASSPORT` | | **Switzerland** (`CHE`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Chile** (`CHL`) | `PASSPORT`, `NATIONAL_ID` | | **China** (`CHN`) | `PASSPORT`, `RESIDENCE_PERMIT` | | **Côte d'Ivoire** (`CIV`) | `PASSPORT`, `NATIONAL_ID` | | **Cameroon** (`CMR`) | `PASSPORT`, `NATIONAL_ID` | | **Congo, The Democratic Republic of the** (`COD`) | `PASSPORT` | | **Congo** (`COG`) | `PASSPORT`, `NATIONAL_ID` | | **Colombia** (`COL`) | `PASSPORT` | | **Comoros** (`COM`) | `PASSPORT` | | **Cabo Verde** (`CPV`) | `PASSPORT` | | **Costa Rica** (`CRI`) | `PASSPORT`, `NATIONAL_ID` | | **Cuba** (`CUB`) | `PASSPORT` | | **Curaçao** (`CUW`) | `PASSPORT`, `NATIONAL_ID` | | **Cayman Islands** (`CYM`) | `PASSPORT` | | **Cyprus** (`CYP`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Czechia** (`CZE`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Germany** (`DEU`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Djibouti** (`DJI`) | `PASSPORT` | | **Dominica** (`DMA`) | `PASSPORT`, `NATIONAL_ID` | | **Denmark** (`DNK`) | `PASSPORT`, `RESIDENCE_PERMIT` | | **Dominican Republic** (`DOM`) | `PASSPORT`, `NATIONAL_ID` | | **Algeria** (`DZA`) | `PASSPORT`, `NATIONAL_ID` | | **Ecuador** (`ECU`) | `PASSPORT`, `NATIONAL_ID` | | **Egypt** (`EGY`) | `PASSPORT`, `NATIONAL_ID` | | **Eritrea** (`ERI`) | `PASSPORT` | | **Spain** (`ESP`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Estonia** (`EST`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Ethiopia** (`ETH`) | `PASSPORT`, `NATIONAL_ID` | | **Finland** (`FIN`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Fiji** (`FJI`) | `PASSPORT` | | **France** (`FRA`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Faroe Islands** (`FRO`) | `PASSPORT` | | **Micronesia, Federated States of** (`FSM`) | `PASSPORT` | | **Gabon** (`GAB`) | `PASSPORT` | | **United Kingdom** (`GBR`) | `PASSPORT`, `RESIDENCE_PERMIT` | | **Georgia** (`GEO`) | `PASSPORT`, `NATIONAL_ID` | | **Guernsey** (`GGY`) | `PASSPORT`, `RESIDENCE_PERMIT` | | **Ghana** (`GHA`) | `PASSPORT`, `NATIONAL_ID` | | **Gibraltar** (`GIB`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Guinea** (`GIN`) | `PASSPORT` | | **Gambia** (`GMB`) | `PASSPORT`, `NATIONAL_ID` | | **Guinea-Bissau** (`GNB`) | `PASSPORT` | | **Equatorial Guinea** (`GNQ`) | `PASSPORT`, `NATIONAL_ID` | | **Greece** (`GRC`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Grenada** (`GRD`) | `PASSPORT`, `NATIONAL_ID` | | **Greenland** (`GRL`) | `PASSPORT` | | **Guatemala** (`GTM`) | `PASSPORT`, `NATIONAL_ID` | | **Guam** (`GUM`) | `PASSPORT` | | **Guyana** (`GUY`) | `PASSPORT`, `NATIONAL_ID` | | **Hong Kong** (`HKG`) | `PASSPORT`, `NATIONAL_ID` | | **Honduras** (`HND`) | `PASSPORT`, `NATIONAL_ID` | | **Croatia** (`HRV`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Haiti** (`HTI`) | `PASSPORT`, `NATIONAL_ID` | | **Hungary** (`HUN`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Indonesia** (`IDN`) | `PASSPORT` | | **Isle of Man** (`IMN`) | `PASSPORT`, `RESIDENCE_PERMIT` | | **India** (`IND`) | `PASSPORT`, `RESIDENCE_PERMIT` | | **Ireland** (`IRL`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Iceland** (`ISL`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Israel** (`ISR`) | `PASSPORT` | | **Italy** (`ITA`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Jamaica** (`JAM`) | `PASSPORT`, `NATIONAL_ID` | | **Jersey** (`JEY`) | `PASSPORT`, `RESIDENCE_PERMIT` | | **Jordan** (`JOR`) | `PASSPORT`, `NATIONAL_ID` | | **Japan** (`JPN`) | `PASSPORT`, `RESIDENCE_PERMIT` | | **Kazakhstan** (`KAZ`) | `PASSPORT`, `NATIONAL_ID` | | **Kenya** (`KEN`) | `PASSPORT` | | **Kyrgyzstan** (`KGZ`) | `PASSPORT`, `NATIONAL_ID` | | **Cambodia** (`KHM`) | `PASSPORT`, `NATIONAL_ID` | | **Kiribati** (`KIR`) | `PASSPORT` | | **Saint Kitts and Nevis** (`KNA`) | `PASSPORT`, `NATIONAL_ID` | | **South Korea** (`KOR`) | `PASSPORT`, `RESIDENCE_PERMIT` | | **Kuwait** (`KWT`) | `PASSPORT`, `NATIONAL_ID` | | **Laos** (`LAO`) | `PASSPORT`, `NATIONAL_ID` | | **Lebanon** (`LBN`) | `PASSPORT` | | **Liberia** (`LBR`) | `PASSPORT` | | **Libya** (`LBY`) | `PASSPORT` | | **Saint Lucia** (`LCA`) | `PASSPORT`, `NATIONAL_ID` | | **Liechtenstein** (`LIE`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Sri Lanka** (`LKA`) | `PASSPORT` | | **Lesotho** (`LSO`) | `PASSPORT` | | **Lithuania** (`LTU`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Luxembourg** (`LUX`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Latvia** (`LVA`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Macao** (`MAC`) | `PASSPORT` | | **Saint Martin (French part)** (`MAF`) | `PASSPORT` | | **Morocco** (`MAR`) | `PASSPORT`, `NATIONAL_ID` | | **Monaco** (`MCO`) | `PASSPORT`, `NATIONAL_ID` | | **Moldova** (`MDA`) | `PASSPORT`, `NATIONAL_ID` | | **Madagascar** (`MDG`) | `PASSPORT`, `NATIONAL_ID` | | **Maldives** (`MDV`) | `PASSPORT` | | **Mexico** (`MEX`) | `PASSPORT`, `RESIDENCE_PERMIT` | | **Marshall Islands** (`MHL`) | `PASSPORT` | | **North Macedonia** (`MKD`) | `PASSPORT`, `NATIONAL_ID` | | **Mali** (`MLI`) | `PASSPORT` | | **Malta** (`MLT`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Myanmar** (`MMR`) | `PASSPORT` | | **Montenegro** (`MNE`) | `PASSPORT`, `NATIONAL_ID` | | **Mongolia** (`MNG`) | `PASSPORT`, `NATIONAL_ID` | | **Mozambique** (`MOZ`) | `PASSPORT`, `NATIONAL_ID` | | **Mauritania** (`MRT`) | `PASSPORT`, `NATIONAL_ID` | | **Montserrat** (`MSR`) | `PASSPORT` | | **Mauritius** (`MUS`) | `PASSPORT`, `NATIONAL_ID` | | **Malawi** (`MWI`) | `PASSPORT`, `NATIONAL_ID` | | **Malaysia** (`MYS`) | `PASSPORT` | | **Namibia** (`NAM`) | `PASSPORT` | | **Niger** (`NER`) | `PASSPORT` | | **Nigeria** (`NGA`) | `PASSPORT`, `DRIVERS_LICENSE`, `NATIONAL_ID` | | **Nicaragua** (`NIC`) | `PASSPORT` | | **Netherlands** (`NLD`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Norway** (`NOR`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Nepal** (`NPL`) | `PASSPORT`, `NATIONAL_ID` | | **Nauru** (`NRU`) | `PASSPORT` | | **New Zealand** (`NZL`) | `PASSPORT`, `RESIDENCE_PERMIT` | | **Oman** (`OMN`) | `PASSPORT`, `NATIONAL_ID` | | **Pakistan** (`PAK`) | `PASSPORT` | | **Panama** (`PAN`) | `PASSPORT`, `NATIONAL_ID` | | **Peru** (`PER`) | `PASSPORT`, `NATIONAL_ID` | | **Philippines** (`PHL`) | `PASSPORT`, `NATIONAL_ID` | | **Palau** (`PLW`) | `PASSPORT` | | **Papua New Guinea** (`PNG`) | `PASSPORT` | | **Poland** (`POL`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Puerto Rico** (`PRI`) | `PASSPORT` | | **Portugal** (`PRT`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Paraguay** (`PRY`) | `PASSPORT`, `NATIONAL_ID` | | **Palestine, State of** (`PSE`) | `PASSPORT`, `NATIONAL_ID` | | **Qatar** (`QAT`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Romania** (`ROU`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Russian Federation** (`RUS`) | `PASSPORT` | | **Rwanda** (`RWA`) | `PASSPORT`, `NATIONAL_ID` | | **Saudi Arabia** (`SAU`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Sudan** (`SDN`) | `PASSPORT` | | **Senegal** (`SEN`) | `PASSPORT`, `NATIONAL_ID` | | **Singapore** (`SGP`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Solomon Islands** (`SLB`) | `PASSPORT` | | **Sierra Leone** (`SLE`) | `PASSPORT` | | **El Salvador** (`SLV`) | `PASSPORT`, `NATIONAL_ID` | | **San Marino** (`SMR`) | `PASSPORT`, `NATIONAL_ID` | | **Somalia** (`SOM`) | `PASSPORT`, `NATIONAL_ID` | | **Serbia** (`SRB`) | `PASSPORT`, `NATIONAL_ID` | | **South Sudan** (`SSD`) | `PASSPORT` | | **Sao Tome and Principe** (`STP`) | `PASSPORT` | | **Suriname** (`SUR`) | `PASSPORT`, `NATIONAL_ID` | | **Slovakia** (`SVK`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Slovenia** (`SVN`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Sweden** (`SWE`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Eswatini** (`SWZ`) | `PASSPORT` | | **Sint Maarten (Dutch part)** (`SXM`) | `NATIONAL_ID` | | **Seychelles** (`SYC`) | `PASSPORT`, `NATIONAL_ID` | | **Syria** (`SYR`) | `PASSPORT`, `NATIONAL_ID` | | **Turks and Caicos Islands** (`TCA`) | `PASSPORT` | | **Chad** (`TCD`) | `PASSPORT` | | **Togo** (`TGO`) | `PASSPORT`, `NATIONAL_ID` | | **Thailand** (`THA`) | `PASSPORT`, `NATIONAL_ID` | | **Tajikistan** (`TJK`) | `PASSPORT` | | **Turkmenistan** (`TKM`) | `PASSPORT` | | **Timor-Leste** (`TLS`) | `PASSPORT` | | **Tonga** (`TON`) | `PASSPORT` | | **Trinidad and Tobago** (`TTO`) | `PASSPORT`, `NATIONAL_ID` | | **Tunisia** (`TUN`) | `PASSPORT`, `NATIONAL_ID` | | **Türkiye** (`TUR`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Tuvalu** (`TUV`) | `PASSPORT` | | **Taiwan** (`TWN`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Tanzania** (`TZA`) | `PASSPORT`, `NATIONAL_ID` | | **Uganda** (`UGA`) | `PASSPORT`, `NATIONAL_ID` | | **Ukraine** (`UKR`) | `PASSPORT` | | **Uruguay** (`URY`) | `PASSPORT`, `NATIONAL_ID` | | **United States** (`USA`) | `PASSPORT`, `DRIVERS_LICENSE` (only when the residential address country is `USA`), `NATIONAL_ID` (only when the residential address country is `USA`) | | **Uzbekistan** (`UZB`) | `PASSPORT`, `NATIONAL_ID` | | **Saint Vincent and the Grenadines** (`VCT`) | `PASSPORT`, `NATIONAL_ID` | | **Venezuela** (`VEN`) | `PASSPORT`, `NATIONAL_ID` | | **Virgin Islands, U.S.** (`VIR`) | `PASSPORT` | | **Vietnam** (`VNM`) | `PASSPORT`, `NATIONAL_ID` | | **Vanuatu** (`VUT`) | `PASSPORT` | | **Samoa** (`WSM`) | `PASSPORT` | | **Kosovo** (`XKX`) | `PASSPORT`, `NATIONAL_ID` | | **Yemen** (`YEM`) | `PASSPORT`, `NATIONAL_ID` | | **South Africa** (`ZAF`) | `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT` | | **Zambia** (`ZMB`) | `PASSPORT`, `NATIONAL_ID` | | **Zimbabwe** (`ZWE`) | `PASSPORT`, `NATIONAL_ID` | ## Address documents Address documents must be dated within the last 90 days and must show the person's full name and residential address. | Type | Description | | :------------------ | :------------------------------------------------ | | `UTILITY_BILL` | Utility bill in the person's name | | `GOVERNMENT_LETTER` | Letter or notice issued by a government authority | | `BANK_STATEMENT` | Bank or financial institution statement | For an individual customer, exactly one address document is required and its `country` must match the customer's `country_of_residence`. Tax identification numbers are captured separately from these documents. See [Individual Tax ID documents](/guides/compliance/individual-tax-id-documents) for the accepted type per country. ## Individual document best practices ### Image and file requirements JPG, JPEG, PNG, and PDF. The file must be an original photo, a scan, or a screenshot — and screenshots are only accepted if the country and document type configuration explicitly allows them (most don't by default). Minimum specs: * File size at least **100 KB** or resolution at least **300 DPI** (one of the two, not both). * Image must be in **color** — black-and-white scans are rejected. * All four corners of the document must be visible inside the frame. * No foreign objects or graphic elements covering the document. * The image must not have been edited with software or converted to PDF after capture. * Information on the document must be readable — no blur, glare, or shadows obscuring data. All of the following must be clearly visible and machine-readable: * Owner's full name * Date of birth * Document number * Photo of the owner * Signature (if the document includes one) * MRZ — Machine Readable Zone (the two or three rows of characters at the bottom of passports and many ID cards) * Validity data — issue date or expiry/validity period If any of these are unreadable, automated text extraction will fail and the document will be flagged for review or rejected. ### Document handling As a general rule: * **Passports** — usually 1 image (the photo page). Some configurations require the full double-page spread. * **ID cards, driver's licenses, residence permits** — both sides required. Per-country settings determine the exact requirement, with four possible options: document not allowed, front side only, both sides required, or either side accepted. When both sides are required, you must upload the second side after the first — otherwise the verification step stays incomplete and the user can't be moved forward for review. Generally **no**. Digital documents lack the physical security features (holograms, raised printing, watermarks) that authenticity checks rely on, which makes them easier to forge. Specific countries can be configured to accept digital versions on a case-by-case basis. If you're unsure whether a particular country allows digital documents, check the configuration first. Not by default. Screenshots are rejected outright in most cases. There's a per-country setting that can be enabled if there's a legitimate reason to allow them, but it's off by default. Photos of a screen (as opposed to true screenshots) are also rejected — they're treated separately as suspected tampering. Yes, notarized copies of identity documents are accepted. However, **documents issued in breakaway regions are not accepted by default.** Expired documents are not accepted. As a cautionary measure, the document's expiry date should be at least **one year away** from the date of submission. This avoids the banking partner coming back later asking for a fresh set of documents when the current one expires. Documents in 40+ languages from 220+ countries and territories are processed, including Korean, Japanese, Chinese, Cyrillic, and Semitic scripts. There are two exception groups: * **Latin characters only** for: Amharic, Bengali, Burmese, Dari, Dhivehi, Hindi, Khmer (Cambodian), Kinyarwanda, Mongolian, Nepali, and Sinhalese. If a document is submitted in the local script, a notarized Latin translation must be provided. * **Available on request, additional cost**: Arabic, Farsi, Urdu, Lao. Yes. Proof of Address documents (such as bank statements, utility bills, rental agreements) do not need to be in English. However, if the document is in a different language, it must be accompanied by a **certified English translation** to ensure accurate review. ### Upload guidance Two pieces of information are mandatory with every document upload: the **document type** (passport, ID card, driver's license, residence permit, etc.) and the **issuing country**. Additional details — document number, issue date, date of birth, place of birth — are optional but recommended; sending them upfront speeds up processing and improves match accuracy. Each side is uploaded as a separate image with a marker indicating whether it's the front or back. For a two-sided document, you must upload both — uploading only the front leaves the verification step incomplete and the user cannot be moved forward for review. Yes. Upload responses will surface warnings or errors immediately for the first few attempts on a given document — use this to prompt the user to retry before marking them as ready for review. After several attempts on the same document, warnings stop appearing on the upload response and any issues will only be caught during the full verification check, which is slower and more disruptive for the user. ### Common rejection and warning reasons | Reason | What it means | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | **Forbidden document** | The document type or country isn't supported, or isn't acceptable for this verification level. | | **Document type or country mismatch** | What was detected in the image doesn't match the document type or country you declared, and the detected type is forbidden by your settings. | | **Missing important information** | Required fields (name, DOB, document number, etc.) couldn't be extracted from the image. | | **No readable data** | Nothing recognizable in the image — usually means it's blank, corrupted, or not actually a document. | | **Expired document** | The document's validity date has passed, and your configuration doesn't allow expired documents. | | **Document cropped** | Parts of the document are cut off at the edges of the photo. | | **No face photo on document** | The face photo on the document isn't clearly visible. | | **Poor selfie quality** | Face on the selfie isn't clearly visible (when comparing selfie to document). | | **Photo of a screen** | The image looks like a photo taken of a screen, not the original document. | | **Screenshot** | The image is a digital screenshot (and screenshots aren't enabled for this country/document). | | **Same side uploaded twice** | The same side of the document was uploaded as both the front and back. | | **Missing MRZ** | The document type sent should have a Machine Readable Zone, but no readable MRZ was found. | | **Missing second side** | The document type requires both sides; only one was sent. | | **Missing double-page spread** | The full double-page spread is required (typical for some passport configurations); only one page was sent. | | **Previously declined image** | This exact image was uploaded and declined earlier for the same user. A different photo is required. | Warnings don't block the upload but signal something to keep an eye on: | Warning | What it means | | ------------------------------------ | ----------------------------------------------------------------------------------------- | | **Bad selfie** | Face and document photo aren't both clearly visible on the selfie — user should retake. | | **Borderline readability** | Information on the document is hard to read — image quality is on the edge of acceptable. | | **Inconsistent documents** | Uploaded photos look like they might not all be of the same document. | | **Possibly expired** | Document appears to be expired but wasn't rejected outright. | | **Document partially outside frame** | Document doesn't fully fit in the photo frame. | ### Verification outcomes and resubmission The user is approved and you receive a positive verification webhook. You can fetch their full data afterwards if you need it for downstream processing. Failures come in two flavors, and they mean very different things: * **Final rejection** — the user is permanently blocked from this verification and cannot resubmit. This is rare (about 1–2% of cases) and typically means a fake account or forged documents. Block them in your system and direct them to support. * **Retry rejection** — the user has fixable issues. They can resubmit only the problematic step (no need to redo the whole flow). Each problematic verification step comes with a human-readable comment explaining what went wrong. Show that comment to the user. Example: *"The text on your identity document is not clearly visible. Upload a new photo."* Have them re-upload only the problematic document, mark them as ready for review again, and wait for the next verification result. Yes. Verification status is not permanent. A user approved today might appear on a sanctions list or blocklist next week, and you'll receive a negative status webhook for that change. Your webhook handler must deal with downgrades, not just upgrades. ### Edge cases and gotchas This is one of the most common upload mistakes. Even though the photo itself is well-framed, if the document's own edges are cut off — corners outside the frame, edges flush against the photo border, or the document extending past what the camera captured — the upload will be rejected. **All four corners of the document must be visible inside the photo**, with a small margin of background around them. Tell users: hold the document so the entire card or page sits inside the frame with space around it. The verification step will not complete. The user cannot be moved forward for review. Always upload the back side after the front for two-sided documents. The upload will be rejected with a same-side error. Both images will be marked inactive. Re-upload with the correct front and back. Re-uploads merge, they don't replace cleanly. If a document of the same type and country already exists for that user: any new metadata fields you send will **overwrite** the existing values, but the new image is **added alongside** the existing one, not replacing it. If you want to invalidate an old image, you need to mark it inactive explicitly. You'll get a previously-declined error. Rejected images are remembered per user — they must take a new photo, not re-submit the same file. If a user uploads a passport, then later uploads a utility bill or a selfie, all of those must match the same person. A passport for John Smith and a driver's license for Jane Doe in the same user profile = inconsistency warning and likely rejection. If you've sent user data (name, DOB, etc.) for cross-checking and it disagrees with what's extracted from the document, the user gets flagged with a problematic-data label. Make sure your application lets users edit their data *before* they hit submit, so they can correct typos rather than face rejection. If the document type or issuing country detected by the verification system doesn't match what you declared during upload, your declared values may be **overwritten** by what was actually detected. If your downstream systems depend on those values, always compare what you sent against what comes back in the response. Yes — and for the Latin-only language list (see "What languages are supported?" above), notarized translations are required if the document is in the local script. Damaged documents are not accepted. The user needs to obtain a replacement from the issuing authority before they can complete verification. # Individual Tax ID documents Source: https://developer.fin.com/guides/customers-and-compliance/individual-tax-id-documents The following lists tax ID types that Fin.com will accept for Individuals and associated parties by region. Pass `OTHER` for the countries not listed below | Region | Identification Type | | :----------------------------------------------------------------- | :-------------------------------------------------------------------- | | **Aruba** - (`ABW`) | `OTHER` - Please provide a description of the document being provided | | **Afghanistan** - (`AFG`) | `TIN` - Tax Identification Number | | **Angola** - (`AGO`) | `NIF` - Número de Identificação Fiscal | | **Albania** - (`ALB`) | `TIN` - Tax Identification Number | | **Andorra** - (`AND`) | `OTHER` - Please provide a description of the document being provided | | **United Arab Emirates** - (`ARE`) | `EMIRATES_ID` - National Identity Card | | **Argentina** - (`ARG`) | `CUIL` - Código Único de Identificación Laboral | | **Argentina** - (`ARG`) | `CDI` - Código de Identificación | | **Argentina** - (`ARG`) | `DNI` - Documento Nacional de Identidad | | **Armenia** - (`ARM`) | `TIN` - Tax Identification Number | | **Australia** - (`AUS`) | `TFN` - Tax File Number | | **Austria** - (`AUT`) | `SI` - Social Insurance Number | | **Azerbaijan** - (`AZE`) | `VOEN` - State Taxpayer Identification Number | | **Belgium** - (`BEL`) | `NRN` - National Register Number | | **Bangladesh** - (`BGD`) | `TIN` - Tax Identification Number | | **Bulgaria** - (`BGR`) | `UCN` - Unified Civil Number | | **Bahrain** - (`BHR`) | `CPR` - Central Population Registry Number | | **Bahamas** - (`BHS`) | `OTHER` - Please provide a description of the document being provided | | **Bosnia and Herzegovina** - (`BIH`) | `JMBG` - Unique Master Citizen Number | | **Belize** - (`BLZ`) | `OTHER` - Please provide a description of the document being provided | | **Bermuda** - (`BMU`) | `OTHER` - Please provide a description of the document being provided | | **Bolivia (Plurinational State of)** - (`BOL`) | `NIT` - Número de Identificación Tributaria | | **Brazil** - (`BRA`) | `CPF` - Cadastro de Pessoas Físicas | | **Barbados** - (`BRB`) | `NRN` - National Registration Number | | **Botswana** - (`BWA`) | `TIN` - Tax Identification Number | | **Canada** - (`CAN`) | `SIN` - Social Insurance Number | | **Switzerland** - (`CHE`) | `AVS` - AHV Number | | **Switzerland** - (`CHE`) | `AHV` - Old Age and Survivors Insurance Number | | **Chile** - (`CHL`) | `RUT` - Registro Único Tributario | | **China** - (`CHN`) | `RICN` - Resident Identity Card Number | | **Côte d'Ivoire** - (`CIV`) | `NIF` - Número de Identificação Fiscal | | **Cameroon** - (`CMR`) | `NIF` - Número de Identificação Fiscal | | **Colombia** - (`COL`) | `NIT` - Número de Identificación Tributaria | | **Colombia** - (`COL`) | `RUT` - Registro Único Tributario | | **Comoros** - (`COM`) | `NIF` - Número de Identificação Fiscal | | **Costa Rica** - (`CRI`) | `TIN` - Tax Identification Number | | **Curaçao** - (`CUW`) | `CRIB` - Chamber of Commerce Registration Number | | **Christmas Island** - (`CXR`) | `TFN` - Tax File Number | | **Cayman Islands** - (`CYM`) | `OTHER` - Please provide a description of the document being provided | | **Cyprus** - (`CYP`) | `TIN` - Tax Identification Number | | **Czechia** - (`CZE`) | `RC` - Residence Code Number | | **Germany** - (`DEU`) | `STEUER_ID` - Steueridentifikationsnummer (Tax Identification Number) | | **Dominica** - (`DMA`) | `TIN` - Tax Identification Number | | **Denmark** - (`DNK`) | `CPR` - Central Person Register Number | | **Dominican Republic** - (`DOM`) | `TIN` - Tax Identification Number | | **Algeria** - (`DZA`) | `NIF` - Número de Identificação Fiscal | | **Ecuador** - (`ECU`) | `RUC` - Registro Único de Contribuyentes | | **Egypt** - (`EGY`) | `TIN` - Tax Identification Number | | **Spain** - (`ESP`) | `NIF` - Número de Identificación Fiscal | | **Spain** - (`ESP`) | `NIE` - Número de Identificación de Extranjeros | | **Estonia** - (`EST`) | `IK` - Individual Code | | **Ethiopia** - (`ETH`) | `TIN` - Tax Identification Number | | **Finland** - (`FIN`) | `HETU` - Finnish Personal Identity Code | | **Fiji** - (`FJI`) | `TIN` - Tax Identification Number | | **France** - (`FRA`) | `SPI` - Social Security Number | | **United Kingdom of Great Britain and Northern Ireland** - (`GBR`) | `NINO` - National Insurance Number | | **United Kingdom of Great Britain and Northern Ireland** - (`GBR`) | `UTR` - Unique Taxpayer Reference Number | | **Georgia** - (`GEO`) | `TIN` - Tax Identification Number | | **Ghana** - (`GHA`) | `TIN` - Tax Identification Number | | **Gibraltar** - (`GIB`) | `CRC` - Company Registration Number | | **Greece** - (`GRC`) | `AOM` - Αριθμός Μητρώου (Social Security Number) | | **Guatemala** - (`GTM`) | `NIT` - Número de Identificación Tributaria | | **Hong Kong** - (`HKG`) | `HKID` - Hong Kong Identity Card Number | | **Honduras** - (`HND`) | `RTN` - Registro Tributario Nacional | | **Croatia** - (`HRV`) | `OIB` - Personal Identification Number | | **Haiti** - (`HTI`) | `NIF` - Número de Identificação Fiscal | | **Hungary** - (`HUN`) | `TIN` - Tax Identification Number | | **Indonesia** - (`IDN`) | `NPWP` - Nomor Pokok Wajib Pajak | | **Isle of Man** - (`IMN`) | `NINO` - National Insurance Number | | **India** - (`IND`) | `PAN` - Permanent Account Number | | **Ireland** - (`IRL`) | `PPSN` - Personal Public Service Number | | **Iraq** - (`IRQ`) | `TIN` - Tax Identification Number | | **Iceland** - (`ISL`) | `TIN` - Tax Identification Number | | **Israel** - (`ISR`) | `TIN` - Tax Identification Number | | **Italy** - (`ITA`) | `CF` - Codice Fiscale (Tax Code) | | **Jamaica** - (`JAM`) | `TRN` - Taxpayer Registration Number | | **Jordan** - (`JOR`) | `TIN` - Tax Identification Number | | **Japan** - (`JPN`) | `MN` - My Number (Individual Number) | | **Kazakhstan** - (`KAZ`) | `IIN` - Individual Identification Number | | **Kenya** - (`KEN`) | `PIN` - Personal Identification Number | | **Kyrgyzstan** - (`KGZ`) | `INN` - Individual Taxpayer Number | | **Cambodia** - (`KHM`) | `TIN` - Tax Identification Number | | **Saint Kitts and Nevis** - (`KNA`) | `OTHER` - Please provide a description of the document being provided | | **Korea (Republic of)** - (`KOR`) | `RRN` - Resident Registration Number | | **Kuwait** - (`KWT`) | `TIN` - Tax Identification Number | | **Lao People's Democratic Republic** - (`LAO`) | `TIN` - Tax Identification Number | | **Lebanon** - (`LBN`) | `OTHER` - Please provide a description of the document being provided | | **Liberia** - (`LBR`) | `TIN` - Tax Identification Number | | **Saint Lucia** - (`LCA`) | `TIN` - Tax Identification Number | | **Sri Lanka** - (`LKA`) | `NIC` - National Identity Card Number | | **Lithuania** - (`LTU`) | `AK` - Personal Code | | **Luxembourg** - (`LUX`) | `MATRICULE` - Matricule Number (Social Security Number) | | **Latvia** - (`LVA`) | `PK` - Person’s Code | | **Morocco** - (`MAR`) | `IF` - Identification Fiscal | | **Monaco** - (`MCO`) | `OTHER` - Please provide a description of the document being provided | | **Moldova (Republic of)** - (`MDA`) | `IDNP` - Identification Number of the Person | | **Madagascar** - (`MDG`) | `NIF` - Número de Identificação Fiscal | | **Mexico** - (`MEX`) | `RFC` - Registro Federal de Contribuyentes | | **Mexico** - (`MEX`) | `CURP` - Clave Única de Registro de Población | | **Mexico** - (`MEX`) | `INE` - Instituto Nacional Electoral | | **Marshall Islands** - (`MHL`) | `OTHER` - Please provide a description of the document being provided | | **North Macedonia** - (`MKD`) | `EMBG` - Unique Identification Number | | **Malta** - (`MLT`) | `TIN` - Tax Identification Number | | **Montenegro** - (`MNE`) | `JMBG` - Unique Master Citizen Number | | **Mozambique** - (`MOZ`) | `NUIT` - Número Único de Identificação Tributária | | **Mauritania** - (`MRT`) | `NIF` - Número de Identificação Fiscal | | **Mauritius** - (`MUS`) | `NICN` - National Identity Card Number | | **Malawi** - (`MWI`) | `TPIN` - Taxpayer Identification Number | | **Malaysia** - (`MYS`) | `ITR` - Income Tax Reference Number | | **Namibia** - (`NAM`) | `TIN` - Tax Identification Number | | **Nigeria** - (`NGA`) | `TIN` - Tax Identification Number | | **Nigeria** - (`NGA`) | `NIN` - National Identification Number | | **Nigeria** - (`NGA`) | `BVN` - Bank Verification Number | | **Nicaragua** - (`NIC`) | `RUC` - Registro Único de Contribuyentes | | **Netherlands** - (`NLD`) | `BSN` - Burgerservicenummer (Citizen Service Number) | | **Norway** - (`NOR`) | `FN` - Fødselsnummer (Personal Identification Number) | | **Nepal** - (`NPL`) | `PAN` - Permanent Account Number | | **New Zealand** - (`NZL`) | `IRD` - Inland Revenue Department Number | | **Oman** - (`OMN`) | `TIN` - Tax Identification Number | | **Pakistan** - (`PAK`) | `NTN` - National Tax Number | | **Panama** - (`PAN`) | `RUC` - Registro Único de Contribuyentes | | **Peru** - (`PER`) | `RUC` - Registro Único de Contribuyentes | | **Philippines** - (`PHL`) | `TIN` - Tax Identification Number | | **Poland** - (`POL`) | `PESEL` - Personal Identification Number | | **Puerto Rico** - (`PRI`) | `SSN` - Social Security Number | | **Portugal** - (`PRT`) | `NIF` - Número de Identificação Fiscal | | **Paraguay** - (`PRY`) | `RUC` - Registro Único de Contribuyentes | | **Qatar** - (`QAT`) | `QID` - Qatar ID | | **Romania** - (`ROU`) | `CNP` - Cod Numeric Personal | | **Rwanda** - (`RWA`) | `TIN` - Tax Identification Number | | **Saudi Arabia** - (`SAU`) | `TIN` - Tax Identification Number | | **Saudi Arabia** - (`SAU`) | `RP` - Iqama (Residency Permit) | | **Senegal** - (`SEN`) | `TIN` - Tax Identification Number | | **Singapore** - (`SGP`) | `NRIC` - National Registration Identity Card | | **Singapore** - (`SGP`) | `FIN` - Foreign Identification Number | | **El Salvador** - (`SLV`) | `NIT` - Número de Identificación Tributaria | | **Somalia** - (`SOM`) | `TIN` - Tax Identification Number | | **Serbia** - (`SRB`) | `JMBG` - Unique Master Citizen Number | | **Suriname** - (`SUR`) | `TIN` - Tax Identification Number | | **Slovakia** - (`SVK`) | `RC` - Rodné Číslo (Personal Identification Number) | | **Slovenia** - (`SVN`) | `TIN` - Tax Identification Number | | **Sweden** - (`SWE`) | `TIN` - Tax Identification Number | | **Seychelles** - (`SYC`) | `TIN` - Tax Identification Number | | **Turks and Caicos Islands** - (`TCA`) | `OTHER` - Please provide a description of the document being provided | | **Togo** - (`TGO`) | `NIF` - Número de Identificação Fiscal | | **Thailand** - (`THA`) | `TIN` - Tax Identification Number | | **Trinidad and Tobago** - (`TTO`) | `BIR` - Business Identification Number | | **Tunisia** - (`TUN`) | `MF` - Matricule Fiscal | | **Türkiye** - (`TUR`) | `TCKN` - Turkish Citizenship Number | | **Taiwan, Province of China** - (`TWN`) | `TIN` - Tax Identification Number | | **Tanzania, United Republic of** - (`TZA`) | `TIN` - Tax Identification Number | | **Uganda** - (`UGA`) | `TIN` - Tax Identification Number | | **Ukraine** - (`UKR`) | `RNOKPP` - Registration Number of the Taxpayer | | **Uruguay** - (`URY`) | `RUT` - Registro Único Tributario | | **Uruguay** - (`URY`) | `CI` - Cédula de identidad | | **United States of America** - (`USA`) | `SSN` - Social Security Number | | **United States of America** - (`USA`) | `ITIN` - Individual Taxpayer Identification Number | | **Uzbekistan** - (`UZB`) | `INN` - Individual Identification Number | | **Saint Vincent and the Grenadines** - (`VCT`) | `TIN` - Tax Identification Number | | **Venezuela (Bolivarian Republic of)** - (`VEN`) | `RIF` - Registro de Información Fiscal | | **Virgin Islands (British)** - (`VGB`) | `OTHER` - Please provide a description of the document being provided | | **Viet Nam** - (`VNM`) | `MST` - Mã Số Thuế (Tax Code) | | **Vanuatu** - (`VUT`) | `OTHER` - Please provide a description of the document being provided | | **Samoa** - (`WSM`) | `OTHER` - Please provide a description of the document being provided | | **Yemen** - (`YEM`) | `TIN` - Tax Identification Number | | **South Africa** - (`ZAF`) | `ITR` - Income Tax Reference Number | | **Zambia** - (`ZMB`) | `TPIN` - Taxpayer Identification Number | | **Zimbabwe** - (`ZWE`) | `TIN` - Tax Identification Number | # Guidance on nested payments & onboarding Source: https://developer.fin.com/guides/customers-and-compliance/nested-payments-and-onboarding How Fin handles nested payments & onboarding ## What "nesting" means Nesting is the use of a virtual account to serve customers of the account holder without those customers being onboarded and monitored as Fin customers in their own right. It is a form of hidden financial intermediation, and it is prohibited by Fin's regulators and banking partners. Nesting is prohibited if you: * collect funds from multiple third parties into a virtual account you hold, and then pay those parties out to different recipients on their behalf; or * use your virtual account to run any activity typical of a bank, money services business, payment service provider, e-money institution, virtual asset service provider, prepaid provider, or similar business, unless you have disclosed that activity to Fin in advance and received written acceptance. These commitments are set out in Fin's Virtual Account No-Nesting Terms, which every developer and every end customer accepts at Virtual Account onboarding. *** ## How Fin works with developers and their customers Fin is a B2B infrastructure platform. Developers integrate with Fin's APIs to offer financial services to their own customers. Here is how the relationship works: 1. **Fin onboards the developer.** We perform KYB on the developer's business, review their AML policies, onboarding criteria, and customer risk assessment framework. Once approved, the developer can use Fin's APIs. At onboarding, the developer also accepts Fin's Developer No-Nesting Terms. 2. **Each end customer must be onboarded individually.** Fin requires every customer (individual or business) to go through KYC or KYB via Fin's platform before they can receive a virtual account or transact. There are no exceptions to this. At onboarding, each end customer also accepts Fin's Customer No-Nesting Terms. 3. **Virtual accounts are issued per onboarded entity.** Once a customer passes verification and meets our banking partner's eligibility criteria, they receive their own virtual account. The developer themselves also receives a virtual account as part of their onboarding, if eligible. Image From Developer Fin Fin does not contact a developer's end customers directly. All customer communication is handled by the developer. *** ## Every account holder must be the beneficial owner of funds Every account holder must be the beneficial owner of the funds in their virtual account. That means the funds must belong to the account holder, even if they are paid in by a named third party such as a customer, supplier, or payment processor. The account holder must also be onboarded with Fin. What Fin does not support is nesting, meaning using a virtual account to receive funds that beneficially belong to someone else who has not been onboarded with Fin. This includes pooling funds from multiple third parties, operating as a money services business, payment service provider, or financial institution through Fin's infrastructure, or otherwise acting as an intermediary for undisclosed downstream customers. ### What "beneficial ownership" means in practice The funds in a virtual account must beneficially belong to the account holder. Where they are paid in by a named third party, the account holder must be able to demonstrate a legitimate business relationship with that third party. **Example: Agency or drop-shipping business** A drop-shipping store onboarded with Fin receives a payment from a supplier or buyer. This is acceptable if: * The payment is tied to a specific invoice or contract. * The account holder can provide documentation (invoice, purchase order, contract) linking the payment to their business activity. * Compliance may request these documents for any inbound transaction that does not originate from the account holder's own named bank account. **Example: Funds received from a payment processor (Stripe, Nuvei, etc.)** A business sells products online and collects payments through a payment processor like Stripe or Nuvei. The processor then settles funds into the business's Fin virtual account. This is permitted, provided: * The business has a verified account with the payment processor under the same legal name as the entity onboarded with Fin. * Fin will require a letter or document confirming the account relationship between the business and the payment processor. Because the funds beneficially belong to the account holder even though they arrive via a processor, this is permitted. **Example: Nested flow (not supported)** A developer or account holder receives a virtual account and instructs multiple third parties to send funds directly into it, pooling money from parties who have not themselves been onboarded with Fin. This is not permitted. Each transacting party must be individually onboarded and issued their own virtual account. **Example: Disclosed financial intermediary (permitted with prior acceptance)** If your business is a licensed money services business, payment service provider, or similar financial intermediary and you wish to use a virtual account in that capacity, you must disclose this to Fin in advance during onboarding. Fin will assess the relationship separately and either accept, condition, or decline it. Do not begin transacting on that basis without written acceptance from Fin. *** ## Documents Fin may request for higher-risk or high-volume activity For payments that are high in value, high in volume, or that raise compliance questions, Fin will request the following if they were not already provided at onboarding: 1. Purpose of the payment. 2. Proof supporting the purpose (e.g., invoice, contract, or purchase order). 3. Source of funds. 4. Proof of source of funds. 5. For customers based in or transacting to higher-risk jurisdictions, Fin may also request additional recipient and counterparty information. These requirements apply to any transaction pattern or jurisdiction that triggers a compliance review, regardless of the individual payment size. *** ## Restricted business activities Certain business types and activities cannot be facilitated through Fin. See [Restricted and High-Risk Businesses](/guides/compliance/high-risk-activities) for the full list. *** ## Frequently asked questions Yes, if the funds beneficially belong to you. Payments from a named third party, such as a payment processor (Stripe, Nuvei, Adyen), a supplier, or a customer of yours, are permitted where you can demonstrate a legitimate business relationship and the funds are yours. What is not permitted is receiving funds that beneficially belong to another person, for example by pooling money from multiple people who have not themselves been onboarded with Fin. Yes. Fin requires KYC (for individuals) or KYB (for businesses) on every customer before they can receive a virtual account or transact. You cannot use your own virtual account to receive funds on behalf of your customers. No. This is a nested flow and is not supported. Each customer must be onboarded separately and issued their own virtual account. Using a single account to pool third-party funds would classify the activity as operating a money service business, which Fin cannot facilitate. Yes, as long as you have a verified account with the payment processor under the same legal name as your Fin account, and you can provide a letter or document confirming the relationship. Because the funds beneficially belong to you, this is permitted. Fin's compliance team may flag the transaction and request supporting documentation such as an invoice, contract, or proof of business relationship. If the payment cannot be verified as legitimate first-party activity, it may be returned or the account may be restricted. Yes. As part of the developer onboarding process (KYB), if your entity meets the eligibility criteria of our banking partners, you will receive a virtual account automatically. Fin may request: (1) purpose of payment, (2) proof of purpose (invoice, contract), (3) source of funds, (4) proof of source of funds. In high-risk jurisdictions, recipient information may also be required. These are standard compliance requirements and apply to all high-volume activity. Not by default. Fin does not support developers using virtual accounts to run money service businesses, payment processing operations, or other financial institution activities without prior disclosure and written acceptance. If your business model does involve licensed intermediation, you must disclose this at onboarding. Fin will assess it separately and either accept, condition, or decline the relationship. See the restricted business activities page for the full list of activities Fin will not support. At Virtual Account onboarding, every developer accepts Fin's Developer No-Nesting Terms and every end customer accepts Fin's Customer No-Nesting Terms. These set out your commitment not to use a virtual account for nested activity, and Fin's rights if you do. Acceptance is a condition of Virtual Account issuance and continued availability. You can request a copy of the version you accepted at any time. # Onboarding Business Customers Source: https://developer.fin.com/guides/customers-and-compliance/onboarding-businesses Complete guide to onboarding business clients with company details, financial profiles, addresses, and associated parties. Onboard business customers to enable cross-border payments and payouts through Fin.com's platform. This guide walks you through creating business customer profiles, uploading verification documents, and managing the compliance workflow. ## Prerequisites \* Required field Before you begin, ensure you have: * **API credentials**: Client ID and secret from the [**API Keys**](https://orchestration.fin.com/api-keys) section * **Access token**: Generated via [**POST /v1/oauth/token**](https://developer.fin.com/api-reference/authentication/issue-a-token) * **Reference data**: Familiarity with [**GET /v1/purposes**](https://developer.fin.com/api-reference/catalogue/list-account-purposes), [**GET /v1/source-of-funds**](https://developer.fin.com/api-reference/catalogue/list-source-of-funds), and [**GET /v1/source-of-wealth**](https://developer.fin.com/api-reference/catalogue/list-source-of-wealth) endpoints *** ## Onboarding Steps | **Step** | **Endpoint** | **Description** | | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- | | 1. Fetch Reference Data | [**GET /v1/purposes?type=BUSINESS**](https://developer.fin.com/api-reference/catalogue/list-account-purposes), [**GET /v1/source-of-funds?type=BUSINESS**](https://developer.fin.com/api-reference/catalogue/list-source-of-funds), [**GET /v1/source-of-wealth?type=BUSINESS**](https://developer.fin.com/api-reference/catalogue/list-source-of-wealth) | Retrieve valid integer IDs for purpose, source of funds, and source of wealth | | 2. Create Customer | [**POST /v2/customers/business**](https://developer.fin.com/api-reference/customers/create-business-customer-v2) | Submit company details, addresses, financial profile, and associated parties | | 3. Upload Documents | [**POST /v1/customers/upload**](https://developer.fin.com/api-reference/customers/upload-document) | Upload business and associated party documents | | 4. Attach Business Docs | [**POST /v2/customers/:customer-id/business/attach**](https://developer.fin.com/api-reference/customers/attach-documents-to-business-customer-v2) | Link formation, ownership, and supporting documents with TOS acceptance | | 5. Attach Party Docs | [**POST /v2/customers/:customer-id/associated-parties/individual/attach**](https://developer.fin.com/api-reference/customers/attach-document-to-associated-party-v2) | Link identity and address proofs for each associated party | | 6. Monitor Status | Webhooks: `customer.status`, `customer.rfi` | Track verification progress (`INCOMPLETE` → `REVIEWING` → `APPROVED`) | *** ## Request Body Structure ### Verification Type (Optional) Verification type determines how customer identity is validated. `STANDARD` uses traditional document verification (default). `RELIANCE` leverages third-party KYB data when enabled for your client. ```json theme={null} { "verification_type": "STANDARD" } ``` The `verification_type` field is optional and defaults to `STANDARD` if omitted. **RELIANCE verification** must be explicitly enabled for your client. If not available, you'll receive a `423` error with message: `"RELIANCE is not available for your client"` *** ### Industry Codes (Required) NAICS 2022 6-digit industry codes describing the business. Minimum 1 item required. ```json theme={null} { "industry_codes": ["541513", "541519"] } ``` | **Field** | **Type** | **Description** | | :---------------------------- | :-------- | :------------------------------------ | | `industry_codes`\* | string\[] | NAICS 2022 6-digit codes. Min 1 item. | Get the full list of industry codes [**here**](https://developer.fin.com/business-industry-codes). *** ### Basic Information (Required) Company details exactly as shown on incorporation documents. All fields must use only English (Latin) characters. | **Field** | **Type** | **Description** | | :-------------------------------------- | :-------- | :--------------------------------------------------------------------- | | `legal_name`\* | string | Official registered business name. Max 255 chars. | | `legal_name_en` | string | English translation of the legal name. Required if non-ASCII. | | `trade_name` | string | Common/operating name (DBA). | | `trade_name_en` | string | English translation of trade name. | | `description`\* | string | Business purpose and activities. Max 500 chars. | | `entity_type`\* | string | Legal entity type. See entity types table below. | | `email`\* | string | Business email address — **must be all lowercase**. | | `phone`\* | string | Business phone in E.164 format. | | `incorporation_date`\* | string | Date of incorporation in `YYYY-MM-DD` format. Cannot be a future date. | | `country_of_incorporation`\* | string | ISO Alpha-3 country code. | | `registration_number`\* | string | Business registration / company number. | | `legal_entity_identifier` | string | LEI code (20-character alphanumeric). | | `is_dao` | boolean | Whether the entity is a Decentralized Autonomous Organization. | | `tax_info`\* | object\[] | Tax/identifying documents. Min 1 item. See Tax Info below. | | `websites`\* | string\[] | Business website URLs. Min 1 item. | **Tax Info object (`tax_info[]`):** | **Field** | **Type** | **Description** | | :--------------------------- | :------- | :----------------------------------------- | | `country_code`\* | string | ISO Alpha-3 issuing country. | | `document_type`\* | string | Document type code, validated per country. | | `document_id`\* | string | The tax ID or registration number. | **Valid Entity Types:** | **Entity Type** | **Description** | | :-------------------- | :----------------------------- | | `LLC` | Limited Liability Company | | `PUBLICLY_LISTED` | Publicly traded company | | `CORPORATION` | Corporation (Inc, Corp) | | `SOLE_PROPRIETORSHIP` | Sole Proprietorship | | `PARTNERSHIP` | Partnership | | `PRIVATE_FOUNDATION` | Private Foundation | | `CHARITY` | Charitable Organization | | `NON_PROFIT` | Non-profit Organization | | `GOVERNMENT_AGENCY` | Government Agency or Authority | Email must be **all lowercase** or validation will fail: `contact@acmecorp.com` ✓ not `Contact@AcmeCorp.com` ✗ Example: ```json theme={null} { "basic_info": { "legal_name": "Acme Corp Ltd", "legal_name_en": "Acme Corp Ltd", "trade_name": "Acme", "trade_name_en": "Acme", "description": "International software and payments company providing cross-border B2B services", "entity_type": "CORPORATION", "email": "contact@acmecorp.com", "phone": "+14155552671", "incorporation_date": "2018-06-15", "country_of_incorporation": "USA", "registration_number": "12-3456789", "legal_entity_identifier": "549300EXAMPLE0001X23", "is_dao": false, "tax_info": [ { "country_code": "USA", "document_type": "EIN", "document_id": "12-3456789" } ], "websites": ["https://acmecorp.com", "https://acmepayments.com"] } } ``` *** ### Financial Profile (Required) Describes account purpose, transaction volumes, and fund sources. Use reference endpoints to fetch valid integer IDs. | **Field** | **Type** | **Description** | **How to Get Value** | | :---------------------------------------------- | :--------- | :------------------------------------------------------------------------------ | :--------------------------------------- | | `purpose_id`\* | integer | Account purpose. | `GET /v1/purposes?type=BUSINESS` | | `purpose_remarks` | string | Additional context for the account purpose. | User input | | `source_of_fund_ids`\* | integer\[] | Source(s) of business funds. Min 1. Order from largest to smallest contributor. | `GET /v1/source-of-funds?type=BUSINESS` | | `source_of_funds_description` | string | Additional context for source of funds. | User input | | `source_of_wealth_ids`\* | integer\[] | Source(s) of owner's wealth. Min 1. | `GET /v1/source-of-wealth?type=BUSINESS` | | `estimated_annual_revenue_usd`\* | integer | Estimated annual revenue in USD. Must be >= 0. | User estimate: `5000000` | | `expected_monthly_deposits_usd`\* | integer | Expected monthly inflow in USD. Must be >= 0. | User estimate: `400000` | | `expected_monthly_withdrawals_usd`\* | integer | Expected monthly outflow in USD. Must be >= 0. | User estimate: `350000` | | `expected_transaction_value_usd` | integer | Typical single transaction value in USD. | User estimate: `50000` | | `expected_monthly_transaction_count` | integer | Expected number of transactions per month. | User estimate: `20` | | `third_party_fund_usage` | boolean | Whether third-party funds will be processed. | User confirmation | **Third-Party Fund Usage**: Set to `true` **only if** this business will be processing, holding, or moving funds on behalf of other parties (e.g., payment processors, escrow services, MSBs). This triggers enhanced compliance review. For most normal businesses (SaaS, import/export, consulting), `third_party_fund_usage` should be `false`. `purpose_id`, `source_of_fund_ids`, and `source_of_wealth_ids` are integer foreign keys — not string enums. Always fetch valid IDs from the reference endpoints before submitting. Use `source_of_funds_description` (not `sof_remarks`) for additional context on source of funds. Enter all amounts in whole USD dollars — `50000` = \$50,000, not cents. Example: ```json theme={null} { "financial_profile": { "purpose_id": 3, "purpose_remarks": "Cross-border B2B payments for international suppliers", "source_of_fund_ids": [13, 16], "source_of_funds_description": "Revenue generated from software licensing and SaaS subscriptions", "source_of_wealth_ids": [2], "estimated_annual_revenue_usd": 5000000, "expected_monthly_deposits_usd": 400000, "expected_monthly_withdrawals_usd": 350000, "expected_transaction_value_usd": 50000, "expected_monthly_transaction_count": 20, "third_party_fund_usage": false } } ``` In this example: `purpose_id: 3` = Cross-border payments, `source_of_fund_ids: [13, 16]` = IDs from the source-of-funds catalogue, `estimated_annual_revenue_usd: 5000000` = \$5,000,000 USD (integer, not cents). *** ### Addresses (Required) Registered and operational addresses for the business. | **Field** | **Description** | | :------------------------------------------ | :----------------------------------------------------------------------- | | `is_incorporated_address_same`\* | `true` if physical and incorporated addresses are identical | | `incorporated_address`\* | Registered address from incorporation documents | | `physical_address` | Operating address — required only if different from incorporated address | **Address object:** | **Field** | **Type** | **Description** | | :------------------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------ | | `street_line_1`\* | string | Primary street address. P.O. Boxes not accepted. | | `street_line_2` | string | Secondary address (suite, floor, etc.). | | `street_line_1_en` | string | English translation. Required if non-ASCII. | | `street_line_2_en` | string | English translation of street line 2. | | `city`\* | string | City name. Max 100 chars. | | `state`\* | string | State/province code from [**/v1/countries/subdivisions**](https://developer.fin.com/api-reference/catalogue/list-subdivisions). | | `subdivision_code`\* | string | State/province code from [**/v1/countries/subdivisions**](https://developer.fin.com/api-reference/catalogue/list-subdivisions). | | `postal_code`\* | string | ZIP or postal code. | | `country`\* | string | ISO Alpha-3 country code. | **Avoid P.O. Boxes** — Use verifiable street addresses for both incorporated and physical addresses. P.O. Boxes may be rejected during verification. Example: ```json theme={null} { "addresses": { "is_incorporated_address_same": false, "incorporated_address": { "street_line_1": "123 Main Street", "street_line_2": "Suite 400", "street_line_1_en": "123 Main Street", "street_line_2_en": "Suite 400", "city": "San Francisco", "state": "US-CA", "subdivision_code": "US-CA", "postal_code": "94105", "country": "USA" }, "physical_address": { "street_line_1": "789 Market Street", "street_line_2": "Floor 10", "city": "San Francisco", "state": "US-CA", "subdivision_code": "US-CA", "postal_code": "94103", "country": "USA" } } } ``` *** ### Associated Parties (Minimum 1 Required) Each business customer must have at least one associated party. At least one party must hold **both** `shareholder` and `ubo` roles simultaneously. A single person can hold both roles. Each associated party must include: **`basic_info`:** | **Field** | **Type** | **Description** | | :---------------------------------- | :-------- | :---------------------------------------------------------------- | | `first_name`\* | string | First name. Max 50 chars. | | `middle_name` | string | Middle name(s). | | `last_name`\* | string | Last/family name. Max 50 chars. | | `first_name_en` | string | English transliteration. Required if non-ASCII. | | `middle_name_en` | string | English transliteration of middle name. | | `last_name_en` | string | English transliteration. Required if non-ASCII. | | `dob`\* | string | Date of birth `YYYY-MM-DD`. Party must be at least 18 years old. | | `email`\* | string | Personal email. Must be unique across all parties in the request. | | `phone`\* | string | Phone in E.164 format. | | `country_of_residence`\* | string | ISO Alpha-3 country code. | | `primary_nationality`\* | string | ISO Alpha-3 country code. | | `secondary_nationality` | string | ISO Alpha-3 for dual citizens. | | `tax_info` | object\[] | Tax/ID documents. Same structure as business `tax_info`. | **`address`:** Residential address using the same Address object structure as business addresses. **`roles` (required):** | **Value** | **Description** | | :------------ | :------------------------------------------------------------------------- | | `shareholder` | Has a shareholding stake in the business | | `ubo` | Ultimate Beneficial Owner — exercises control or has significant ownership | At least one associated party must hold **both** `shareholder` and `ubo` roles. A single party can hold both: `"roles": ["shareholder", "ubo"]` **`ownership_info` (required when `roles` includes `ubo`):** | **Field** | **Type** | **Description** | | :--------------------------------------------- | :------- | :------------------------------------------------------- | | `designation`\* | string | Title or position. Max 100 chars. | | `percentage_of_ownership`\* | float | Ownership stake as a percentage (0–100). | | `relationship_establishment_date`\* | string | When relationship with the business began. `YYYY-MM-DD`. | | `has_control`\* | boolean | Whether this party has significant control. | | `is_signer`\* | boolean | Whether this party is an authorized signatory. | | `is_director`\* | boolean | Whether this party serves as a director. | **Ownership Validation**: Total ownership percentages across all associated parties must be > 0.01% and \< 100%. Individual parties may have a `percentage_of_ownership` of 0. Example: ```json theme={null} { "associated_parties": [ { "ref": "owner-001", "basic_info": { "first_name": "John", "middle_name": "Michael", "last_name": "Doe", "first_name_en": "John", "middle_name_en": "Michael", "last_name_en": "Doe", "dob": "1985-03-20", "email": "john.doe@acmecorp.com", "phone": "+14155551234", "country_of_residence": "USA", "primary_nationality": "USA", "secondary_nationality": "GBR", "tax_info": [ { "country_code": "USA", "document_type": "SSN", "document_id": "123-45-6789" } ] }, "address": { "street_line_1": "456 Oak Avenue", "street_line_2": "Apt 12B", "city": "San Francisco", "state": "US-CA", "subdivision_code": "US-CA", "postal_code": "94102", "country": "USA" }, "roles": ["shareholder", "ubo"], "ownership_info": { "designation": "CEO & Founder", "percentage_of_ownership": 60.0, "relationship_establishment_date": "2018-06-15", "has_control": true, "is_signer": true, "is_director": true } }, { "ref": "owner-002", "basic_info": { "first_name": "Jane", "last_name": "Doe", "dob": "1988-07-12", "email": "jane.doe@acmecorp.com", "phone": "+14155555678", "country_of_residence": "USA", "primary_nationality": "USA", "tax_info": [ { "country_code": "USA", "document_type": "SSN", "document_id": "987-65-4321" } ] }, "address": { "street_line_1": "321 Pine Street", "city": "San Francisco", "state": "US-CA", "subdivision_code": "US-CA", "postal_code": "94108", "country": "USA" }, "roles": ["ubo"], "ownership_info": { "designation": "CTO & Co-Founder", "percentage_of_ownership": 40.0, "relationship_establishment_date": "2018-06-15", "has_control": false, "is_signer": false, "is_director": false } } ] } ``` *** ### Holding Structure (Optional) For businesses with corporate shareholders or foreign branches. | **Field** | **Type** | **Description** | | :------------------------------------ | :-------- | :--------------------------------------------------------- | | `has_material_intermediary_ownership` | boolean | Whether any intermediary holds a material ownership stake. | | `corporate_shareholders` | object\[] | List of corporate shareholders. See below. | | `foreign_branches` | object\[] | List of foreign branch registrations. See below. | **Corporate Shareholder object:** | **Field** | **Type** | **Description** | | :--------------------------------------- | :------- | :------------------------------------------ | | `entity_name`\* | string | Corporate shareholder's legal name. | | `entity_name_en` | string | English translation. Required if non-ASCII. | | `registration_country_code`\* | string | ISO Alpha-3 country of registration. | | `ownership_percentage`\* | float | Ownership stake (0–100). | | `registration_number` | string | Entity registration number. | | `entity_type` | string | Type of entity. | | `incorporation_date` | string | Incorporation date `YYYY-MM-DD`. | **Foreign Branch object:** | **Field** | **Type** | **Description** | | :--------------------------------------- | :------- | :-------------------------------------------------- | | `registration_country_code`\* | string | ISO Alpha-3 country where the branch is registered. | | `name` | string | Branch name. | | `registration_number` | string | Branch registration number. | Example: ```json theme={null} { "holding_structure": { "has_material_intermediary_ownership": true, "corporate_shareholders": [ { "entity_name": "Acme Ventures LLC", "entity_name_en": "Acme Ventures LLC", "registration_country_code": "USA", "ownership_percentage": 0.0, "registration_number": "98-7654321", "entity_type": "LLC", "incorporation_date": "2015-03-01" } ], "foreign_branches": [ { "registration_country_code": "GBR", "name": "Acme Corp UK Branch", "registration_number": "BR000123" }, { "registration_country_code": "SGP", "name": "Acme Corp Singapore Branch", "registration_number": "T18FC0001A" } ] } } ``` *** ### Public Listings (Optional) For publicly traded companies. | **Field** | **Type** | **Description** | | :-------------- | :------- | :--------------------------------------------------------- | | `mic` | string | ISO 10383 Market Identifier Code. | | `isin` | string | International Securities Identification Number (12 chars). | | `ticker_symbol` | string | Stock exchange ticker. | Example: ```json theme={null} { "public_listings": [ { "mic": "XNAS", "isin": "US0231351067", "ticker_symbol": "ACME" } ] } ``` *** ### Compliance (Optional) For regulated businesses, MSBs, and high-risk industries. | **Field** | **Type** | **Description** | | :------------------------------------------------ | :------- | :---------------------------------------------------------- | | `operates_in_prohibited_countries` | boolean | Whether the business operates in OFAC/sanctioned countries. | | `additional_description_for_compliance_screening` | string | Free-text compliance notes for manual review. | | `risk_profile` | object | Risk classification details. See Risk Profile below. | | `regulated_activity` | object | Regulatory licensing details. See Regulated Activity below. | | `aml` | object | AML/CFT program details. See AML below. | **Risk Profile (`risk_profile`):** | **Field** | **Type** | **Description** | | :------------------------------------ | :-------- | :------------------------------------------------------------------ | | `high_risk_activities` | string\[] | High-risk activities the business engages in. | | `high_risk_activities_explanation` | string | Explanation of declared activities. Required if array is non-empty. | | `conducts_money_services` | boolean | Whether the business provides money services. | | `conducts_money_services_via_fin` | boolean | Whether money services are provided via financial intermediaries. | | `conducts_money_services_description` | string | Details about the money services offered. | Valid `high_risk_activities` values: `adult_entertainment`, `crypto_exchange`, `gambling`, `cannabis`, `weapons`, `money_services`, `cross_border_payments` **Regulated Activity (`regulated_activity`):** | **Field** | **Type** | **Description** | | :-------------------------------------------- | :------- | :----------------------------------------------- | | `description`\* | string | Description of the regulated activity. | | `primary_authority_country_code`\* | string | ISO Alpha-3 country of the regulatory authority. | | `primary_authority_name`\* | string | Name of the primary regulatory authority. | | `license_number`\* | string | Regulatory license or registration number. | **AML (`aml`):** | **Field** | **Type** | **Description** | | :----------------------------------------------------- | :-------- | :------------------------------------------------------------------ | | `supervisory_authority_name` | string | Name of the AML supervisory authority. | | `license_number` | string | AML license number. | | `has_appointed_mlro` | boolean | Whether a Money Laundering Reporting Officer has been appointed. | | `customer_risk_split` | object | Breakdown of customer risk percentages. Must sum to 100. See below. | | `prohibits_anonymous_or_fictitious_accounts` | boolean | Policy on anonymous or fictitious accounts. | | `prohibits_accounts_for_unlicensed_or_shell_customers` | boolean | Policy on unlicensed or shell customers. | | `customer_identity_verification` | object | CDD verification method and system. See Verification Method below. | | `pep_and_sanctions_screening` | object | PEP/sanctions screening method and system. | | `sanction_lists` | string\[] | Sanction lists screened against. | | `customer_risk_classification_from_due_diligence` | boolean | Whether risk classification is based on due diligence. | | `enhanced_due_diligence_process` | boolean | Whether enhanced due diligence is in place. | | `transaction_monitoring` | object | Transaction monitoring method and system. | | `procedures_for_transaction_monitoring` | boolean | Whether formal TM procedures are documented. | | `subject_to_ml_or_tf_investigation` | string | Current ML/TF investigation status. | | `subject_to_regulatory_enforcement_past_2_years` | string | Regulatory enforcement history (last 2 years). | | `confirms_no_service_to_sanctioned_countries` | boolean | Confirmation of no services to sanctioned jurisdictions. | | `client_funds_accessibility` | string | Client fund accessibility policy. | | `aml_ctf_audit_completed` | boolean | Whether an AML/CTF audit has been completed. | | `planned_audit_date` | string | Planned next audit date. `YYYY-MM-DD`. | **Customer Risk Split object (`customer_risk_split`):** Represents how your customer base is distributed across risk tiers. These percentages reflect what proportion of your customers you classify as low, medium, or high risk based on your own due diligence process. | **Field** | **Type** | **Description** | | :------------------------- | :------- | :------------------------------------------------- | | `low_risk`\* | integer | Percentage of customers classified as low risk. | | `medium_risk`\* | integer | Percentage of customers classified as medium risk. | | `high_risk`\* | integer | Percentage of customers classified as high risk. | Percentages must sum to 100. **Verification Method object** (used by `customer_identity_verification`, `pep_and_sanctions_screening`, `transaction_monitoring`): | **Field** | **Type** | **Description** | | :-------------------- | :------- | :-------------------------------------------------------------------------- | | `method`\* | enum | How the verification is performed. One of: `automated`, `manual`, `hybrid`. | | `system`\* | string | The vendor or system used. Required when `method` is `automated`. | | **`method` value** | **Description** | | :----------------- | :----------------------------------------------------- | | `automated` | Fully system-driven verification with no manual review | | `manual` | Human-reviewed verification process | | `hybrid` | Combination of automated screening and manual review | Example: ```json theme={null} { "compliance": { "operates_in_prohibited_countries": false, "additional_description_for_compliance_screening": "We do not operate in any OFAC-sanctioned jurisdictions. All transactions are screened against OFAC, EU, and UN sanction lists in real time.", "risk_profile": { "high_risk_activities": ["adult_entertainment"], "high_risk_activities_explanation": "We facilitate cross-border B2B payments, which are subject to enhanced due diligence procedures.", "conducts_money_services": true, "conducts_money_services_via_fin": false, "conducts_money_services_description": "Licensed money transmitter providing international wire transfer services to business clients." }, "regulated_activity": { "description": "Licensed money transmitter operating under FinCEN registration and state-level MSB licenses", "primary_authority_country_code": "USA", "primary_authority_name": "FinCEN", "license_number": "MSB-12345678" }, "aml": { "supervisory_authority_name": "FinCEN", "license_number": "MSB-12345678", "has_appointed_mlro": true, "customer_risk_split": { "low_risk": 70, "medium_risk": 25, "high_risk": 5 }, "prohibits_anonymous_or_fictitious_accounts": true, "prohibits_accounts_for_unlicensed_or_shell_customers": true, "customer_identity_verification": { "method": "automated", "system": "Jumio" }, "pep_and_sanctions_screening": { "method": "automated", "system": "Dow Jones Risk & Compliance" }, "sanction_lists": ["OFAC", "EU", "UN", "HMT"], "customer_risk_classification_from_due_diligence": true, "enhanced_due_diligence_process": true, "transaction_monitoring": { "method": "automated", "system": "Actimize" }, "procedures_for_transaction_monitoring": true, "subject_to_ml_or_tf_investigation": "none", "subject_to_regulatory_enforcement_past_2_years": "none", "confirms_no_service_to_sanctioned_countries": true, "client_funds_accessibility": "closed_loop", "aml_ctf_audit_completed": true, "planned_audit_date": "2026-12-01" } } } ``` *** ### Metadata (Optional) Client-defined reference for internal tracking: ```json theme={null} { "meta_data": { "reference": "client-internal-ref-00123" } } ``` *** ## Document Upload & Attachment After creating the business customer, upload and attach verification documents. ### Step 1: Upload Documents Upload files using `multipart/form-data`: ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/customers/upload \ --header 'Authorization: Bearer ' \ --header 'Content-Type: multipart/form-data' \ --form 'customer_id=3fa85f64-5717-4562-b3fc-2c963f66afa6' \ --form 'file1=@/path/to/certificate_of_incorporation.pdf' \ --form 'file2=@/path/to/shareholder_registry.pdf' ``` **Allowed file types**: PDF, JPG, JPEG, PNG **Response:** ```json theme={null} { "data": { "files": [ { "file1": "/AbAcQ4hn_0652746727637.pdf" }, { "file2": "/XyZ123mn_0652746727638.pdf" } ] } } ``` Save these URIs — you'll use them in the attachment requests. *** ### Step 2: Attach Business Documents Link formation, ownership, and supporting documents to the business customer: ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v2/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/business/attach \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "formation_documents": [ { "type": "EVIDENCE_OF_DIRECTORS_AND_CONTROLLERS", "description": "Certificate of Incorporation", "files": [{ "uri": "/AbAcQ4hn_0652746727637.pdf" }] }, { "type": "REGISTRATION_DOCUMENT", "description": "Business registration doc", "files": [{ "uri": "/AbAcQ4hn_0652746727638.pdf" }] } ], "ownership_documents": [ { "type": "PROOF_OF_SIGNATORY_AUTHORITY", "description": "Shareholder Registry", "files": [{ "uri": "/XyZ123mn_0652746727639.pdf" }] } ], "supporting_documents": [ { "type": "PROOF_OF_SOURCE_OF_FUNDS", "files": [{ "uri": "/PoAdef45_0652746727640.pdf" }] }, { "type": "PROOF_OF_ADDRESS", "files": [{ "uri": "/PoAdef45_0652746727641.pdf" }] } ], "tos_policies_value": "f11e77c6-8dc0-4d4b-a3f2-ed84c8ccfc69" }' ``` The `tos_policies_value` should be parsed from the `tos_policies_url` query parameter returned when creating the customer. Providing this value signifies that the customer was shown the terms and accepted them. **Document Types:** | **Category** | **Type** | **Description** | | :--------------------- | :-------------------------------------- | :---------------------------------------------------------- | | `formation_documents` | `REGISTRATION_DOCUMENT` | Certificate of Incorporation / Registration Certificate | | `formation_documents` | `CONSTITUTIONAL_DOCUMENT` | Articles of Incorporation, Partnership Agreement | | `formation_documents` | `EVIDENCE_OF_DIRECTORS_AND_CONTROLLERS` | Evidence of all directors and controllers (non-US entities) | | `formation_documents` | `PROOF_OF_TAX_IDENTIFICATION` | Tax registration certificate | | `ownership_documents` | `SHAREHOLDER_REGISTER` | Shareholder registry or cap table | | `ownership_documents` | `PROOF_OF_SIGNATORY_AUTHORITY` | Power of attorney or equivalent | | `ownership_documents` | `DIRECTORS_REGISTRY` | Registry of directors and officers | | `ownership_documents` | `OWNERSHIP_CHART` | Org chart showing ownership | | `ownership_documents` | `CERT_OF_INCUMBENCY` | Certificate of incumbency | | `supporting_documents` | `PROOF_OF_ADDRESS` | Utility bill, lease agreement, or bank statement | | `supporting_documents` | `PROOF_OF_SOURCE_OF_FUNDS` | Documentation of business fund origins | | `supporting_documents` | `PROOF_OF_SOURCE_OF_WEALTH` | Supporting docs proving wealth origin | | `supporting_documents` | `AML_COMFORT_LETTER` | AML compliance letter from legal counsel | | `supporting_documents` | `FLOW_OF_FUNDS` | One-page fund flow statement or diagram | | `supporting_documents` | `MARKETING_MATERIALS` | Website, invoices, or business plan | | `supporting_documents` | `TAX_EXEMPT_ENTITY_CONFIRMATION` | Tax exemption certificate | | `supporting_documents` | `OTHER` | Any other supporting document | *** ### Step 3: Attach Associated Party Documents Attach identity and address documents for each associated party: ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v2/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/associated-parties/individual/attach \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "associated_party_attachments": [ { "associated_party_id": "5a42d32b-a23f-4b7f-9daf-1a9ceef0f0ea", "identifying_documents": [ { "type": "PASSPORT", "number": "A12345678", "country": "USA", "issue_date": "2020-01-15", "expiry_date": "2030-01-15", "files": [ { "uri": "/id_john_0652746727640.pdf" } ] }, { "type": "DRIVERS_LICENSE", "number": "DL987654321", "country": "USA", "issue_date": "2019-06-01", "expiry_date": "2029-06-01", "files": [ { "side": "FRONT", "uri": "/dl_front_john_0652746727641.pdf" }, { "side": "BACK", "uri": "/dl_back_john_0652746727642.pdf" } ] } ], "address_documents": [ { "type": "BANK_STATEMENT", "files": [ { "uri": "/bank_john_0652746727643.pdf" } ] } ] } ] }' ``` The `associated_party_id` is returned in the [**GET /v2/customers/:customer-id**](https://developer.fin.com/api-reference/customers/get-customer-details-v2) response after creating the business customer. For `NATIONAL_ID` and `DRIVERS_LICENSE`, you **must** provide both `FRONT` and `BACK` images using the `side` field. For `PASSPORT`, the `side` field is optional. **Identity Document Types:** | **Type** | **Description** | **Side Required** | | :----------------------- | :---------------------------------------------------- | :--------------------- | | `PASSPORT` | Passport | No (optional) | | `NATIONAL_ID` | National ID card | Yes (`FRONT` + `BACK`) | | `DRIVERS_LICENSE` | Driver's license | Yes (`FRONT` + `BACK`) | | `RESIDENCE_PERMIT` | Residence permit | No (optional) | | `PERMANENT_RESIDENCY_ID` | Permanent Residency / Green Card (USA residents only) | No (optional) | **Address Document Types:** | **Type** | **Description** | | :------------------ | :----------------------------------------- | | `UTILITY_BILL` | Recent utility bill (gas, electric, water) | | `BANK_STATEMENT` | Bank statement (within last 90 days) | | `GOVERNMENT_LETTER` | Official government correspondence | | `RESIDENCE_PERMIT` | Residence permit document | | `PASSPORT` | Passport showing address | | `NATIONAL_ID` | National ID showing address | | `DRIVERS_LICENSE` | Driver's license showing address | | `COMPANY_DOC` | Company document showing address | *** ## Customer Status & Webhooks After document submission, customers go through a verification workflow: **Status Lifecycle:** Business Customer Transition Flow **Webhook Events:** | **Event** | **Triggered When** | **Resulting Status** | | :----------------- | :---------------------------------------------- | :------------------- | | `customer.created` | Customer record is created | `INCOMPLETE` | | `customer.status` | Verification status changes | Varies | | `customer.rfi` | Compliance team requests additional information | `ACTION_REQUIRED` | Subscribe to webhooks to automate your onboarding flow. See [**Verifying Webhooks**](https://developer.fin.com/guides/webhooks/verifying-webhooks) for setup. *** ## Error Response Examples **Email validation error (not lowercase):** ```json theme={null} { "status": 400, "message": "Validation failed", "data": { "basic_info.email": "Must be a valid email address" } } ``` **RELIANCE not enabled:** ```json theme={null} { "status": 423, "message": "RELIANCE is not available for your client" } ``` **Ownership percentage validation:** ```json theme={null} { "status": 400, "message": "Validation failed", "data": { "associated_parties": "Total ownership percentages must be > 0 and < 100" } } ``` *** ## What's Next? ### 1. Monitor Verification Status * Subscribe to `customer.created`, `customer.status`, and `customer.rfi` webhooks * Handle status transitions: `INCOMPLETE` → `PROCESSING` → `REVIEWING` → `APPROVED` * For `ACTION_REQUIRED` status (triggered by `customer.rfi`), respond with the requested documents * See [**Webhook Verification**](https://developer.fin.com/guides/webhooks/verifying-webhooks) for implementation details ### 2. Test Edge Cases * ✓ Email with uppercase characters * ✓ Ownership percentages totaling > 100% * ✓ Non-Latin characters in text fields * ✓ Missing required fields * ✓ RELIANCE verification when not enabled * ✓ P.O. Box addresses ### 3. Production Checklist * Implemented webhook handling for status updates * Added proper error handling for all failure scenarios * Client-side validation for email lowercase * Fetched and cached reference data (purposes, source-of-funds, source-of-wealth) * Implemented document upload UI/flow * Reviewed [**High-Risk Business Activities**](https://developer.fin.com/guides/compliance/high-risk-activities) * Set up monitoring for failed verifications * Tested the complete workflow end-to-end ### 4. Create Beneficiaries Once your business customer is approved, you can create beneficiaries for payouts: * See [**Beneficiary Account Validation**](https://developer.fin.com/bank-account-and-routing-validation-rules) * Review [**Beneficiary Relationships**](https://developer.fin.com/guides/beneficiaries/sender-and-receiver-relationships) *** ## Common Pitfalls & Solutions | **Pitfall** | **Solution** | | :-------------------------------- | :----------------------------------------------------------------------------------------------- | | **Email validation fails** | Must be all lowercase before sending: `contact@acme.com` ✓ not `Contact@Acme.com` ✗ | | **RELIANCE 423 error** | RELIANCE must be enabled for your client. Contact support or use `STANDARD`. | | **Ownership percentage error** | Total across all parties must be \< 100%. Individual parties may have 0% ownership. | | **Non-Latin character rejection** | Use `legal_name_en`, `first_name_en`, `street_line_1_en` etc. for non-ASCII names and addresses. | | **P.O. Box address rejected** | Use verifiable street addresses. Avoid P.O. Boxes. | | **Phone format rejected** | Use E.164 format with country code: `+14155552671`, not `(415) 555-2671`. | | **Amount rejected** | Provide amount in USD as integer (not cents): `50000` for \$50,000. | | `purpose_id`**invalid** | Fetch valid IDs from `GET /v1/purposes?type=BUSINESS`. Do not use string enums. | | `source_of_fund_ids`**invalid** | Fetch valid IDs from `GET /v1/source-of-funds?type=BUSINESS`. | | `source_of_wealth_ids`**invalid** | Fetch valid IDs from `GET /v1/source-of-wealth?type=BUSINESS`. | *** *Last updated: April 2026 — Reflects V2 API (`POST /v2/customers/business`)* # Onboarding Individual Customers Source: https://developer.fin.com/guides/customers-and-compliance/onboarding-individuals Complete guide to onboarding individual customers with personal details, financial profiles, and identity verification Onboard individual customers to enable cross-border payments and payouts through Fin.com's platform. This guide walks you through creating individual customer profiles, uploading verification documents, and managing the compliance workflow using the **V2 API**. ## Prerequisites Before you begin, ensure you have: * **API credentials**: Client ID and secret from the [API Keys](https://orchestration.fin.com/api-keys) section * **Access token**: Generated via [POST /v1/oauth/token](/api-reference/authentication/issue-a-token) * **Catalogue data**: Familiarity with [/v1/occupations](/api-reference/catalogue/list-occupations), [/v1/purposes](/api-reference/catalogue/list-account-purposes), and [/v1/source-of-funds](/api-reference/catalogue/list-source-of-funds) endpoints ## Onboarding Steps | Step | Endpoint | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | 1. Fetch Catalogue Data | [GET /v1/occupations](/api-reference/catalogue/list-occupations), [GET /v1/purposes?type=INDIVIDUAL](/api-reference/catalogue/list-account-purposes), [GET /v1/source-of-funds?type=INDIVIDUAL](/api-reference/catalogue/list-source-of-funds) | Retrieve valid IDs for occupations, purposes, and fund sources | | 2. Create Customer | [POST /v2/customers/individual](/api-reference/customers/create-individual-customer-v2) | Submit personal details, address, and financial profile | | 3. Upload Documents | [POST /v1/customers/upload](/api-reference/customers/upload-document) | Upload identity, selfie, and address proof files | | 4. Attach Documents | Link uploaded documents to the customer (processed asynchronously) | | | 5. Monitor Status | Webhooks: `customer.status` | Track verification progress (INCOMPLETE → REVIEWING → APPROVED) | *** ## Request Body Structure ### Verification Type (Required) > **Verification type** determines how customer identity is validated. **STANDARD** uses traditional document verification. On **RELIANCE**, Fin.com relies on your KYC. Please contact our compliance team to know more. ```json theme={null} { "verification_type": "STANDARD" } ``` **RELIANCE verification** must be explicitly enabled for your client. If not available, you'll receive a 423 error with the message: `"RELIANCE is not available for your client"` ### Basic Information (Required) > Personal details exactly as shown on identity documents. **All fields must use only English (Latin) characters**. If any field contains non-ASCII characters, provide a transliterated value in the corresponding `_en` field. **Fields:** | Field | Type | Required | Description | Example | | ----------------------- | -------------- | ----------- | --------------------------------------------------------------------------------- | ---------------------------- | | `first_name` | string | Yes | Legal first name as shown on ID | `"María"` | | `first_name_en` | string | Conditional | English transliteration. Required if `first_name` contains non-ASCII characters. | `"Maria"` | | `middle_name` | string | No | Middle name | `"Elena"` | | `middle_name_en` | string | Conditional | English transliteration. Required if `middle_name` contains non-ASCII characters. | `"Elena"` | | `last_name` | string | Yes | Legal last name as shown on ID | `"García"` | | `last_name_en` | string | Conditional | English transliteration. Required if `last_name` contains non-ASCII characters. | `"Garcia"` | | `dob` | string (date) | Yes | Date of birth in YYYY-MM-DD format. Age must be between 18 and 120. | `"1990-04-15"` | | `email` | string (email) | Yes | Personal email address - **must be all lowercase** | `"maria.garcia@example.com"` | | `phone` | string | Yes | Phone number in E.164 format | `"+14155552671"` | | `country_of_residence` | string | Yes | ISO Alpha-3 country code where person resides | `"USA"` | | `primary_nationality` | string | Yes | ISO Alpha-3 country code of primary citizenship | `"USA"` | | `secondary_nationality` | string | No | ISO Alpha-3 country code of secondary citizenship | `"MEX"` | | `gender` | string | No | `MALE` or `FEMALE` | `"FEMALE"` | | `tax_info` | array | Yes | Tax identification documents (see below) | -- | Email must be **all lowercase** or validation will fail. Convert to lowercase before sending: `maria.garcia@example.com` ✓ not `Maria.Garcia@Example.com` ✗ *** #### Tax Info Array Each entry in `tax_info` must have a unique `document_id`. | Field | Type | Required | Description | Example | | --------------- | ------ | -------- | -------------------------------------- | --------------- | | `country_code` | string | Yes | ISO Alpha-3 country code | `"USA"` | | `document_type` | string | Yes | Tax document type (e.g., `SSN`, `TIN`) | `"SSN"` | | `document_id` | string | Yes | Tax identification number | `"123-45-6789"` | **TIN Format by Country:** * **USA**: Social Security Number in format `xxx-xx-xxxx` (e.g., `123-45-6789`) * **Other countries**: Must use the country's official Tax Identification Number format **V2 Change: `tax_info` replaces `tin`**. V1 used a single `tin` string field. V2 uses a `tax_info` array, which supports multiple tax documents across different countries. **Example:** ```json theme={null} { "basic_info": { "first_name": "Maria", "middle_name": "Elena", "last_name": "Garcia", "dob": "1990-04-15", "email": "maria.garcia@example.com", "phone": "+14155552671", "country_of_residence": "USA", "primary_nationality": "USA", "secondary_nationality": "MEX", "gender": "FEMALE", "tax_info": [ { "country_code": "USA", "document_type": "SSN", "document_id": "123-45-6789" } ] } } ``` *** ### Address (Required) > Current residential address of the customer. The `country` field **must match** `basic_info.country_of_residence`. **Fields:** | Field | Type | Required | Description | Example | | ------------------ | ------ | ----------- | ----------------------------------------------------------------------------------- | --------------------- | | `street_line_1` | string | Yes | Primary street address | `"123 Market Street"` | | `street_line_1_en` | string | Conditional | English transliteration. Required if `street_line_1` contains non-ASCII characters. | `"123 Market Street"` | | `street_line_2` | string | No | Apartment, suite, unit, etc. | `"Apt 4B"` | | `street_line_2_en` | string | Conditional | English transliteration. Required if `street_line_2` contains non-ASCII characters. | `"Apt 4B"` | | `city` | string | Yes | City name | `"San Francisco"` | | `subdivision_code` | string | Yes | ISO 3166-2 subdivision code | `"US-CA"` | | `postal_code` | string | Yes | Postal or ZIP code | `"94103"` | | `country` | string | Yes | ISO Alpha-3 country code. **Must match `country_of_residence`.** | `"USA"` | **Subdivision Code Format**: Use ISO 3166-2 codes from the catalogue API. For example, use `US-CA` instead of `CA` for California, or `GB-ENG` instead of `England`. Fetch valid codes from [/v1/countries/](/api-reference/catalogue/list-subdivisions)[/subdivisions](/api-reference/catalogue/list-subdivisions). **V2 Change: Address fields**. V1 used a single `street` field. V2 splits this into `street_line_1` and `street_line_2`. The `state` field has been renamed to `subdivision_code`. **Example:** ```json theme={null} { "address": { "street_line_1": "123 Market Street", "street_line_2": "Apt 4B", "city": "San Francisco", "subdivision_code": "US-CA", "postal_code": "94103", "country": "USA" } } ``` *** ### Financial Profile (Required) > Describes employment status, occupation, transaction purpose, volume, and fund sources. Use catalogue endpoints to fetch valid IDs. **Fields:** | Field | Type | Required | Description | How to Get Value | | ----------------------------- | ---------- | -------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | | `employment_status` | string | Yes | One of: `EMPLOYED`, `SELF_EMPLOYED`, `RETIRED`, `STUDENT`, `UNEMPLOYED` | Select from enum | | `occupation_id` | integer | Yes | Customer's occupation | [GET /v1/occupations](/api-reference/catalogue/list-occupations) | | `purpose_id` | integer | Yes | Purpose of using the service | [GET /v1/purposes?type=INDIVIDUAL](/api-reference/catalogue/list-account-purposes) | | `purpose_remarks` | string | No | Free-text description of the purpose | User input | | `source_of_fund_ids` | integer\[] | Yes | Source(s) of funds (supports multiple) | [GET /v1/source-of-funds?type=INDIVIDUAL](/api-reference/catalogue/list-source-of-funds) | | `source_of_funds_description` | string | No | Free-text description of fund sources | User input | | `monthly_volume_usd` | integer | Yes | Expected monthly transaction volume in **USD** (not cents). Accepts `0`. | User estimate: `5000` | When fetching catalogue data for individual customers, use the `?type=INDIVIDUAL` query parameter to get the correct options for `purpose_id` and `source_of_fund_ids`. **V2 Change: Multiple fund sources**. V1 accepted a single `source_of_fund_id` integer. V2 uses `source_of_fund_ids` as an array, allowing multiple sources. V2 also adds `employment_status` (required), `purpose_remarks`, and `source_of_funds_description`. **Example:** ```json theme={null} { "financial_profile": { "employment_status": "EMPLOYED", "occupation_id": 42, "purpose_id": 3, "purpose_remarks": "Personal remittances to family", "source_of_fund_ids": [1, 5], "source_of_funds_description": "Monthly salary from employment", "monthly_volume_usd": 5000 } } ``` *** ### Metadata (Optional) Custom key-value pairs for internal tracking: ```json theme={null} { "meta_data": { "reference": "client-ref-abc-001" } } ``` *** ## Document Upload & Attachment After creating the individual customer, you must upload and attach verification documents. ### Step 1: Upload Documents Upload files using multipart/form-data: ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/customers/upload \ --header 'Authorization: Bearer ' \ --header 'Content-Type: multipart/form-data' \ --form 'customer_id=55bd6b4e-c20a-4cc8-9535-91d5557a67d9' \ --form 'file1=@/path/to/selfie.jpg' \ --form 'file2=@/path/to/license_front.pdf' \ --form 'file3=@/path/to/license_back.pdf' \ --form 'file4=@/path/to/bank_statement.pdf' ``` **Allowed file types**: PDF, JPG, JPEG, PNG **Response:** ```json theme={null} { "data": { "files": [ {"file1": "/AbAcQ4hn_0652746727637.pdf"}, {"file2": "/AbAcQ4hn_0652746727638.pdf"}, {"file3": "/XyZ123mn_0652746727639.pdf"}, {"file4": "/PoAdef45_0652746727640.pdf"} ] } } ``` Save these URIs - you'll use them in the attachment request. *** ### Step 2: Attach Documents In V2, the `customer_id` moves to the URL path. The request body uses `identifying_documents` and `address_documents` arrays instead of V1's `proof_of_identity` and `proof_of_address` objects. * The customer must be in `INCOMPLETE` or `ACTION_REQUIRED` status. Only one attach request can be in flight per customer. A second concurrent request returns `409`. * The `tos_policies_value` should be parsed from the `tos_policies_url` query parameter returned when creating the customer. Providing this value signifies that the customer was shown the terms and accepted them. ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v2/customers/55bd6b4e-c20a-4cc8-9535-91d5557a67d9/individual/attach \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "identifying_documents": [ { "type": "SELFIE", "files": [ {"uri": "/AbAcQ4hn_0652746727637.pdf"} ] }, { "type": "DRIVERS_LICENSE", "number": "DL987654321", "country": "USA", "state": "US-CA", "issue_date": "2019-06-01", "expiry_date": "2029-06-01", "files": [ {"side": "FRONT", "uri": "/AbAcQ4hn_0652746727638.pdf"}, {"side": "BACK", "uri": "/XyZ123mn_0652746727639.pdf"} ] } ], "address_documents": [ { "type": "BANK_STATEMENT", "country": "USA", "files": [ {"uri": "/PoAdef45_0652746727640.pdf"} ] } ], "tos_policies_value": "e9414388-fbdf-4407-b5c2-bc39eae3645b" }' ``` **Response (200 - queued for async processing):** ```json theme={null} { "data": { "customer_id": "55bd6b4e-c20a-4cc8-9535-91d5557a67d9" }, "meta": null } ``` V2 document attachment is **asynchronous**. A `200` response means the request is validated and queued, not that processing is complete. Listen for `customer.status` webhooks to track progress. #### Identity Document Types & Side Requirements | Type | Files | Sides Required | `state` field | | ------------------ | ----- | ------------------------ | ------------------------------------------------ | | `PASSPORT` | 1 | Optional | Forbidden | | `NATIONAL_ID` | 2 | One `FRONT` + one `BACK` | Forbidden | | `DRIVERS_LICENSE` | 2 | One `FRONT` + one `BACK` | Required if country is `USA`, optional otherwise | | `RESIDENCE_PERMIT` | 2 | One `FRONT` + one `BACK` | Forbidden | | `SELFIE` | 1 | Optional | N/A | At most **one non-SELFIE** identity document may be included per request. A `SELFIE` entry may be required depending on your client configuration. When required, include exactly one `SELFIE` entry with at least one file. #### Address Proof Types | Type | Description | | ------------------- | ------------------------------------------ | | `UTILITY_BILL` | Recent utility bill (gas, electric, water) | | `BANK_STATEMENT` | Bank statement (within the last 3 months) | | `GOVERNMENT_LETTER` | Official government correspondence | Exactly **one** `address_documents` entry is required. The `country` on the address document must match the customer's `country_of_residence`. **Proof of Address Requirements:** * Document must show the customer's **full name** and **complete address** * Address must match the `address` provided in the customer creation request * Document should be issued within the **last 90 days** (for utility bills, bank statements, and government letters) #### Key Rules * File URIs must be **unique** across the entire reques and must belong to this customer. * `expiry_date` is required for all identity document types except `SELFIE` and must be in the future. *** ## Customer Status & Webhooks After document submission, customers go through a verification workflow: **Status Lifecycle:** Individual Status Lifecycle | Status | Description | | ----------------- | -------------------------------------------------------------- | | `INCOMPLETE` | Customer created but documents not yet attached | | `REVIEWING` | Documents submitted and under compliance review | | `APPROVED` | Verification complete, customer can transact | | `ACTION_REQUIRED` | Additional documents or corrections needed (re-attach allowed) | | `ON_HOLD` | Additional information required via RFI | | `REJECTED` | Verification failed, see rejection reason | **Webhook Events:** * `customer.created` - Fired when a customer is created * `customer.status` - Fired when status changes Subscribe to webhooks to automate your onboarding flow. See [Verifying Webhooks](/guides/webhooks/verifying-webhooks) for setup. *** ## Error Response Examples **Email validation error (not lowercase):** ```json theme={null} { "message": "Validation failed", "errors": { "basic_info.email": ["Email must be all lowercase"] } } ``` **RELIANCE not enabled:** ```json theme={null} { "message": "RELIANCE is not available for your client" } ``` **Address country mismatch:** ```json theme={null} { "message": "Validation failed", "errors": { "address.country": ["Must match basic_info.country_of_residence"] } } ``` **Concurrent attach conflict (409):** ```json theme={null} { "error": { "code": "conflict", "message": "An attach request is already in progress for this customer" } } ``` **Customer not eligible for attach (403):** ```json theme={null} { "error": { "code": "forbidden", "message": "Customer is not eligible for this operation" } } ``` *** ## What's Next? You've successfully created an individual customer using V2. Here's what to do next: ### 1. Monitor Verification Status Listen for webhook events to track verification progress: * Subscribe to `customer.created` and `customer.status` webhooks * Handle status transitions: `INCOMPLETE` → `REVIEWING` → `APPROVED` * For `ACTION_REQUIRED` statuses, re-submit corrected documents via the attach endpoint * For `ON_HOLD` statuses, respond to RFIs (Requests for Information) via email or Slack with additional documents * See [Webhook Verification](/guides/webhooks/verifying-webhooks) for implementation details ### 2. Test Edge Cases Validate your integration handles common errors: * ✓ Email with uppercase characters * ✓ `address.country` not matching `country_of_residence` * ✓ Non-ASCII characters without `_en` transliteration fields * ✓ Missing required fields * ✓ RELIANCE verification when not enabled * ✓ Concurrent attach requests (409) * ✓ Expired identity documents * ✓ Duplicate file URIs across documents ### 3. Production Checklist Before going live, ensure you have: * Implemented webhook handling for status updates * Added proper error handling for all failure scenarios (400, 401, 403, 409, 422) * Client-side validation for email lowercase and tax document format * Fetched and cached catalogue data (occupations, purposes, source-of-funds) * Implemented document upload UI/flow including selfie capture * Set up monitoring for failed verifications * Tested the complete workflow end-to-end ### 4. Create Beneficiaries Once your individual customer is approved, you can create beneficiaries for payouts: * See [Beneficiary Account Validation](/bank-account-and-routing-validation-rules) * Review [Beneficiary Relationships](/guides/beneficiaries/sender-and-receiver-relationships) *** ## V1 to V2 Migration Summary | Area | V1 | V2 | | -------------------- | -------------------------------------- | -------------------------------------------------------------------- | | Create endpoint | `POST /v1/customers/individual` | `POST /v2/customers/individual` | | `verification_type` | Optional (defaults to STANDARD) | Required | | Name fields | `first_name`, `last_name` | Adds `middle_name` + `_en` transliteration fields | | Nationality | `nationality` | `primary_nationality` + optional `secondary_nationality` | | Gender | Not supported | Optional `gender` field | | Tax ID | Single `tin` string | `tax_info` array with `country_code`, `document_type`, `document_id` | | Address street | Single `street` field | `street_line_1` + `street_line_2` + `_en` fields | | Address state | `state` | `subdivision_code` | | Address country | No validation against residence | Must match `country_of_residence` | | Employment | Not supported | Required `employment_status` enum | | Source of funds | Single `source_of_fund_id` | Array `source_of_fund_ids` + `source_of_funds_description` | | Purpose | `purpose_id` only | `purpose_id` + optional `purpose_remarks` | | Attach endpoint | `POST /v1/customers/individual/attach` | `POST /v2/customers/{customer_id}/individual/attach` | | Attach body | `customer_id` in body | `customer_id` in URL path | | Identity docs | `proof_of_identity` object | `identifying_documents` array | | Address docs | `proof_of_address` object | `address_documents` array (max 1 entry) | | Selfie | Not supported | `SELFIE` type in `identifying_documents` | | Residence permit | Not supported as ID type | `RESIDENCE_PERMIT` type supported | | Address proof types | 8 types | 3 types: `UTILITY_BILL`, `BANK_STATEMENT`, `GOVERNMENT_LETTER` | | `tos_policies_value` | Required in attach body | Not required in attach body | | Processing | Synchronous | Asynchronous (200 = queued) | | Concurrency | No guard | 409 if attach already in flight | *** ## Common Pitfalls & Solutions | Pitfall | Solution | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Email validation fails** | Ensure email is **all lowercase** before sending: `maria.garcia@example.com` ✓ not `Maria.Garcia@Example.com` ✗ | | **Address country mismatch** | `address.country` must exactly match `basic_info.country_of_residence`. | | **RELIANCE 423 error** | RELIANCE verification must be enabled for your client. Contact support or use `STANDARD`. | | **Non-ASCII without `_en` field** | If name or address contains non-Latin characters, provide the transliterated value in the `_en` counterpart field. | | **Subdivision code validation fails** | | | **Phone format rejected** | Use E.164 format with country code: `+14155552671`, not `(415) 555-2671`. | | **Monthly volume rejected** | Provide amount in USD as integer (not cents): `5000` for \$5,000, not `500000`. | | **Missing document sides** | For `NATIONAL_ID`, `DRIVERS_LICENSE`, and `RESIDENCE_PERMIT`, include both `FRONT` and `BACK` files. | | **Concurrent attach fails (409)** | Only one attach per customer at a time. Wait for the first to complete before retrying. | | **Expired identity document** | `expiry_date` must be in the future. Ensure documents are not expired before submitting. | | **Selfie missing** | If your client requires selfie, include exactly one `SELFIE` entry in `identifying_documents`. | | **Duplicate file URIs** | File URIs must be unique across the request (SELFIE excluded). Don't reuse the same URI for identity and address docs. | # Responding to RFIs Source: https://developer.fin.com/guides/customers-and-compliance/responding-to-rfis How Fin.com requests additional customer information, where the RFI payload appears, and how to submit a response with the Patch Customer RFI endpoint. A Request for Information (RFI) is raised when compliance needs something more from a customer before verification can complete. It names exactly which documents or fields are missing, expired, or invalid, so you never have to guess what to resend. An RFI puts the customer into `ACTION_REQUIRED` and holds verification there until you respond. Nothing progresses in the meantime. An RFI can also be raised after a customer is already `APPROVED`. In that case the customer status does not change. The only signal is the `customer.rfi` webhook and the populated `request_for_information` array. *** ## How an RFI Reaches You There are two ways to find an open RFI, and both carry the same structure. | **Channel** | **Reference** | **When to use it** | | :------------------------------ | :-------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ | | `customer.rfi` webhook | [**customer.rfi**](https://developer.fin.com/api-reference/webhooks/customer-rfi) | Primary path. Fires the moment compliance raises the request. | | `request_for_information` field | [**GET /v2/customers/:customer-id**](https://developer.fin.com/api-reference/customers/get-customer-details-v2) | Reconciliation. Read the open RFI on demand, or recover one whose webhook you missed. | The `customer.status` webhook fires alongside `customer.rfi` when the status actually changes. Treat `customer.rfi` as the payload that tells you what to do, and `customer.status` as the state transition. *** ## Reading the RFI Payload The payload is a list of sections. Each section holds one or more document categories, and each category holds the individual fields with a problem. ``` request_for_information[] └── section The document section with the issue └── categories[] └── document_type The document that was requested or rejected └── fields[] ├── field_name The specific field to resubmit ├── data_type URI, DATE, TEXT, or ENUM ├── status MISSING, EXPIRED, or INVALID ├── side FRONT or BACK, file fields only └── reason Why it was rejected, null when MISSING ``` ### Field Status Values | **Status** | **Meaning** | **What to send** | | :--------- | :------------------------------------------------------------ | :----------------------------------- | | `MISSING` | The document or field was never provided. `reason` is `null`. | The missing document or value. | | `EXPIRED` | The document has passed its expiry date. | A current document of the same type. | | `INVALID` | The value does not meet requirements. `reason` explains why. | A corrected document or value. | ### Section Values by Customer Type | **Customer Type** | **Sections** | | :-------------------- | :------------------------------------------------------------------- | | Individual | `proof_of_identity`, `proof_of_address`, `tos_policies_value` | | Business V1 | `company_details`, `ownership_structure`, `legal_presence` | | Business V2 | `formation_documents`, `ownership_documents`, `supporting_documents` | | Associated Party (V1) | `proof_of_identity`, `proof_of_address` | | Associated Party (V2) | `identifying_documents`, `tax_info`, `address_documents` | An RFI can be scoped to the customer's own records or to a specific associated party. Sections from the associated party rows above tell you the request concerns a party rather than the business itself. *** ## Example: The `customer.rfi` Webhook An individual customer whose passport has expired on the front, is damaged on the back, is missing both dates, and carries a name mismatch: ```json theme={null} { "event": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "event_reference_id": "cust-uuid-1234", "type": "customer.rfi", "created_at": "2026-04-04T10:00:00.000000Z", "sandbox_mode": false }, "data": { "customer_id": "cust-uuid-1234", "request_for_information": [ { "section": "proof_of_identity", "categories": [ { "document_type": "GOVERNMENT_ID", "fields": [ { "field_name": "files", "data_type": "URI", "status": "EXPIRED", "reason": "Document has expired", "side": "FRONT" }, { "field_name": "issue_date", "data_type": "DATE", "status": "MISSING", "reason": null } ] } ] }, { "section": "proof_of_address", "categories": [ { "document_type": "PROOF_OF_ADDRESS", "fields": [ { "field_name": "files", "data_type": "URI", "status": "MISSING", "reason": null } ] } ] } ] } } ``` Every webhook request is signed. Verify the `x-fin-signature` header before acting on the payload. See [**Verifying webhooks**](https://developer.fin.com/guides/webhooks/verifying-webhooks). *** ## Example: Get Customer Details The same request is readable at any time on the customer record. `request_for_information` is an empty array when nothing is outstanding. ```json theme={null} { "data": { "customer_id": "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06", "type": "BUSINESS", "business_name": "Fin.com", "customer_status": "ACTION_REQUIRED", "request_for_information": [ { "section": "ownership_documents", "categories": [ { "document_type": "SHAREHOLDER_REGISTRY", "fields": [ { "field_name": "files", "data_type": "URI", "status": "INVALID", "reason": "Unacceptable document." } ] } ] } ] } } ``` For individual customers the same array is returned by [**GET /v1/customers/:customer-id**](https://developer.fin.com/api-reference/customers/get-customer-details-v2), with two additional fields per entry: `scope`, which is `CUSTOMER` or `ASSOCIATED_PARTY`, and `options`, which lists permitted values when `data_type` is `ENUM`. *** ## Responding to an RFI Responding takes two calls: upload the files, then patch the customer with the returned URIs. Post the files to [**POST /v1/customers/upload**](https://developer.fin.com/api-reference/customers/upload-document) as `multipart/form-data`. Field names are arbitrary and are echoed back as the keys in the response. ```bash theme={null} curl -X POST https://sandbox.api.fin.com/v1/customers/upload \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -F "customer_id=ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" \ -F "passport=@passport-front.jpg" \ -F "poa=@utility-bill.pdf" ``` ```json theme={null} { "data": { "files": [ { "passport": "/CwW9PHhP_passport-front.jpg" }, { "poa": "/KVdLfqjR_utility-bill.pdf" } ] } } ``` Allowed file types are `PDF`, `JPG`, `JPEG`, and `PNG`. Keep the returned URIs; the next call needs them. Send the requested fields to [**PATCH /v1/customers/:customer-id**](https://developer.fin.com/api-reference/customers/patch-customer-rfi). The same endpoint serves individual and business customers, and its body accepts the same fields as the Attach Documents endpoints. Submit only the fields the RFI listed. Sending data that was not requested returns an error. The customer returns to `REVIEWING` while compliance reassesses. Listen on `customer.status` for the result, and on `customer.rfi` in case a further request is raised. ### Individual Customer Response Answering the `proof_of_identity` and `proof_of_address` sections from the webhook example above: ```json theme={null} { "proof_of_identity": { "type": "PASSPORT", "number": "A12345678", "country": "USA", "issue_date": "2020-01-15", "expiry_date": "2030-01-15", "files": [ { "uri": "/CwW9PHhP_passport-front.jpg", "side": "FRONT" } ] }, "proof_of_address": { "type": "UTILITY_BILL", "country": "USA", "files": [ { "uri": "/KVdLfqjR_utility-bill.pdf" } ] } } ``` ### Business Customer Response Business sections map to top level arrays. An RFI scoped to an associated party is answered inside `associated_party_attachments`, keyed by `associated_party_id`: ```json theme={null} { "ownership_documents": [ { "type": "PROOF_OF_SIGNATORY_AUTHORITY", "description": "Shareholder Registry", "files": [ { "uri": "/AbAcQ4hn_0652746727639.pdf" } ] } ], "associated_party_attachments": [ { "associated_party_id": "f6b13e01-044a-4f74-a70b-d5f66b6449af", "identifying_documents": [ { "type": "PASSPORT", "number": "A12345678", "country": "USA", "issue_date": "2020-01-15", "expiry_date": "2030-01-15", "files": [ { "uri": "/AbAcQ4hn_0652746727637.pdf" } ] } ], "address_documents": [ { "type": "BANK_STATEMENT", "files": [ { "uri": "/AbAcQ4hn_0652746727638.pdf" } ] } ] } ] } ``` A successful patch returns the customer ID: ```json theme={null} { "data": { "customer_id": "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" } } ``` A `400` response means validation failed. The `data` object names the offending fields. A `404` means the customer ID does not exist. *** ## Common Mistakes | **Mistake** | **Result** | | :-------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | | Sending fields the RFI did not ask for | Request rejected with a validation error. | | Resubmitting the document or field value that was rejected, unchanged | A second RFI naming the same field. Read `reason` and send a corrected or replacement version, not the original. | | Omitting `side` on a two sided document | The missing side stays outstanding. | | Patching before the upload call | The URIs do not resolve and the documents are not attached. | | Treating `ACTION_REQUIRED` as terminal | Verification resumes as soon as the RFI is answered. | # SLAs for Compliance Source: https://developer.fin.com/guides/customers-and-compliance/sla-for-compliance Onboarding · Support availability · Query response · RFI handling. Version 2.0 · September 2026 This document defines the operational and customer service standards Fin.com maintains in the delivery of its payment services. It applies to all clients onboarded through the Fin.com platform and governs the relationship between Fin.com, its clients, and its regulated banking partners. ## 01 · CLIENT ONBOARDING ### Onboarding timeliness. Fin.com targets onboarding decisions within 1 to 5 business days from receipt of a complete documentation package, based on the customer’s assessed risk classification. | RISK CLASSIFICATION | INDICATIVE TARGET | | :--------------------------------- | :---------------- | | Low risk | 1 business day | | Standard risk | 2 business days | | High risk (enhanced due diligence) | 4 business days | | PEP or sanctions-adjacent | 5 business days | Targets assume a complete submission. Each RFI cycle extends the target by one business day. The clock pauses while documents are outstanding from the client, during banking partner review where applicable, or where escalation to the compliance team is required for manual review. ## 02 · OPERATING HOURS & AVAILABILITY ### When we are open. Compliance operates Monday to Friday, 02:00–13:00 EST (03:00–14:00 EDT during US daylight saving). Submissions received before the daily 13:00 EST cutoff are reviewed the same working day; submissions received after the cutoff or on weekends are reviewed the next working day. Customer service is available 24 hours / 7 days across email, dedicated Slack channels for B2B clients. Complex compliance queries raised outside compliance operating hours may be addressed the next business day. ## 03 · CUSTOMER RESPONSE TIMES ### Query response & resolution. | PRIORITY | QUERY TYPE | FIRST RESPONSE | TARGET RESOLUTION | | :------------ | :--------------------------------------------------------- | :------------- | :--------------------- | | P1 · Critical | Transaction frozen, account blocked, compliance escalation | Within 10mins | Same business day | | P2 · High | Payment issue, onboarding status, RFI follow-up | Within 15 min | 1–2 business days | | P3 · Standard | General enquiries, document requests, account questions | Within 1 hour | 3–5 business days | | P4 · Low | Informational or non-urgent requests | Within 4 hours | Up to 10 business days | All queries are tracked via Pylon to ensure full accountability and audit trail. ## 04 · OUTBOUND RFIS TO CLIENTS ### Deadlines & escalation. | STAGE | STANDARD | URGENT / HIGH RISK | | :------------------------------------ | :--------------- | :----------------- | | Client response deadline | 14 calendar days | 7 calendar days | | First reminder | Day 7 | Day 3 | | Final warning + compliance escalation | Day 12 | Day 5 | | Account restriction | Day 15 | Day 8 | | Offboarding review | Day 30 | Day 30 | ## 05 · INBOUND RFIS FROM BANKING PARTNERS ### Response commitments. | STAGE | TIMELINE | | :------------------------------------------ | :----------------------- | | Acknowledgement to banking partner | Within 4 business hours | | Preliminary assessment | T+2 business days | | Interim status update to banking partner | Day 5, then every 5 days | | Full response — records already held | T+5 business days | | Full response — client cooperation required | Up to 14 calendar days | Fin.com proactively communicates with banking partners on client non-response rather than waiting for deadlines to lapse. # Fin.com Setup Guide Source: https://developer.fin.com/guides/get-started/fin-com-setup-guide How to get onboarded, sign in to the Orchestration Dashboard, and issue your first API keys. Getting set up takes two things: a commercial conversation with our team, and a few minutes in the Orchestration Dashboard to issue your keys. ## How do I get started with the platform? Start by [booking a call with our team](https://calendar.app.google/7isCxrBmR8hLoND2A). We will walk through your use case, the corridors you need, and get your account set up. Visit [orchestration.fin.com](https://orchestration.fin.com) and submit the registered email Sign Up Screen Enter the One-Time Password (OTP) sent to your registered contact method to verify your identity. Once verified, you will be automatically redirected to your account dashboard. Navigate to the **API Keys** menu to issue your initial set of keys and begin exploring our API collection. ## API base URLs Your keys work against two environments. Sandbox mirrors production and moves no real money, so build against it first. | Environment | Base URL | | :---------- | :---------------------------- | | Sandbox | `https://sandbox.api.fin.com` | | Production | `https://api.fin.com` | The API uses OAuth 2.0 client credentials. Exchange your client ID and secret for an access token, refresh it without re-authenticating, and send it on every request. See [Issue a Token](/api-reference/authentication/issue-a-token). ## OpenAPI spec The full specification is published as a single YAML file. Import it into Postman, Insomnia, or a client generator to scaffold your integration. Download the OpenAPI spec (YAML) To fetch it from the command line: ```bash theme={null} curl -o FinOpenAPI.yaml https://developer.fin.com/api-reference/openapi.yaml ``` The file is regenerated on every deploy, so it always matches what you see in the API Reference. ## Can I access Production API keys immediately? To ensure security and compliance, Production keys are only issued after the commercial agreements & sandbox integration is completed. **Need help moving to production?** Please contact in your dedicated Slack for more information on the onboarding process. # Glossary Source: https://developer.fin.com/guides/get-started/glossary The core concepts behind the Fin.com API: customers, virtual accounts, beneficiaries, webhooks, coverage, and catalogue data. The terms below come up throughout this documentation. Each links to the guide that covers it in full. ## Customer The individuals and businesses you serve. Every customer is verified through Fin.com, with KYC for individuals and KYB for businesses, before they can hold an account or transact. Fin.com never contacts your customers directly. See [Onboarding individual customers](/guides/customers-and-compliance/onboarding-individuals) and [Onboarding business customers](/guides/customers-and-compliance/onboarding-businesses). ## Virtual account A set of bank details issued to one customer. Money paid into those details is converted and settled as stablecoin to a wallet address you nominate. A customer can hold one virtual account per currency and payment rail. See [Creating a virtual account](/guides/virtual-accounts/creating-a-virtual-account). ## Beneficiary A recipient your customer pays. A beneficiary belongs to one customer and has a single destination: a bank account, an e-wallet, or a crypto wallet. See [Beneficiary onboarding](/guides/beneficiaries/beneficiary-onboarding). ## Liquidation address The address issued for a bank or e-wallet beneficiary. Crypto sent to it is converted and paid out to that beneficiary in local currency, after fees. See [Creating your first beneficiary and payout](/guides/orchestration-dashboard/creating-your-first-beneficiary). ## Deposit instructions The bank details a virtual account exposes once it is active. Which fields are populated depends on the payment rail, so fields that do not apply come back empty. See [Receiving the first deposit](/guides/virtual-accounts/receiving-the-first-deposit). ## Developer fee Your own markup on a transaction. It can be a fixed amount, a percentage, or both, and both are applied together. It is deducted alongside conversion, so the settled amount is less than the amount sent. ## Counter party Whether your customer is paying themselves or someone else. First party means the customer is the beneficiary. Third party means they are paying a supplier, employee, or other recipient, which may bring additional compliance checks. See [Sender and receiver relationships](/guides/beneficiaries/sender-and-receiver-relationships). ## Beneficial ownership The funds in an account must belong to the account holder, even when paid in by a named third party such as a payment processor. Receiving funds that beneficially belong to someone who has not been onboarded is nesting, and is not permitted. See [Guidance on nested payments & onboarding](/guides/customers-and-compliance/nested-payments-and-onboarding). ## Webhook How Fin.com tells you something happened. Every event carries an envelope identifying the delivery and the resource it concerns, and every request is signed. See [Event structure](/guides/webhooks/event-structure) and [Verifying webhooks](/guides/webhooks/verifying-webhooks). ## RFI A request for information. Raised when more is needed to complete verification, whether from Fin.com to you, or from a banking partner to Fin.com. Nothing progresses until it is answered. See [SLAs for Compliance](/guides/customers-and-compliance/sla-for-compliance). ## Capabilities What a given customer is actually eligible for, by currency and rail. A customer can be approved without being eligible for every corridor, so check capabilities before assuming a flow is available. ## Coverage Which currencies and rails are available in each direction, and the risk classification applied per country of residence. See [Coverage & capabilities](/guides/coverage/coverage-and-capabilities) and [Supported rails and currencies](/guides/coverage/supported-rails-and-currencies). ## Catalogue Reference data the API expects in requests: occupations, transaction purposes, sources of funds, countries, and subdivision codes. Fetch these rather than hard-coding them. ## Rail The payment network money moves over. On the fiat side that means ACH, Fedwire, or SWIFT. On the crypto side it means the blockchain network, such as Ethereum or Polygon. ## Prefunding Holding a balance with Fin.com in advance so payouts can be settled without waiting for funds to arrive. Local currency payouts require it. See [Funding your balance](/guides/move-money/funding-your-balance). # Funding Your Balance Source: https://developer.fin.com/guides/move-money/funding-your-balance Learn how to fund your Fin.com balance to enable transfers and payouts to beneficiaries on behalf of your customers Fin.com supports developer balance pre-funding via USDC / USDT pre-funding for Non-USD currency payouts. Funds are credited as USD in a developers balance which they can use to run payouts. Prefunding is required for **non-USD currency payouts only**. USD payouts do not draw on a prefunded balance. ## Balance Type Prefunded amounts are credited to your **USD LOCAL** balance. For local-currency payouts (BDT, PKR, INR, etc.) Prefunding made on weekends will be processed on the next working day. ## Prefunding Process. ### 1. Send Your Funds Send **USDC or USDT** to the designated wallet address your account manager provides. ### 2. Submit Prefunding Request Fill up this [form](https://tally.so/r/BzX5bY) with your request, and Fin's treasury team will pick it up and email you with a receipt. ### 3. Receive Confirmation You'll receive an email confirmation once your balance is credited. ## Settlement Timeline Settlement times vary based on the prefunding amount and deposit timing (Singapore Time, SGT). ### By Amount | Amount | Settlement Time | Notes | | --------------------------- | --------------- | ------------------------------------------------ | | **≥ \$20,000 USDC / USDT** | T+2 | Funds available 2 business days after submission | | **\< \$20,000 USDC / USDT** | T+1 or T+0 | Depending on fund availability | ### Deposit Timing | Deposit Time | Availability | | ------------------- | --------------------------------------- | | Before 12:00 PM SGT | Next business day (or same day for T+0) | | After 12:00 PM SGT | Following business day | ## Important Considerations * All balances are denominated in USD * **Funds are non-refundable**: Once credited to your balance, funds can only be withdrawn through payouts. To retrieve funds, create a payout to your own beneficiary account * Missing or incomplete information will delay processing * Contact your account manager for any questions or issues # How USD features work for a customer Source: https://developer.fin.com/guides/move-money/how-usd-features-work-for-a-customer Create a customer, get them approved, turn on USD, and issue a virtual account. This guide walks you through onboarding a customer all the way to a USD virtual account: creating the customer, getting them approved, enabling USD, and issuing the account. It also sets expectations on timelines and what can go wrong. You move through three parties: you (the developer), Fin, and the banking partner. You trigger each step with an API call. Fin and the banking partner each run their own review. Always use the latest version of an endpoint. Where both a V1 and a V2 exist, use V2. If you already integrated an older version, migrate to the latest version. ## The flow at a glance ```mermaid theme={null} sequenceDiagram participant Dev as Developer participant Fin participant Bank as Banking partner Dev->>Fin: Create customer (Individual / Business Customer) Fin-->>Dev: customer_id + TOS value Dev->>Fin: Upload documents (per file) Fin-->>Dev: file URI Dev->>Fin: Attach documents (Attach Customer, TOS value + URIs by group) Note over Fin: Compliance review (KYC / KYB) Fin-->>Dev: RFI raised if issued (webhook) Dev->>Fin: Resolve RFI (re-upload + Patch Customer RFI, repeat until resolved) Fin-->>Dev: Customer approved (status / webhook) Fin->>Bank: USD forwarded automatically for review Note over Bank: Bank review (own risk framework) Bank-->>Fin: Bank decision Dev->>Fin: Poll capabilities (Get Customer Capabilities) Fin-->>Dev: USD rail = true (ACH / Fedwire / SWIFT) Dev->>Fin: Create virtual account (Create Virtual Account) Fin-->>Dev: Virtual account issued ``` *Solid arrows are calls you make. Dashed arrows are responses or status returned to you.* ## Step by step Call **Create Individual Customer** for an individual, or **Create Business Customer** for a business. Send only textual information here: legal name, financial profile, estimated annual revenue, website, and so on. Do not send documents in this call. The response returns the `customer_id` and a TOS value (the terms of service policies URL). Keep both. You need the TOS value in step 3. Call **Upload Documents** once per file. You can name each file however you like. Each call returns a file URI. Save these for the next step. Check the document guide for which documents each entity type requires. Call **Attach Customer**. Pass two things: * The TOS value from step 1. This confirms the customer accepted Fin's terms. * The file URIs from step 2, placed in the correct document groups for the entity type. Document groups depend on the entity. An LLC, for example, needs registration documents, constitutional documents, and evidence of directors and controllers. Fin reviews the customer (KYC for individuals, KYB for businesses). Subscribe to webhooks to track progress. You get events for customer created, status changes, and RFIs. If Fin needs more information, you receive an RFI webhook describing what is required and for which section. To respond: upload the corrected file with **Upload Documents**, then submit it with **Patch Customer RFI**. Do not re-run **Attach Customer**. The RFI object tells you how to construct the update. Repeat until every RFI is cleared. *Today, RFIs cover documents only. Textual-data RFIs are coming soon.* When Fin approves the customer, you see it on the status webhook or by checking customer status. Approval does not mean the customer has a virtual account yet, and it does not guarantee the banking partner will approve. See what to expect. Once the customer is approved, Fin forwards the USD Feature request to the banking partner for review automatically. USD is never turned on automatically. You have to request it.  You no longer call a separate endpoint to request USD. The **Enable USD Feature** API is deprecated. USD is now requested automatically once the customer is approved, so there is no manual call to make here. The banking partner reviews the customer against its own risk framework. Typical timelines: about 5 to 6 minutes for an individual, about 2 to 3 days for a business. If the bank flags something or raises its own RFI, expect up to 24 hours. Poll **Get Customer Capabilities**. USD is live when the on-ramp and off-ramp USD rail returns `true` (rail: Fedwire). Use **Get Customer Capabilities** for this. **Get Customer Details V2** does not expose capabilities. Once USD shows `true`, call **Create Virtual Account / Create a beneficiary, up to you.** If the customer is not yet eligible, you get a prompt instead of an account. ## What to expect Fin approval does not guarantee bank approval. The banking partner applies its own risk framework and can still reject a customer Fin approved. In most cases approval at Fin leads to approval at the bank, but not always. If the bank rejects, we may route you to another partner, though a rejection usually ends USD eligibility for that customer. A USD virtual account is not instant after approval. After Fin approves the customer, the banking partner reviews the USD request before the account is issued. Drive your flow off webhooks for customer status and RFIs, and off **Get Customer Capabilities** for USD status. Poll capabilities until the USD rail returns `true`. ## FAQ Use **Create Individual Customer** for individuals and **Create Business Customer** for businesses. Always use the latest version, and migrate off any older version you already integrated. No. The create call takes textual information only. Upload files with **Upload Documents**, then link them with **Attach Customer**. It is returned by the create call, inside the terms of service policies URL. Pass it in **Attach Customer** to confirm the customer accepted Fin's terms. Upload the corrected file with **Upload Documents**, then submit it with **Patch Customer RFI**. Do not re-run **Attach Customer**. Repeat until all RFIs are cleared. RFIs currently cover documents only. After Fin approves and you request USD, the banking partner review usually takes about 5 to 6 minutes for an individual and about 2 to 3 days for a business. Flags or a bank RFI can add up to 24 hours. After Fin approves the customer, the banking partner review usually takes about 5 to 6 minutes for an individual and about 2 to 3 days for a business. Flags or a bank RFI can add up to 24 hours. Approval does not issue an account on its own. Call **Enable USD Feature** to request USD, wait for the banking partner review, then create the account with **Create Virtual Account** once capabilities show `true`. Approval does not issue an account on its own. After approval, USD is requested automatically. Wait for the banking partner review, then create the account with **Create Virtual Account** once capabilities show `true`. Call **Get Customer Capabilities**. USD is enabled when the on-ramp and off-ramp USD rail returns `true` example: (rail: Fedwire, ACH, SWIFT). **Get Customer Details V2** does not return capabilities. For USD status, use **Get Customer Capabilities**. No. The banking partner runs its own risk framework and can reject a customer Fin approved. A bank rejection usually ends USD eligibility for that customer. # Bank Holidays 2026 Source: https://developer.fin.com/guides/operations/bank-holidays-2026 Banking partner holiday schedule for US and Singapore rails in 2026. Fiat rails follow the banking calendar of the relevant jurisdiction. On the dates below, the corresponding banking partners are closed and fiat transactions are processed on the next business day. Crypto rails are unaffected and continue to operate **24/7/365**. A **✓** indicates the rail is closed; a **—** indicates normal banking operations. ## Holiday Schedule
Holiday Date US Singapore
New Year's DayThu, Jan 1✓✓
Martin Luther King Jr. DayMon, Jan 19✓—
Presidents' DayMon, Feb 16✓—
Chinese New YearTue, Feb 17—✓
Second Day of Chinese New YearWed, Feb 18—✓
Hari Raya PuasaSat, Mar 21—✓
Good FridayFri, Apr 3—✓
Labour DayFri, May 1—✓
Memorial DayMon, May 25✓—
Hari Raya HajiWed, May 27—✓
Vesak Day (Observed)Mon, Jun 1—✓
Juneteenth National Independence DayFri, Jun 19✓—
Independence Day (Observed)Fri, Jul 3✓—
National Day (Observed)Mon, Aug 10—✓
Labor DayMon, Sep 7✓—
Columbus Day / Indigenous Peoples' DayMon, Oct 12✓—
Deepavali (Observed)Mon, Nov 9—✓
Veterans DayWed, Nov 11✓—
Thanksgiving DayThu, Nov 26✓—
Christmas DayFri, Dec 25✓✓
Crypto rails operate continuously, including weekends and bank holidays. Fiat transactions initiated on a holiday — or outside banking hours — are processed on the next business day for the relevant jurisdiction. See [Processing Windows & Cutoffs](/guides/operations/processing-windows-and-cutoffs) for settlement timing. # Processing Windows & Cutoff Times Source: https://developer.fin.com/guides/operations/processing-windows-and-cutoffs Cutoff times and settlement windows across fiat and crypto rails. [Fin.com](http://Fin.com) operates on **banking days and hours** for fiat transactions and **24/7/365** for crypto. The tables below summarize the cutoff times and expected settlement windows for each rail. The cutoff times and settlement windows below apply to **both payins and payouts**. ## 1. Fiat Rails (USD) | Rail | Cutoff | Settlement | Notes | | :----------- | :--------------------------- | :------------------------ | :----------------------------- | | Next Day ACH | 4:45 PM ET | 8:30 AM next business day | Standard ACH transfer | | Same Day ACH | 9:30 AM, 1:45 PM, 2:30 PM ET | Same business day | Capped at \$1M per transaction | | Wire | 4:45 PM ET | Within 2 hours | Domestic USD wires | ## 2. International Fiat Rails | Rail | Currency | Cutoff | Settlement | | :-------------- | :------- | :------------------- | :---------------- | | SEPA Instant | EUR | No cutoff (24/7/365) | Up to 5 minutes | | SEPA Credit | EUR | 7:00 AM | 1–3 business days | | SPEI | MXN | No cutoff | Up to 30 minutes | | PIX | BRL | No cutoff | Up to 30 minutes | | Bre-B | COP | No cutoff | Up to 30 minutes | | Faster Payments | GBP | No cutoff | Up to 30 minutes | ## 3. Crypto Rails (24/7/365) | Asset Type | Settlement Window | | :-------------------------------------------------- | :---------------------------------------------------- | | USDC / EURC / [Fin.com](http://Fin.com) stablecoins | Up to 30 minutes | | USDT | Up to 60 minutes (slower due to trading requirements) | | Non-stablecoins | Up to 60 minutes | Crypto rails operate continuously, including weekends and holidays. Settlement windows reflect typical end-to-end processing time including network confirmations. ## 4. Additional Notes * **Large transactions (>\$500K):** May require up to one additional hour for processing. * **Onramps:** May undergo risk reviews that add up to two business hours to standard settlement times. * **Holidays & weekends:** Fiat rails follow the banking calendar of the relevant jurisdiction. Transactions initiated outside banking hours are processed on the next business day. # Creating a virtual account and receiving your first deposit Source: https://developer.fin.com/guides/orchestration-dashboard/creating-a-virtual-account How to set up a virtual account for a customer in the Dashboard, share the deposit details, and watch the first payment settle. A virtual account gives your customer a set of bank details they can receive money into. When someone sends a payment to those details, the money is converted and settled to the blockchain address you choose. This guide walks through both halves of that flow in the Dashboard: creating the account, then receiving the first deposit into it. ## What do I need before I start? Virtual accounts belong to a customer, so the customer has to exist and be approved first. Create the customer, submit their documents, and wait for the status to show as approved. Verification is not instant, and you cannot open a virtual account for a customer who is still under review. Not every approved customer can hold a virtual account. Check the customer's eligibility in the **Capabilities** tab of the customer before you start, so you do not fill in the form only to be turned down at the end. Image Not sure whether a customer is eligible? Contact us in your dedicated Slack channel and we will confirm. ## How do I create the virtual account? Go to **Customer details** for the customer you want the account for, then open the **Virtual Accounts** tab. Customer details screen with the Virtual Accounts tab selected The Create virtual account button on the Virtual Accounts tab This is the fiat side of the account, meaning the bank details your customer will hand out. * **Source payment rail** is the payment network the money arrives on, such as SWIFT, ACH, or Fedwire. * **Currency** is the currency the account receives. * **Banking partner** is the bank that issues the account and takes in the payment. The partners you can pick from depend on how your account is set up, and not every partner supports every rail. * **Developer fees** are the fees you charge on top of each deposit. You can set a fixed amount, a percentage, or both. Form fields for source payment rail, currency, banking partner, and developer fees This is the crypto side of the account. Pick the **destination blockchain**, the **currency** you want to receive, and the **wallet address** the settled funds should go to. Double-check the wallet address before you continue. Funds sent to a wrong address cannot be recovered. Form fields for destination blockchain, currency, and wallet address Select **Continue** to submit the request. New accounts are reviewed before they open. Come back to the **Virtual Accounts** tab and check the **Status** column to follow progress. Virtual Accounts tab listing two accounts with their status shown as Active Once the status shows **Active**, the account is ready. Open it to see the bank details your customer can be paid into, under **Payment rail instructions**. Each field has a copy button beside it, and **PDF instructions** downloads the whole set as a document. Virtual account panel showing the payment rail instructions, a copy button on each field, and a PDF instructions download A customer can hold only one virtual account per currency and payment rail. ## How do I receive the first deposit? Send the deposit details to whoever is paying in. From the account you can either copy the details directly or download them as a PDF instruction sheet to forward on. Share every field exactly as shown. A payment sent with incomplete details may be delayed or returned. Once the payment has been made, it appears in the **Transactions** tab. Payments are not instant, and how long they take depends on the rail the sender used. Transactions tab listing an onramp and a crypto deposit, both marked Completed When the deposit completes, the amount received is converted and settled to the destination address you set when you created the account. The transaction record shows both sides, so you can see what arrived as fiat and what settled as crypto. ## Do I have to do this for every customer? Yes. A virtual account is tied to one customer, so each customer needs their own. Once an account is active it stays available, so you only go through this once per customer, per currency and rail. **Need a hand with your first account?** Contact us in your dedicated Slack channel and we will walk through it with you. # Creating your first beneficiary and payout Source: https://developer.fin.com/guides/orchestration-dashboard/creating-your-first-beneficiary How to add a beneficiary in the Dashboard, whether you are paying out to a bank account or an e-wallet, and how the payout then works. A beneficiary is someone your customer pays out to. You add them once, and from then on you can send money to them as often as you need. Every beneficiary belongs to a customer and has a single destination. Pick the tab below for the kind of payout you are setting up. ## What do I need before I start? Beneficiaries belong to a customer, so the customer has to exist and be approved first. You cannot add a beneficiary to a customer who is still under review. You will be asked for the recipient's name, address, destination details, and some compliance information. Collect them before you start, since every field marked with an asterisk has to be filled in before the form can be saved. ## How do I create the beneficiary? Go to **Customer details** for the customer you want the beneficiary for, open the **Beneficiaries** tab, then select **Add Beneficiary**. Customer details screen with the Beneficiaries tab selected and the Add Beneficiary button highlighted Choose **Bank / E-wallet**. Create beneficiary form with Bank / E-wallet selected as the destination type **Beneficiary type** says whether the recipient is an **Individual** or a **Business**. **Counter party** says who your customer is paying. **First party (self)** means they are paying themselves, such as a business sending funds to its own account elsewhere. **Third party** means they are paying someone else, such as a supplier or an employee. This drives the compliance checks, and third party payouts may bring extra ones depending on the country. Beneficiary type and Counter party options highlighted on the Create beneficiary form Under **Country & Payment Selection**, set the **Destination country**, the **Account scheme**, the **Currency**, and **Bank transfer** as the **Payment method**. Country and Payment Selection section with destination country, account scheme, currency, and payment method Give the recipient's **First name**, **Last name**, **Email address**, and **Phone**, then their **Account holder address**: street, city, country, state, and postal code. Account Holder Information and Account holder address sections Pick the receiving bank from the **Bank** list. If it is not there, choose **Not listed / enter bank name** and type the **Bank name** yourself. Then give the **Account number** and **Account type**. The remaining fields depend on the account scheme you chose, because countries identify a bank in different ways. On a SWIFT payout you are asked for the **SWIFT Code** and, optionally, an **Intermediary bank routing number**. Then give the **Bank address**: street, city, country, state, and postal code. Bank Details section with the bank picker, account number, account type, SWIFT code, and bank address Bank details are validated against the rules for the destination country, so a number in the wrong format is rejected when you save. See [Bank account and routing number validation rules](/bank-account-and-routing-validation-rules) for what each country expects. Give the **Transaction purpose**, **Occupation**, **Relationship**, and **Nationality**, plus the **Government ID number** with its **issue** and **expiry** dates. The purpose and occupation each take optional remarks. The relationship options change depending on whether your customer and the recipient are individuals or businesses. See [Sender and receiver relationships](/guides/beneficiaries/sender-and-receiver-relationships) for which combinations are allowed. Compliance information section with transaction purpose, occupation, relationship, nationality, and government ID fields Under **Developer fee**, set what you charge on top of each payout. You can set a **Fixed fee**, a **Percentage fee**, or both. When you set both, they are added together. Developer fee section with fixed fee and percentage fee fields This is how the payout gets funded. **Deposit rail** and **Deposit currency** are the network and token you send in. **Refund wallet address** is where funds are returned if a payout cannot be completed. Deposit and refund configuration section with deposit rail, deposit currency, and refund wallet address **Enable auto settlement** controls when the payout goes out. Leave it on and the payout is sent as soon as the funds arrive. Leave it off and the funds are held until you release them yourself. The Enable auto settlement checkbox selected Local currency payouts, such as BDT, INR, and EUR, have to be pre-funded. See [Funding your balance](/guides/move-money/funding-your-balance) for how that works. Select **Create beneficiary** to submit. Go to **Customer details** for the customer you want the beneficiary for, open the **Beneficiaries** tab, then select **Add Beneficiary**. Customer details screen with the Beneficiaries tab selected and the Add Beneficiary button highlighted Choose **Bank / E-wallet**. Create beneficiary form with Bank / E-wallet selected as the destination type **Beneficiary type** says whether the recipient is an **Individual** or a **Business**. **Counter party** says who your customer is paying. **First party (self)** means they are paying themselves. **Third party** means they are paying someone else. This drives the compliance checks, and third party payouts may bring extra ones depending on the country. Beneficiary type and Counter party options highlighted on the Create beneficiary form Under **Country & Payment Selection**, set the **Destination country**, the **Currency**, and **E-Wallet** as the **Payment method**. There is no account scheme to choose. Give the recipient's **First name**, **Last name**, **Email address**, and **Phone**, then their **Account holder address**: street, city, country, state, and postal code. Account Holder Information and Account holder address sections Give the **Wallet provider**, chosen from the providers supported in that country, and the **Wallet number**, which is usually the phone number the wallet is registered to. That is all an e-wallet needs. There is no bank name, bank code, or bank address to fill in. E-Wallet Details section with the wallet provider and wallet number fields Give the **Transaction purpose**, **Occupation**, **Relationship**, and **Nationality**, plus the **Government ID number** with its **issue** and **expiry** dates. The purpose and occupation each take optional remarks. The relationship options change depending on whether your customer and the recipient are individuals or businesses. See [Sender and receiver relationships](/guides/beneficiaries/sender-and-receiver-relationships) for which combinations are allowed. Compliance information section with transaction purpose, occupation, relationship, nationality, and government ID fields Under **Developer fee**, set what you charge on top of each payout. You can set a **Fixed fee**, a **Percentage fee**, or both. When you set both, they are added together. Developer fee section with fixed fee and percentage fee fields This is how the payout gets funded. **Deposit rail** and **Deposit currency** are the network and token you send in. **Refund wallet address** is where funds are returned if a payout cannot be completed. Deposit and refund configuration section with deposit rail, deposit currency, and refund wallet address **Enable auto settlement** controls when the payout goes out. Leave it on and the payout is sent as soon as the funds arrive. Leave it off and the funds are held until you release them yourself. The Enable auto settlement checkbox selected Local currency payouts, such as BDT, INR, and EUR, have to be pre-funded. See [Funding your balance](/guides/move-money/funding-your-balance) for how that works. Select **Create beneficiary** to submit. ## How do I make a payment to my bank account and e-wallet? Payouts are funded in crypto. Every beneficiary is issued its own **Liquidation address**, and money you send to that address is converted and paid out to the beneficiary's bank account or wallet. On the **Beneficiaries** tab, select the beneficiary you want to pay. The **Details** panel opens. Under **Deposit and settlement** you will find the **Liquidation address**, along with the **Deposit** token and network the address expects. Copy the address. Beneficiary details panel showing the Deposit and settlement section with the liquidation address highlighted Send only the token and network shown under **Deposit**. Anything else may be lost. Send the amount you want paid out to that liquidation address, from whichever wallet you fund payouts with. Once the crypto arrives, we convert it to the beneficiary's currency, take the fees, and pay the remainder to their bank account or e-wallet. What the beneficiary receives is the converted amount after fees. Open the **Transactions** tab on the beneficiary to see the payout as it progresses. The beneficiary's **Details** panel also shows whether **Auto settlement** is enabled. With it on, the payout is sent as soon as the crypto arrives at the liquidation address, so sending the crypto is the only step you take. With it off, we hold the funds until you release them. ## When can I start paying out? A new beneficiary is not usable straight away. The details are validated first, and you can follow that in the **Status** column on the **Beneficiaries** tab. | Status | Meaning | | :------------- | :--------------------------------------------------------- | | **Processing** | The details are still being validated | | **Active** | Validation passed, and you can pay out to this beneficiary | | **Rejected** | Validation failed, and this beneficiary cannot be used | Beneficiaries tab listing two beneficiaries, one Rejected and one Active, with the Status column highlighted ## Why did my beneficiary fail to be created? One reason is that the recipient is already there. The same recipient cannot be added twice for one customer, so when the destination details match a beneficiary that already exists, the form does not save and you are told it could not be created. These are the details compared: | Destination | What is compared | | :----------- | :---------------------------------------------------------------- | | Bank account | The account scheme and number, plus the routing scheme and number | | E-wallet | The wallet provider and number | If that happens, the beneficiary you need is already on the **Beneficiaries** tab. Use that one instead of creating another. **Need a hand with your first beneficiary?** Contact us in your dedicated Slack channel and we will walk through it with you. # Getting started Source: https://developer.fin.com/guides/orchestration-dashboard/get-started Guide on getting started with the Fin.com Orchestration Dashboard. ## How do I get started with the platform? Setting up your account is a straightforward process. To obtain sandbox access and API keys, navigate to [**orchestration.fin.com**](http://orchestration.fin.com) and complete the following steps: Visit [orchestration.fin.com](https://orchestration.fin.com) and submit the registered email Sign Up Screen Enter the One-Time Password (OTP) sent to your registered contact method to verify your identity. Once verified, you will be automatically redirected to your account dashboard. # Creating a virtual account Source: https://developer.fin.com/guides/virtual-accounts/creating-a-virtual-account How to issue a virtual account for a customer, follow it to ACTIVE, and receive the first deposit as stablecoin. A virtual account gives your customer a set of bank details to receive fiat into. When a payment lands, Fin.com converts it and settles the proceeds as stablecoin to a wallet address you nominate. This guide covers the whole path: what to have in place first, how to create the account, how to follow it to `ACTIVE`, and what to expect on the first deposit. ## Before you start * **An approved customer.** Virtual accounts belong to a customer, so the customer has to exist and have reached `APPROVED`. See [Onboarding individual customers](/guides/customers/onboarding-individuals) or [Onboarding business customers](/guides/customers/onboarding-businesses). * **Confirm your customer has the capability.** Call [Get Customer Capabilities](/api-reference/customers/get-customer-capabilities) and check the `on_ramp` entry for the currency and rail you intend to use. A customer can be approved without being eligible for every corridor. * **A destination wallet that you have custody of.** The converted funds settle to an address you nominate, and Fin.com does not custody them for you. Have the address ready on the network you intend to use, and the means to sign transactions out of it. ## Choosing the source and destination A virtual account has two sides. The **source** is the fiat side, meaning the bank details your customer hands out. The **destination** is the crypto side, meaning where the converted funds settle. | Side | Field | Available now | | :---------- | :--------- | :------------------------ | | Source | `currency` | `USD` | | Source | `rail` | `ACH`, `FEDWIRE`, `SWIFT` | | Source | `bank` | `SSB`, `PORTAGE` | | Destination | `currency` | `USDC` | | Destination | `rail` | `POLYGON`, `ETHEREUM` | This guide covers issuing USD virtual accounts only. Not every combination is valid even within these values. Check [Supported rails and currencies](/guides/others/supported-rails-and-currencies) before you build against a pair, and note that what is enabled for your account may be narrower still. The `destination.wallet` format follows the network: Ethereum, Base and Polygon take a hexadecimal address, Solana takes base58. Check it carefully. Funds settled to a wrong address cannot be recovered. ## Creating the account Call [Create Virtual Account](/api-reference/virtual-accounts/create-virtual-account-v3) with the customer in the path. ```json theme={null} POST /v3/customers/{customer_id}/virtual-accounts { "destination": { "wallet": "0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39", "currency": "USDC", "rail": "ETHEREUM" }, "source": { "currency": "USD", "rail": "FEDWIRE", "bank": "SSB" }, "developer_fee": { "fixed": 0, "percentage": 0 } } ``` `developer_fee` is your own markup on each deposit. Set a fixed amount, a percentage, or both, and both are applied. ### What comes back A `200` with the account in `data`. The field to read first is `status`, and on a fresh account it is `PROCESSING`: ```json theme={null} { "data": { "id": "b84f17e1-96a8-4034-8394-e902ed403d96", "status": "PROCESSING", "deposit_instructions": null, "destination": { "address": "0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39", "currency": "USDC", "destination_chain": "ETHEREUM" }, "bank": "SSB", "rfi": null } } ``` `deposit_instructions` is `null` until the banking partner issues the account. Do not treat a `200` as the account being ready, and do not send a customer anywhere to pay until you have the deposit instructions in hand. ### One account per currency and rail A customer can hold only one virtual account per source currency and rail. Requesting one that already exists returns `422`, with the colliding `source` in `errors` and the `virtual_account_id` of the existing account: ```json theme={null} { "errors": [ { "customer_id": "c1f4a8e2-3b57-4d09-9a61-7e2b5c8d4f30", "source": { "currency": "USD", "rail": "FEDWIRE" } }, { "virtual_account_id": "9d2b7f41-6c8a-45e3-b071-2fa93c5e8d16" } ], "message": "Virtual account already exists for the given parameters." } ``` Use the account it points at rather than retrying. Treat `422` here as a lookup result, not a failure. ## Waiting for the account to go live New accounts are reviewed before the banking partner issues them. The account moves through these states: | Status | Meaning | | :------------------------ | :----------------------------------------------------------------------------- | | `PROCESSING` | Submitted and under review | | `IN_COMPLIANCE` | Under compliance review | | `REQUEST_FOR_INFORMATION` | More information is needed. The `rfi` object says what | | `ACTIVE` | Issued. `deposit_instructions` are populated and the account can receive money | | `INACTIVE` | No longer usable | | `DECLINED` | Not issued | ### Which webhooks to subscribe to Subscribe to both: | Event | Fires when | | :--------------------------------------------------------------------------------- | :------------------------------------------------------- | | [`virtual_account.created.v2`](/api-reference/webhooks/virtual-account-created-v2) | The account record is created, while still `PROCESSING` | | [`virtual_account.status.v2`](/api-reference/webhooks/virtual-account-status-v2) | The status changes, including the transition to `ACTIVE` | `virtual_account.status.v2` is the one that matters operationally. It carries the full account object, so when `status` becomes `ACTIVE` the same payload contains the populated `deposit_instructions`. You do not need a follow-up call to fetch them. ```json theme={null} { "data": { "id": "ed96d65a-5fb1-49f2-8715-0c6aa32220ca", "rfi": null, "status": "ACTIVE", "created_at": "2026-03-17T14:27:49.073891Z", "updated_at": "2026-03-17T14:42:55.788231316Z", "customer_id": "c3088a8d-50de-48cf-a137-8d46815394f8", "destination": { "address": "0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39", "currency": "USDC", "destination_chain": "ETHEREUM" }, "developer_fee_fixed": 0.22, "deposit_instructions": { "currency": "USD", "bank_code": { "code": "SSBAUS32", "type": "SWIFT" }, "bank_name": "SSB Bank", "account_type": "BankSwift", "bank_address": null, "bank_country": "USA", "payment_rails": [ "ACH" ], "bank_account_number": "235464829825", "bank_routing_number": "" }, "developer_fee_percent": 0 }, "event": { "id": "8c236a87-4ab2-49af-b22f-02d1d8e12cfa", "type": "virtual_account.status.v2", "created_at": "2026-03-17T14:42:55.813225Z", "sandbox_mode": true, "event_reference_id": "ed96d65a-5fb1-49f2-8715-0c6aa32220ca" } } ``` `event_reference_id` carries the virtual account ID, so you can match the event to your own record without parsing `data`. ### How long it takes Issuance is not instant and is not a fixed interval. It depends on the banking partner and on the customer's risk profile, and a `REQUEST_FOR_INFORMATION` pauses it until you respond. Build for this rather than polling tightly: * **Drive off the webhook.** Treat `ACTIVE` as an event you react to, not a state you wait on inside a request. * **If you must poll, poll slowly.** [Get Virtual Account Details](/api-reference/virtual-accounts/get-virtual-account-details) returns the same object. Minutes between calls, not seconds. * **Handle `REQUEST_FOR_INFORMATION`.** The `rfi` object is populated only in this state and tells you what is outstanding. Nothing progresses until it is answered. * **Do not show a customer any bank details** until you have seen `deposit_instructions` populated. ## Next: receiving the first deposit The account can now receive money. See [Receiving the first deposit](/guides/virtual-accounts/receiving-the-first-deposit) for what to hand to the payer, what lands at your destination wallet, and how to reconcile it. ## Managing accounts * [List Virtual Accounts](/api-reference/virtual-accounts/list-virtual-accounts-v3) returns every account for a customer, paginated. * [Get Virtual Account Details](/api-reference/virtual-accounts/get-virtual-account-details) returns one account, including its deposit instructions. * [Fetch Virtual Account Transactions](/api-reference/virtual-accounts/fetch-virtual-account-transactions) returns what has been received. **Need help getting set up?** Contact us in your dedicated Slack channel to confirm which banking partners and corridors are enabled for you. # Receiving the first deposit Source: https://developer.fin.com/guides/virtual-accounts/receiving-the-first-deposit How to share a virtual account's deposit instructions, what arrives at your destination wallet, and how to reconcile it. Once a virtual account reaches `ACTIVE`, it can receive money. This guide covers what to hand out, what lands at your destination wallet, and how to tie the two together. If the account is not `ACTIVE` yet, see [Creating a virtual account](/guides/virtual-accounts/creating-a-virtual-account) first. `deposit_instructions` stays `null` until the banking partner issues the account. ## Sharing the deposit instructions Read `deposit_instructions` from the account and pass every populated field to whoever is paying in. You get the same object from the `virtual_account.status.v2` webhook and from [Get Virtual Account Details](/api-reference/virtual-accounts/get-virtual-account-details), which returns the whole account: | Field | Notes | | :-------------------------- | :-------------------------------------------------------------------------- | | `bank_name`, `bank_address` | The receiving bank | | `bank_account_number` | The account to pay into | | `bank_routing_number` | Domestic routing. Not populated on rails that do not use one, such as SWIFT | | `bank_beneficiary_name` | The name the payment must be made out to | | `bank_code` | An object with `type` and `code`, for example a `BIC` | | `bic_swift` | The BIC, for SWIFT deposits | | `bank_country` | Country of the receiving bank | | `account_type` | The kind of account | | `payment_rails` | The rails this account accepts | | `currency` | The currency the account receives | ```json theme={null} { "data": { "id": "b84f17e1-96a8-4034-8394-e902ed403d96", "status": "ACTIVE", "developer_fee_percent": 2, "developer_fee_fixed": 2, "customer_id": "f60b6730-1bf1-4efa-a49e-be5ef5e75bb8", "created_at": "2026-09-09T12:27:57.657953Z", "updated_at": "2026-09-09T12:28:11.061185Z", "deposit_instructions": { "currency": "USD", "bank_name": "SSB Bank", "bank_address": null, "bank_routing_number": "", "bank_account_number": "235464829825", "bank_beneficiary_name": "WeiMing Tan", "bank_beneficiary_address": null, "payment_rails": [ "ACH" ], "bank_country": "USA", "account_type": "BankSwift", "bank_code": { "type": "SWIFT", "code": "SSBAUS32" }, "bic_swift": "SSBAUS32" }, "destination": { "currency": "USDC", "destination_chain": "ETHEREUM", "address": "0xE6F46b9Fa4Bc867816f78323EC92887E9d325DbE" }, "rfi": null, "bank": "SSB" } } ``` Which fields are populated depends on the rail. Fields that do not apply come back empty, either as `null` or as an empty string, so check for both rather than assuming a fixed set. Pass on the beneficiary name exactly as given: a payment made out to a different name may be returned. Send the payer only the rails listed in `payment_rails`. A payment sent over a rail the account does not accept may be delayed or returned. ## What happens when money arrives The deposit is converted and settled to the `destination` address you set when you created the account. What lands is the deposited amount, less conversion and any `developer_fee` you configured, so the settled amount will not equal the amount sent. Both fee components apply if you set both: | Field | Effect | | :---------------------- | :------------------------------------ | | `developer_fee_fixed` | A flat amount taken from each deposit | | `developer_fee_percent` | A percentage of the deposit amount | Settlement is not instant, and the two legs move on different clocks. The fiat leg depends on the rail the payer used, so an ACH deposit and a Fedwire deposit do not arrive on the same timeline. The crypto leg then depends on the destination network. ## Monitoring the deposit Subscribe to [`transaction.status`](/api-reference/webhooks/transaction-status) to follow a deposit from arrival to settlement. This is the event that tells you money has landed, not the virtual account events: those only describe the account itself. A virtual account deposit arrives with `transaction_type` set to `ONRAMP`. | Status | Meaning | | :--------------- | :------------------------------------------ | | `FUNDS_RECEIVED` | The fiat has arrived at the virtual account | | `PROCESSING` | Conversion and settlement are under way | | `COMPLETED` | Settled to your destination address | | `FAILED` | The deposit did not complete | | `CANCELLED` | The deposit was cancelled | ```json theme={null} { "data": { "id": "53003b38-8f34-468d-9a40-1ec9abd0b0da", "hash": "0xbe69b3602a5abc54d9616b13114060ec029b66afd3f3c156e5979b9434b4b48c", "status": "COMPLETED", "fx_rate": 1, "batch_info": { "batch_id": null, "batch_item_id": null }, "created_at": "2026-09-14T11:55:08.717927Z", "updated_at": "2026-09-14T11:59:38.024335243Z", "from_amount": 6, "developer_fee": 1.06, "from_currency": "USD", "payout_amount": 3.934, "beneficiary_id": null, "payout_currency": "USDC", "transaction_type": "ONRAMP", "processing_amount": 6, "transaction_ref_id": "b23cf755-bc0a-4cef-a5cb-939f651dc0c6", "virtual_account_id": "1ce59fee-a6ed-476f-9952-1719ea38ed91", "developer_fee_fixed": 1, "developer_fee_percentage": 1 }, "event": { "id": "e16fa3ca-fb51-4e64-8fc2-7e3c8cc101af", "type": "transaction.status", "created_at": "2026-09-14T11:59:38.081148Z", "sandbox_mode": true, "event_reference_id": "53003b38-8f34-468d-9a40-1ec9abd0b0da" } } ``` The payload carries what you need to account for the deposit without a follow-up call: | Field | Use | | :----------------------------------------------------------------- | :---------------------------------------------- | | `virtual_account_id` | Which virtual account received the deposit | | `from_amount`, `from_currency` | The fiat that went in | | `payout_amount`, `payout_currency` | The stablecoin that came out | | `processing_amount` | The amount taken into conversion | | `fx_rate` | The rate applied | | `developer_fee`, `developer_fee_fixed`, `developer_fee_percentage` | Your fee, in total and by component | | `hash` | The on-chain transaction hash of the settlement | | `transaction_ref_id` | Your own reference, if you set one | `hash` is the link between the deposit and what appears in your wallet. Store it against your record of the deposit, and reconciliation against the chain becomes a lookup rather than a guess. Expect more than one event per deposit. The same transaction ID arrives with each status change, so key on `data.id` and treat a repeat as an update rather than a new deposit. ## Reconciling the deposit Webhooks tell you about a deposit as it happens. To check the record afterwards, or to catch up on anything you missed, use [Fetch Virtual Account Transactions](/api-reference/virtual-accounts/fetch-virtual-account-transactions), which lists what has arrived on one account and is paginated. ``` GET /v1/virtual-account/{virtual_account_id}/transactions ``` Reconcile against these records rather than against your wallet balance. A balance tells you that funds arrived, not which deposit they came from, and a wallet receiving settlements from several virtual accounts gives you no way to attribute them. Keep your own mapping of virtual account ID to customer. The settlement arriving on chain does not carry the customer with it. ## Troubleshooting **Nothing has arrived.** Confirm the payer used a rail in `payment_rails`, and that they used every field exactly as given. An incomplete or mistyped beneficiary name is the most common cause of a returned payment. **The settled amount looks wrong.** Check `developer_fee_fixed` and `developer_fee_percent` on the account. Both are deducted, alongside conversion. **The deposit shows on the account but not at the wallet.** The fiat leg has completed and the crypto leg has not. Give the destination network time to confirm before treating it as missing. **Something not adding up?** Contact us in your dedicated Slack channel with the virtual account ID and we will trace the deposit. # Event structure Source: https://developer.fin.com/guides/webhooks/event-structure The shape of every Fin.com webhook payload, the events you can subscribe to, and the status values each one carries. Every Fin.com webhook arrives as a `POST` with the same two top-level keys: an `event` envelope that identifies the delivery, and a `data` object that carries the resource the event is about. ```json theme={null} { "event": { ... }, "data": { ... } } ``` The envelope is identical across all events. The `data` object differs per event, and its shape matches the schema documented on that event's API reference page. ## Event categories Webhook events are grouped into the following categories: * `customer` * `transaction` * `beneficiary` * `batch.transaction.item` * `transit.payment` ## Supported events | Category | Event | Reference | | :----------------------- | :-------------------------------- | :----------------------------------------------------------------------------------------- | | `customer` | `customer.created` | [Customer Created](/api-reference/webhooks/customer-created) | | `customer` | `customer.status` | [Customer Status](/api-reference/webhooks/customer-status) | | `customer` | `customer.rfi` | [Customer RFI](/api-reference/webhooks/customer-rfi) | | `transaction` | `transaction.status` | [Transaction Status](/api-reference/webhooks/transaction-status) | | `beneficiary` | `beneficiary.created` | [Beneficiary Created](/api-reference/webhooks/beneficiary-created) | | `beneficiary` | `beneficiary.status` | [Beneficiary Status](/api-reference/webhooks/beneficiary-status) | | `beneficiary` | `beneficiary.liquidation.deposit` | [Beneficiary Liquidation Deposit](/api-reference/webhooks/beneficiary-liquidation-deposit) | | `batch.transaction.item` | `batch.transaction.item.status` | [Batch Transaction Item Status](/api-reference/webhooks/batch-transaction-item-status) | | `transit.payment` | `transit.payment.status` | [Transit Payment Status](/api-reference/webhooks/transit-payment-status) | ## The event envelope Every payload carries the same `event` object. All five fields are always present. | Field | Type | Description | | :------------------- | :---------- | :-------------------------------------------------------------------------------------------- | | `id` | `uuid` | Unique identifier for this delivery. | | `event_reference_id` | `uuid` | Identifier of the resource the event is about, such as the beneficiary or virtual account ID. | | `type` | `string` | The event name, for example `customer.created`. | | `created_at` | `date-time` | When the event was generated, in ISO 8601 with microsecond precision. | | `sandbox_mode` | `boolean` | `true` when the event originated in sandbox. | ```json theme={null} { "event": { "id": "40061557-f125-4b39-97d6-c16a0f1230c1", "event_reference_id": "e8fccaeb-fb9d-4fae-846e-ea7c97c70b31", "type": "beneficiary.status", "created_at": "2026-04-04T17:38:26.843132Z", "sandbox_mode": true }, "data": { "type": "INDIVIDUAL", "active": false, "status": "PROCESSING", "customer_id": "ecbd3a73-3bcb-40ae-be06-0e71f9b27c2f", "beneficiary_id": "e8fccaeb-fb9d-4fae-846e-ea7c97c70b31" } } ``` ## The data object The `data` object matches the schema on the event's own reference page. Several events share a schema. | Event | `data` contains | | :------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer.created`, `customer.status` | Individual or business customer fields, depending on `type`. Individuals carry `first_name`, `last_name`, `country_of_residence`. Businesses carry `business_name`, `country_of_incorporation`, `associated_parties`. | | `customer.rfi` | The customer identifier plus the outstanding request for information. | | `transaction.status` | Transaction identifier, `status`, and amount details. | | `beneficiary.created`, `beneficiary.status` | `beneficiary_id`, `customer_id`, `type`, `active`, `status`. | | `beneficiary.liquidation.deposit` | The deposit credited against a beneficiary liquidation address. | | `batch.transaction.item.status` | The batch item identifier and its status. | | `transit.payment.status` | Payment status, including `retry_attempts`. | Open the reference page for an event to see its full schema and every example payload. ## Status values Events that report a status carry one of a fixed set of values. | Event | Status field | Values | | :----------------------------- | :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer.status` (individual) | `customer_status` | `INCOMPLETE`, `QUEUED`, `PROCESSING`, `REVIEWING`, `APPROVED`, `ON_HOLD`, `IN_COMPLIANCE`, `REINITIATE`, `ACTION_REQUIRED`, `REJECTED` | | `customer.status` (business) | `customer_status` | `INCOMPLETE`, `QUEUED`, `PROCESSING`, `REVIEWING`, `APPROVED`, `ASSOCIATED_PARTIES_REMAINING`, `ON_HOLD`, `IN_COMPLIANCE`, `REINITIATE`, `ACTION_REQUIRED`, `REJECTED` | | `customer.status` (business) | `associated_parties[].status` | `INITIATED`, `PENDING_REVIEW`, `APPROVED`, `REJECTED`, `ON_HOLD` | | `transaction.status` | `status` | `FUNDS_RECEIVED`, `PROCESSING`, `COMPLETED`, `FAILED`, `CANCELLED` | | `beneficiary.status` | `status` | `PROCESSING`, `ACTIVE`, `INACTIVE`, `REJECTED` | ## Verifying deliveries Every webhook request is signed. See [Verifying Webhooks](/guides/webhooks/verifying-webhooks) for the HMAC verification steps and code examples. ## Responding Return `200` once you have accepted the delivery. # Verifying Webhooks Source: https://developer.fin.com/guides/webhooks/verifying-webhooks Learn how to verify webhook signatures to ensure authenticity and security ## Overview Webhook signature verification ensures that incoming webhook requests are genuinely from Fin and have not been tampered with. This process uses HMAC (Hash-based Message Authentication Code) to validate each webhook payload. ## How It Works 1. **Extract the signature**: Retrieve the signature value from the webhook request header 2. **Recalculate the signature**: Use your secret key and the same hash algorithm to compute the HMAC signature for the received payload 3. **Compare signatures**: Verify that your computed signature matches the one provided in the header ## Verification Steps Follow these steps to verify webhook signatures in your application: 1. **Read the raw request body** - Capture the HTTP body as raw bytes without any modifications or parsing 2. **Extract signature headers** - Read the `x-fin-signature` and `x-fin-signature-algorithm` headers from the request 3. **Compute the HMAC** - Using your webhook secret key and the algorithm specified in `x-fin-signature-algorithm`, calculate: ``` HMAC(algorithm, secretKey, rawBodyBytes) → hexadecimal string ``` 4. **Compare signatures** - Accept the webhook only if your computed signature exactly matches the `x-fin-signature` header value Always use a constant-time comparison function to prevent timing attacks when comparing signatures. ## Code Examples Here are implementation examples in different programming languages: ```javascript Node.js theme={null} const crypto = require('crypto'); function verifyWebhookSignature(request, webhookSecret) { // Extract headers const receivedSignature = request.headers['x-fin-signature']; const algorithm = request.headers['x-fin-signature-algorithm'] || 'sha256'; // Get raw body as string or buffer const rawBody = request.body; // Ensure this is the raw body, not parsed JSON // Compute HMAC const computedSignature = crypto .createHmac(algorithm, webhookSecret) .update(rawBody, 'utf8') .digest('hex'); // Compare signatures using constant-time comparison return crypto.timingSafeEqual( Buffer.from(receivedSignature), Buffer.from(computedSignature) ); } // Usage example with Express.js app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => { const isValid = verifyWebhookSignature(req, process.env.WEBHOOK_SECRET); if (!isValid) { return res.status(401).send('Invalid signature'); } // Process the webhook const payload = JSON.parse(req.body); console.log('Valid webhook received:', payload); res.status(200).send('OK'); }); ``` ```go Go theme={null} package main import ( "crypto/hmac" "crypto/sha256" "crypto/subtle" "encoding/hex" "io" "net/http" ) func verifyWebhookSignature(r *http.Request, webhookSecret string) (bool, error) { // Extract headers receivedSignature := r.Header.Get("x-fin-signature") algorithm := r.Header.Get("x-fin-signature-algorithm") if algorithm == "" { algorithm = "sha256" } // Read raw body rawBody, err := io.ReadAll(r.Body) if err != nil { return false, err } // Compute HMAC (using SHA-256 as example) mac := hmac.New(sha256.New, []byte(webhookSecret)) mac.Write(rawBody) computedSignature := hex.EncodeToString(mac.Sum(nil)) // Constant-time comparison return subtle.ConstantTimeCompare( []byte(receivedSignature), []byte(computedSignature), ) == 1, nil } // HTTP handler example func webhookHandler(w http.ResponseWriter, r *http.Request) { webhookSecret := os.Getenv("WEBHOOK_SECRET") isValid, err := verifyWebhookSignature(r, webhookSecret) if err != nil || !isValid { http.Error(w, "Invalid signature", http.StatusUnauthorized) return } // Process the webhook w.WriteHeader(http.StatusOK) w.Write([]byte("OK")) } ``` ```python Python theme={null} import hmac import hashlib from flask import Flask, request, abort def verify_webhook_signature(request, webhook_secret): """ Verify the HMAC signature of an incoming webhook request. Args: request: Flask request object webhook_secret: Your webhook secret key Returns: bool: True if signature is valid, False otherwise """ # Extract headers received_signature = request.headers.get('x-fin-signature') algorithm = request.headers.get('x-fin-signature-algorithm', 'sha256') if not received_signature: return False # Get raw body bytes raw_body = request.get_data() # Compute HMAC hash_func = getattr(hashlib, algorithm) computed_signature = hmac.new( webhook_secret.encode('utf-8'), raw_body, hash_func ).hexdigest() # Constant-time comparison return hmac.compare_digest(received_signature, computed_signature) # Flask example app = Flask(__name__) @app.route('/webhooks', methods=['POST']) def webhook_handler(): webhook_secret = os.environ.get('WEBHOOK_SECRET') if not verify_webhook_signature(request, webhook_secret): abort(401, 'Invalid signature') # Process the webhook payload = request.get_json() print(f'Valid webhook received: {payload}') return 'OK', 200 ``` ```java Java theme={null} import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.security.MessageDigest; import java.util.HexFormat; public class WebhookVerifier { public static boolean verifyWebhookSignature( String receivedSignature, String algorithm, byte[] rawBody, String webhookSecret ) { try { // Default to SHA-256 if algorithm not specified if (algorithm == null || algorithm.isEmpty()) { algorithm = "sha256"; } // Convert algorithm name to Java format (e.g., "sha256" -> "HmacSHA256") String javaAlgorithm = "Hmac" + algorithm.toUpperCase().replace("SHA", "SHA"); // Compute HMAC Mac mac = Mac.getInstance(javaAlgorithm); SecretKeySpec secretKeySpec = new SecretKeySpec( webhookSecret.getBytes("UTF-8"), javaAlgorithm ); mac.init(secretKeySpec); byte[] hmacBytes = mac.doFinal(rawBody); // Convert to hex string String computedSignature = HexFormat.of().formatHex(hmacBytes); // Constant-time comparison return MessageDigest.isEqual( receivedSignature.getBytes(), computedSignature.getBytes() ); } catch (Exception e) { e.printStackTrace(); return false; } } // Spring Boot example @PostMapping("/webhooks") public ResponseEntity handleWebhook( @RequestHeader("x-fin-signature") String signature, @RequestHeader(value = "x-fin-signature-algorithm", defaultValue = "sha256") String algorithm, @RequestBody byte[] rawBody ) { String webhookSecret = System.getenv("WEBHOOK_SECRET"); boolean isValid = verifyWebhookSignature(signature, algorithm, rawBody, webhookSecret); if (!isValid) { return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("Invalid signature"); } // Process the webhook String payload = new String(rawBody, StandardCharsets.UTF_8); System.out.println("Valid webhook received: " + payload); return ResponseEntity.ok("OK"); } } ``` ## Best Practices Never hardcode your webhook secret in your source code. Use environment variables or a secure secrets management system. Always use constant-time comparison functions (like `crypto.timingSafeEqual` in Node.js or `hmac.compare_digest` in Python) to prevent timing attacks. Ensure your web framework provides access to the raw request body before any parsing or modifications occur. Return appropriate HTTP status codes (401 Unauthorized) for failed verifications without revealing specific error details. ## Troubleshooting If signature verification is failing: * **Check the raw body**: Ensure you're using the exact raw bytes received, not a re-serialized version * **Verify the secret**: Confirm you're using the correct webhook secret from your Fin dashboard * **Check character encoding**: Make sure you're using UTF-8 encoding consistently * **Inspect headers**: Verify that `x-fin-signature` and `x-fin-signature-algorithm` headers are present * **Test the algorithm**: Confirm you're using the algorithm specified in the `x-fin-signature-algorithm` header # Welcome Source: https://developer.fin.com/index Fin.com's Orchestration API: move money between fiat and stablecoin, across borders, through one integration. Fin.com is payments infrastructure for businesses. You integrate once, and your customers can receive money as local fiat and have it settle as stablecoin, or send stablecoin and have it arrive in a local bank account or mobile wallet. Everything runs on one set of APIs: onboard a customer, give them an account to be paid into, add the people they pay, and move the money. This documentation covers how to do that, what each corridor supports, and what to expect when something needs review. ## What you can build * **Collect money in local currency.** Issue a customer their own bank details. Deposits are converted and settled as stablecoin to a wallet address you nominate. * **Pay out to local rails.** Send stablecoin and have it arrive as local fiat in a bank account or an e-wallet, across a growing list of corridors. * **Onboard customers under your own brand.** Run KYC and KYB through the API. Fin.com never contacts your customers directly. * **Move crypto between venues.** Route payments between exchanges and wallets through Crypto Orchestration. ## Get started Walkthroughs for onboarding, virtual accounts, beneficiaries, and payouts. Every endpoint and webhook, with request and response schemas. Do the same things without writing code, from the Orchestration Dashboard. What shipped, what changed, and what is being retired. ## Core concepts New to Fin.com? The [Glossary](/guides/get-started/glossary) defines the terms used throughout this documentation, from virtual accounts and beneficiaries to liquidation addresses and prefunding. ## Getting help We are glad you are building with us. If something is unclear or not behaving as documented, reach out in your dedicated Slack channel and we will pick it up.