# 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 POST /v2/beneficiaries Create a new beneficiary account for payments and transfers This endpoint was deprecated on May 20, 2026. Use [Create Beneficiary V3](https://developer.fin.com/api-reference/beneficiaries/create-beneficiary-v3) instead. ## Rules * Beneficiary creation requires the customer to be in the `APPROVED` status. * Two beneficiaries with the same destination are not allowed. ## De-Duplication Logic For *bank accounts*, the system checks: `bank_account.scheme`, `bank_account.number`, `bank_routing.scheme`, `bank_routing.number`. For *e-wallets*: `e_wallet.scheme`, `e_wallet.number`. ## Country-Specific Validation ### GBR (United Kingdom) * **Bank account number**: Must match `^[0-9]{4,9}$` for both `LOCAL` and `SWIFT` schemes. # Create Beneficiary V3 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, e-wallets, and external crypto wallets as destination types. The beneficiary will be ready for transactions only when its `status` is `APPROVED` and `active` is true. ## 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` | | External Crypto Wallet | `destination_wallet.address`, `destination_wallet.rail` | # Fetch Beneficiary Details v1 Source: https://developer.fin.com/api-reference/beneficiaries/fetch-beneficiary-details-v1 GET /v1/beneficiaries/details Retrieve detailed information for a specific beneficiary This endpoint was deprecated on May 20, 2026. Use [Fetch Beneficiary Details V2](https://developer.fin.com/api-reference/beneficiaries/fetch-beneficiary-details-v2) instead. # Fetch Beneficiary Details v2 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 # 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 **Create Business Customer V1** only. It is not applicable for Create Business Customer V2. # 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](https://developer.fin.com/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](https://developer.fin.com/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](https://developer.fin.com/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 Document To Associated Party Source: https://developer.fin.com/api-reference/customers/attach-document-to-associated-party POST /v1/customers/associated-parties/individual/attach Attach proof of identity and proof of address documents to associated parties of an existing customer This endpoint was deprecated on May 20, 2026. Use [Attach Documents to Associated Party V2](https://developer.fin.com/api-reference/customers/attach-documents-to-associated-party-v2) instead. * Before calling this endpoint, upload documents using the [Upload document](https://developer.fin.com/api-reference/customers/upload-document) endpoint to obtain the URIs needed for the `files` arrays. * This endpoint allows attaching documents for multiple associated parties in a single request. # Attach Documents to Associated Party V2 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 POST /v1/customers/business/attach Attach ownership structure, company details, and legal presence documents to an existing business customer This endpoint was deprecated on May 20, 2026. Use [Attach Documents to Business Customer V2](https://developer.fin.com/api-reference/customers/attach-documents-to-business-customer-v2) instead. * Before calling this endpoint, upload documents using the [Upload document](https://developer.fin.com/api-reference/customers/upload-document) endpoint to obtain the URIs needed for the `files` arrays. * The `tos_policies_value` should be parsed from the `tos_policies_url` query parameter returned from the Create Business Customer endpoint. # Attach Documents to Business Customer V2 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 POST /v1/customers/individual/attach Attach proof of identity and proof of address documents to an existing individual customer This endpoint will be deprecated soon. We recommend using the [Attach Documents to Individual Customer V2](https://developer.fin.com/api-reference/customers/attach-documents-to-individual-customer-v2) endpoint instead. * Before calling this endpoint, upload documents using the [Upload document](https://developer.fin.com/api-reference/customers/upload-document) endpoint to obtain the URIs needed for the `files` arrays. * The `tos_policies_value` should be parsed from the `tos_policies_url` query parameter returned from the Create Individual Customer endpoint. # Attach Documents to Individual Customer V2 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 POST /v1/customers/business Create a new business customer with verification details, addresses, and associated parties This endpoint was deprecated on May 20, 2026. Use [Create Business Customer V2](https://developer.fin.com/api-reference/customers/create-business-customer-v2) instead. ## 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" * **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 # Create Business Customer V2 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 POST /v1/customers/individual Create a new individual customer with verification details This endpoint will be deprecated soon. We recommend using the [Create Individual Customer V2](https://developer.fin.com/api-reference/customers/create-individual-customer-v2) endpoint instead. Only English (Latin) characters are allowed as inputs for all fields. ## 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" # Create Individual Customer V2 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. # Enable USD Features Source: https://developer.fin.com/api-reference/customers/enable-usd-features POST /v1/customers/enable-preference Enable USD features for an existing customer This endpoint is deprecated and will be removed in a future release. Do not use it in new integrations. You can skip this step entirely and call [Create Virtual Account V2](https://developer.fin.com/api-reference/virtual-accounts/create-virtual-account-v2) directly, which handles USD feature enablement as part of account creation. # 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 GET /v1/customers/{customer_id} Retrieve detailed information for a specific customer Use this endpoint to fetch individual customer details. For business customer details, use [Get Customer Details V2](https://developer.fin.com/api-reference/customers/get-customer-details-v2). # Get Customer Details V2 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). # Get Customer Wallets Source: https://developer.fin.com/api-reference/customers/get-customer-wallets GET /v2/customers/{customer_id}/wallets Returns all crypto wallets linked to a customer across supported chains and tokens. Fin.com issued crypto wallets require pre-configuration. Contact support to learn more. Upon approval, the customer is provisioned wallet addresses for the following rails and currencies: | Rail | Currency | | -------- | -------- | | POLYGON | USDC | | ETHEREUM | USDC | | SOLANA | USDC | # List Customers Source: https://developer.fin.com/api-reference/customers/list-customers GET /v1/customers Retrieve a list of customers filtered by type This endpoint was deprecated on May 20, 2026. Use [List Customers V2](https://developer.fin.com/api-reference/customers/list-customers-v2) instead. # List Customers V2 Source: https://developer.fin.com/api-reference/customers/list-customers-v2 GET /v2/customers Retrieve a list of customers filtered by type # Update Customer Source: https://developer.fin.com/api-reference/customers/update-customer 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 Business Customer V2 * Attach Document To Associated Party * Attach Document To Associated Party V2 # 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-fx/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-fx/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 Pay-in Source: https://developer.fin.com/api-reference/transactions/create-a-pay-in POST /v2/transactions/pay-ins Create a pay-in instruction for a customer. Make payment before expiry with mandatory reference code and receive crypto in the destination wallet address. Pay-in instructions require separate configuration. Contact support to enable this feature for your account. # 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 `true`. # 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 `true`. **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 V1 Source: https://developer.fin.com/api-reference/transactions/fetch-transaction-details-v1 GET /v1/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. For **CRYPTO\_DEPOSIT** and **CRYPTO\_WITHDRAWAL** transaction types, you must use [Fetch Transaction Details V2](/api-reference/transactions/fetch-transaction-details-v2). We also recommend migrating all transaction detail lookups to V2, as V1 will be deprecated soon. # Fetch Transaction Details V2 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 ``` # List Pay-ins Source: https://developer.fin.com/api-reference/transactions/list-pay-ins GET /v2/transactions/pay-ins Returns a paginated list of pay-ins. # Pay-in Details Source: https://developer.fin.com/api-reference/transactions/pay-in-details GET /v2/transactions/pay-ins/{payin_id} Returns full details for a pay-in by ID, including status, amounts, fees, and deposit instructions. # 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 # 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 POST /v1/customers/virtual-account Create a virtual bank account for a customer to convert USD deposits to USDC on Polygon This endpoint was deprecated on May 20, 2026. Use [Create Virtual Account V2](https://developer.fin.com/api-reference/virtual-accounts/create-virtual-account-v2) instead. # Create Virtual Account V2 Source: https://developer.fin.com/api-reference/virtual-accounts/create-virtual-account-v2 POST /v2/customers/{customer_id}/virtual-accounts Create a virtual bank account for a specific customer to convert USD deposits to USDC. The `customer_id` path parameter identifies the customer for whom the virtual account is being created. # 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 # List Virtual Accounts V1 Source: https://developer.fin.com/api-reference/virtual-accounts/list-virtual-accounts-v1 GET /v1/customers/virtual-account Retrieve a list of all virtual accounts for a specific customer This endpoint was deprecated on May 20, 2026. Use [List Virtual Accounts V2](https://developer.fin.com/api-reference/virtual-accounts/list-virtual-accounts-v2) instead. # List Virtual Accounts V2 Source: https://developer.fin.com/api-reference/virtual-accounts/list-virtual-accounts-v2 GET /v2/customers/{customer_id}/virtual-accounts Retrieve a list of all virtual accounts for a specific customer # Update Virtual Account Source: https://developer.fin.com/api-reference/virtual-accounts/update-virtual-account PUT /v1/customers/virtual-account Update an existing virtual bank account's developer fee percentage and destination wallet address # 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 V1 Source: https://developer.fin.com/api-reference/webhooks/virtual-account-created-v1 WEBHOOK virtual_account.created Triggered when a new virtual account is created for a customer. # 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 V1 Source: https://developer.fin.com/api-reference/webhooks/virtual-account-status-v1 WEBHOOK virtual_account.status Triggered when a virtual account's status changes. # 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. # Bank account & routing number validation rules Source: https://developer.fin.com/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", "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 } } ``` # 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-&-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-&-fx-rates/calculate-fees) 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](/api-reference/beneficiaries/create-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-&-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/calculate) 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, 2025 Source: https://developer.fin.com/changelogs/2026-02-16 Changelog for February 16, 2025 ## ✨ 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](/api-reference/beneficiaries/create-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 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-document-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}` — [reference](/api-reference/customers/get-customer-details) | `GET /v2/customers/{customer_id}` — [reference](/api-reference/customers/get-customer-details-v2) | ### Beneficiaries | Resource | Deprecated Endpoint | New Endpoint | | ----------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Create beneficiary | `POST /v2/beneficiaries` — [reference](/api-reference/beneficiaries/create-beneficiary) | `POST /v3/beneficiaries` — [reference](/api-reference/beneficiaries/create-beneficiary-v3) | | Get beneficiary details | `GET /v1/beneficiaries/details` — [reference](/api-reference/beneficiaries/fetch-beneficiary-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` — [reference](/api-reference/virtual-accounts/create-virtual-account-v2) | | List virtual accounts | `GET /v1/customers/virtual-account` — [reference](/api-reference/virtual-accounts/list-virtual-accounts) | `GET /v2/customers/virtual-account` — [reference](/api-reference/virtual-accounts/list-virtual-accounts-v2) | *** ## 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**. # April 13, 2026 Source: https://developer.fin.com/changelogs/april-13-2026 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. Also adds an optional `supporting_documents` array. 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. # June 10, 2026 Source: https://developer.fin.com/changelogs/june-10-2026 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/june-16-2026 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) | # May 01, 2026 Source: https://developer.fin.com/changelogs/untitled-page 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. # Definition of Statuses Source: https://developer.fin.com/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/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](https://developer.fin.com/crypto-orchestration). 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/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** — 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/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/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](https://developer.fin.com/crypto-orchestration). ## 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/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. 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, 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 — 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 ``` *** ## Flow of APIs for Crypto transfer to external wallets: Fin Crypto Transfer Flow \ **Step 1: Get crypto wallets for a given customer** * Call the [Get Customer Details](https://developer.fin.com/api-reference/customers/get-customer-wallets) API to get the wallet addresses assigned to the customer along with their balances. * Fin provisions wallets for the following chains: Polygon, Ethereum, and Solana. (Save wallet IDs to use in quote later) * You will receive crypto in these wallets from the external sources. \ **Step 2: Create an external crypto wallet to withdraw crypto from Fin wallets** * Call the [Create beneficiary V3](https://developer.fin.com/api-reference/beneficiaries/create-beneficiary-v3) endpoint with the fields required for external crypto. (Save beneficiary ID to use in quote later) * Follow the exact payload structure given in the request example. * Monitor webhook for beneficiary approval ([beneficiary.created](https://developer.fin.com/api-reference/webhooks/beneficiary-created), [beneficiary.status](https://developer.fin.com/api-reference/webhooks/beneficiary-status)). It's almost instant. * You can check beneficiary details using [Fetch beneficiary details V2](https://developer.fin.com/api-reference/beneficiaries/fetch-beneficiary-details-v2) \ **Step 3: Monitor crypto deposit in the Fin issues wallet** * Webhook event to monitor: `transaction.status` * TransactionType: `CRYPTO_DEPOSIT` * Status: `FUND_RECEIVED` \ **Step 4: Create a quote to get a quote estimation** * Call the [Create quote](https://developer.fin.com/api-reference/transactions/create-quote) with `beneficiary_id` and `crypto_wallet_id` . * You will get a quote estimation and expiry time \ **Step 5: Execute the quote before it expires** * Call [Execute quote](https://developer.fin.com/api-reference/transactions/execute-quote) with the `quote_id` from the former response \ **Step 6: Monitor the webhook for withdrawal confirmation** * Webhook event to monitor: `transaction.status` * TransactionType: `CRYPTO_WITHDRAWAL` * Status: `FUND_REQUEST_SUCCESS` # Legends & Concepts Source: https://developer.fin.com/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/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 ``` # How USD features work for a customer Source: https://developer.fin.com/faqs/how-usd-feature-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 V2. ## 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 V2) 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 + Update Customer, 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 (Fedwire) Dev->>Fin: Create virtual account (Create Virtual Account V2) 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 V2** 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 **Update Customer**. 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. 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 V2 / 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 V2** 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 **Update Customer**. Do not re-run **Attach Customer**. Repeat until all RFIs are cleared. RFIs currently cover documents only. 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. After approval, USD is requested automatically. Wait for the banking partner review, then create the account with **Create Virtual Account V2** 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. # Individual ID Document Upload Source: https://developer.fin.com/faqs/individual-id-document-upload Best practices and edge cases for uploading individual ID documents through fin.com. ## 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. # Technical Integration Source: https://developer.fin.com/faqs/technical-integration FAQs regarding API integration, sandbox testing, and technical 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 — more are 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 # business-industry-codes Source: https://developer.fin.com/guides/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/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/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` | | **Trust** | `FORMATION_DOCUMENT` | `PROOF_OF_SIGNATORY_AUTHORITY` | `PROOF_OF_ADDRESS`, `PROOF_OF_SOURCE_OF_FUNDS`, `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` | | **Charity** | `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` | | **Government Agency** | `CONSTITUTIONAL_DOCUMENT` | `PROOF_OF_SIGNATORY_AUTHORITY` | `PROOF_OF_ADDRESS`, `PROOF_OF_SOURCE_OF_FUNDS`, `SHAREHOLDER_REGISTER`, `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 Types & Descriptions | Document | Description | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `REGISTRATION_DOCUMENT` | Certificate of Incorporation OR Certificate of Formation/Registration or Limited Partnership | | `CONSTITUTIONAL_DOCUMENT` | Constitutional or formation documents OR Articles of Organization OR Partnership Agreement OR Operating/LP Agreement (if applicable) OR Articles of Incorporation/Bylaws or equivalent document | | `EVIDENCE_OF_DIRECTORS_AND_CONTROLLERS` | A Certificate of Incumbency or a Register of Directors (or their equivalent) | | `FORMATION_DOCUMENT` | Trust Agreement | | `PROOF_OF_TAX_IDENTIFICATION` | Tax Filings | | `PROOF_OF_SIGNATORY_AUTHORITY` | Authorized Representative List OR List of Manager or similar person(s) that has(have) the ability to legally bind the entity and carry out its instructions | | `SHAREHOLDER_REGISTER` | Register of shareholders or members | | `OWNERSHIP_INFORMATION` | Voting Records | | `OWNERSHIP_CHART` | Fund Structure Chart | | `CERT_OF_INCUMBENCY` | Certificate of Incumbency | | `PROOF_OF_ADDRESS` | Proof of Business Entity Address | | `PROOF_OF_SOURCE_OF_FUNDS` | Proof of Source of Funds (if applicable) | | `PROOF_OF_SOURCE_OF_WEALTH` | Annual Reports | | `PROOF_OF_NATURE_OF_BUSINESS` | Business License | | `PROOF_OF_ENTITY_NAME_CHANGE` | Trade Name Registration / Doing Business As (DBA) Filing | | `TAX_EXEMPT_ENTITY_CONFIRMATION` | Tax Exemption or Charity Registration Letter (for US, provide IRS Determination Letter) | | `MARKETING_MATERIALS` | Prospectus, Offering Memorandum, or Private Placement Memorandum | | `AML_COMFORT_LETTER` | AML Attestation Letter issued by Fund Administrator | | `E_SIGNATURE_CERTIFICATE` | Electronic Signature Certificate. Provide an authorized representative list, board resolution, or equivalent document for the entity to verify signing authority. | | `FLOW_OF_FUNDS` | Flow of Funds diagram or statement | | `EVIDENCE_OF_GOOD_STANDING` | Certificate of Good Standing | | `PROOF_OF_NATURE_OF_BUSINESS_LICENSE` | National or State License or Registration to provide money transmission or digital asset services | | `PROOF_OF_NATURE_OF_BUSINESS_AML_POLICY` | AML and Sanctions Policy | | `PROOF_OF_ACCOUNT_PURPOSE` | Statement of Account Purpose | # High Risk Activities Source: https://developer.fin.com/guides/compliance/high-risk-businesses 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 Tax ID documents Source: https://developer.fin.com/guides/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 | # Business Onboarding Requirements — Quick Reference Source: https://developer.fin.com/guides/compliance/kyb-guidelines-to-succeed ## What You Need to Submit ### Company Basics * Exact legal name (must match formation documents) * Physical operating address (NO virtual/PO Box/registered agent addresses — use UBO's home address if remote) * Formation document with filing stamp * Registration / Tax ID number (EIN, ITIN, RFC, or VAT) * Business email, phone, and functional website (if no website: provide invoices or marketing materials) * Entity type (LLC, Corporation, Partnership, Investment Fund, Foundation/NPO, Trust, Sole Proprietorship, DAO, Government Body) ### Business Description * Industry type (NAICS code — regulated industries need license proof) * Nature of business * Account purpose * Source of funds and source of wealth ### Financial Details * Estimated annual revenue * Anticipated monthly fiat deposits and withdrawals * Public company status * Third-party payout intent * Provide bank statements and invoices (for large transactions) ### Related Parties * All UBOs: full name, DOB, nationality, residential address, government-issued photo ID (unexpired), proof of address (utility bill \<90 days), SSN/ITIN (US residents) * At least 1 Authorized Person * Person with Significant Management Control (CEO/CFO/COO — required even without ownership) * Directors (non-U.S. companies only) * Corporate shareholders: legal name, country, registration number, ownership % ### Supporting Documents (by entity type) * **All entities:** Proof of business address, proof of source of funds, shareholder registry (or cap table/org chart), formation document with filing stamp, control structure document * **Investment Funds:** Prospectus, AML Comfort Letter, Fund Structure Chart * **Foundations/NPOs:** Tax Exemption Letter, Annual Reports * **Trusts:** Trust Agreement * **Sole Proprietorships:** Business License, DBA Filing, Tax Filings * **DAOs:** Voting Records * **Regulated entities** (MSB, PSP, DASP): Current license + AML & Sanctions Policy ### Document Validity * Proof of address / bank statements / financial statements: **90 days** * Tax returns: **1 year** * Formation documents: **No expiration** * Government ID: **Must not be expired** *** ## Pre-Submission Checklist ### Always Required * Company name, physical address, formation document, Tax ID * Business description (250+ chars), industry selection, account purpose * Source of funds, monthly volume estimate * Business activity docs (invoices or business plan) * UBO info + government ID for all owners and control person ### Conditionally Required * DBA documents (if operating under different name) * Proof of address (if address flagged) * Investment funding agreement (if source is investment) * Third-party fund explanation + funds flow diagram (if handling others' funds) * Bank statements (if monthly volume > \$1M) * Org chart (if complex ownership) * Licenses (if regulated industry) *** **Need Help?** Contact [compliance@fin.com](mailto:compliance@fin.com) # Guidance on nested in payments & onboarding Source: https://developer.fin.com/guides/compliance/nested-payments-and-onboarding How Fin handles nested payments & 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. 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. 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. *** ## All transactions must be first-party Every transaction processed through Fin must be first-party. This means the funds in a virtual account must belong to the account holder, and the account holder must be onboarded with Fin. Fin does not support nested flows. A developer cannot collect payments from multiple third parties into a single virtual account and operate as a money service business or financial institution through Fin's infrastructure. ### What "first-party" means in practice A first-party transaction is one where the sender and the virtual account holder are the same entity, or where the account holder can demonstrate a legitimate business reason for receiving funds from a named 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. Even though the transaction originates from "Stripe" or "Nuvei," it is still considered first-party because the underlying funds belong to the onboarded customer. **Example: Nested flow (not supported)** A developer onboards with Fin and receives a virtual account. They then instruct their own customers to send funds directly into that single virtual account, pooling money from multiple parties. This is not permitted. Each customer must be individually onboarded and issued their own virtual account. *** ## Documents required for high-volume first-party payments For first-party payments that are substantially high in volume, Fin will require the following documents if they were not already provided during 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. In high-risk jurisdictions, Fin may also request recipient information (which, for first-party payments, refers to the account holder themselves). These requirements apply regardless of payment size if the transaction pattern or jurisdiction triggers a compliance review. *** ## Restricted business activities Certain business types and activities cannot be facilitated through Fin. See [Restricted and High-Risk Businesses](/guides/compliance/high-risk-businesses) for the full list. *** ## Frequently asked questions It depends on the context. If you are receiving funds from a payment processor (like Stripe or Nuvei) where you have a verified account under your legal name, that is permitted with documentation. If you are collecting funds from multiple unrelated third parties without onboarding them, that is not supported. Every entity transacting through Fin must be individually onboarded. 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. Fin will ask for a letter or document confirming this relationship. Since the funds ultimately belong to you, this is still a first-party transaction. 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. No. Fin does not support developers using virtual accounts to run money service businesses, payment processing operations, or financial institution activities. See the restricted business activities page for details. # Onboarding Business Customers Source: https://developer.fin.com/guides/customers/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 | | `TRUST` | Trust | | `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-subdivision-codes). | | `subdivision_code`\* | string | State/province code from [**/v1/countries/subdivisions**](https://developer.fin.com/api-reference/catalogue/list-subdivision-codes). | | `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` | `FORMATION_DOCUMENT` | Trust Agreement (for Trust entities) | | `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" } ] } ], "supporting_documents": [] } ] }' ``` 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:** ```text theme={null} INCOMPLETE → ASSOCIATED_PARTIES_REMAINING → PROCESSING → REVIEWING → APPROVED ↕ IN_COMPLIANCE / REJECTED ↕ ACTION_REQUIRED ``` **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-businesses) * 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/api-reference/beneficiaries/account-info-validation) * Review [**Beneficiary Relationships**](https://developer.fin.com/api-reference/beneficiaries/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`)* ## 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/industries](/api-reference/catalogue/list-industries), [/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/industries](/api-reference/catalogue/list-industries), [GET /v1/purposes?type=BUSINESS](/api-reference/catalogue/list-account-purposes), [GET /v1/source-of-funds?type=BUSINESS](/api-reference/catalogue/list-source-of-funds) | Retrieve valid IDs for industries, purposes, and fund sources | | 2. Create Customer | [POST /v1/customers/business](/api-reference/customers/create-business-customer) | Submit company details, addresses, financial profile, and associated parties (UBOs) | | 3. Upload Documents | [POST /v1/customers/upload](/api-reference/customers/upload-document) | Upload business and associated party documents | | 4. Attach Business Docs | [POST /v1/customers/business/attach](/api-reference/customers/attach-documents-to-business-customer) | Link ownership structure, company details, and legal presence documents with TOS acceptance | | 5. Attach Party Docs | [POST /v1/customers/associated-parties/individual/attach](/api-reference/customers/attach-document-to-associated-party) | Link identity and address proofs for each associated party | | 6. Monitor Status | Webhooks: `customer.status` | 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 KYC 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"` #### Basic Information (Required) > Company details exactly as shown on incorporation documents. **All fields must use only English (Latin) characters**. **Fields:** | Field | Type | Description | Example | | -------------------------- | -------------- | -------------------------------------------------- | ----------------------------- | | `business_name` | string | Full legal name from Certificate of Incorporation | `"Acme Corporation"` | | `business_trade_name` | string | Brand or DBA (Doing Business As) name *(optional)* | `"Acme"` | | `description` | string | Description of the company's business activities | `"Software development"` | | `entity_type` | enum | Legal entity structure (see table below) | `"LIMITED_LIABILITY_COMPANY"` | | `website` | string (uri) | Company website URL | `"https://acmecorp.com"` | | `email` | string (email) | Business email address — **must be all lowercase** | `"contact@acmecorp.com"` | | `incorporation_date` | string (date) | Date of incorporation in YYYY-MM-DD format | `"2020-01-15"` | | `phone` | string | Business phone number in E.164 format | `"+14155552671"` | | `country_of_incorporation` | string | ISO Alpha-3 country code | `"USA"` | | `registration_number` | string | Business registration number | `"87-1234567"` | | `tax_id` | string | Tax identification number (EIN for USA businesses) | `"12-3456789"` | Email must be **all lowercase** or validation will fail. Convert to lowercase before sending: `contact@acmecorp.com` ✓ not `Contact@AcmeCorp.com` ✗ **Valid Entity Types:** | Entity Type | Description | | ---------------------------- | --------------------------------- | | `LIMITED_LIABILITY_COMPANY` | Limited Liability Company (LLC) | | `PRIVATE_LIMITED` | Private Limited Company (Pte Ltd) | | `PUBLICLY_LISTED_COMPANY` | Publicly traded corporation | | `CORPORATION` | Corporation (Inc, Corp) | | `SOLE_PROPRIETOR` | Sole proprietorship | | `PARTNERSHIP` | Partnership | | `TRUST` | Trust | | `PRIVATE_FOUNDATION` | Private foundation | | `CHARITY` | Charitable organization | | `NONPROFIT_ORGANIZATION` | Non-profit organization | | `PUBLIC_AGENCY_OR_AUTHORITY` | Government agency or authority | #### Financial Profile (Required) > Describes business purpose, industry, transaction volume, and fund sources. Use catalogue endpoints to fetch valid IDs. **Fields:** | Field | Type | Description | How to Get Value | | ------------------------ | ------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | `purpose_id` | integer | Account purpose | [GET /v1/purposes?type=BUSINESS](/api-reference/catalogue/list-account-purposes) | | `other_purpose` | string | Custom purpose (only when purpose\_id = "Other") | User input | | `business_industry_id` | integer | Industry classification | [GET /v1/industries](/api-reference/catalogue/list-industries) | | `monthly_volume` | integer | Expected monthly volume in **USD** (not cents). Accepts `0`. | User estimate: `50000` | | `source_of_fund_id` | integer | Source of funds | [GET /v1/source-of-funds?type=BUSINESS](/api-reference/catalogue/list-source-of-funds) | | `third_party_fund_usage` | boolean | Processing funds on behalf of others | 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, money services). This triggers enhanced compliance review. See [High-Risk Business Activities](/guides/compliance/high-risk-businesses) for details. For most normal businesses (SaaS companies, import/export, consulting agencies), `third_party_fund_usage` should be `false`. Only MSBs, payment facilitators, and similar businesses should set this to `true`. **Example:** ```json theme={null} { "financial_profile": { "purpose_id": 10, "business_industry_id": 1, "monthly_volume": 50000, "source_of_fund_id": 13, "third_party_fund_usage": false } } ``` In this example: `purpose_id: 10` = Cross-border payouts, `business_industry_id: 1` = Technology, `monthly_volume: 50000` = \$50,000 USD (integer, not cents), `source_of_fund_id: 13` = Sales revenue. #### Addresses (Required) > Registered and operational addresses for the business. **Fields:** | Field | Required | Description | | ------------------------------ | ----------- | ------------------------------------------------------------------------ | | `is_incorporated_address_same` | Yes | `true` if physical and incorporated addresses are identical | | `incorporated_address` | Yes | Registered address from incorporation papers | | `physical_address` | Conditional | Operating address (required only if different from incorporated address) | **Address Object:** | Field | Type | Description | Example | | ------------- | ------ | ------------------------ | ------------------------------- | | `street` | string | Street address | `"123 Market Street Suite 400"` | | `city` | string | City name | `"San Francisco"` | | `state` | string | `"US-CA"` | | | `postal_code` | string | Postal or ZIP code | `"94103"` | | `country` | string | ISO Alpha-3 country code | `"USA"` | **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": "10 Anson Road #26-04 International Plaza", "city": "Singapore", "state": "SG-01", "postal_code": "079903", "country": "SGP" }, "physical_address": { "street": "456 Market Street Floor 3", "city": "San Francisco", "state": "US-CA", "postal_code": "94103", "country": "USA" } } } ``` #### Associated Parties (Minimum 1 Required) > **UBO (Ultimate Beneficial Owner)**: Individuals with ≥10% ownership OR significant control over the entity. All must be disclosed for regulatory compliance. Each associated party must include: **basic\_info (all fields required):** | Field | Description | | ---------------------- | ---------------------------- | | `first_name` | First name | | `last_name` | Last name | | `dob` | Date of birth (YYYY-MM-DD) | | `email` | Email address | | `phone` | Phone number in E.164 format | | `country_of_residence` | ISO Alpha-3 country code | | `nationality` | ISO Alpha-3 country code | | `tin` | Tax Identification Number | **address (all fields required):** Residential address with same structure as business address (`street`, `city`, `state`, `postal_code`, `country`). **ownership\_info (all fields required):** | Field | Type | Description | | --------------------------------- | ------------- | ---------------------------------------------- | | `designation` | string | Role or position (e.g., CEO, Director, UBO) | | `percentage_of_ownership` | number | Percentage of ownership in the business | | `relationship_establishment_date` | string (date) | When relationship was established (YYYY-MM-DD) | **Ownership Validation**: Total ownership percentages across all associated parties must be **\< 100%**. Individual parties may have a `percentage_of_ownership` of 0. **Example:** ```json theme={null} { "associated_parties": [ { "basic_info": { "first_name": "John", "last_name": "Smith", "dob": "1985-03-20", "email": "john.smith@acmecorp.com", "phone": "+14155551234", "country_of_residence": "USA", "nationality": "USA", "tin": "123-45-6789" }, "address": { "street": "456 Oak Avenue", "city": "San Francisco", "state": "US-CA", "postal_code": "94102", "country": "USA" }, "ownership_info": { "designation": "CEO", "percentage_of_ownership": 75.0, "relationship_establishment_date": "2020-01-15" } }, { "basic_info": { "first_name": "Jane", "last_name": "Doe", "dob": "1988-07-12", "email": "jane.doe@acmecorp.com", "phone": "+14155555678", "country_of_residence": "USA", "nationality": "USA", "tin": "987-65-4321" }, "address": { "street": "789 Pine Street Apt 12", "city": "San Francisco", "state": "US-CA", "postal_code": "94109", "country": "USA" }, "ownership_info": { "designation": "CFO", "percentage_of_ownership": 25.0, "relationship_establishment_date": "2020-01-15" } } ] } ``` #### Metadata (Optional) Custom key-value pairs for internal tracking: ```json theme={null} { "meta_data": { "reference": "REF-20250123-ACME", "internal_notes": "Enterprise tier customer", "sales_rep": "john.sales@yourcompany.com" } } ``` ### Document Upload & Attachment After creating the business 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=2d0a9df3-e1e5-4955-9759-ce0522e0ddc9' \ --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 documents to the business customer: ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/customers/business/attach \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "customer_id": "2d0a9df3-e1e5-4955-9759-ce0522e0ddc9", "ownership_structure": [ { "type": "SHAREHOLDER_REGISTRY", "files": [{"uri": "/XyZ123mn_0652746727638.pdf"}] } ], "company_details": [ { "type": "CERT_OF_INCORPORATION", "files": [{"uri": "/AbAcQ4hn_0652746727637.pdf"}] } ], "legal_presence": [ { "type": "PROOF_OF_ADDRESS", "files": [{"uri": "/PoAdef45_0652746727639.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 | | --------------------- | --------------------------- | ------------------------------------------------ | | `ownership_structure` | `SHAREHOLDER_REGISTRY` | Shareholder registry or cap table | | `company_details` | `CERT_OF_INCORPORATION` | Certificate of incorporation | | `company_details` | `MEMORANDUM_OF_ASSOCIATION` | Memorandum of association | | `legal_presence` | `PROOF_OF_ADDRESS` | Utility bill, lease agreement, or bank statement | #### Step 3: Attach Associated Party Documents Upload identity and address proofs for each UBO: ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/customers/associated-parties/individual/attach \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "customer_id": "2d0a9df3-e1e5-4955-9759-ce0522e0ddc9", "associated_party_attachments": [ { "associated_party_id": "a7c3b4e2-d8f1-4a5c-9e7d-2f6b8c3a1e9f", "proof_of_identity": { "type": "NATIONAL_ID", "number": "A12345678", "country": "USA", "issue_date": "2020-01-15", "expiry_date": "2030-01-15", "files": [ {"side": "FRONT", "uri": "/id_front_john_0652746727640.pdf"}, {"side": "BACK", "uri": "/id_back_john_0652746727641.pdf"} ] }, "proof_of_address": { "type": "UTILITY_BILL", "country": "USA", "files": [ {"uri": "/utility_john_0652746727642.pdf"} ] } } ] }' ``` The `associated_party_id` is returned in the [GET /v1/customers/:customer\_id](/api-reference/customers/get-customer-details) 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) | **Address Proof Types:** | Type | Description | | ------------------- | ------------------------------------------ | | `UTILITY_BILL` | Recent utility bill (gas, electric, water) | | `BANK_STATEMENT` | Bank statement (within last 3 months) | | `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:** ```text theme={null} INCOMPLETE → REVIEWING → APPROVED ↓ ON_HOLD / REJECTED ``` **Special Status:** * `ASSOCIATED_PARTIES_REMAINING` — Some party documents still needed **Webhook Events:** * `customer.created` — Fired when 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" } ``` **Ownership percentage validation:** ```json theme={null} { "message": "Validation failed", "errors": { "associated_parties": ["Total ownership percentages must be > 0 and < 100"] } } ``` *** ## What's Next? You've successfully created a business customer. 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 `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 * ✓ 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 Before going live, ensure you have: * Implemented webhook handling for status updates * Added proper error handling for all failure scenarios * Client-side validation for email lowercase * Fetched and cached catalogue data (industries, purposes, source-of-funds) * Implemented document upload UI/flow * Reviewed [High-Risk Business Activities](/guides/compliance/high-risk-businesses) * 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](/api-reference/beneficiaries/account-info-validation) * Review [Beneficiary Relationships](/api-reference/beneficiaries/relationships) *** ## Common Pitfalls & Solutions | Pitfall | Solution | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Email validation fails** | Ensure email is **all lowercase** before sending: `contact@acme.com` ✓ not `Contact@Acme.com` ✗ | | **RELIANCE 423 error** | RELIANCE verification must be enabled for your client. Contact support or use `STANDARD` verification type. | | **Ownership percentage error** | Total ownership across all parties must be **\< 100%**. Individual parties may have 0% ownership. Check calculations before submitting. | | **Non-Latin character rejection** | All text fields accept only English (Latin) characters. Transliterate or romanize names (e.g., `José` → `Jose`). | | **P.O. Box address rejected** | Use verifiable street addresses for both incorporated and physical addresses. Avoid P.O. Boxes. | | **State code validation fails** | Use state codes from [/v1/countries/subdivisions](/api-reference/catalogue/list-subdivision-codes-—-iso-3166-1-alpha-2). Format: `US-CA`, not `CA`. | | **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): `50000` for \$50,000, not `5000000`. | # Onboarding Individual Customers Source: https://developer.fin.com/guides/customers/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-subdivision-codes-—-iso-3166-1-alpha-2)[/subdivisions](/api-reference/catalogue/list-subdivision-codes-—-iso-3166-1-alpha-2). **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](/api-reference/beneficiaries/account-info-validation) * Review [Beneficiary Relationships](/api-reference/beneficiaries/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. | 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. ## 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 /v1/customers/individual](/api-reference/customers/create-individual-customer) | Submit personal details, address, and financial profile | | 3. Upload Documents | [POST /v1/customers/upload](/api-reference/customers/upload-document) | Upload identity and address proof files | | 4. Attach Documents | [POST /v1/customers/individual/attach](/api-reference/customers/attach-documents-to-individual-customer) | Link uploaded documents to customer with TOS acceptance | | 5. Monitor Status | Webhooks: `customer.status` | 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 KYC 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"` #### Basic Information (Required) > Personal details exactly as shown on identity documents. **All fields must use only English (Latin) characters**. **Fields:** | Field | Type | Description | Example | | ---------------------- | -------------- | -------------------------------------------------- | ------------------------ | | `first_name` | string | Legal first name as shown on ID | `"John"` | | `last_name` | string | Legal last name as shown on ID | `"Doe"` | | `dob` | string (date) | Date of birth in YYYY-MM-DD format | `"1990-01-15"` | | `email` | string (email) | Personal email address - **must be all lowercase** | `"john.doe@example.com"` | | `phone` | string | Phone number in E.164 format | `"+14155552671"` | | `country_of_residence` | string | ISO Alpha-3 country code where person resides | `"USA"` | | `nationality` | string | ISO Alpha-3 country code of citizenship | `"USA"` | | `tin` | string | Tax Identification Number | `"123-45-6789"` | Email must be **all lowercase** or validation will fail. Convert to lowercase before sending: `john.doe@example.com` ✓ not `John.Doe@Example.com` ✗ **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 **Example:** ```json theme={null} { "basic_info": { "first_name": "John", "last_name": "Doe", "dob": "1990-01-15", "email": "john.doe@example.com", "phone": "+14155552671", "country_of_residence": "USA", "nationality": "USA", "tin": "123-45-6789" } } ``` #### Address (Required) > Current residential address of the customer. This must match the address on proof of address documents. **Fields:** | Field | Type | Description | Example | | ------------- | ------ | --------------------------------------------------- | -------------------------- | | `street` | string | Full street address including apartment/unit number | `"123 Main Street Apt 4B"` | | `city` | string | City name | `"San Francisco"` | | `state` | string | `"US-CA"` | | | `postal_code` | string | Postal or ZIP code | `"94103"` | | `country` | string | ISO Alpha-3 country code | `"USA"` | **State Code Format**: Use subdivision codes from the catalogue API, not abbreviations. For example, use `US-CA` instead of `CA` for California, or `GB-ENG` instead of `England`. **Example:** ```json theme={null} { "address": { "street": "123 Main Street Apt 4B", "city": "San Francisco", "state": "US-CA", "postal_code": "94103", "country": "USA" } } ``` #### Financial Profile (Required) > Describes occupation, transaction purpose, volume, and fund sources. Use catalogue endpoints to fetch valid IDs. **Fields:** | Field | Type | Description | How to Get Value | | -------------------- | ------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | | `occupation_id` | integer | Customer's occupation | [GET /v1/occupations](/api-reference/catalogue/list-occupations) | | `source_of_fund_id` | integer | Source of funds | [GET /v1/source-of-funds?type=INDIVIDUAL](/api-reference/catalogue/list-source-of-funds) | | `purpose_id` | integer | Purpose of using the service | [GET /v1/purposes?type=INDIVIDUAL](/api-reference/catalogue/list-account-purposes) | | `monthly_volume_usd` | integer | 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 `source_of_fund_id` and `purpose_id`. **Example:** ```json theme={null} { "financial_profile": { "occupation_id": 1, "source_of_fund_id": 1, "purpose_id": 1, "monthly_volume_usd": 5000 } } ``` In this example: `occupation_id: 1` = Software Engineer, `source_of_fund_id: 1` = Employment income, `purpose_id: 1` = Personal remittance, `monthly_volume_usd: 5000` = \$5,000 USD per month. #### Metadata (Optional) Custom key-value pairs for internal tracking: ```json theme={null} { "meta_data": { "customer_reference": "REF-20250123-JOHN", "internal_notes": "Premium tier customer", "referral_code": "FRIEND2025" } } ``` ### 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/passport_front.pdf' \ --form 'file2=@/path/to/utility_bill.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 request. #### Step 2: Attach Documents Link identity and address proof documents to the customer: ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/customers/individual/attach \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "customer_id": "55bd6b4e-c20a-4cc8-9535-91d5557a67d9", "proof_of_identity": { "type": "PASSPORT", "number": "A12345678", "country": "USA", "issue_date": "2020-01-15", "expiry_date": "2030-01-15", "files": [ {"uri": "/AbAcQ4hn_0652746727637.pdf"} ] }, "proof_of_address": { "type": "UTILITY_BILL", "country": "USA", "files": [ {"uri": "/XyZ123mn_0652746727638.pdf"} ] }, "tos_policies_value": "e9414388-fbdf-4407-b5c2-bc39eae3645b" }' ``` 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. 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. **Example with National ID (requires front and back):** ```json theme={null} { "proof_of_identity": { "type": "NATIONAL_ID", "number": "A12345678", "country": "USA", "issue_date": "2020-01-15", "expiry_date": "2030-01-15", "files": [ {"side": "FRONT", "uri": "/id_front_0652746727640.pdf"}, {"side": "BACK", "uri": "/id_back_0652746727641.pdf"} ] } } ``` **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) | **Address Proof Types:** | Type | Description | | ------------------- | ------------------------------------------ | | `UTILITY_BILL` | Recent utility bill (gas, electric, water) | | `BANK_STATEMENT` | Bank statement (within last 3 months) | | `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 | **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) ### Customer Status & Webhooks After document submission, customers go through a verification workflow: **Status Lifecycle:** ```text theme={null} INCOMPLETE → REVIEWING → APPROVED ↓ ON_HOLD / REJECTED ``` | Status | Description | | ------------ | ----------------------------------------------- | | `INCOMPLETE` | Customer created but documents not yet attached | | `REVIEWING` | Documents submitted and under compliance review | | `APPROVED` | Verification complete, customer can transact | | `ON_HOLD` | Additional information or documents required | | `REJECTED` | Verification failed, see rejection reason | **Webhook Events:** * `customer.created` - Fired when 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" } ``` **TIN format validation (USA):** ```json theme={null} { "message": "Validation failed", "errors": { "basic_info.tin": ["TIN must be in SSN format (xxx-xx-xxxx) for USA customers"] } } ``` **Missing required field:** ```json theme={null} { "message": "Validation failed", "errors": { "financial_profile.occupation_id": ["occupation_id is required"] } } ``` *** ## What's Next? You've successfully created an individual customer. 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 `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 * ✓ TIN in wrong format for country * ✓ Non-Latin characters in text fields * ✓ Missing required fields * ✓ RELIANCE verification when not enabled * ✓ Invalid state codes ### 3. Production Checklist Before going live, ensure you have: * Implemented webhook handling for status updates * Added proper error handling for all failure scenarios * Client-side validation for email lowercase and TIN format * Fetched and cached catalogue data (occupations, purposes, source-of-funds) * Implemented document upload UI/flow * 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](/api-reference/beneficiaries/account-info-validation) * Review [Beneficiary Relationships](/api-reference/beneficiaries/relationships) *** ## Common Pitfalls & Solutions | Pitfall | Solution | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Email validation fails** | Ensure email is **all lowercase** before sending: `john.doe@example.com` ✓ not `John.Doe@Example.com` ✗ | | **RELIANCE 423 error** | RELIANCE verification must be enabled for your client. Contact support or use `STANDARD` verification type. | | **TIN format rejected** | TIN must follow the country's official format. For USA, use SSN format `xxx-xx-xxxx`. | | **Non-Latin character rejection** | All text fields accept only English (Latin) characters. Transliterate or romanize names (e.g., `Jose` not `Jose`). | | **State 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`. | | **Document side missing** | For `NATIONAL_ID` and `DRIVERS_LICENSE`, include `side: "FRONT"` and `side: "BACK"` in the files array. | | **Address mismatch** | Ensure proof of address document shows the same address provided in the `address` object. | # Funding Your Balance Source: https://developer.fin.com/guides/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 USD prefunding via **USDC on Polygon** or **USD via SWIFT/Wire via Named Virtual accounts issued for Developers**. Funds are credited to your USD balance and used for payouts. 🎉 — Fiat prefunding via USD over SWIFT or FeWire is now available! ## Balance Types Fin.com maintains two separate USD balances. **You must specify which balance you're funding** when submitting your prefunding request. For local-currency payouts (BDT, PKR, INR, etc.) For USD SWIFT payouts only Funds allocated to one balance cannot be used for the other. Incorrect allocation will delay your payouts. ## Prefunding Process. ### 1. Send Your Funds Depending on your preferred funding method you can send **USDC / USD**. If you are sending USDC then your account manager will provide you with a designated wallet addres, if you are willing to prefund in USD then your account manager will issue you a vIBAN under you entity where you can transfer USD from 1st party only. ### 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 USD/USDC** | T+2 | Funds available 2 business days after submission | | **\< \$20,000 USD/USDC** | 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 * Ensure sufficient balance in the correct ledger (LOCAL vs SWIFT) before initiating payouts * **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 # Orchestration Dashboard Usage Source: https://developer.fin.com/guides/others/dashboard-platform 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 complete the registration form. Sign Up Screen 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. ## 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. # Supported cryptocurrencies Source: https://developer.fin.com/guides/others/supported-cryptocurrencies ### Crypto coverage Fin.com currently exclusively supports **USDC** on the **Polygon** network, with **USDT** on the **Polygon** support scheduled for future release. For integration requirements involving additional tokens or chains, please reach out to your account manager or contact our team in your dedicated slack channel. ### Conversion rate Fin.com applies a fixed **1:1 conversion rate** for **USDC-to-USD** transactions. For all other assets, conversion rates are variable and subject to real-time market fluctuations. ### Crypto custody Fin.com does not custody crypto assets. All conversions into fiat are executed immediately upon receipt. Fin is set to release Crypto custody soon. # Coverage & capabilities Source: https://developer.fin.com/guides/pricing-and-coverage/coverage-and-capabilities Details on Fin.com's 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. 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) -** Only Businesses. For individuals, please get in touch with support. ### 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. Individual USD SWIFT virtual accounts are **restricted** to the following US states: **HI, NY,** and **TN**. 3. Business USD SWIFT virtual accounts are **restricted** to the following US states: **TN** and **NY.** 4. Fin.com provides named USD virtual accounts only. We do not offer omnibus or pooled USD accounts. 5. MXN Payins and payouts require separate configuration. Please contact support if you want to enable these capabilities for your customers. 6. For MXN Payins, Fin.com doesn't provide dedicated virtual accounts. You can create Payin instructions for your customers. Check our [API reference](https://developer.fin.com/api-reference/transactions/create-a-pay-in) to know more. | Country of Residence | Country Code | USD ACH/Fedwire | USD SWIFT | MXN SPEI | | ----------------------------------------------------------------- | ------------ | ------------------- | ------------------- | ------------- | | Afghanistan | AFG | Prohibited | Restricted | Not High Risk | | Albania | ALB | Enhanced Monitoring | Not High Risk | Not High Risk | | Algeria | DZA | Restricted | Enhanced Monitoring | Prohibited | | American Samoa | ASM | Not High Risk | Not High Risk | Not High Risk | | Andorra | AND | Not High Risk | Not High Risk | Not High Risk | | Angola | AGO | Enhanced Monitoring | Enhanced Monitoring | Prohibited | | Anguilla | AIA | Not High Risk | Not High Risk | Not High Risk | | Antigua and Barbuda | ATG | Not High Risk | Not High Risk | Not High Risk | | Argentina | ARG | Not High Risk | Not High Risk | Not High Risk | | Armenia | ARM | Not High Risk | Not High Risk | Not High Risk | | Aruba | ABW | Not High Risk | Not High Risk | Not High Risk | | Australia | AUS | Not High Risk | Restricted | Not High Risk | | Austria | AUT | Not High Risk | Not High Risk | Not High Risk | | Azerbaijan | AZE | Not High Risk | Not High Risk | Not High Risk | | Bahamas | BHS | Not High Risk | Not High Risk | Not High Risk | | Bahrain | BHR | Not High Risk | Not High Risk | Not High Risk | | Bangladesh | BGD | Restricted | Not High Risk | Not High Risk | | Barbados | BRB | Enhanced Monitoring | Enhanced Monitoring | Not High Risk | | Belarus | BLR | Prohibited | Restricted | Not High Risk | | Belgium | BEL | Not High Risk | Not High Risk | Not High Risk | | Belize | BLZ | Not High Risk | Not High Risk | Not High Risk | | Benin | BEN | Not High Risk | Enhanced Monitoring | Not High Risk | | Bermuda | BMU | Not High Risk | Not High Risk | Not High Risk | | Bhutan | BTN | Enhanced Monitoring | Not High Risk | Not High Risk | | Bolivia | BOL | Not supported | Enhanced Monitoring | Not High Risk | | Bosnia and Herzegovina | BIH | Not supported | Not High Risk | Not High Risk | | Botswana | BWA | Enhanced Monitoring | Not High Risk | Not High Risk | | Brazil | BRA | Not High Risk | Not High Risk | Not High Risk | | British Virgin Islands | VGB | Not supported | Enhanced Monitoring | Not High Risk | | Brunei | BRN | Not supported | Not High Risk | Not High Risk | | Bulgaria | BGR | Not High Risk | Not High Risk | Prohibited | | Burkina Faso | BFA | Enhanced Monitoring | Enhanced Monitoring | Prohibited | | Burundi | BDI | Enhanced Monitoring | Enhanced Monitoring | Not High Risk | | Cabo Verde | CPV | Not High Risk | Not High Risk | Not High Risk | | Cambodia | KHM | Not High Risk | Enhanced Monitoring | Not High Risk | | Cameroon | CMR | Enhanced Monitoring | Enhanced Monitoring | Prohibited | | Canada | CAN | Not High Risk | Restricted | Not High Risk | | Cayman Islands | CYM | Not High Risk | Not High Risk | Not High Risk | | Central African Republic | CAF | Not supported | Restricted | Not High Risk | | Chad | TCD | Not High Risk | Enhanced Monitoring | Not High Risk | | Chile | CHL | Not High Risk | Not High Risk | Not High Risk | | China | CHN | Restricted | Not High Risk | Not High Risk | | Colombia | COL | Not High Risk | Not High Risk | Not High Risk | | Comoros | COM | Not High Risk | Not High Risk | Not High Risk | | Cook Islands | COK | Not High Risk | Not High Risk | Not High Risk | | Costa Rica | CRI | Not High Risk | Not High Risk | Not High Risk | | Côte d'Ivoire | CIV | Not supported | Enhanced Monitoring | Prohibited | | Croatia | HRV | Enhanced Monitoring | Not High Risk | Prohibited | | Cuba | CUB | Prohibited | Prohibited | Not High Risk | | Curaçao | CUW | Not High Risk | Not High Risk | Not High Risk | | Cyprus | CYP | Not High Risk | Not High Risk | Not High Risk | | Czech Republic | CZE | Not supported | Not High Risk | Not High Risk | | Democratic Republic of the Congo | COD | Not supported | Restricted | Prohibited | | Denmark | DNK | Not High Risk | Not High Risk | Not High Risk | | Djibouti | DJI | Not High Risk | Not High Risk | Not High Risk | | Dominica | DMA | Not High Risk | Not High Risk | Not High Risk | | Dominican Republic | DOM | Not High Risk | Not High Risk | Not High Risk | | Ecuador | ECU | Not High Risk | Not High Risk | Not High Risk | | Egypt | EGY | Not High Risk | Not High Risk | Not High Risk | | El Salvador | SLV | Not High Risk | Not High Risk | Not High Risk | | Equatorial Guinea | GNQ | Not High Risk | Not High Risk | Not High Risk | | Eritrea | ERI | Enhanced Monitoring | Not High Risk | Not High Risk | | Estonia | EST | Not High Risk | Not High Risk | Not High Risk | | Eswatini | SWZ | Not High Risk | Enhanced Monitoring | Not High Risk | | Ethiopia | ETH | Enhanced Monitoring | Enhanced Monitoring | Not High Risk | | Falkland Islands | FLK | Not supported | Not High Risk | Not High Risk | | Faroe Islands | FRO | Not High Risk | Not High Risk | Not High Risk | | Fiji | FJI | Not High Risk | Not High Risk | Not High Risk | | Finland | FIN | Not High Risk | Not High Risk | Not High Risk | | France | FRA | Not High Risk | Not High Risk | Not High Risk | | French Polynesia | PYF | Not High Risk | Not High Risk | Not High Risk | | Gabon | GAB | Not High Risk | Enhanced Monitoring | Not High Risk | | Gambia | GMB | Not High Risk | Not High Risk | Not High Risk | | Georgia | GEO | Not High Risk | Not High Risk | Not High Risk | | Germany | DEU | Not High Risk | Not High Risk | Not High Risk | | Ghana | GHA | Not High Risk | Not High Risk | Not High Risk | | Gibraltar | GIB | Not High Risk | Not High Risk | Not High Risk | | Greece | GRC | Not High Risk | Not High Risk | Not High Risk | | Greenland | GRL | Not High Risk | Not High Risk | Not High Risk | | Grenada | GRD | Not High Risk | Not High Risk | Not High Risk | | Guam | GUM | Not High Risk | Not High Risk | Not High Risk | | Guatemala | GTM | Not High Risk | Enhanced Monitoring | Not High Risk | | Guernsey | GGY | Not High Risk | Not High Risk | Not High Risk | | Guinea | GIN | Not High Risk | Restricted | Not High Risk | | Guinea-Bissau | GNB | Not supported | Enhanced Monitoring | Not High Risk | | Guyana | GUY | Not High Risk | Not High Risk | Not High Risk | | Haiti | HTI | Restricted | Enhanced Monitoring | Prohibited | | Honduras | HND | Not High Risk | Not High Risk | Not High Risk | | Hong Kong | HKG | Not High Risk | Not High Risk | Not High Risk | | Hungary | HUN | Not High Risk | Not High Risk | Not High Risk | | Iceland | ISL | Not High Risk | Not High Risk | Not High Risk | | India | IND | Not High Risk | Restricted | Not High Risk | | Indonesia | IDN | Not High Risk | Not High Risk | Not High Risk | | Iran | IRN | Not supported | Prohibited | Prohibited | | Iraq | IRQ | Prohibited | Enhanced Monitoring | Not High Risk | | Ireland | IRL | Not High Risk | Not High Risk | Not High Risk | | Isle of Man | IMN | Not High Risk | Not High Risk | Not High Risk | | Israel | ISR | Not High Risk | Not High Risk | Not High Risk | | Italy | ITA | Not High Risk | Not High Risk | Not High Risk | | Jamaica | JAM | Enhanced Monitoring | Not High Risk | Not High Risk | | Japan | JPN | Not High Risk | Restricted | Not High Risk | | Jersey | JEY | Not High Risk | Not High Risk | Not High Risk | | Jordan | JOR | Not High Risk | Not High Risk | Not High Risk | | Kazakhstan | KAZ | Not High Risk | Not High Risk | Not High Risk | | Kenya | KEN | Enhanced Monitoring | Enhanced Monitoring | Prohibited | | Kiribati | KIR | Not High Risk | Not High Risk | Not High Risk | | Kuwait | KWT | Not High Risk | Not High Risk | Not High Risk | | Kyrgyzstan | KGZ | Not High Risk | Enhanced Monitoring | Not High Risk | | Laos | LAO | Not supported | Enhanced Monitoring | Not High Risk | | Latvia | LVA | Not High Risk | Not High Risk | Not High Risk | | Lebanon | LBN | Prohibited | Enhanced Monitoring | Prohibited | | Lesotho | LSO | Not High Risk | Not High Risk | Not High Risk | | Liberia | LBR | Not High Risk | Enhanced Monitoring | Not High Risk | | Libya | LBY | Prohibited | Restricted | Not High Risk | | Liechtenstein | LIE | Not High Risk | Not High Risk | Not High Risk | | Lithuania | LTU | Not High Risk | Not High Risk | Not High Risk | | Luxembourg | LUX | Not High Risk | Not High Risk | Not High Risk | | Macao | MAC | Not High Risk | Not High Risk | Not High Risk | | Madagascar | MDG | Not High Risk | Enhanced Monitoring | Not High Risk | | Malawi | MWI | Not High Risk | Not High Risk | Not High Risk | | Malaysia | MYS | Not High Risk | Not High Risk | Not High Risk | | Maldives | MDV | Not High Risk | Not High Risk | Not High Risk | | Mali | MLI | Not High Risk | Restricted | Prohibited | | Malta | MLT | Not High Risk | Not High Risk | Not High Risk | | Marshall Islands | MHL | Not High Risk | Not High Risk | Not High Risk | | Mauritania | MRT | Not High Risk | Enhanced Monitoring | Not High Risk | | Mauritius | MUS | Not High Risk | Not High Risk | Not High Risk | | Mexico | MEX | Not High Risk | Not High Risk | Not High Risk | | Micronesia | FSM | Not supported | Not High Risk | Not High Risk | | Moldova | MDA | Not supported | Enhanced Monitoring | Not High Risk | | Monaco | MCO | Enhanced Monitoring | Enhanced Monitoring | Prohibited | | Mongolia | MNG | Not High Risk | Not High Risk | Not High Risk | | Montenegro | MNE | Not High Risk | Not High Risk | Not High Risk | | Montserrat | MSR | Not High Risk | Not High Risk | Not High Risk | | Morocco | MAR | Restricted | Not High Risk | Not High Risk | | Mozambique | MOZ | Restricted | Enhanced Monitoring | Prohibited | | Myanmar | MMR | Prohibited | Prohibited | Prohibited | | Namibia | NAM | Enhanced Monitoring | Enhanced Monitoring | Prohibited | | Nauru | NRU | Not High Risk | Not High Risk | Not High Risk | | Nepal | NPL | Restricted | Enhanced Monitoring | Not High Risk | | Netherlands | NLD | Not High Risk | Not High Risk | Not High Risk | | New Caledonia | NCL | Not High Risk | Not High Risk | Not High Risk | | New Zealand | NZL | Not High Risk | Not High Risk | Not High Risk | | Nicaragua | NIC | Enhanced Monitoring | Enhanced Monitoring | Not High Risk | | Niger | NER | Enhanced Monitoring | Enhanced Monitoring | Not High Risk | | Nigeria | NGA | Enhanced Monitoring | Enhanced Monitoring | Prohibited | | North Korea | PRK | Not supported | Prohibited | Prohibited | | North Macedonia | MKD | Restricted | Not High Risk | Not High Risk | | Norway | NOR | Not High Risk | Not High Risk | Not High Risk | | Oman | OMN | Not High Risk | Not High Risk | Not High Risk | | Pakistan | PAK | Restricted | Not High Risk | Not High Risk | | Palau | PLW | Not High Risk | Not High Risk | Not High Risk | | Palestine - West Bank | PSE | Not supported | Restricted | Not High Risk | | Panama | PAN | Not High Risk | Enhanced Monitoring | Not High Risk | | Papua New Guinea | PNG | Not High Risk | Not High Risk | Not High Risk | | Paraguay | PRY | Not High Risk | Not High Risk | Not High Risk | | Peru | PER | Not High Risk | Not High Risk | Not High Risk | | Philippines | PHL | Not High Risk | Not High Risk | Prohibited | | Poland | POL | Not High Risk | Not High Risk | Not High Risk | | Portugal | PRT | Not High Risk | Not High Risk | Not High Risk | | Puerto Rico | PRI | Not High Risk | Not High Risk | Not High Risk | | Qatar | QAT | Restricted | Restricted | Not High Risk | | Republic of the Congo | COG | Not supported | Restricted | Not High Risk | | Romania | ROU | Not High Risk | Not High Risk | Not High Risk | | Russia | RUS | Not supported | Restricted | Not High Risk | | Rwanda | RWA | Not High Risk | Not High Risk | Not High Risk | | Saint Helena | SHN | Not supported | Not High Risk | Not High Risk | | Saint Kitts and Nevis | KNA | Not High Risk | Not High Risk | Not High Risk | | Saint Lucia | LCA | Not High Risk | Not High Risk | Not High Risk | | Saint Martin | MAF | Not supported | Not High Risk | Not High Risk | | Saint Vincent and the Grenadines | VCT | Not High Risk | Not High Risk | Not High Risk | | Samoa | WSM | Not High Risk | Not High Risk | Not High Risk | | San Marino | SMR | Not High Risk | Not High Risk | Not High Risk | | São Tomé and Príncipe | STP | Not supported | Not High Risk | Not High Risk | | Saudi Arabia | SAU | Not High Risk | Not High Risk | Not High Risk | | Senegal | SEN | Enhanced Monitoring | Enhanced Monitoring | Not High Risk | | Serbia | SRB | Not High Risk | Not High Risk | Not High Risk | | Seychelles | SYC | Not High Risk | Not High Risk | Not High Risk | | Sierra Leone | SLE | Not High Risk | Enhanced Monitoring | Not High Risk | | Singapore | SGP | Not High Risk | Restricted | Not High Risk | | Sint Maarten | SXM | Not supported | Not High Risk | Not High Risk | | Slovakia | SVK | Not High Risk | Not High Risk | Not High Risk | | Slovenia | SVN | Not High Risk | Not High Risk | Not High Risk | | Solomon Islands | SLB | Not High Risk | Enhanced Monitoring | Not High Risk | | Somalia | SOM | Prohibited | Restricted | Not High Risk | | South Africa | ZAF | Enhanced Monitoring | Enhanced Monitoring | Prohibited | | South Korea | KOR | Not supported | Not High Risk | Not High Risk | | South Sudan | SSD | Prohibited | Restricted | Prohibited | | Spain | ESP | Not High Risk | Not High Risk | Not High Risk | | Sri Lanka | LKA | Not High Risk | Not High Risk | Not High Risk | | Sudan | SDN | Prohibited | Restricted | Not High Risk | | Suriname | SUR | Not High Risk | Enhanced Monitoring | Not High Risk | | Sweden | SWE | Not High Risk | Not High Risk | Not High Risk | | Switzerland | CHE | Not High Risk | Not High Risk | Not High Risk | | Syria | SYR | Prohibited | Prohibited | Prohibited | | Taiwan | TWN | Not supported | Not High Risk | Not High Risk | | Tajikistan | TJK | Not High Risk | Not High Risk | Not High Risk | | Tanzania | TZA | Enhanced Monitoring | Enhanced Monitoring | Prohibited | | Thailand | THA | Not High Risk | Not High Risk | Not High Risk | | Timor-Leste | TLS | Not High Risk | Not High Risk | Not High Risk | | Togo | TGO | Not High Risk | Enhanced Monitoring | Not High Risk | | Tonga | TON | Not High Risk | Enhanced Monitoring | Not High Risk | | Trinidad and Tobago | TTO | Not supported | Enhanced Monitoring | Not High Risk | | Tunisia | TUN | Not High Risk | Enhanced Monitoring | Not High Risk | | Turkey | TUR | Enhanced Monitoring | Not High Risk | Not High Risk | | Turkmenistan | TKM | Not High Risk | Enhanced Monitoring | Not High Risk | | Turks and Caicos Islands | TCA | Not High Risk | Not High Risk | Not High Risk | | Tuvalu | TUV | Not High Risk | Not High Risk | Not High Risk | | Uganda | UGA | Enhanced Monitoring | Enhanced Monitoring | Not High Risk | | Ukraine | UKR | Enhanced Monitoring | Not High Risk | Not High Risk | | Ukraine Regions (Crimea, Donetsk, Luhansk, Zaporizhzhia, Kherson) | N/A | Not supported | Prohibited | Not High Risk | | United Arab Emirates | ARE | Not High Risk | Not High Risk | Not High Risk | | United Kingdom | GBR | Not supported | Restricted | Not High Risk | | United States | USA | Not supported | Not High Risk | Not High Risk | | Uruguay | URY | Not High Risk | Not High Risk | Not High Risk | | US Virgin Islands | VIR | Not supported | Not High Risk | Not High Risk | | Uzbekistan | UZB | Not High Risk | Not High Risk | Not High Risk | | Vanuatu | VUT | Enhanced Monitoring | Enhanced Monitoring | Not High Risk | | Venezuela | VEN | Prohibited | Restricted | Prohibited | | Vietnam | VNM | Enhanced Monitoring | Enhanced Monitoring | Prohibited | | Yemen | YEM | Prohibited | Restricted | Prohibited | | Zambia | ZMB | Not High Risk | Not High Risk | Not High Risk | | Zimbabwe | ZWE | Enhanced Monitoring | Enhanced Monitoring | 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 uses different partner banks for different corridors. USD SWIFT Payout (Config 2) is available for Business customers only. | Payout Country | Country Code | Payout Currency | Local Payout | USD SWIFT Payout (Config 1) | USD SWIFT Payout (Config 2) | Notes | | ----------------------- | ------------ | --------------- | ------------ | --------------------------- | --------------------------- | ----------------------------------------------------------------------------------------- | | Afghanistan | AFG | AFN | No | No | Yes | | | Åland Islands | ALA | EUR | Yes | On-Request | No | Subject to EU limits | | Algeria | DZA | DZD | No | No | Yes | | | Andorra | AND | EUR | Yes | On-Request | No | Subject to EU limits | | Angola | AGO | AOA | No | No | Yes | | | Armenia | ARM | AMD | No | No | Yes | | | Australia | AUS | AUD | Yes | Yes | No | Type: C2C/C2B/B2C/B2B; Time: Same Day/T+1; Limits: None | | Austria | AUT | EUR | Yes | On-Request | No | No max limit | | Bahrain | BHR | BHD | On-Request | On-Request | No | Type: C2C; Time: Same Day; Limit: BHD 2,800 | | Bangladesh | BGD | BDT | Yes | Yes | Yes | Type: C2C; Time: Same Day/T+1; Limits: Brac Bank (No limit), Others via BEFTN (T+0/1) | | Belgium | BEL | EUR | Yes | On-Request | No | No max limit | | Benin | BEN | XOF | On-Request | On-Request | No | | | Bolivia | BOL | BOB | No | No | Yes | | | Brazil | BRA | BRL | On-Request | Yes | Yes | | | Brunei Darussalam | BRN | BND | On-Request | On-Request | No | | | Bulgaria | BGR | BGN | Yes | On-Request | No | No max limit; EDD requirements may apply | | Burkina Faso | BFA | XOF | On-Request | On-Request | No | | | Burundi | BDI | BIF | On-Request | On-Request | No | | | Cambodia | KHM | KHR | On-Request | On-Request | Yes | Type: C2C; Time: Real-time; Limit: KHR 10,000,000 | | Cameroon | CMR | XAF | On-Request | On-Request | No | | | Canada | CAN | CAD | Yes | Yes | Yes | Type: C2C/C2B/B2C/B2B; Time: T+1/2; Limits: None | | Chile | CHL | CLP | No | No | Yes | | | China | CHN | CNY | On-Request | Yes | Yes (First party only) | Type: C2C/B2B/B2C; Time: Same Day/T+1; C2C Limits: CNY 50k Daily / 500k Annual | | Christmas Island | CXR | AUD | No | No | Yes | | | Colombia | COL | COP | No | No | Yes | | | Comoros | COM | KMF | No | No | Yes | | | Costa Rica | CRI | CRC | No | No | Yes | | | Cote d'Ivoire | CIV | XOF | No | No | Yes | | | Croatia | HRV | EUR | Yes | On-Request | Yes | Subject to EU limits | | Cyprus | CYP | EUR | Yes | On-Request | No | | | Czechia | CZE | CZK | Yes | On-Request | No | | | Denmark | DNK | DKK | Yes | On-Request | Yes | | | Dominica | DMA | XCD | No | No | Yes | | | Dominican Republic | DOM | DOP | No | No | Yes | | | Ecuador | ECU | USD | No | No | Yes | | | Egypt | EGY | EGP | On-Request | On-Request | Yes | | | Estonia | EST | EUR | Yes | On-Request | No | | | Ethiopia | ETH | ETB | No | No | Yes | | | European Union | EU | EUR | Yes | On-Request | No | Type: C2C/C2B/B2C/B2B; Time: Same Day/T+1; Limits: None | | Fiji | FJI | FJD | No | No | Yes | | | Finland | FIN | EUR | On-Request | On-Request | Yes | | | France | FRA | EUR | Yes | Yes | No | No max limit | | French Guiana | GUF | EUR | Yes | On-Request | No | Subject to EU limits | | Gabon | GAB | XAF | On-Request | On-Request | No | | | Germany | DEU | EUR | Yes | Yes | No | | | Ghana | GHA | GHS | On-Request | On-Request | Yes | | | Gibraltar | GIB | GIP | Yes | On-Request | No | Subject to EU limits | | Greece | GRC | EUR | Yes | On-Request | No | Subject to EU limits | | Guadeloupe | GLP | EUR | Yes | On-Request | No | Subject to EU limits | | Guatemala | GTM | GTQ | No | No | Yes | | | Guernsey | GGY | GBP | Yes | On-Request | No | Subject to EU limits | | Haiti | HTI | HTG | No | No | Yes | | | Holy See | VAT | EUR | Yes | On-Request | No | | | Hong Kong | HKG | HKD | On-Request | Yes | Yes (First party only) | Type: C2C/C2B/B2C/B2B; Time: Same Day/T+1; Limits: C2C HKD 200k, B2B HKD 1M | | Hungary | HUN | HUF | Yes | On-Request | Yes | Subject to EU limits | | Iceland | ISL | ISK | Yes | On-Request | No | Subject to EU limits | | India | IND | INR | Yes | Yes | No | Type: C2C/C2B/B2C/B2B; Time: Real-time/T+1; Limit: Real-time up to INR 500k | | Indonesia | IDN | IDR | On-Request | On-Request | Yes | Type: C2C/C2B/B2C/B2B; Time: Same Day/T+1; Limit: IDR 100,000,000 | | Iraq | IRQ | IQD | No | No | Yes | | | Ireland | IRL | EUR | Yes | On-Request | Yes | Subject to EU limits | | Isle of Man | IMN | GBP | Yes | On-Request | No | Subject to EU limits | | Italy | ITA | EUR | Yes | On-Request | Yes | No max limit | | Jamaica | JAM | JMD | No | No | Yes | | | Japan | JPN | JPY | Yes | Yes | No | Type: C2C/B2B; Time: Same Day/T+1; Limit: JPY 30,000,000 | | Jersey | JEY | GBP | Yes | On-Request | No | Subject to EU limits | | Jordan | JOR | JOD | On-Request | On-Request | Yes | Type: C2C; Time: Same Day; Limit: JOD 5,000 | | Kazakhstan | KAZ | KZT | No | No | Yes | | | Kuwait | KWT | KWD | On-Request | On-Request | No | | | Laos | LAO | LAK | No | No | Yes | | | Latvia | LVA | EUR | Yes | On-Request | No | Subject to EU limits | | Liberia | LBR | LRD | No | No | Yes | | | Liechtenstein | LIE | CHF | Yes | On-Request | No | Subject to EU limits | | Lithuania | LTU | EUR | Yes | On-Request | No | Subject to EU limits | | Luxembourg | LUX | EUR | Yes | On-Request | No | Subject to EU limits | | Madagascar | MDG | MGA | No | No | Yes | | | Malaysia | MYS | MYR | On-Request | On-Request | No | Type: C2C/C2B/B2C/B2B; Time: Real-time; Limit: MYR 1M (lower for loan/non-resident accts) | | Malta | MLT | EUR | Yes | On-Request | No | Subject to EU limits | | Mauritania | MRT | MRU | No | No | Yes | | | Mayotte | MYT | EUR | Yes | On-Request | No | Subject to EU limits | | Mexico | MEX | MXN | On-Request | No | Yes | | | Monaco | MCO | EUR | Yes | On-Request | No | Subject to EU limits | | Mozambique | MOZ | MZN | On-Request | On-Request | No | | | Namibia | NAM | NAD | No | No | Yes | | | Nepal | NPL | NPR | Yes | On-Request | Yes | Type: C2C/B2C; Time: Same Day/T+1; Limit: NPR 10,000,000 | | Netherlands | NLD | EUR | Yes | On-Request | No | Subject to EU limits | | New Zealand | NZL | NZD | On-Request | On-Request | No | | | Nicaragua | NIC | NIO | No | No | Yes | | | Nigeria | NGA | NGN | On-Request | Yes | No | | | Norway | NOR | NOK | Yes | On-Request | No | Subject to EU limits | | Oman | OMN | OMR | On-Request | On-Request | No | | | Pakistan | PAK | PKR | Yes | On-Request | No | Type: C2C/C2B/B2C/B2B; Time: Real-time/T+1; Limit: Real-time up to PKR 1M | | Panama | PAN | PAB | No | No | Yes | | | Peru | PER | PEN | No | No | Yes | | | Philippines | PHL | PHP | Yes | Yes | Yes | Type: C2C/C2B/B2C/B2B; Time: Real-time/T+1; Limit: Real-time up to PHP 50k; Max PHP 100M | | Poland | POL | PLN | Yes | Yes | No | Subject to EU limits | | Portugal | PRT | EUR | Yes | On-Request | No | Subject to EU limits | | Qatar | QAT | QAR | On-Request | On-Request | No | | | Réunion | REU | EUR | Yes | On-Request | No | Subject to EU limits | | Romania | ROU | RON | Yes | On-Request | No | Subject to EU limits | | Rwanda | RWA | RWF | On-Request | On-Request | No | | | Saint Barthélemy | BLM | EUR | Yes | On-Request | No | Subject to EU limits | | Saint Lucia | LCA | XCD | No | No | Yes | | | Saint Martin | MAF | EUR | Yes | On-Request | No | Subject to EU limits | | Saint Pierre & Miquelon | SPM | EUR | Yes | On-Request | No | Subject to EU limits | | San Marino | SMR | EUR | Yes | On-Request | No | Subject to EU limits | | Saudi Arabia | SAU | SAR | On-Request | On-Request | No | | | Senegal | SEN | XOF | On-Request | On-Request | No | | | Singapore | SGP | SGD | Yes | Yes | No | Type: C2C/C2B/B2C/B2B; Time: T+0/1; Limit: SGD 200,000 | | Slovakia | SVK | EUR | Yes | On-Request | No | Subject to EU limits | | Slovenia | SVN | EUR | Yes | On-Request | No | Subject to EU limits | | South Africa | ZAF | ZAR | On-Request | Yes | Yes | | | South Korea | KOR | KRW | On-Request | On-Request | No | Type: C2C/C2B/B2C/B2B; Time: Real-time; Limits: None | | Spain | ESP | EUR | Yes | Yes | No | | | Sri Lanka | LKA | LKR | On-Request | On-Request | No | Type: C2C/C2B/B2C/B2B; Time: Same Day/T+1; Limit: Real-time up to LKR 5M | | Sweden | SWE | SEK | Yes | On-Request | No | Subject to EU limits | | Switzerland | CHE | CHF | Yes | On-Request | No | | | Tanzania | TZA | TZS | On-Request | On-Request | No | | | Thailand | THA | THB | On-Request | On-Request | Yes | Type: C2C/C2B/B2C/B2B; Time: Real-time; Limits: THB 50k-2M depending on bank | | Turkey | TUR | TRY | On-Request | Yes | No | | | Uganda | UGA | UGX | On-Request | On-Request | Yes | | | United Arab Emirates | ARE | AED | On-Request | Yes | Yes | | | United Kingdom (EURO) | GBR | EUR | Yes | Yes | No | Limit: €1,000,000 per txn | | United Kingdom (GBP) | GBR | GBP | Yes | Yes | No | Type: C2C/C2B/B2C/B2B; Time: Real-time 24/7; Limit: £1,000,000 | | United States | USA | USD | Yes | Yes | Yes | Limits: 10M/txn for Businesses | | Viet Nam | VNM | VND | On-Request | Yes | No | | | Yemen | YEM | YER | No | No | Yes | | | Zambia | ZMB | ZMW | On-Request | On-Request | 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. ## High-Value Transaction Management (>\$1M) Fin.com handles high-value transfers up to \$10M through our specialized OTC service. To learn more or get started, reach out to us at [a@fin.com](mailto:a@fin.com). ## Named SWIFT Support Fin.com supports named SWIFT payouts to all countries where SWIFT coverage is available. # 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 # Introduction & Key Concepts Source: https://developer.fin.com/index Fin.com's Orchestration API documentation ## Welcome to Fin.com API Explore our complete API documentation with detailed endpoints, request/response examples, and authentication guides. ## API Base URLs * Sandbox: `https://sandbox.api.fin.com` * Production: `https://api.fin.com` ## Key Concepts Understanding these core concepts will help you integrate with the Fin.com API effectively: ### Authentication The API uses OAuth 2.0 client credentials flow with an enhanced token refresh mechanism. Authenticate securely using your client credentials to obtain access tokens, with the ability to refresh them without re-authentication. All API requests require a valid access token to ensure the security of your transactions and data. ### Customers Customers represent the profiles used to initiate transactions within the system. When processing transactions, your customers are the entities that send funds to beneficiaries. Each customer can have multiple beneficiaries associated with their profile. ### Beneficiaries A beneficiary is a recipient to whom your customers send funds. Beneficiaries are linked to specific customers, and each customer can maintain multiple beneficiaries for recurring or varied transactions. ### Catalogue Pre-defined data provided by Fin.com to facilitate various operations within the API. The catalogue includes reference data, supported countries, currencies, and other essential information needed to execute API actions. ### Exchange Rates Real-time and historical exchange rates for currency conversions. Access up-to-date rates to calculate the cost of sending funds from one currency to another. # Beneficiary Onboarding Guide Source: https://developer.fin.com/onboarding-beneficiaries 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](/receiver-relationship). ### 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" } } ``` Only Polygon rail and USDC currency is available now. USDT is coming soon. ### 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/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`, `CURRENT` | **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}` # Bank Holidays 2026 Source: https://developer.fin.com/operational-information/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](/operational-information/processing-windows-and-cutoffs) for settlement timing. # Processing Windows & Cutoff Times Source: https://developer.fin.com/operational-information/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. ## 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. # SLAs for Compliance Source: https://developer.fin.com/operational-information/sla-for-compliance This Service Level Agreement (SLA) defines the operational and customer service standards maintained by [Fin.com](http://Fin.com) in the delivery of its payment and financial services. It establishes clear commitments across four key service areas: * Client onboarding timelines (KYB/KYC) * Customer service availability * Customer query response and resolution times * Request for Information (RFI) handling timelines This document applies to all clients onboarded through [Fin.com](http://Fin.com)'s platform and governs the relationship between [Fin.com](http://Fin.com), its clients, and its banking partners. ## 2. Client Onboarding Times [Fin.com](http://Fin.com) commits to completing the KYB/KYC onboarding process within 5 business days from receipt of a complete documentation package. **The onboarding clock is paused during any period where documents or information are outstanding from the client.** ### 2.1 Onboarding Timeline by Risk Tier [Fin.com](http://Fin.com) completes its own review within 24 to 48 hours of receiving a complete submission. The banking partner review then follows, with the total timeline depending on the risk classification of the customer. | Risk Classification | [Fin.com](http://Fin.com) Review | Banking Partner Review | Total Target | | :------------------ | :------------------------------- | :--------------------- | :-------------- | | Low Risk | Up to 2 business days | 3 business days | 5 business days | | High Risk | Up to 2 business days | 4 business days | 6 business days | If an RFI is raised at any stage, add 1 business day per RFI for review and response. See Section 5 for full RFI handling timelines. ### 2.2 Compliance Operating Hours The compliance and onboarding team operates Monday to Friday. Saturday and Sunday are non-working days. | | | | :------------------------------------------- | :---------------------------- | | Working days | Monday to Friday | | Operating hours | 2:00 AM to 1:00 PM EST | | Submitted before 1:00 PM EST | Reviewed the same working day | | Submitted after 1:00 PM EST, or on a weekend | Reviewed the next working day | The team works fixed hours in its local time zone. During US daylight saving time the window shifts to 3:00 AM to 2:00 PM EDT, with the daily cutoff at 2:00 PM EDT. ### 2.3 Clock Pause Conditions The onboarding SLA clock is paused in the following circumstances: * Outstanding documents from the client (RFI issued - see Section 5) * Awaiting banking partner review or approval * Escalation to compliance team for manual review The 5-day indicative target applies to standard low-risk onboardings where all required documents are submitted upfront. Clients are encouraged to prepare documentation in advance using [Fin.com](http://Fin.com)'s onboarding checklist. ## 3. Customer Service Availability [Fin.com](http://Fin.com) operates a 24/7 customer service function to ensure uninterrupted support for all clients across global time zones. ### 3.1 Service Availability | Service Channel | Availability | Coverage | | :-------------------------------- | :--------------------------------------- | :----------------------- | | Email Support | 24 hours / 7 days a week | All client enquiries | | Slack (Dedicated Client Channels) | 24 hours / 7 days a week | Dedicated B2B clients | | Pylon / Ticketing System | 24 hours / 7 days a week | Tracked issue resolution | | Compliance & Onboarding Team | Monday to Friday, 2:00 AM to 1:00 PM EST | KYB/KYC, RFI handling | **Note:** While [Fin.com](http://Fin.com) operates around the clock, complex compliance or onboarding queries requiring team input may be addressed the next business day if raised outside of core hours. ## 4. Customer Response Times [Fin.com](http://Fin.com) maintains industry-leading response times as a core operational commitment. All client queries are acknowledged and resolved within the following timeframes: ### 4.1 First Response SLA | Priority | Query Type | First Response | Target Resolution | | :------------ | :--------------------------------------------------------- | :---------------------------------------- | :--------------------- | | P1 - Critical | Transaction frozen, account blocked, compliance escalation | Within 2 minutes (target); max 10 minutes | Same business day | | P2 - High | Payment issue, onboarding status, RFI follow-up | Within 10 minutes | 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 | ## 4.2 [Fin.com](http://Fin.com) Response Commitment [Fin.com](http://Fin.com) commits to the following response performance targets: * **Standard response time: 2 minutes** * **Maximum response time: 10 minutes** * All queries are tracked via Pylon to ensure full accountability and audit trail ## 5. Request for Information (RFI) Handling An RFI is a formal request issued by [Fin.com](http://Fin.com) or its banking partners to a client, seeking additional information required for compliance, transaction monitoring, or enhanced due diligence purposes. RFIs are managed with urgency to protect both the client relationship and [Fin.com](http://Fin.com)'s regulatory obligations. ### 5.1 Outbound RFIs - Sent to Clients When [Fin.com](http://Fin.com) issues an RFI to a client, the following timeline applies: | Stage | Timeline | | :----------------------------------------------- | :------------------------------------------------------------------------- | | RFI issued to client | Same day as trigger event (e.g. compliance alert, banking partner request) | | Client response deadline - Standard | Within 14 calendar days of RFI issuance | | Client response deadline - Urgent / High Risk | Within 7 calendar days of RFI issuance | | First reminder (if no response) | Day 7 (standard) / Day 3 (urgent) | | Second reminder + escalation warning | Day 12 (standard) / Day 5 (urgent) | | Account restriction (if no response by deadline) | Day 15 (standard) / Day 8 (urgent) | | Account closure review (continued non-response) | Day 30 | ### 5.2 Inbound RFIs - Received from Banking Partners When [Fin.com](http://Fin.com) receives an RFI from a banking partner the following response commitments apply: | Stage | Timeline | | :---------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- | | Acknowledgement to banking partner | Within 1 business day of receipt | | [Fin.com](http://Fin.com) internal response to banking partner (where client docs already held) | T+1 business day (standard); T+2 business day (worst case) | | [Fin.com](http://Fin.com) response once client submits documents | Within 1 hour of document receipt from client | | Where client cooperation is required | Up to 14 calendar days (with status update to banking partner at Day 7) | [Fin.com](http://Fin.com) proactively communicates to banking partners if a client is non-responsive, rather than waiting for the deadline to lapse. This ensures the banking partner is kept informed throughout the RFI lifecycle. ### 5.3 RFI Escalation Consequences The following consequences apply where a client fails to respond to an RFI within the stated deadlines: | Non-Response Stage | Action Taken | | :------------------------------------------------ | :------------------------------------------------------------------------ | | No response by Day 7 (standard) / Day 3 (urgent) | First reminder issued; [Fin.com](http://Fin.com) account manager notified | | No response by Day 12 (standard) / Day 5 (urgent) | Final warning issued; escalation to Compliance team | | No response by Day 15 (standard) / Day 8 (urgent) | Account temporarily restricted pending response | | No response by Day 30 | Account reviewed for potential offboarding; SAR consideration | ## 6. SLA Summary Reference The table below provides a consolidated at-a-glance reference for all SLA commitments documented in this agreement. | Service Area | Commitment | | :------------------------------------------------ | :----------------------------------------------------------------- | | Onboarding (Low Risk) | 5 business days from complete document receipt | | Onboarding (High Risk) | 6 business days from complete document receipt | | Onboarding RFI Impact | Add 1 business day per RFI | | Compliance Operating Hours | Monday to Friday, 2:00 AM to 1:00 PM EST; daily cutoff 1:00 PM EST | | Customer Service Availability | 24/7 across all channels | | Customer Response - Standard | 2 minutes (target), 10 minutes (maximum) | | RFI Response to Banking Partner (where docs held) | T+1 day (standard), T+2 day (worst case) | | RFI Response after client submission | Within 1 hour of receiving client documents | | Client RFI Response Deadline - Standard | 14 calendar days | | Client RFI Response Deadline - Urgent | 7 calendar days | ## 7. Document Review & Version Control | Version | Date | Author | Change Description | | :------ | :------------ | :---------------------- | :-------------------------------------------------------------------------------------- | | 1.0 | 02 April 2026 | Operations & Compliance | Initial SLA document issued | | 1.1 | 03 July 2026 | Operations & Compliance | Updated onboarding risk tiers, added compliance operating hours and daily review cutoff | This document is subject to review every 6 months or upon material change in operations, regulatory requirements, or banking partner arrangements. The current version supersedes all prior informal communications regarding service timelines. # Sender & Receiver Relationships Source: https://developer.fin.com/receiver-relationship 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.