openapi: 3.1.0 info: title: Fin.com API version: 1.0.0 description: A simple API specification for Fin.com, a financial services platform that provides a range of banking and payment solutions for businesses and individuals. This API allows developers to integrate Fin.com's services into their applications, enabling functionalities such as customer management, transaction processing, and access to financial data. servers: - url: https://sandbox.api.fin.com description: Sandbox server - url: https://api.fin.com description: Production server tags: - name: Authentication description: A modified OAuth 2.0 Client Credential Flow - name: Customers description: Customer management and document upload operations - name: Balances description: Retrieve wallet balance information - name: Catalogue description: | A set of endpoints to retrieve contextual data to assemble requests to fin.com's API - name: Beneficiaries description: Manage beneficiary accounts for payments and transfers - name: Transactions description: Transaction history and management for beneficiaries - name: Virtual Accounts description: Create and manage virtual accounts for USD to USDC conversions - name: Fees & FX Rates description: Retrieve fees and foreign exchange rates - name: Crypto Orchestration description: Accept crypto deposits from exchange and external wallets and settle them to a destination wallet paths: # ───────────────────────────────────────────────────────────────────────── # AUTHENTICATION # ───────────────────────────────────────────────────────────────────────── "/v1/oauth/token": post: summary: Issue a Token description: Generate an access token using client credentials x-mint: content: | 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 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` tags: - Authentication requestBody: required: true content: application/json: schema: type: object required: - client_id - client_secret properties: client_id: type: string description: Client ID client_secret: type: string description: Client Secret format: password responses: "200": description: Token issued successfully content: application/json: schema: $ref: "#/components/schemas/TokenResponse" "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" "/v1/oauth/refresh-token": post: summary: Refresh a Token description: Generate a new token pair based on a refresh token. x-mint: content: | 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 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` tags: - Authentication requestBody: required: true content: application/json: schema: type: object required: - refresh_token properties: refresh_token: type: string description: The refresh_token received from the [Issue a token](https://developer.fin.com/api-reference/authentication/issue-a-token) endpoint. responses: "200": description: Token issued successfully content: application/json: schema: $ref: "#/components/schemas/TokenResponse" "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" # ───────────────────────────────────────────────────────────────────────── # CUSTOMERS # ───────────────────────────────────────────────────────────────────────── # ───────────────────────────────────────────────────────────────────────── # LIST CUSTOMERS V2 (new, added above V1) # ───────────────────────────────────────────────────────────────────────── "/v2/customers": get: summary: List Customers description: Retrieve a list of customers filtered by type tags: - Customers security: - bearerAuth: [] parameters: - name: type in: query description: Filter customers by type required: true schema: type: string enum: - INDIVIDUAL - BUSINESS - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/CurrentPageParam" responses: "200": description: List of customers retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: type: object properties: current_page: type: integer example: 1 per_page: type: integer example: 40 total_page: type: integer example: 1 total: type: integer example: 4 customers: type: array items: oneOf: - type: object title: Individual Customer properties: customer_id: type: string format: uuid example: "56c41b8e-e650-4f55-94f6-26a888a9b64d" type: type: string enum: [INDIVIDUAL] first_name: type: string example: "John" last_name: type: string example: "Doe" email: type: string format: email example: "john.doe@example.com" phone: type: string example: "+14155551234" country_of_residence: type: string example: "USA" customer_status: type: string example: "INCOMPLETE" tos_policies_url: type: string format: uri example: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=56c41b8e-e650-4f55-94f6-26a888a9b64d&tos_policies_value=e9414388-fbdf-4407-b5c2-bc39eae3645b" created_at: type: string format: date-time example: "2026-04-01T12:03:03Z" updated_at: type: string format: date-time example: "2026-04-01T12:03:03Z" - type: object title: Business Customer properties: customer_id: type: string format: uuid example: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" type: type: string enum: [BUSINESS] business_name: type: string example: "Fin.com" email: type: string format: email example: "m@tech.com" phone: type: string example: "+8801529876543" country_of_incorporation: type: string example: "BGD" customer_status: type: string example: "IN_COMPLIANCE" tos_policies_url: type: string format: uri example: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24" created_at: type: string format: date-time example: "2026-04-13T11:38:57Z" updated_at: type: string format: date-time example: "2026-04-13T11:40:51Z" examples: OK: summary: OK value: data: pagination: current_page: 1 per_page: 40 total_page: 1 total: 2 customers: - customer_id: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" type: "BUSINESS" business_name: "Fin.com" email: "m@tech.com" phone: "+8801529876543" country_of_incorporation: "BGD" customer_status: "IN_COMPLIANCE" tos_policies_url: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24" created_at: "2026-04-13T11:38:57Z" updated_at: "2026-04-13T11:40:51Z" - customer_id: "56c41b8e-e650-4f55-94f6-26a888a9b64d" type: "INDIVIDUAL" first_name: "John" last_name: "Doe" email: "john.doe@example.com" phone: "+14155551234" country_of_residence: "USA" customer_status: "INCOMPLETE" tos_policies_url: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=56c41b8e-e650-4f55-94f6-26a888a9b64d&tos_policies_value=e9414388-fbdf-4407-b5c2-bc39eae3645b" created_at: "2026-04-01T12:03:03Z" updated_at: "2026-04-01T12:03:03Z" "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" "/v2/customers/{customer_id}": get: summary: Get Customer Details description: Retrieve detailed information for a specific customer x-mint: content: | 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-v2). tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid example: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" responses: "200": description: Customer details retrieved successfully content: application/json: schema: type: object properties: data: oneOf: - $ref: "#/components/schemas/IndividualCustomerDetailV2" - $ref: "#/components/schemas/BusinessCustomerDetailV2" examples: Business: summary: Business customer value: data: customer_id: "671536f8-ddc5-4b1e-bd6f-27d0ed07a27c" type: "BUSINESS" business_name: "Fin.com" email: "contact@fin.com" phone: "+14155552671" country_of_incorporation: "USA" verification_type: "STANDARD" customer_status: "ACTION_REQUIRED" tos_policies_url: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=671536f8-ddc5-4b1e-bd6f-27d0ed07a27c&tos_policies_value=4e0e505a-36f0-4c9e-8eb1-3916410f227c" associated_parties: - id: "2e719a54-cdef-43f9-a5ac-f6ef679ea1dc" type: "INDIVIDUAL" ownership_percent: 60 email: "jane.smith@acmecorp.com" verification: status: "REJECTED" reason: for_customer: null for_developer: null updated_at: "2026-05-04T12:36:42Z" - id: "4ef045ea-c7a7-46dc-84a0-9a3d83186971" type: "INDIVIDUAL" ownership_percent: 40 email: "robert.chen@acmecorp.com" verification: status: "APPROVED" reason: for_customer: null for_developer: null updated_at: "2026-05-04T12:29:47Z" created_at: "2026-05-04T12:11:27Z" updated_at: "2026-05-04T12:34:03Z" last_status_updated_at: "2026-05-04T12:32:34.47927Z" rejection_reason: applicant: moderation_comment: "" reject_labels: - "LOW_QUALITY" - "UNFILLED_ID" - "DOCUMENT_TEMPLATE" - "NOT_DOCUMENT" documents: - uri: "/ZuyUaH3a_testdoc1.png" category: "SUPPORTING_DOCUMENTS" moderation_comment: "This document is not accepted.\n - The document should be of good quality." reject_labels: - "LOW_QUALITY" - uri: "/ZuyUaH3a_testdoc1.png" category: "OWNERSHIP_DOCUMENTS" moderation_comment: "This document is not accepted.\n - The document is not authentic" reject_labels: - "UNFILLED_ID" - uri: "/ZuyUaH3a_testdoc1.png" category: "OWNERSHIP_DOCUMENTS" moderation_comment: "This document is not accepted.\n - The uploaded file appears to be a document template." reject_labels: - "DOCUMENT_TEMPLATE" - uri: "/ZuyUaH3a_testdoc1.png" category: "SUPPORTING_DOCUMENTS" moderation_comment: "This document is not accepted.\n - The file is not a document" reject_labels: - "NOT_DOCUMENT" associated_parties: - id: "2e719a54-cdef-43f9-a5ac-f6ef679ea1dc" applicant: moderation_comment: "" reject_labels: - "EXPIRATION_DATE" documents: - uri: "/OUkUie0z_approved_passport.jpg" category: "PROOF_OF_IDENTITY" moderation_comment: "Your identity document must be valid for at least 2 month(s) from the date of submission." reject_labels: - "EXPIRATION_DATE" request_for_information: - scope: "ASSOCIATED_PARTY" associated_party_id: "2e719a54-cdef-43f9-a5ac-f6ef679ea1dc" section: "identifying_documents" categories: - document_type: "PASSPORT" fields: - field_name: "type" data_type: "ENUM" status: "INVALID" options: [] - field_name: "expiry_date" data_type: "DATE" status: "INVALID" options: [] - field_name: "issue_date" data_type: "DATE" status: "INVALID" options: [] - field_name: "files" data_type: "URI" status: "INVALID" reason: "User identity document is not valid for at least 2 month(s) from the date of submission." options: [] - scope: "CUSTOMER" section: "formation_documents" categories: - document_type: "EVIDENCE_OF_DIRECTORS_AND_CONTROLLERS" fields: - field_name: "type" data_type: "ENUM" status: "INVALID" options: [] - field_name: "files" data_type: "URI" status: "INVALID" reason: "Unacceptable document." options: [] - scope: "CUSTOMER" section: "supporting_documents" categories: - document_type: "PROOF_OF_SOURCE_OF_FUNDS" fields: - field_name: "type" data_type: "ENUM" status: "INVALID" options: [] - field_name: "files" data_type: "URI" status: "INVALID" reason: "Unacceptable document." options: [] - scope: "CUSTOMER" section: "ownership_documents" categories: - document_type: "PROOF_OF_SIGNATORY_AUTHORITY" fields: - field_name: "type" data_type: "ENUM" status: "INVALID" options: [] - field_name: "files" data_type: "URI" status: "INVALID" reason: "Document appears to be corrupted" options: [] Individual: summary: Individual customer value: data: customer_id: "1f45e58d-0420-4ad8-a790-413169bfab28" type: "INDIVIDUAL" first_name: "John" last_name: "Doe" email: "john.doe@example.com" phone: "+8801748386269" country_of_residence: "BGD" verification_type: "STANDARD" customer_status: "ACTION_REQUIRED" tos_policies_url: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=1f45e58d-0420-4ad8-a790-413169bfab28&tos_policies_value=ffefb0cd-4f0a-4585-ad1c-f4ea76ba41b8" created_at: "2026-05-04T12:40:03Z" updated_at: "2026-05-04T12:47:50Z" last_status_updated_at: "2026-05-04T12:44:42.707598Z" rejection_reason: applicant: moderation_comment: "" reject_labels: - "EXPIRATION_DATE" - "PROBLEMATIC_APPLICANT_DATA" documents: - uri: "/SuElNZpi_approved_passport.jpg" category: "PROOF_OF_IDENTITY" moderation_comment: "Your identity document has expired and can't be used for verification. Please upload a different identity document." reject_labels: - "EXPIRATION_DATE" request_for_information: - scope: "CUSTOMER" section: "proof_of_identity" categories: - document_type: "PASSPORT" fields: - field_name: "type" data_type: "ENUM" status: "INVALID" options: [] - field_name: "expiry_date" data_type: "DATE" status: "INVALID" options: [] - field_name: "issue_date" data_type: "DATE" status: "INVALID" options: [] - field_name: "files" data_type: "URI" status: "INVALID" reason: "Expired Identity document. A new document has been requested." options: [] "401": $ref: "#/components/responses/AuthenticationError" "404": $ref: "#/components/responses/NotFoundError" "422": $ref: "#/components/responses/ValidationError" # ───────────────────────────────────────────────────────────────────────── # GET CUSTOMER DETAILS V1 (existing, preserved) # ───────────────────────────────────────────────────────────────────────── "/v1/customers/{customer_id}": patch: summary: Patch Customer RFI description: >- 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. x-mint: content: | Only submit the fields explicitly listed in the RFI. Sending unrequested fields will result in an error. The request body accepts the same fields as the following endpoints: - Attach Documents to Individual Customer - Attach Documents to Business Customer - Attach Documents to Associated Party tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid description: Unique identifier of the customer to update example: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" requestBody: required: true content: application/json: schema: oneOf: - title: Individual Customer type: object properties: proof_of_identity: type: object properties: type: type: string example: "PASSPORT" number: type: string example: "A12345678" country: type: string example: "USA" issue_date: type: string format: date example: "2020-01-15" expiry_date: type: string format: date example: "2030-01-15" files: type: array items: type: object properties: uri: type: string example: "/AbAcQ4hn_0652746727637.pdf" side: type: string enum: [FRONT, BACK] example: "FRONT" proof_of_address: type: object description: "The proof of address document must not be older than three months." properties: type: type: string example: "UTILITY_BILL" country: type: string example: "USA" files: type: array items: type: object properties: uri: type: string example: "/AbAcQ4hn_0652746727638.pdf" - title: Business Customer type: object properties: ownership_documents: type: array description: Ownership documents for the business customer (e.g. shareholder registry, proof of signatory authority) items: type: object properties: type: type: string example: "PROOF_OF_SIGNATORY_AUTHORITY" description: type: string example: "Shareholder Registry" files: type: array items: type: object properties: uri: type: string example: "/AbAcQ4hn_0652746727639.pdf" formation_documents: type: array description: Formation documents for the business customer (e.g. certificate of incorporation, registration document) items: type: object properties: type: type: string example: "REGISTRATION_DOCUMENT" description: type: string example: "Certificate of Incorporation" files: type: array items: type: object properties: uri: type: string example: "/AbAcQ4hn_0652746727637.pdf" supporting_documents: type: array description: Supporting documents for the customer items: type: object properties: type: type: string example: "PROOF_OF_SOURCE_OF_FUNDS" description: type: string example: "Proof of source of funds doc" files: type: array items: type: object properties: uri: type: string example: "/PoAdef45_0652746727640.pdf" associated_party_attachments: type: array description: Document attachments for associated parties of a business customer items: type: object properties: associated_party_id: type: string format: uuid description: ID of the associated party example: "f6b13e01-044a-4f74-a70b-d5f66b6449af" identifying_documents: type: array items: type: object properties: type: type: string enum: [PASSPORT, NATIONAL_ID, DRIVERS_LICENSE, RESIDENCE_PERMIT] number: type: string country: type: string issue_date: type: string format: date expiry_date: type: string format: date files: type: array items: type: object properties: side: type: string enum: [FRONT, BACK] uri: type: string address_documents: type: array items: type: object properties: type: type: string files: type: array items: type: object properties: uri: type: string examples: "Business Customer": value: ownership_documents: - type: "PROOF_OF_SIGNATORY_AUTHORITY" description: "Shareholder Registry" files: - uri: "/AbAcQ4hn_0652746727639.pdf" formation_documents: - type: "REGISTRATION_DOCUMENT" description: "Certificate of Incorporation" files: - uri: "/AbAcQ4hn_0652746727637.pdf" supporting_documents: - type: "PROOF_OF_SOURCE_OF_FUNDS" description: "Proof of source of funds doc" files: - uri: "/PoAdef45_0652746727640.pdf" associated_party_attachments: - associated_party_id: "f6b13e01-044a-4f74-a70b-d5f66b6449af" identifying_documents: - type: "PASSPORT" number: "A12345678" country: "USA" issue_date: "2020-01-15" expiry_date: "2030-01-15" files: - uri: "/AbAcQ4hn_0652746727637.pdf" - type: "DRIVERS_LICENSE" number: "DL987654321" country: "USA" issue_date: "2019-06-01" expiry_date: "2029-06-01" files: - side: "FRONT" uri: "/AbAcQ4hn_0652746727645.pdf" - side: "BACK" uri: "/AbAcQ4hn_0652746727646.pdf" address_documents: - type: "BANK_STATEMENT" files: - uri: "/AbAcQ4hn_0652746727638.pdf" - associated_party_id: "f71dc19f-b9a0-49fb-bd2d-5add3c01626e" identifying_documents: - type: "NATIONAL_ID" number: "NID-987654" country: "USA" issue_date: "2021-03-10" expiry_date: "2031-03-10" files: - side: "FRONT" uri: "/XyZ123mn_0652746727650.pdf" - side: "BACK" uri: "/XyZ123mn_0652746727651.pdf" address_documents: - type: "UTILITY_BILL" files: - uri: "/XyZ123mn_0652746727652.pdf" "Individual Customer": value: proof_of_identity: type: "PASSPORT" number: "A12345678" country: "USA" issue_date: "2020-01-15" expiry_date: "2030-01-15" files: - uri: "/AbAcQ4hn_0652746727637.pdf" side: "FRONT" proof_of_address: type: "UTILITY_BILL" country: "USA" files: - uri: "/AbAcQ4hn_0652746727638.pdf" responses: "200": description: Customer updated successfully content: application/json: schema: type: object properties: data: type: object properties: customer_id: type: string format: uuid example: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" example: data: customer_id: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" "400": description: Validation failed content: application/json: schema: type: object properties: status: type: integer example: 400 message: type: string example: Validation failed data: type: object additionalProperties: type: string "401": $ref: "#/components/responses/AuthenticationError" "404": $ref: "#/components/responses/NotFoundError" "422": $ref: "#/components/responses/ValidationError" "/v2/customers/{customer_id}/capabilities": get: summary: Get Customer Capabilities description: 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. tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid example: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" responses: "200": description: Customer capabilities retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: on_ramp: type: array items: type: object properties: currency: type: string description: Payin currency. example: "USD" rail: type: string description: Payin rail for this currency. example: "ACH" status: type: boolean description: Whether this route is currently enabled for the customer. example: true crypto: type: array description: >- Chains and tokens the payin can settle to. See [Supported rails and currencies](https://developer.fin.com/guides/others/supported-rails-and-currencies). items: type: object properties: chain: type: string example: "POLYGON" tokens: type: array items: type: string example: ["USDC", "USDT"] off_ramp: type: array items: type: object properties: corridor: type: string description: Payout country, ISO 3166-1 alpha-3. example: "BGD" currency_wise_rail: type: array items: type: object properties: currency: type: string example: "BDT" scheme: type: string nullable: true description: >- Payout scheme for this currency, LOCAL or INTERNATIONAL. Null when the corridor has no scheme distinction. example: "LOCAL" rails: type: array items: type: object properties: rail: type: string nullable: true description: >- Named rail within the scheme, for example SPEI. Null when the scheme has no named rail. example: "SPEI" status: type: boolean description: Whether this route is currently enabled for the customer. example: true crypto: type: array description: >- Chains and tokens that can fund a payout on this route. See [Supported rails and currencies](https://developer.fin.com/guides/others/supported-rails-and-currencies). items: type: object properties: chain: type: string example: "POLYGON" tokens: type: array items: type: string example: ["USDC", "USDT"] examples: OK: summary: OK value: data: on_ramp: - currency: "USD" rail: "SWIFT" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - currency: "USD" rail: "ACH" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - chain: "SOLANA" tokens: - "USDC" - "USDT" - currency: "USD" rail: "FEDWIRE" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - chain: "SOLANA" tokens: - "USDC" - "USDT" off_ramp: - corridor: "AUS" currency_wise_rail: - currency: "USD" scheme: "INTERNATIONAL" rails: - rail: "SWIFT" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - corridor: "BGD" currency_wise_rail: - currency: "BDT" scheme: "LOCAL" rails: - rail: null status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - currency: "USD" scheme: "INTERNATIONAL" rails: - rail: "SWIFT" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - corridor: "CAN" currency_wise_rail: - currency: "USD" scheme: "INTERNATIONAL" rails: - rail: "SWIFT" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - corridor: "DEU" currency_wise_rail: - currency: "USD" scheme: "INTERNATIONAL" rails: - rail: "SWIFT" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - corridor: "GBR" currency_wise_rail: - currency: "GBP" scheme: "LOCAL" rails: - rail: null status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - currency: "USD" scheme: "INTERNATIONAL" rails: - rail: "SWIFT" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - corridor: "IND" currency_wise_rail: - currency: "INR" scheme: "LOCAL" rails: - rail: null status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - currency: "USD" scheme: "INTERNATIONAL" rails: - rail: "SWIFT" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - corridor: "MEX" currency_wise_rail: - currency: "MXN" scheme: "LOCAL" rails: - rail: "SPEI" status: false crypto: [] - corridor: "NPL" currency_wise_rail: - currency: "USD" scheme: "INTERNATIONAL" rails: - rail: "SWIFT" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - corridor: "PAK" currency_wise_rail: - currency: "USD" scheme: "INTERNATIONAL" rails: - rail: "SWIFT" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - currency: "PKR" scheme: null rails: - rail: null status: false crypto: [] - corridor: "PHL" currency_wise_rail: - currency: "USD" scheme: "INTERNATIONAL" rails: - rail: "SWIFT" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - corridor: "POL" currency_wise_rail: - currency: "USD" scheme: "INTERNATIONAL" rails: - rail: "SWIFT" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - corridor: "SGP" currency_wise_rail: - currency: "SGD" scheme: "LOCAL" rails: - rail: null status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - currency: "USD" scheme: "INTERNATIONAL" rails: - rail: "SWIFT" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - corridor: "USA" currency_wise_rail: - currency: "USD" scheme: "INTERNATIONAL" rails: - rail: "SWIFT" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - "USDT" - chain: "SOLANA" tokens: - "USDC" - "USDT" - currency: "USD" scheme: "LOCAL" rails: - rail: "ACH" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - chain: "SOLANA" tokens: - "USDC" - "USDT" - rail: "FEDWIRE" status: true crypto: - chain: "BASE" tokens: - "USDC" - chain: "ETHEREUM" tokens: - "USDC" - "USDT" - chain: "POLYGON" tokens: - "USDC" - chain: "SOLANA" tokens: - "USDC" - "USDT" "401": $ref: "#/components/responses/AuthenticationError" "404": $ref: "#/components/responses/NotFoundError" "422": $ref: "#/components/responses/ValidationError" # ───────────────────────────────────────────────────────────────────────── # CREATE INDIVIDUAL CUSTOMER V2 (new, added above V1) # ───────────────────────────────────────────────────────────────────────── "/v2/customers/individual": post: summary: Create Individual Customer description: >- Create a new individual customer with verification details, basic info, address, and financial profile. tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateIndividualCustomerV2Input" example: verification_type: STANDARD 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: 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: employment_status: EMPLOYED occupation_id: 42 purpose_id: 3 purpose_remarks: Personal remittances to family source_of_funds_description: Monthly salary from employment source_of_fund_ids: - 1 - 5 monthly_volume_usd: 5000 meta_data: reference: client-ref-abc-001 responses: "200": description: Individual customer created successfully content: application/json: schema: type: object properties: data: type: object properties: customer_id: type: string format: uuid example: "0ca13984-63f3-45d7-99a7-52b9133f0259" tos_policies_url: type: string format: uri description: >- URL for the customer to accept Terms of Service. Parse the tos_policies_value query parameter for later use. example: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=0ca13984-63f3-45d7-99a7-52b9133f0259&tos_policies_value=7e8873f7-519b-43d7-9565-c81befc52dd6" "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" "423": description: "Locked. RELIANCE verification is not available for your client." content: application/json: schema: type: object properties: message: type: string example: "RELIANCE is not available for your client" "/v2/customers/business": post: summary: Create Business Customer description: >- Create a new business customer with full KYB profile, associated parties (UBOs/directors), compliance data, and optionally holding structure and public listing details. x-mint: content: | ## 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. tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateBusinessCustomerV2Input" example: verification_type: STANDARD industry_codes: - "541512" - "522390" basic_info: legal_name: Fin.com legal_name_en: Fin.com trade_name: Toronggo trade_name_en: Toronggo description: >- Bangladesh-based technology company providing cross-border B2B payment and financial technology services to enterprise clients entity_type: LIMITED_LIABILITY_COMPANY email: m@tech.com phone: "+8801529876543" incorporation_date: "2018-06-15" country_of_incorporation: BGD registration_number: "C-123456/2018" is_dao: false tax_info: - country_code: BGD document_type: TIN document_id: "123456789012" websites: - https://fin.com financial_profile: purpose_id: 3 purpose_remarks: Cross-border B2B payments for international suppliers source_of_fund_ids: - 1 - 4 source_of_funds_description: Revenue from software licensing and technology services 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 addresses: is_incorporated_address_same: false incorporated_address: street_line_1: House 12, Road 4, Dhanmondi city: Dhaka state: BD-13 subdivision_code: BD-13 postal_code: "1205" country: BGD physical_address: street_line_1: Level 5, 45 Gulshan Avenue city: Dhaka state: BD-13 subdivision_code: BD-13 postal_code: "1212" country: BGD associated_parties: - ref: owner-001 basic_info: first_name: Fatima last_name: Rahman dob: "1990-05-15" email: fatima.rahman22@acmecorp.com.bd phone: "+8801711223344" country_of_residence: BGD primary_nationality: BGD tax_info: - country_code: BGD document_type: TIN document_id: "1234567890123" address: street_line_1: House 12, Road 4, Dhanmondi city: Dhaka state: BD-13 subdivision_code: BD-13 postal_code: "1205" country: BGD roles: - shareholder 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: Karim last_name: Islam dob: "1992-08-22" email: karim.islam22@acmecorp.com.bd phone: "+8801822334455" country_of_residence: BGD primary_nationality: BGD tax_info: - country_code: BGD document_type: TIN document_id: "9876543210123" address: street_line_1: Flat 3B, 78 Mirpur Road city: Dhaka state: BD-13 subdivision_code: BD-13 postal_code: "1216" country: BGD 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: has_material_intermediary_ownership: true corporate_shareholders: - entity_name: Toronggo Ventures Limited entity_name_en: Toronggo Ventures Limited registration_country_code: BGD ownership_percentage: 0.0 registration_number: "C-987654/2015" entity_type: LIMITED_LIABILITY_COMPANY incorporation_date: "2015-03-01" compliance: operates_in_prohibited_countries: false additional_description_for_compliance_screening: >- We do not operate in any OFAC-sanctioned jurisdictions. risk_profile: high_risk_activities: - adult_entertainment high_risk_activities_explanation: >- We facilitate cross-border B2B payments, subject to enhanced due diligence. conducts_money_services: true conducts_money_services_via_fin: false conducts_money_services_description: Licensed payment service provider offering international transfer services. regulated_activity: description: Licensed payment service provider under Bangladesh Bank regulation primary_authority_country_code: BGD primary_authority_name: Bangladesh Bank license_number: PSP-2019-00123 aml: supervisory_authority_name: Bangladesh Financial Intelligence Unit license_number: PSP-2019-00123 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" meta_data: reference: REF-20250123-TORONGGO responses: "201": description: Business customer created successfully content: application/json: schema: type: object properties: customer_id: type: string format: uuid description: Unique identifier for the created customer example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06 tos_policies_url: type: string format: uri description: >- URL for customer to accept Terms of Service. Parse the tos_policies_value query parameter and pass it when attaching business documents. example: >- https://orchestration.fin.com/orchestration-customer-tos?customer_id=ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24 "400": description: Validation failed content: application/json: schema: type: object properties: status: type: integer example: 400 message: type: string example: Validation failed data: type: object additionalProperties: type: string example: basic_info.email: Must be a valid email address associated_parties[0].basic_info.dob: Party must be at least 18 years old addresses.physical_address: Required when is_incorporated_address_same is false "401": $ref: "#/components/responses/AuthenticationError" "423": description: "Locked. RELIANCE verification is not available for your client." content: application/json: schema: type: object properties: status: type: integer example: 423 message: type: string example: RELIANCE is not available for your client "500": description: Internal server error content: application/json: schema: type: object properties: status: type: integer example: 500 message: type: string example: Internal server error "/v1/customers/upload": post: summary: Upload Document description: Upload customer documents using multipart/form-data. Files can be uploaded with arbitrary field names (e.g., poa, poi, passport, file1, etc.) x-mint: content: | ## 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. tags: - Customers security: - bearerAuth: [] requestBody: required: true content: multipart/form-data: schema: type: object properties: customer_id: type: string format: uuid example: "55bd6b4e-c20a-4cc8-9535-91d5557a67d9" passport: type: string format: binary poa: type: string format: binary poi: type: string format: binary responses: "200": description: Documents uploaded successfully content: application/json: schema: type: object properties: data: type: object properties: files: type: array items: type: object additionalProperties: type: string example: - passport: "/CwW9PHhP_Germany-passport.jpg" - poa: "/KVdLfqjR_germany-poa-green.jpg" "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" # ───────────────────────────────────────────────────────────────────────── # ATTACH DOCUMENTS TO INDIVIDUAL CUSTOMER V2 (new, added above V1) # ───────────────────────────────────────────────────────────────────────── "/v2/customers/{customer_id}/individual/attach": post: summary: Attach Documents to Individual Customer description: >- 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. tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid description: Unique identifier for the individual customer example: "55bd6b4e-c20a-4cc8-9535-91d5557a67d9" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AttachDocumentsToIndividualCustomerV2Input" example: 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" responses: "200": description: Request validated and queued for asynchronous processing content: application/json: schema: type: object properties: data: type: object properties: customer_id: type: string format: uuid example: "55bd6b4e-c20a-4cc8-9535-91d5557a67d9" meta: type: object nullable: true example: null "400": description: Malformed JSON or unparseable payload content: application/json: schema: type: object properties: status: type: integer example: 400 message: type: string example: Malformed request body "401": $ref: "#/components/responses/AuthenticationError" "403": description: >- Customer not owned by the client, wrong api_version, or not in an allowed status, or a file URI does not belong to the customer content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: forbidden message: type: string example: "Customer is not eligible for this operation" "404": $ref: "#/components/responses/NotFoundError" "409": description: Another attach for this customer is already in flight content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: conflict message: type: string example: "An attach request is already in progress for this customer" "422": $ref: "#/components/responses/ValidationError" "500": description: Internal server error content: application/json: schema: type: object properties: status: type: integer example: 500 message: type: string example: Internal server error "/v2/customers/{customer_id}/business/attach": post: summary: Attach Documents to Business Customer description: >- 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. x-mint: content: | - 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/customers-and-compliance/entity-wise-document-requirement) for all valid `type` values per category and entity type. tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid description: Unique identifier for the business customer example: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AttachDocumentsToBusinessCustomerV2Input" example: 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: "6955e70b-f9f3-4076-b1ce-5c897085dd24" responses: "200": description: Documents attached successfully content: application/json: schema: type: object properties: data: type: object description: Generic response object "400": description: Validation failed content: application/json: schema: type: object properties: status: type: integer example: 400 message: type: string example: Validation failed data: type: object additionalProperties: type: string "401": $ref: "#/components/responses/AuthenticationError" "404": $ref: "#/components/responses/NotFoundError" "422": $ref: "#/components/responses/ValidationError" "/v2/customers/{customer_id}/associated-parties/individual/attach": post: summary: Attach Documents to Associated Party description: >- 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. x-mint: content: | 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) | tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid description: Unique identifier for the business customer example: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AttachDocumentsToAssociatedPartyV2Input" example: associated_party_attachments: - associated_party_id: "f6b13e01-044a-4f74-a70b-d5f66b6449af" identifying_documents: - type: PASSPORT number: "A12345678" country: USA issue_date: "2020-01-15" expiry_date: "2030-01-15" files: - uri: "/AbAcQ4hn_0652746727637.pdf" - type: DRIVERS_LICENSE number: "DL987654321" country: USA issue_date: "2019-06-01" expiry_date: "2029-06-01" files: - side: FRONT uri: "/AbAcQ4hn_0652746727645.pdf" - side: BACK uri: "/AbAcQ4hn_0652746727646.pdf" address_documents: - type: BANK_STATEMENT files: - uri: "/AbAcQ4hn_0652746727638.pdf" - associated_party_id: "f71dc19f-b9a0-49fb-bd2d-5add3c01626e" identifying_documents: - type: NATIONAL_ID number: "NID-987654" country: USA issue_date: "2021-03-10" expiry_date: "2031-03-10" files: - side: FRONT uri: "/XyZ123mn_0652746727650.pdf" - side: BACK uri: "/XyZ123mn_0652746727651.pdf" address_documents: - type: UTILITY_BILL files: - uri: "/XyZ123mn_0652746727652.pdf" responses: "200": description: Documents attached successfully content: application/json: schema: type: object properties: data: type: object description: Generic response object "400": description: Validation failed content: application/json: schema: type: object properties: status: type: integer example: 400 message: type: string example: Validation failed data: type: object additionalProperties: type: string "401": $ref: "#/components/responses/AuthenticationError" "404": $ref: "#/components/responses/NotFoundError" "422": $ref: "#/components/responses/ValidationError" # ───────────────────────────────────────────────────────────────────────── # BENEFICIARIES # ───────────────────────────────────────────────────────────────────────── "/v1/beneficiaries/countries": get: summary: List Available Countries description: Retrieve a list of countries supported for beneficiary creation with available payment methods and phone validation rules tags: - Beneficiaries security: - bearerAuth: [] responses: "200": description: Countries list retrieved successfully content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: integer example: 4 code: type: string example: "AUS" name: type: string example: "Australia" currency_code: type: string example: "AUD" phone: type: object properties: code: type: string example: "+61" max_length: type: integer example: 9 min_length: type: integer example: 9 available_methods: type: array items: type: string enum: - BANK - E_WALLET example: ["BANK"] flag: type: string format: uri example: "https://flagcdn.com/au.svg" "401": $ref: "#/components/responses/AuthenticationError" "/v1/beneficiaries/methods": get: summary: List Bank Identifiers description: Retrieve a list of available banks or e-wallet providers for a specific country and method type tags: - Beneficiaries security: - bearerAuth: [] parameters: - name: country_code in: query required: true schema: type: string example: "BGD" - name: method in: query required: true schema: type: string enum: - BANK - E_WALLET - name: currency in: query required: false description: Filter results by settlement currency, as an ISO 4217 alpha-3 code. schema: type: string pattern: "^[A-Z]{3}$" example: "BDT" - name: scheme in: query required: false description: "Filter results by payout scheme. Available options: LOCAL, SWIFT." schema: type: string enum: - LOCAL - SWIFT example: "LOCAL" responses: "200": description: Bank/method identifiers retrieved successfully content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: integer example: 1461 name: type: string example: "AB BANK LTD." method: type: string enum: - BANK - E_WALLET example: "BANK" has_branch: type: boolean example: true "401": $ref: "#/components/responses/AuthenticationError" "/v1/beneficiaries/methods/{method_id}/branches": get: summary: List Bank Branch Identifiers description: Retrieve a list of available branches for a specific bank or payment method tags: - Beneficiaries security: - bearerAuth: [] parameters: - name: method_id in: path required: true schema: type: string example: "1472" responses: "200": description: Branch identifiers retrieved successfully content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: integer example: 21513 name: type: string example: "SITAKUNDA" branch_code: type: string example: "020157391" "401": $ref: "#/components/responses/AuthenticationError" # ───────────────────────────────────────────────────────────────────────── # CREATE BENEFICIARY V3 (new, added above V2) # ───────────────────────────────────────────────────────────────────────── "/v3/beneficiaries": post: summary: Create Beneficiary description: Create a new beneficiary for payments and transfers. Supports bank accounts and e-wallets as destination types. x-mint: content: | 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` | tags: - Beneficiaries security: - bearerAuth: [] requestBody: required: true content: application/json: schema: allOf: - type: object required: - customer_id - country - currency - counter_party - account_holder - account_holder_address - receiver_meta_data - developer_fee properties: customer_id: type: string format: uuid example: "6fa1ccd4-ffbd-4b20-a113-ccc286b35443" country: type: string pattern: "^[A-Z]{3}$" example: "BGD" currency: type: string example: "BDT" counter_party: type: string enum: [FIRST_PARTY, THIRD_PARTY] example: "FIRST_PARTY" account_holder: oneOf: - title: Individual type: object required: - type - first_name - last_name - email - phone properties: type: type: string enum: [INDIVIDUAL] first_name: type: string example: "John" last_name: type: string example: "Doe" email: type: string format: email example: "john.doe@example.com" phone: type: string example: "+8801912244626" - title: Business type: object required: - type - business_name - email - phone properties: type: type: string enum: [BUSINESS] business_name: type: string example: "Acme Corp" email: type: string format: email example: "contact@acmecorp.com" phone: type: string example: "+8801912244626" account_holder_address: type: object required: - street_line_1 - city - state - postcode - country properties: street_line_1: type: string example: "42 Wallaby Way" city: type: string example: "Dhaka" state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: "BD-13" postcode: type: string example: "1212" country: type: string pattern: "^[A-Z]{3}$" example: "BGD" receiver_meta_data: type: object required: - transaction_purpose_id - relationship - nationality properties: nationality: type: string pattern: "^[A-Z]{3}$" example: "AUS" transaction_purpose_id: type: integer example: 1 transaction_purpose_remarks: type: string nullable: true example: null occupation_id: type: integer example: 5 occupation_remarks: type: string example: "Software Engineer" relationship: type: string enum: - EMPLOYEE - FREELANCER - GIG_WORKER - AFFILIATE - CUSTOMER - FAMILY_MEMBER - FRIEND - SELF - OTHER - SUPPLIER - VENDOR - SERVICE_PROVIDER - MERCHANT - CONTRACTOR - SUBSIDIARY - PARENT_COMPANY - AFFILIATE_BUSINESS - BANK_ACCOUNT - BROKER - EXCHANGE - WALLET example: "FAMILY_MEMBER" relationship_remarks: type: string example: "Family & Friends" govt_id_number: type: string example: "JG1121316A" govt_id_issue_date: type: string format: date example: "2024-12-30" govt_id_expire_date: type: string format: date example: "2027-12-30" intermediary_routing_number: type: string description: >- Required for SWIFT payouts. Routing number of an intermediary bank, when the payout has to be routed through one before it reaches the beneficiary bank. example: "021000021" developer_fee: type: object required: - fixed - percentage properties: fixed: type: number example: 0.02 percentage: type: number example: 0.01 - oneOf: - title: Bank Account type: object required: - bank_account - bank_address - bank_routing - deposit_instruction - refund_instruction properties: bank_account: type: object required: - bank_name - number - scheme - type properties: bank_name: type: string example: "Commonwealth Bank of Australia" number: type: string example: "1234572211" scheme: type: string enum: [LOCAL, SWIFT] example: "LOCAL" type: type: string enum: [CHECKING, SAVINGS] example: "SAVINGS" bank_address: type: object required: - street_line_1 - city - state - postcode - country properties: street_line_1: type: string example: "Ground Floor Tower 1, 201 Sussex Street" city: type: string example: "Dhaka" state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: "BD-13" postcode: type: string example: "1212" country: type: string pattern: "^[A-Z]{3}$" example: "BGD" bank_routing: type: array description: "For country-specific routing validation rules, see [Bank Account and Routing Validation Rules](https://developer.fin.com/bank-account-and-routing-validation-rules)." items: type: object required: - scheme - number properties: scheme: type: string enum: - ACH - BANK_CODE - BANK_IDENTIFIER - BRANCH_CODE - BRANCH_IDENTIFIER - BSB - IBAN - IFSC - SWIFT - TRANSIT_NUMBER - WIRE example: "SWIFT" number: oneOf: - type: string - type: integer example: "CLNOUS66BRX" deposit_instruction: type: object description: >- Token and network the customer deposits on to fund this beneficiary. The `currency` and `rail` must match `refund_instruction`. Availability depends on the payout currency, and not every token is issued on every network. See [Supported rails and currencies](https://developer.fin.com/guides/others/supported-rails-and-currencies) for valid combinations. required: - currency - rail properties: currency: type: string enum: [USDC, USDT] example: "USDC" rail: type: string enum: [POLYGON, ETHEREUM, SOLANA, BASE] example: "POLYGON" refund_instruction: type: object description: The `currency` and `rail` must match `deposit_instruction`. required: - wallet_address - currency - rail properties: wallet_address: type: string example: "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F" currency: type: string enum: [USDC, USDT] example: "USDC" rail: type: string enum: [POLYGON, ETHEREUM, SOLANA, BASE] example: "POLYGON" settlement_config: type: object properties: auto_settlement: type: boolean example: true - title: E Wallet type: object required: - e_wallet - deposit_instruction - refund_instruction properties: e_wallet: type: object required: - scheme - number properties: scheme: type: string example: "BKASH" number: type: string example: "+8801688502814" deposit_instruction: type: object description: >- Token and network the customer deposits on to fund this beneficiary. The `currency` and `rail` must match `refund_instruction`. Availability depends on the payout currency, and not every token is issued on every network. See [Supported rails and currencies](https://developer.fin.com/guides/others/supported-rails-and-currencies) for valid combinations. required: - currency - rail properties: currency: type: string enum: [USDC, USDT] example: "USDC" rail: type: string enum: [POLYGON, ETHEREUM, SOLANA, BASE] example: "POLYGON" refund_instruction: type: object description: The `currency` and `rail` must match `deposit_instruction`. required: - wallet_address - currency - rail properties: wallet_address: type: string example: "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F" currency: type: string enum: [USDC, USDT] example: "USDC" rail: type: string enum: [POLYGON, ETHEREUM, SOLANA, BASE] example: "POLYGON" settlement_config: type: object properties: auto_settlement: type: boolean example: true examples: "Bank (Local)": summary: Bank beneficiary, local rail value: customer_id: "c1f4a8e2-3b57-4d09-9a61-7e2b5c8d4f30" counter_party: "THIRD_PARTY" country: "USA" currency: "USD" account_holder: type: "INDIVIDUAL" first_name: "Walter" last_name: "Reed" email: "walter.reed@example.com" phone: "+12125550143" account_holder_address: street_line_1: "1 Wall Street" city: "New York" state: "US-NY" postcode: "10005" country: "USA" bank_account: bank_name: "Chase" number: "12345678901" scheme: "LOCAL" type: "CHECKING" bank_routing: - scheme: "FEDWIRE" number: "021000021" bank_address: street_line_1: "270 Park Ave" city: "New York" state: "US-NY" postcode: "10017" country: "USA" deposit_instruction: currency: "USDC" rail: "ETHEREUM" refund_instruction: wallet_address: "0x3D6b18Ea54c9F27b0A83d1e6C475b920Fa8E13d4" currency: "USDC" rail: "ETHEREUM" developer_fee: fixed: 0 percentage: 0 settlement_config: auto_settlement: true receiver_meta_data: transaction_purpose_id: 1 occupation_id: 53 nationality: "USA" relationship: "FRIEND" "Bank (International)": summary: Bank beneficiary, international rail value: customer_id: "c1f4a8e2-3b57-4d09-9a61-7e2b5c8d4f30" counter_party: "THIRD_PARTY" country: "BGD" currency: "USD" account_holder: type: "INDIVIDUAL" first_name: "Rahim" last_name: "Uddin" email: "rahim.uddin@example.com" phone: "+8801712345678" account_holder_address: street_line_1: "12 Gulshan Avenue" city: "Dhaka" state: "BD-13" postcode: "1212" country: "BGD" bank_account: bank_name: "Eastern Commercial Bank" number: "20501174963" scheme: "SWIFT" type: "CHECKING" bank_routing: - scheme: "SWIFT" number: "ABCDBDDHXXX" bank_address: street_line_1: "9 Motijheel C/A" city: "Dhaka" state: "BD-13" postcode: "1000" country: "BGD" deposit_instruction: currency: "USDC" rail: "ETHEREUM" refund_instruction: wallet_address: "0x3D6b18Ea54c9F27b0A83d1e6C475b920Fa8E13d4" currency: "USDC" rail: "ETHEREUM" developer_fee: fixed: 0 percentage: 0 receiver_meta_data: transaction_purpose_id: 1 occupation_id: 53 nationality: "BGD" relationship: "FRIEND" intermediary_routing_number: "021000021" "Ewallet": summary: E-wallet beneficiary value: 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: "fahmi.testbenvtwo@example.com" phone: "+8801688502814" account_holder_address: street_line_1: "42 Chamelibag Shantinagar" city: "Dhaka" state: "BD-13" postcode: "1217" country: "BGD" receiver_meta_data: nationality: "BGD" transaction_purpose_id: 1 transaction_purpose_remarks: "Education expenses" occupation_id: 2 occupation_remarks: "Software Engineer" relationship: "FRIEND" e_wallet: number: "+8801688502814" scheme: "BKASH" developer_fee: fixed: 1.55 percentage: 0.48 deposit_instruction: currency: "USDC" rail: "POLYGON" refund_instruction: wallet_address: "0xabcdef1234567890abcdef1234567890abcdef12" currency: "USDC" rail: "POLYGON" settlement_config: auto_settlement: false responses: "200": description: Beneficiary created successfully content: application/json: schema: type: object properties: data: type: object properties: beneficiary_id: type: string format: uuid example: "0254b433-e47d-412e-844b-b735c4bbba74" examples: OK: summary: OK value: data: beneficiary_id: "0254b433-e47d-412e-844b-b735c4bbba74" "400": description: Bad Request - Invalid input format content: application/json: schema: type: object properties: errors: type: array items: type: object message: type: string example: "Validation failed!" "401": $ref: "#/components/responses/AuthenticationError" "409": description: Conflict - A beneficiary with the same account details already exists content: application/json: schema: type: object properties: message: type: string example: "A beneficiary with the same account details already exists." error: type: object properties: beneficiary_id: type: string format: uuid example: "0254b433-e47d-412e-844b-b735c4bbba74" "422": $ref: "#/components/responses/ValidationError" # ───────────────────────────────────────────────────────────────────────── # CREATE BENEFICIARY V2 (existing, preserved) # ───────────────────────────────────────────────────────────────────────── "/v1/customers/{customer_id}/beneficiaries": get: summary: List Beneficiaries For a Customer description: Retrieve all beneficiaries associated with a specific customer tags: - Beneficiaries security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid example: "ad41fac1-e406-445b-aea4-69381c39ca5d" responses: "200": description: Beneficiaries list retrieved successfully content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string format: uuid example: "f653e109-6c62-4aa4-869c-418c874e0a6c" customer_id: type: string format: uuid example: "ad41fac1-e406-445b-aea4-69381c39ca5d" active: type: boolean example: true country_code: type: string example: "AUS" business_name: type: string example: "Investment bank" type: type: string enum: - INDIVIDUAL - BUSINESS example: "BUSINESS" nationality: type: string example: "AUS" email: type: string format: email example: "michael.oconnor@example.com" phone: type: string example: "+61412345678" method: type: string enum: - BANK - E_WALLET example: "BANK" currency: type: string example: "AUD" account_number: type: string example: "*****6789" refund_wallet_address: type: string example: "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F" developer_fee_fixed: type: number example: 1.25 developer_fee_percentage: type: number example: 0.45 liquidation_address: type: string example: "0x185571d849dcfefff449bd1e9f847b1322f22834" auto_settlement: type: boolean example: false source_currency: type: string example: "USDC" source_chain: type: string example: "POLYGON" created_at: type: string format: date-time example: "2025-12-09T14:56:47.916263Z" updated_at: type: string format: date-time example: "2025-12-09T14:56:49.1308Z" "401": $ref: "#/components/responses/AuthenticationError" # ───────────────────────────────────────────────────────────────────────── # FETCH BENEFICIARY DETAILS V2 (existing, preserved) # ───────────────────────────────────────────────────────────────────────── "/v2/beneficiaries/details": get: summary: Fetch Beneficiary Details description: Retrieve detailed information for a specific beneficiary. Returns structured data for bank accounts, e-wallets, and external crypto wallet destinations. tags: - Beneficiaries security: - bearerAuth: [] parameters: - name: customer_id in: query required: true schema: type: string format: uuid example: "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9" - name: beneficiary_id in: query required: true schema: type: string format: uuid example: "4c0c63db-580f-4e16-af24-e84ea8937dd8" responses: "200": description: Beneficiary details retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid example: "4c0c63db-580f-4e16-af24-e84ea8937dd8" customer_id: type: string format: uuid example: "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9" active: type: boolean example: true status: type: string enum: [INITIATED, PROCESSING, ACTIVE, INACTIVE, REJECTED] example: "ACTIVE" counter_party: type: string enum: [FIRST_PARTY, THIRD_PARTY] example: "FIRST_PARTY" currency: type: string example: "AUD" country: type: string example: "AUS" account_holder: type: object properties: type: type: string enum: - INDIVIDUAL - BUSINESS example: "INDIVIDUAL" first_name: type: string example: "John" last_name: type: string example: "Doe" business_name: type: string email: type: string format: email example: "john.doe@example.com" phone: type: string example: "+61412345678" bank_account: type: object properties: bank_name: type: string example: "Commonwealth Bank of Australia" number: type: string example: "123456782" scheme: type: string example: "LOCAL" type: type: string enum: - BANK - E_WALLET example: "BANK" bank_routing: type: array items: type: object properties: scheme: type: string example: "BANK_IDENTIFIER" name: type: string example: "AUS BANK" receiver_meta_data: type: object properties: transaction_purpose_id: type: integer example: 1 transaction_purpose_remarks: type: string example: "Send to Family & Friends" occupation_id: type: integer example: 504 occupation_remarks: type: string example: "Software quality assurance analyst and tester" relationship: type: string example: "FAMILY_MEMBER" relationship_remarks: type: string example: "Family & Friends" nationality: type: string example: "AUS" bank_address: type: object properties: street_line_1: type: string example: "Ground Floor Tower 1, 201 Sussex Street" city: type: string example: "Sydney" state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: "AU-SA" postcode: type: string example: "2000" country: type: string example: "AUS" account_holder_address: type: object properties: street_line_1: type: string example: "42 Wallaby Way" city: type: string example: "Queensland" state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: "AU-SA" postcode: type: string example: "2000" country: type: string example: "AUS" developer_fee: type: object properties: fixed: type: number example: 1.25 percentage: type: number example: 0.45 deposit_instruction: type: object properties: currency: type: string example: "USDC" rail: type: string example: "POLYGON" liquidation_address: type: string example: "0xc0470baa27e383a570226298f598fac0612f1143" refund_instruction: type: object properties: wallet_address: type: string example: "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F" currency: type: string example: "USDC" rail: type: string example: "POLYGON" e_wallet: type: object nullable: true properties: scheme: type: string example: "BKASH" number: type: string example: "+8801688502814" settlement_config: type: object properties: auto_settlement: type: boolean example: false created_at: type: string format: date-time example: "2025-12-31T14:29:07.100041Z" updated_at: type: string format: date-time example: "2025-12-31T14:29:08.675022Z" examples: "Bank / Ewallet": summary: Bank or e-wallet beneficiary value: data: id: "4c0c63db-580f-4e16-af24-e84ea8937dd8" customer_id: "31526861-ebe0-4f84-a7b2-2c3ec1cc47f9" active: true status: "ACTIVE" counter_party: "FIRST_PARTY" currency: "AUD" country: "AUS" account_holder: type: "INDIVIDUAL" first_name: "John" last_name: "Doe" email: "john.doe@example.com" phone: "+61412345678" bank_account: bank_name: "Commonwealth Bank of Australia" number: "123456782" scheme: "LOCAL" type: "BANK" bank_routing: - scheme: "BANK_IDENTIFIER" name: "AUS BANK" receiver_meta_data: 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" nationality: "AUS" 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" developer_fee: fixed: 1.25 percentage: 0.45 deposit_instruction: currency: "USDC" rail: "POLYGON" liquidation_address: "0xc0470baa27e383a570226298f598fac0612f1143" refund_instruction: wallet_address: "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F" currency: "USDC" rail: "POLYGON" e_wallet: null settlement_config: auto_settlement: false created_at: "2025-12-31T14:29:07.100041Z" updated_at: "2025-12-31T14:29:08.675022Z" "404": $ref: "#/components/responses/NotFoundError" "401": $ref: "#/components/responses/AuthenticationError" "/v1/beneficiaries": patch: summary: Update Beneficiary Active Status description: Update the active status of a beneficiary to enable or disable it tags: - Beneficiaries security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - beneficiary_id - active properties: beneficiary_id: type: string format: uuid example: "f653e109-6c62-4aa4-869c-418c874e0a6c" active: type: boolean example: true responses: "200": description: Beneficiary updated successfully content: application/json: schema: type: object properties: data: type: object properties: message: type: string example: "Beneficiary updated successfully" "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" "/v1/beneficiaries/{beneficiary_id}/documents": post: summary: Upload Beneficiary Documents description: Upload one or more documents for a specific beneficiary using multipart/form-data x-mint: content: | ## Allowed File Types - `PDF` - `JPG` / `JPEG` - `PNG` tags: - Beneficiaries security: - bearerAuth: [] parameters: - name: beneficiary_id in: path required: true schema: type: string format: uuid requestBody: required: true content: multipart/form-data: schema: type: object properties: doc1: type: string format: binary responses: "200": description: Documents uploaded successfully content: application/json: schema: type: object properties: data: type: object properties: files: type: array items: type: object additionalProperties: type: string example: - invoice1: "/wKbvfH5E_Invoice.pdf" - invoice2: "/XUOdWacK_Invoice.jpg" "/v2/transactions": get: summary: List Customer Transactions description: Returns a paginated list of transactions for a customer, optionally filtered by transaction type. x-mint: content: | ``` GET /v2/transactions?customer_id=765d498e-a267-4154-9d2f-9e411a0b50dd&type=CRYPTO_WITHDRAWAL¤t_page=1&per_page=10 ``` tags: - Transactions security: - bearerAuth: [] parameters: - name: customer_id in: query required: true schema: type: string description: The customer ID to fetch transactions for. example: "765d498e-a267-4154-9d2f-9e411a0b50dd" - name: type in: query required: false schema: type: string enum: - ONRAMP - OFFRAMP - CRYPTO_WITHDRAWAL - CRYPTO_DEPOSIT description: Filter transactions by type. example: CRYPTO_WITHDRAWAL - $ref: "#/components/parameters/CurrentPageParam" - name: per_page in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 10 description: Number of results per page. Must be between 1 and 100. example: 10 responses: "200": description: Transactions retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: type: object properties: current_page: type: integer example: 1 per_page: type: integer example: 10 total_page: type: integer example: 1 total: type: integer example: 2 transactions: type: array items: type: object properties: id: type: string format: uuid example: "8c92e9dd-6456-4aee-a441-1861144f1d8b" transaction_type: type: string enum: - ONRAMP - OFFRAMP - CRYPTO_WITHDRAWAL - CRYPTO_DEPOSIT example: CRYPTO_WITHDRAWAL customer_id: type: string format: uuid example: "1a8e3bdc-05c9-4486-bdef-93464d24c9af" beneficiary_id: type: string format: uuid example: "6af8d598-36a5-477d-9320-d7c5ba309107" hash: type: string description: On-chain transaction hash. example: "0xd2a3d65ce04c24c7af2b4ab86ac8c3ca525d010c600733bb062be74ee3899ec9" status: type: string example: COMPLETED source_currency: type: string example: USDC destination_currency: type: string example: USDC source_amount: type: number example: 5 destination_amount: type: number example: 4.98535 total_fee: type: number example: 0.014649 created_at: type: string format: date-time example: "2026-04-29T09:56:14.906031Z" updated_at: type: string format: date-time example: "2026-04-29T09:56:58.631047Z" example: data: pagination: current_page: 1 per_page: 10 total_page: 1 total: 2 transactions: - id: "8c92e9dd-6456-4aee-a441-1861144f1d8b" transaction_type: CRYPTO_WITHDRAWAL customer_id: "1a8e3bdc-05c9-4486-bdef-93464d24c9af" beneficiary_id: "6af8d598-36a5-477d-9320-d7c5ba309107" hash: "0xd2a3d65ce04c24c7af2b4ab86ac8c3ca525d010c600733bb062be74ee3899ec9" status: COMPLETED source_currency: USDC destination_currency: USDC source_amount: 5 destination_amount: 4.98535 total_fee: 0.014649 created_at: "2026-04-29T09:56:14.906031Z" updated_at: "2026-04-29T09:56:58.631047Z" - id: "2b7b52cd-20df-4a03-83a0-bc6d989fd6ad" transaction_type: CRYPTO_WITHDRAWAL customer_id: "1a8e3bdc-05c9-4486-bdef-93464d24c9af" beneficiary_id: "b6a1d0c1-c202-43a8-a8c9-4d09ac5eb8f2" hash: "0x03eebd78faba32e5e04b03fa0e163de557d77de7e4e25b935d992964fa0b05db" status: COMPLETED source_currency: USDC destination_currency: USDC source_amount: 5.1 destination_amount: 4.996173 total_fee: 0.103826 created_at: "2026-04-25T20:50:34.759464Z" updated_at: "2026-04-25T20:51:22.070885Z" "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" post: summary: Execute Quote description: Executes a quote returned from the Create Quote endpoint, initiating a crypto withdrawal to the beneficiary's external wallet. tags: - Transactions security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - quote_id properties: quote_id: type: string format: uuid description: The quote ID returned from the Create Quote endpoint. example: "9ba7d6db-ac78-4a41-acae-f787ee6b1f24" example: quote_id: "9ba7d6db-ac78-4a41-acae-f787ee6b1f24" responses: "200": description: Quote executed successfully content: application/json: schema: type: object properties: data: type: object properties: transaction_id: type: string format: uuid example: "8c92e9dd-6456-4aee-a441-1861144f1d8b" beneficiary_id: type: string format: uuid example: "6af8d598-36a5-477d-9320-d7c5ba309107" created_at: type: string format: date-time example: "2026-04-29T09:56:14.906031567Z" example: data: transaction_id: "8c92e9dd-6456-4aee-a441-1861144f1d8b" beneficiary_id: "6af8d598-36a5-477d-9320-d7c5ba309107" created_at: "2026-04-29T09:56:14.906031567Z" "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" "/v1/beneficiaries/{beneficiary_id}/transactions": get: summary: List Beneficiary Transactions description: Retrieve a paginated list of all transactions for a specific beneficiary tags: - Transactions security: - bearerAuth: [] parameters: - name: beneficiary_id in: path required: true schema: type: string format: uuid - name: page in: query required: false schema: type: integer default: 1 minimum: 1 - name: limit in: query required: false schema: type: integer default: 10 minimum: 1 maximum: 100 responses: "200": description: Transactions retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: type: object properties: current_page: type: integer example: 1 per_page: type: integer example: 10 total_page: type: integer example: 1 total: type: integer example: 1 transactions: type: array items: type: object properties: id: type: string format: uuid example: "f656afd1-7735-43b0-b630-04f0ff7158b3" transaction_type: type: string example: "OFFRAMP" beneficiary_id: type: string format: uuid hash: type: string nullable: true transaction_ref_id: type: string from_amount: type: number example: 3 payout_amount: type: number example: 4.35 processing_amount: type: number example: 3 status: type: string enum: - CREATED - PENDING - COMPLETED - FAILED example: "COMPLETED" fx_rate: type: number example: 1.45 developer_fee: type: number example: 0 developer_fee_percentage: type: number example: 0.45 developer_fee_fixed: type: number example: 1.25 from_currency: type: string example: "USDC" payout_currency: type: string example: "AUD" created_at: type: string format: date-time updated_at: type: string format: date-time "401": $ref: "#/components/responses/AuthenticationError" # ───────────────────────────────────────────────────────────────────────── # TRANSACTIONS # ───────────────────────────────────────────────────────────────────────── "/v1/transactions/transfer-payout": post: summary: Create a Transfer description: | 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 x-mint: content: | This endpoint can only be used with beneficiaries created with `auto_settlement` set to `false`. tags: - Transactions security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - beneficiary_id - reference_id - amount - remarks properties: beneficiary_id: type: string format: uuid example: "d6ae4ea6-0482-47ab-a895-02e50ea6358b" reference_id: type: string example: "REF-12345-ABC" amount: type: integer description: Amount in cents (multiply by 100). Minimum 500 cents required. example: 10000 minimum: 500 remarks: type: string example: "Monthly payment for services" attachments: type: array minItems: 1 items: type: object required: - remark - uri properties: remark: type: string example: "Invoice PDF DOC" uri: type: string example: "/XUOdWacK_Invoice.pdf" responses: "200": description: Transfer created successfully content: application/json: schema: type: object properties: data: type: object properties: transfer_id: type: string format: uuid example: "c78dee10-7c46-4ad5-8ac8-070e39d87ff1" reference_id: type: string example: "REF-12345-ABC" deposit_instruction: type: object properties: liquidation_address: type: string example: "0x203061afd3f3dd5f5756cec992d1d247f7668384" currency: type: string example: "USDC" rail: type: string example: "POLYGON" quotation: type: object properties: currency: type: string example: "EUR" to_amount: type: integer example: 108 developer_fee: type: integer example: 67 created_at: type: string format: date-time example: "2026-01-01T07:35:53Z" expire_at: type: string format: date-time example: "2026-01-01T07:45:53Z" "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" "/v1/transactions/transfer-payout/settle": post: summary: Settle a Transfer description: Settle a previously created transfer payout tags: - Transactions security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - transfer_id properties: transfer_id: type: string example: "9ac6872b-8904-4ea5-beb7-d5a936ffee10" responses: "200": description: Transfer settled successfully content: application/json: schema: type: object required: - data properties: data: type: object required: - transaction_id properties: transaction_id: type: string example: "9ac6872b-8904-4ea5-beb7-d5a936ffee10" "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" "/v1/batch/transactions/commit": post: summary: Execute Batch Transfer description: Execute multiple transfer payouts in a single batch operation. x-mint: content: | This endpoint can only be used with beneficiaries created with `auto_settlement` set to `false`. **Amount Specification:** - Each transaction must include exactly one of `source_amount` or `destination_amount` (not both) - `source_amount`: Minimum 500 cents (e.g. 500 = $5.00) - Only `PREFUNDED_BALANCE` transactions are eligible for refunds if they fail tags: - Transactions security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: array items: type: object required: - beneficiary_id - source_currency - deduct_from properties: beneficiary_id: type: string format: uuid example: "d6ae4ea6-0482-47ab-a895-02e50ea6358b" source_amount: type: number minimum: 500 description: Amount in cents (e.g. 530 = $5.30). Minimum 500 cents. example: 530 destination_amount: type: number example: 62000 source_currency: type: string example: "USD" deduct_from: type: string enum: - PREFUNDED_BALANCE - LIQUIDATION_ADDRESS remarks: type: string example: "Monthly salary payment" examples: With source amount: value: - beneficiary_id: "d6ae4ea6-0482-47ab-a895-02e50ea6358b" source_amount: 530 source_currency: "USD" deduct_from: "PREFUNDED_BALANCE" remarks: "Monthly salary payment" With destination amount: value: - beneficiary_id: "d6ae4ea6-0482-47ab-a895-02e50ea6358b" destination_amount: 62000 source_currency: "USD" deduct_from: "PREFUNDED_BALANCE" remarks: "Monthly salary payment" responses: "201": description: Batch created successfully content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid example: "3b1d73c0-0000-0000-0000-51aa2461f1" examples: With source amount: value: data: id: "3b1d73c0-0000-0000-0000-51aa2461f1" With destination amount: value: data: id: "3b1d73c0-0000-0000-0000-51aa2461f1" "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" "/v1/batch/transactions/commit/{batch_id}": get: summary: Fetch Batch Details description: Retrieve detailed information about a batch transaction including all items and their statuses tags: - Transactions security: - bearerAuth: [] parameters: - name: batch_id in: path required: true schema: type: string format: uuid example: "ad1a0a29-5a7f-4982-98cc-3f4416724660" responses: "200": description: Batch details retrieved successfully content: application/json: schema: type: object required: - data properties: data: type: object required: - batch_id - items properties: batch_id: type: string format: uuid example: "ad1a0a29-5a7f-4982-98cc-3f4416724660" items: type: array items: type: object properties: id: type: string format: uuid beneficiary_id: type: string format: uuid source_amount: type: number example: 456 source_currency: type: string enum: - USD deduct_from: type: string enum: - PREFUNDED_BALANCE - LIQUIDATION_ADDRESS remarks: type: string reason: type: string nullable: true status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - REFUNDED example: "PROCESSING" transaction_id: type: string format: uuid exchange_rate: type: number example: 135 destination_currency: type: string example: "BDT" destination_amount: type: number example: 261 developer_fee: type: object properties: fixed: type: number percentage: type: number total: type: number "401": $ref: "#/components/responses/AuthenticationError" "/v2/transactions/quote": post: summary: Create Quote description: Returns fee and receivable amount estimations for a crypto withdrawal from a Fin.com internal wallet to a customer's external crypto wallet. x-mint: content: | 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. tags: - Transactions security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - type - beneficiary_id - amount - source properties: type: type: string enum: - CRYPTO_WITHDRAWAL description: Transaction type for the quote. example: "CRYPTO_WITHDRAWAL" beneficiary_id: type: string format: uuid description: ID of the destination beneficiary. example: "6af8d598-36a5-477d-9320-d7c5ba309107" amount: type: number description: Amount to send in the source currency. example: 5 source: type: object required: - crypto_wallet_id properties: crypto_wallet_id: type: string format: uuid description: ID of the Fin.com internal crypto wallet to send from. example: "c92dfe1d-220e-4446-a5e4-cd7d46031ba5" example: type: "CRYPTO_WITHDRAWAL" beneficiary_id: "6af8d598-36a5-477d-9320-d7c5ba309107" amount: 5 source: crypto_wallet_id: "c92dfe1d-220e-4446-a5e4-cd7d46031ba5" responses: "200": description: Quote generated successfully content: application/json: schema: type: object properties: data: type: object properties: quote_id: type: string format: uuid description: Unique identifier for this quote. Use this to create a transaction. example: "9ba7d6db-ac78-4a41-acae-f787ee6b1f24" expire_at: type: string format: date-time description: Timestamp at which the quote expires. example: "2026-04-29T10:09:33.524075766Z" amount: type: number description: Source amount quoted. example: 5 destination_details: type: object properties: address: type: string example: "0xD2Ba7d0DaBd36498df5906fC7B054Fa9EfA9843E" currency: type: string example: "USDC" rail: type: string example: "POLYGON" quote_estimation: type: object properties: developer_fee_fixed: type: number example: 0.01 developer_fee_percentage: type: number example: 0.0005 network_fee: type: number example: 0.004149 total_fee: type: number example: 0.014649 receivable_amount: type: number example: 4.98535 ata_fee_applied: type: boolean example: false example: data: quote_id: "9ba7d6db-ac78-4a41-acae-f787ee6b1f24" expire_at: "2026-04-29T10:09:33.524075766Z" amount: 5 destination_details: address: "0xD2Ba7d0DaBd36498df5906fC7B054Fa9EfA9843E" currency: "USDC" rail: "POLYGON" quote_estimation: developer_fee_fixed: 0.01 developer_fee_percentage: 0.0005 network_fee: 0.004149 total_fee: 0.014649 receivable_amount: 4.98535 ata_fee_applied: false "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" "/v2/transactions/{transaction_id}": get: operationId: getTransactionByIdV2 summary: Fetch Transaction Details description: Returns full details for a transaction by ID, including status, amounts, fees, and settlement data. The populated fields vary based on the transaction type. tags: - Transactions security: - bearerAuth: [] parameters: - name: transaction_id in: path required: true schema: type: string format: uuid example: "8c92e9dd-6456-4aee-a441-1861144f1d8b" responses: "200": description: Transaction details retrieved successfully content: application/json: schema: type: object required: - data properties: data: oneOf: - title: Onramp type: object properties: id: type: string format: uuid example: "8fe1ca7c-4e6e-44c6-8706-87ac74c22554" transaction_type: type: string example: "ONRAMP" customer_id: type: string format: uuid nullable: true example: "80fd79d6-ad3d-4797-ad61-fc2dd1b7639d" beneficiary_id: type: string format: uuid nullable: true example: null hash: type: string nullable: true example: "0x3eef859d9c1745ba24209331d67e04f26e38ce45e48c85ed50f5e66a42cd57e9" status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - REFUNDED example: "COMPLETED" batch_info: type: object nullable: true properties: batch_id: type: string format: uuid batch_item_id: type: string format: uuid example: null fiat_details: type: object nullable: true properties: source_amount: type: number nullable: true example: 17 source_currency: type: string nullable: true example: "USD" destination_amount: type: number nullable: true example: 17 destination_currency: type: string nullable: true example: "USDC" fx_rate: type: number nullable: true example: 0 crypto_details: type: object nullable: true properties: source_amount: type: number nullable: true example: null source_currency: type: string nullable: true example: null source_rail: type: string nullable: true example: null source_address: type: string nullable: true example: null destination_amount: type: number nullable: true example: null destination_currency: type: string nullable: true example: null destination_rail: type: string nullable: true example: null destination_address: type: string nullable: true example: null tx_hash: type: string nullable: true example: null fees: type: object nullable: true properties: developer_fee: type: object properties: fixed: type: number example: 0 percentage: type: number example: 0 total_developer_fee: type: number example: 0 network_fee: type: number example: 0 conversion_fee: type: number example: 0 total_fee: type: number example: 0 created_at: type: string format: date-time example: "2026-03-02T15:36:39.167822Z" updated_at: type: string format: date-time example: "2026-03-02T15:36:39.167822Z" - title: Offramp type: object properties: id: type: string format: uuid example: "4835aa27-3c8d-4a68-b4c8-331ade5bb496" transaction_type: type: string example: "OFFRAMP" customer_id: type: string format: uuid nullable: true example: "1a8e3bdc-05c9-4486-bdef-93464d24c9af" beneficiary_id: type: string format: uuid nullable: true example: "8d7f5ac6-0188-47c9-83f2-36a4aca7b472" hash: type: string nullable: true example: null status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - REFUNDED example: "COMPLETED" batch_info: type: object nullable: true properties: batch_id: type: string format: uuid example: "c54b8cd6-efb4-4e36-92f0-2d289eefea52" batch_item_id: type: string format: uuid example: "32cf1b58-d026-494b-b6c6-d1e0af78060c" fiat_details: type: object nullable: true properties: source_amount: type: number nullable: true example: 5 source_currency: type: string nullable: true example: "USD" destination_amount: type: number nullable: true example: 526.48 destination_currency: type: string nullable: true example: "BDT" fx_rate: type: number nullable: true example: 117.19 crypto_details: type: object nullable: true properties: source_amount: type: number nullable: true example: null source_currency: type: string nullable: true example: null source_rail: type: string nullable: true example: null source_address: type: string nullable: true example: null destination_amount: type: number nullable: true example: null destination_currency: type: string nullable: true example: null destination_rail: type: string nullable: true example: null destination_address: type: string nullable: true example: null tx_hash: type: string nullable: true example: null fees: type: object nullable: true properties: developer_fee: type: object properties: fixed: type: number example: 0.5 percentage: type: number example: 0 total_developer_fee: type: number example: 0.51 network_fee: type: number example: 0 conversion_fee: type: number example: 0 total_fee: type: number example: 0.51 created_at: type: string format: date-time example: "2026-04-25T20:40:08.235667Z" updated_at: type: string format: date-time example: "2026-04-25T20:42:52.072478Z" - title: Crypto deposit type: object properties: id: type: string format: uuid example: "11e9dea6-7891-43dd-a582-281394edd288" transaction_type: type: string example: "CRYPTO_DEPOSIT" customer_id: type: string format: uuid nullable: true example: "1a8e3bdc-05c9-4486-bdef-93464d24c9af" beneficiary_id: type: string format: uuid nullable: true example: null hash: type: string nullable: true example: "31NgS1hCLaH6sitUSFRbXDF9tPhMrA5nqSNSSvvLPFRrScwDdDRUnE8FV8mLgxdx7TDhxdk7chKNhc1gbeFRNkAf" status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - REFUNDED example: "COMPLETED" batch_info: type: object nullable: true properties: batch_id: type: string format: uuid batch_item_id: type: string format: uuid example: null fiat_details: type: object nullable: true properties: source_amount: type: number nullable: true example: null source_currency: type: string nullable: true example: null destination_amount: type: number nullable: true example: null destination_currency: type: string nullable: true example: null fx_rate: type: number nullable: true example: null crypto_details: type: object nullable: true properties: source_amount: type: number nullable: true example: 15 source_currency: type: string nullable: true example: "USDC" source_rail: type: string nullable: true example: "SOLANA" source_address: type: string nullable: true example: "FEAp246mLPgWGVa12KG99GcRuptuCF3uTADp95pcy2cr" destination_amount: type: number nullable: true example: 15 destination_currency: type: string nullable: true example: "USDC" destination_rail: type: string nullable: true example: "SOLANA" destination_address: type: string nullable: true example: "BCSZEokfpVsSpUuuZJMScLiUpYjvvUmrrAJkNbrTTnng" tx_hash: type: string nullable: true example: "31NgS1hCLaH6sitUSFRbXDF9tPhMrA5nqSNSSvvLPFRrScwDdDRUnE8FV8mLgxdx7TDhxdk7chKNhc1gbeFRNkAf" fees: type: object nullable: true properties: developer_fee: type: object properties: fixed: type: number example: 0 percentage: type: number example: 0 total_developer_fee: type: number example: 0 network_fee: type: number example: 0 conversion_fee: type: number example: 0 total_fee: type: number example: 0 created_at: type: string format: date-time example: "2026-04-25T19:12:07.804074Z" updated_at: type: string format: date-time example: "2026-04-25T19:12:07.804074Z" - title: Crypto withdrawal type: object properties: id: type: string format: uuid example: "8c92e9dd-6456-4aee-a441-1861144f1d8b" transaction_type: type: string example: "CRYPTO_WITHDRAWAL" customer_id: type: string format: uuid nullable: true example: "1a8e3bdc-05c9-4486-bdef-93464d24c9af" beneficiary_id: type: string format: uuid nullable: true example: "6af8d598-36a5-477d-9320-d7c5ba309107" hash: type: string nullable: true example: "0xd2a3d65ce04c24c7af2b4ab86ac8c3ca525d010c600733bb062be74ee3899ec9" status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - REFUNDED example: "COMPLETED" batch_info: type: object nullable: true properties: batch_id: type: string format: uuid batch_item_id: type: string format: uuid example: null fiat_details: type: object nullable: true properties: source_amount: type: number nullable: true example: null source_currency: type: string nullable: true example: null destination_amount: type: number nullable: true example: null destination_currency: type: string nullable: true example: null fx_rate: type: number nullable: true example: null crypto_details: type: object nullable: true properties: source_amount: type: number nullable: true example: 5 source_currency: type: string nullable: true example: "USDC" source_rail: type: string nullable: true example: "POLYGON" source_address: type: string nullable: true example: "0xc42a5f7083c7e8f1d9820c7660867277289cd998" destination_amount: type: number nullable: true example: 4.98535 destination_currency: type: string nullable: true example: "USDC" destination_rail: type: string nullable: true example: "POLYGON" destination_address: type: string nullable: true example: "0xD2Ba7d0DaBd36498df5906fC7B054Fa9EfA9843E" tx_hash: type: string nullable: true example: "0xd2a3d65ce04c24c7af2b4ab86ac8c3ca525d010c600733bb062be74ee3899ec9" fees: type: object nullable: true properties: developer_fee: type: object properties: fixed: type: number example: 0.01 percentage: type: number example: 0.0005 total_developer_fee: type: number example: 0.0105 network_fee: type: number example: 0.004149 conversion_fee: type: number example: 0 total_fee: type: number example: 0.014649 created_at: type: string format: date-time example: "2026-04-29T09:56:14.906031Z" updated_at: type: string format: date-time example: "2026-04-29T09:56:58.631047Z" examples: Onramp: summary: Onramp transaction value: data: id: "8fe1ca7c-4e6e-44c6-8706-87ac74c22554" transaction_type: ONRAMP customer_id: "80fd79d6-ad3d-4797-ad61-fc2dd1b7639d" beneficiary_id: null hash: "0x3eef859d9c1745ba24209331d67e04f26e38ce45e48c85ed50f5e66a42cd57e9" status: COMPLETED created_at: "2026-03-02T15:36:39.167822Z" updated_at: "2026-03-02T15:36:39.167822Z" batch_info: null fiat_details: source_amount: 17 source_currency: USD destination_amount: 17 destination_currency: USDC fx_rate: 0 crypto_details: source_amount: null source_currency: null source_rail: null source_address: null destination_amount: null destination_currency: null destination_rail: null destination_address: null tx_hash: null fees: developer_fee: fixed: 0 percentage: 0 total_developer_fee: 0 network_fee: 0 conversion_fee: 0 total_fee: 0 Offramp: summary: Offramp transaction value: data: id: "4835aa27-3c8d-4a68-b4c8-331ade5bb496" transaction_type: OFFRAMP customer_id: "1a8e3bdc-05c9-4486-bdef-93464d24c9af" beneficiary_id: "8d7f5ac6-0188-47c9-83f2-36a4aca7b472" hash: null status: COMPLETED created_at: "2026-04-25T20:40:08.235667Z" updated_at: "2026-04-25T20:42:52.072478Z" batch_info: batch_id: "c54b8cd6-efb4-4e36-92f0-2d289eefea52" batch_item_id: "32cf1b58-d026-494b-b6c6-d1e0af78060c" fiat_details: source_amount: 5 source_currency: USD destination_amount: 526.48 destination_currency: BDT fx_rate: 117.19 crypto_details: source_amount: null source_currency: null source_rail: null source_address: null destination_amount: null destination_currency: null destination_rail: null destination_address: null tx_hash: null fees: developer_fee: fixed: 0.5 percentage: 0 total_developer_fee: 0.51 network_fee: 0 conversion_fee: 0 total_fee: 0.51 Crypto deposit: summary: Crypto deposit transaction value: data: id: "11e9dea6-7891-43dd-a582-281394edd288" transaction_type: CRYPTO_DEPOSIT customer_id: "1a8e3bdc-05c9-4486-bdef-93464d24c9af" beneficiary_id: null hash: "31NgS1hCLaH6sitUSFRbXDF9tPhMrA5nqSNSSvvLPFRrScwDdDRUnE8FV8mLgxdx7TDhxdk7chKNhc1gbeFRNkAf" status: COMPLETED created_at: "2026-04-25T19:12:07.804074Z" updated_at: "2026-04-25T19:12:07.804074Z" batch_info: null fiat_details: source_amount: null source_currency: null destination_amount: null destination_currency: null fx_rate: null crypto_details: source_amount: 15 source_currency: USDC source_rail: SOLANA source_address: "FEAp246mLPgWGVa12KG99GcRuptuCF3uTADp95pcy2cr" destination_amount: 15 destination_currency: USDC destination_rail: SOLANA destination_address: "BCSZEokfpVsSpUuuZJMScLiUpYjvvUmrrAJkNbrTTnng" tx_hash: "31NgS1hCLaH6sitUSFRbXDF9tPhMrA5nqSNSSvvLPFRrScwDdDRUnE8FV8mLgxdx7TDhxdk7chKNhc1gbeFRNkAf" fees: developer_fee: fixed: 0 percentage: 0 total_developer_fee: 0 network_fee: 0 conversion_fee: 0 total_fee: 0 Crypto withdrawal: summary: Crypto withdrawal transaction value: data: id: "8c92e9dd-6456-4aee-a441-1861144f1d8b" transaction_type: CRYPTO_WITHDRAWAL customer_id: "1a8e3bdc-05c9-4486-bdef-93464d24c9af" beneficiary_id: "6af8d598-36a5-477d-9320-d7c5ba309107" hash: "0xd2a3d65ce04c24c7af2b4ab86ac8c3ca525d010c600733bb062be74ee3899ec9" status: COMPLETED created_at: "2026-04-29T09:56:14.906031Z" updated_at: "2026-04-29T09:56:58.631047Z" batch_info: null fiat_details: source_amount: null source_currency: null destination_amount: null destination_currency: null fx_rate: null crypto_details: source_amount: 5 source_currency: USDC source_rail: POLYGON source_address: "0xc42a5f7083c7e8f1d9820c7660867277289cd998" destination_amount: 4.98535 destination_currency: USDC destination_rail: POLYGON destination_address: "0xD2Ba7d0DaBd36498df5906fC7B054Fa9EfA9843E" tx_hash: "0xd2a3d65ce04c24c7af2b4ab86ac8c3ca525d010c600733bb062be74ee3899ec9" fees: developer_fee: fixed: 0.01 percentage: 0.0005 total_developer_fee: 0.0105 network_fee: 0.004149 conversion_fee: 0 total_fee: 0.014649 "401": $ref: "#/components/responses/AuthenticationError" "404": $ref: "#/components/responses/NotFoundError" "/v1/transit/payment": post: summary: Create a Payment description: Create a new payment order for a supported integration type (ByBit, Kraken, OKX, Pass Through) x-mint: content: | Creates a payment order for the specified integration type with automatic settlement to a destination 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, the original status code will be forwarded. tags: - Crypto Orchestration security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - integration_type - order_info properties: integration_type: type: string enum: - BYBIT - PASS_THROUGH - KRAKEN - OKX description: Integration provider type. example: BYBIT order_info: type: object required: - merchant_trade_no - currency - currency_type - success_url - failed_url - payment_type - goods - env properties: merchant_name: type: string example: "PayPal" client_id: type: string example: "client_001" payment_type: type: string enum: [E_COMMERCE] example: E_COMMERCE merchant_trade_no: type: string format: uuid example: "841e4ba2-1234-5678-9abc-a2a45de7bd00" order_amount: type: string description: Conditionally required when quote_id is not provided. example: "100.00" quote_id: type: string description: Conditionally required when order_amount is not provided. example: "FIN_PROVIDED_QUOTE_ID" currency: type: string enum: [USDC, USDT, BTC, ETH] example: USDT rail: type: string description: Blockchain rail for the destination. Required for OKX and Kraken. enum: [SOLANA, BITCOIN, ETHEREUM, TRON, BASE] example: SOLANA currency_type: type: string enum: [crypto] example: crypto redirection_url: type: string format: uri description: Optional redirect URL after payment completion. Used for OKX. example: "https://example.com/redirect" remarks: type: string description: Optional order remarks. example: "" success_url: type: string format: uri maxLength: 256 example: "https://example.com/success" failed_url: type: string format: uri maxLength: 256 example: "https://example.com/failed" order_expire_time: type: integer minimum: 600 maximum: 3600 default: 3600 example: 3600 customer: type: object required: - uid - external_user_id - user_name - register_time - kyc_country properties: uid: type: string example: "user_123" external_user_id: type: string example: "ext_user_001" user_name: type: string example: "John Li" register_time: type: integer example: 1739178959 kyc_country: type: string example: "AUS" goods: type: array minItems: 1 items: type: object required: - shopping_name - mcc_code - goods_name properties: shopping_name: type: string example: "test good1" mcc_code: type: string example: "1520" goods_name: type: string example: "test1" goods_detail: type: string example: "First product" env: type: object required: - terminal_type - device - browser_version - ip properties: terminal_type: type: string enum: [APP, WEB, WAP, MINIAPP, OTHERS] example: APP device: type: string example: "iPhone 15" browser_version: type: string example: "iOS 17.0 Safari" ip: type: string format: ipv4 example: "192.168.0.1" risk_info: type: object required: - terminal_type properties: terminal_type: type: string enum: [APP, WEB, WAP, MINIAPP, OTHERS] example: APP fin: type: object description: Required when quote_id is not provided. required: - settlement_config properties: settlement_config: type: object required: - settlement_via - destination_details properties: settlement_via: type: string enum: [ONE_TO_ONE, MARKET_ORDER, FEE_RETENTION] example: MARKET_ORDER destination_details: type: object required: - wallet_address - currency - rail properties: wallet_address: type: string currency: type: string enum: [USDC, USDT, BTC, ETH, PYUSD] example: USDC rail: type: string enum: [SOLANA, BITCOIN, ETHEREUM, BASE, TRON] example: SOLANA developer_fee: type: object nullable: true description: Developer fee configuration. Nullable. Both fields default to 0. Used as a sibling of settlement_config for OKX. properties: fixed: type: string description: Fixed fee in USD per transaction. Defaults to 0. example: "0.15" percentage: type: string description: Percentage fee applied to order_amount. Defaults to 0. example: "2.5" examples: createPaymentWithAmount: summary: Create payment with order_amount (no quote_id) value: integration_type: BYBIT order_info: merchant_name: "PayPal" client_id: "client_001" payment_type: E_COMMERCE merchant_trade_no: "841e4ba2-1234-5678-9abc-a2a45de7bd00" order_amount: "100.00" currency: USDT currency_type: crypto success_url: "https://example.com/success" failed_url: "https://example.com/failed" 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: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: USDC rail: SOLANA createPaymentWithQuoteId: summary: Create payment with quote_id (no order_amount or fin) value: integration_type: BYBIT order_info: payment_type: E_COMMERCE merchant_trade_no: "941e4ba2-5678-1234-9abc-b3b56ef8ce11" quote_id: "FIN_PROVIDED_QUOTE_ID" currency: USDT currency_type: crypto success_url: "https://example.com/success" failed_url: "https://example.com/failed" goods: - shopping_name: "test good1" mcc_code: "1520" goods_name: "test1" env: terminal_type: WEB device: "Chrome Desktop" browser_version: "Chrome 121.0" ip: "10.0.0.1" createOKXPaymentWithAmount: summary: "OKX: Create payment with order_amount (no quote_id)" value: integration_type: OKX order_info: merchant_name: "MESH Shop" merchant_trade_no: "841e4ba2-1234-5678-9abc-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: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: USDC rail: SOLANA developer_fee: fixed: "0.15" percentage: "2.5" createOKXPaymentWithQuoteId: summary: "OKX: Create payment with quote_id (no order_amount or fin)" value: integration_type: OKX order_info: merchant_trade_no: "841e4ba2-1234-5678-9abc-a2a45de7bd00" quote_id: "FIN_PROVIDED_QUOTE_ID" currency: USDC rail: SOLANA currency_type: crypto responses: "200": description: Payment created successfully content: application/json: schema: type: object properties: data: type: object properties: payment_id: type: string format: uuid example: "FIN_PROVIDED_UUID" integration_type: type: string example: BYBIT provider_response: type: object description: Provider-specific response fields. Shape varies by integration_type. properties: pay_id: type: string description: Provider-generated payment ID. example: "01JN6AZVEMAC8H9SED6JES3QH8" terminal_type: type: string description: Terminal type used for the payment. Present for ByBit orders. nullable: true example: APP expire_time: type: integer description: Unix timestamp when the payment link expires. example: 1740751953 create_time: type: integer description: Unix timestamp when the order was created. example: 1740748353 checkout_link: type: string description: Payment checkout link. For OKX orders this is the QR-code deeplink. example: "" qr_content: type: string description: Base64-encoded QR code image. Present for ByBit orders. nullable: true example: "data:image/png;base64,/9j/2...f/Z" "401": $ref: "#/components/responses/AuthenticationError" "422": description: Validation error detected by Fin content: application/json: schema: type: object properties: error: type: object properties: code: type: integer example: 422 type: type: string enum: [FIN_ERROR] example: FIN_ERROR message: type: string example: "One or more fields are invalid" details: type: array nullable: true items: type: object properties: field: type: string message: type: string "428": description: Error thrown from provider (forwards partner's HTTP status code) content: application/json: schema: type: object properties: error: type: object properties: code: type: integer example: 500104 type: type: string enum: [PROVIDER_ERROR] example: PROVIDER_ERROR message: type: string example: "Balance not Available" details: type: array nullable: true items: type: object "/v1/transit/payment/{payment_id}": get: summary: Fetch a Payment description: Retrieve payment details by payment ID x-mint: content: | ## 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`. tags: - Crypto Orchestration security: - bearerAuth: [] parameters: - name: payment_id in: path required: true schema: type: string format: uuid description: The unique payment identifier returned from Create Payment example: "FIN_PROVIDED_UUID" responses: "200": description: Payment details retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: payment_id: type: string format: uuid example: "FIN_PROVIDED_UUID" integration_type: type: string example: "BYBIT" quote_id: type: string format: uuid example: "FIN_PROVIDED_UUID" status: type: string enum: - PAY_INIT - PAY_PROCESS - PAY_SUCCESS - PAY_FAILED - PAY_TIMEOUT - PAY_CANCEL - SETTLEMENT_INIT - SETTLEMENT_HOLD - SETTLEMENT_SUCCESS - SETTLEMENT_FAILED example: "PAY_INIT" create_time: type: integer example: 1740748353 payment_info: type: object properties: pay_id: type: string example: "01JN6AZVEMAC8H9SED6JES3QH8" merchant_trade_no: type: string example: "841e4ba2-...-a2a45de7bd00" amount: type: string example: "100" status: type: string enum: [PAY_INIT, PAY_PROCESS, PAY_SUCCESS, PAY_FAILED, PAY_TIMEOUT, PAY_CANCEL] example: "PAY_INIT" currency: type: string example: "USDT" currency_type: type: string example: "crypto" expire_time: type: integer example: 1740751953 payment_time: type: integer description: 0 until PAY_SUCCESS example: 0 settlement_info: type: object nullable: true description: null until PAY_SUCCESS properties: settlement_via: type: string enum: [ONE_TO_ONE, MARKET_ORDER, FEE_RETENTION] example: "MARKET_ORDER" wallet_address: type: string currency: type: string enum: [USDC, USDT, BTC, ETH] example: "USDC" rail: type: string enum: [SOLANA, BITCOIN, ETHEREUM, BASE] example: "SOLANA" amount: type: string example: "100" trx_hash: type: string example: "0x580..." settle_time: type: integer example: 1740748353 status: type: string enum: [SETTLEMENT_INIT, SETTLEMENT_HOLD, SETTLEMENT_SUCCESS, SETTLEMENT_FAILED] example: "SETTLEMENT_SUCCESS" retry_attempts: type: integer minimum: 0 maximum: 3 example: 0 examples: paymentInitiated: summary: Payment in initial state value: data: payment_id: "FIN_PROVIDED_UUID" integration_type: "BYBIT" status: "PAY_INIT" create_time: 1740748353 payment_info: pay_id: "01JN6AZVEMAC8H9SED6JES3QH8" merchant_trade_no: "841e4ba2-...-a2a45de7bd00" amount: "100" status: "PAY_INIT" currency: "USDT" currency_type: "crypto" expire_time: 1740751953 payment_time: 0 settlement_info: null paymentSettled: summary: Payment successfully settled value: data: payment_id: "FIN_PROVIDED_UUID" integration_type: "BYBIT" status: "SETTLEMENT_SUCCESS" create_time: 1740748353 payment_info: pay_id: "01JN6AZVEMAC8H9SED6JES3QH8" merchant_trade_no: "841e4ba2-...-a2a45de7bd00" amount: "100" status: "PAY_SUCCESS" currency: "USDT" currency_type: "crypto" expire_time: 1740751953 payment_time: 1740748353 settlement_info: settlement_via: "MARKET_ORDER" wallet_address: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: "USDC" rail: "SOLANA" amount: "100" trx_hash: "0x580..." settle_time: 1740748353 status: "SETTLEMENT_SUCCESS" retry_attempts: 0 "401": $ref: "#/components/responses/AuthenticationError" "403": description: Payment ID doesn't belong to you content: application/json: schema: type: object properties: error: type: object properties: code: type: integer example: 403 type: type: string enum: [FIN_ERROR] example: "FIN_ERROR" message: type: string example: "Payment ID doesn't belong to you" "404": description: Payment ID not found content: application/json: schema: type: object properties: error: type: object properties: code: type: integer example: 404 type: type: string enum: [FIN_ERROR] example: "FIN_ERROR" message: type: string example: "Payment ID not found" "/v1/transit/quote": post: summary: Create a crypto payment quote description: Generate a fee estimation quote for a transit payment x-mint: content: | The quote has a limited validity period indicated by `expire_at`. Request a new quote if it has expired. See the **Quote Request by Integration** tabs on this page for per-integration request examples (Bybit, Kraken, Pass Through). tags: - Crypto Orchestration security: - bearerAuth: [] requestBody: required: true content: application/json: schema: oneOf: - title: Bybit type: object required: - order_amount - integration_type - settlement_config properties: order_amount: type: string description: Order amount in USD. example: "100.00" integration_type: type: string enum: [BYBIT] example: "BYBIT" settlement_config: type: object required: - settlement_via - rebalance_fee - destination_details properties: settlement_via: type: string enum: [MARKET_ORDER, ONE_TO_ONE] example: "MARKET_ORDER" rebalance_fee: type: boolean description: "When true, fees are absorbed and total_order_amount equals order_amount. When false, settlement_amount equals order_amount minus total_fee." example: true destination_details: type: object required: - wallet_address - currency - rail properties: wallet_address: type: string description: Destination wallet address. example: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: type: string enum: [USDC, PYUSD] description: "Destination currency. See [supported chains and currencies](https://developer.fin.com/crypto-orchestration/integration-types/bybit#chains-rails-and-constraints) for valid currency and rail combinations." example: "USDC" rail: type: string enum: [SOLANA, ETHEREUM, BASE] example: "SOLANA" - title: Kraken type: object required: - order_amount - integration_type - settlement_config properties: order_amount: type: string description: Order amount in USD. example: "100.00" integration_type: type: string enum: [KRAKEN] example: "KRAKEN" settlement_config: type: object required: - settlement_via - rebalance_fee - destination_details properties: settlement_via: type: string enum: [ONE_TO_ONE] example: "ONE_TO_ONE" rebalance_fee: type: boolean description: "When true, fees are absorbed and total_order_amount equals order_amount. When false, settlement_amount equals order_amount minus total_fee." example: false destination_details: type: object required: - wallet_address - currency - rail properties: wallet_address: type: string description: Destination wallet address. example: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: type: string enum: [USDC, PYUSD] example: "PYUSD" rail: type: string enum: [SOLANA] example: "SOLANA" developer_fee: type: object nullable: true description: "Developer fee configuration. Nullable. Both fields default to 0." properties: fixed: type: string description: Fixed fee in USD per transaction. Defaults to 0. example: "0.15" percentage: type: string description: Percentage fee applied to order_amount. Defaults to 0. example: "2.5" - title: Pass Through type: object required: - order_amount - integration_type - settlement_config properties: order_amount: type: string description: Order amount in USD. example: "100.00" integration_type: type: string enum: [PASS_THROUGH] example: "PASS_THROUGH" settlement_config: type: object required: - settlement_via - rebalance_fee - destination_details properties: settlement_via: type: string enum: [FEE_RETENTION] example: "FEE_RETENTION" rebalance_fee: type: boolean description: Only false is supported for PASS_THROUGH. Passing true returns an error. example: false destination_details: type: object required: - wallet_address - currency - rail properties: wallet_address: type: string description: Destination wallet address. example: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" currency: type: string enum: [BTC, ETH, USDT, USDC] example: "BTC" rail: type: string enum: [BITCOIN, ETHEREUM, TRON, SOLANA] example: "BITCOIN" developer_fee: type: object nullable: true description: "Developer fee configuration. Nullable. Both fields default to 0." properties: fixed: type: string description: Fixed fee in USD per transaction. Defaults to 0. example: "0.15" percentage: type: string description: Percentage fee applied to order_amount. Defaults to 0. example: "2.5" - title: OKX type: object required: - order_amount - integration_type - settlement_config properties: order_amount: type: string description: Order amount in USD. example: "100.00" integration_type: type: string enum: [OKX] example: "OKX" settlement_config: type: object required: - settlement_via - rebalance_fee - destination_details properties: settlement_via: type: string enum: [ONE_TO_ONE] example: "ONE_TO_ONE" rebalance_fee: type: boolean description: "When true, fees are absorbed and total_order_amount equals order_amount. When false, settlement_amount equals order_amount minus total_fee." example: false destination_details: type: object required: - wallet_address - currency - rail properties: wallet_address: type: string description: Destination wallet address. example: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: type: string enum: [USDC] description: USDC only for OKX (milestone-1). example: "USDC" rail: type: string enum: [SOLANA] description: SOLANA only for OKX (milestone-1). example: "SOLANA" developer_fee: type: object nullable: true description: "Developer fee configuration. Nullable. Both fields default to 0." properties: fixed: type: string description: Fixed fee in USD per transaction. Defaults to 0. example: "0.15" percentage: type: string description: Percentage fee applied to order_amount. Defaults to 0. example: "2.5" examples: Bybit: summary: "Bybit" value: order_amount: "100.00" integration_type: "BYBIT" settlement_config: settlement_via: "MARKET_ORDER" rebalance_fee: true destination_details: wallet_address: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: "USDC" rail: "SOLANA" Kraken: summary: "Kraken" value: order_amount: "100.00" integration_type: "KRAKEN" settlement_config: settlement_via: "ONE_TO_ONE" rebalance_fee: false destination_details: wallet_address: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: "PYUSD" rail: "SOLANA" developer_fee: fixed: "0.15" percentage: "2.5" "Pass Through": summary: "Pass Through" value: order_amount: "100.00" integration_type: "PASS_THROUGH" settlement_config: settlement_via: "FEE_RETENTION" rebalance_fee: false destination_details: wallet_address: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" currency: "BTC" rail: "BITCOIN" developer_fee: fixed: "0.15" percentage: "2.5" OKX: summary: "OKX" value: order_amount: "100.00" integration_type: "OKX" settlement_config: settlement_via: "ONE_TO_ONE" rebalance_fee: false destination_details: wallet_address: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: "USDC" rail: "SOLANA" developer_fee: fixed: "0.15" percentage: "2.5" responses: "200": description: Quote created successfully content: application/json: schema: oneOf: - title: Bybit type: object properties: data: type: object properties: quote_id: type: string format: uuid description: Unique quote identifier. Pass as quote_id when creating a payment to lock in the quoted fees. example: "4081fa09-7761-42b6-8f66-24beae1a2ca5" expire_at: type: integer description: Unix timestamp when this quote expires. Request a new quote after expiry. example: 1770916749 order_amount: type: string description: Order amount provided in the request, in USD. example: "100.00" integration_type: type: string example: "BYBIT" settlement_config: type: object properties: settlement_via: type: string example: "MARKET_ORDER" rebalance_fee: type: boolean example: true destination_details: type: object properties: wallet_address: type: string example: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: type: string example: "USDC" rail: type: string example: "SOLANA" quote_estimation: type: object properties: payment_fee: type: string description: Fee charged by the exchange for processing the payment. example: "0.00" conversion_fee: type: string description: Fee charged for currency conversion where applicable. example: "0.00" withdrawal_fee: type: string description: Fee charged for withdrawing funds from the exchange. example: "0.00" gas_fee: type: string description: Blockchain network gas fee for the on-chain settlement transaction. example: "0.50" total_fee: type: string description: "Total of all fees: gas_fee + payment_fee + conversion_fee + withdrawal_fee." example: "0.50" total_order_amount: type: string description: "Gross amount charged to the payer. When rebalance_fee is true, equals order_amount (fees absorbed into the order)." example: "100.00" ata_fee_applied: type: boolean description: Whether a Solana Associated Token Account creation fee was applied to gas_fee. example: false - title: Kraken type: object properties: data: type: object properties: quote_id: type: string format: uuid description: Unique quote identifier. Pass as quote_id when creating a payment to lock in the quoted fees. example: "76e8bcc0-a6b4-41f7-b3d2-76cfbe910fe3" expire_at: type: integer description: Unix timestamp when this quote expires. Request a new quote after expiry. example: 1770916749 order_amount: type: string description: Order amount provided in the request, in USD. example: "100.00" integration_type: type: string example: "KRAKEN" settlement_config: type: object properties: settlement_via: type: string example: "ONE_TO_ONE" rebalance_fee: type: boolean example: false destination_details: type: object properties: wallet_address: type: string example: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: type: string example: "PYUSD" rail: type: string example: "SOLANA" quote_estimation: type: object properties: payment_fee: type: string description: Fee charged by the exchange for processing the payment. example: "0.00" conversion_fee: type: string description: Fee charged for currency conversion where applicable. example: "0.00" withdrawal_fee: type: string description: Fee charged for withdrawing funds from the exchange. example: "0.00" gas_fee: type: string description: Blockchain network gas fee for the on-chain settlement transaction. example: "0.50" total_developer_fee: type: string description: "Sum of developer-configured fees: fixed fee plus percentage of order_amount." example: "2.65" total_fee: type: string description: "Total of all fees: gas_fee + payment_fee + conversion_fee + withdrawal_fee + total_developer_fee." example: "3.15" total_order_amount: type: string description: "Gross amount charged to the payer. When rebalance_fee is false, settlement_amount equals order_amount minus total_fee." example: "100.00" ata_fee_applied: type: boolean description: Whether a Solana Associated Token Account creation fee was applied to gas_fee. example: false - title: Pass Through type: object properties: data: type: object properties: quote_id: type: string format: uuid description: Unique quote identifier. Pass as quote_id when creating a payment to lock in the quoted fees. example: "5831ce86-cd88-4aba-b1fd-32dcf6e1a030" expire_at: type: integer description: Unix timestamp when this quote expires. Request a new quote after expiry. example: 1770916749 order_amount: type: string description: Order amount provided in the request, in USD. example: "100.00" integration_type: type: string example: "PASS_THROUGH" settlement_config: type: object properties: settlement_via: type: string example: "FEE_RETENTION" rebalance_fee: type: boolean example: false destination_details: type: object properties: wallet_address: type: string example: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" currency: type: string example: "BTC" rail: type: string example: "BITCOIN" quote_estimation: type: object properties: payment_fee: type: string description: Fee charged by the exchange for processing the payment. example: "0.00" conversion_fee: type: string description: Fee charged for currency conversion where applicable. example: "0.00" withdrawal_fee: type: string description: Fee charged for withdrawing funds from the exchange. example: "0.00" gas_fee: type: string description: Blockchain network gas fee for the on-chain settlement transaction. example: "0.50" total_developer_fee: type: string description: "Sum of developer-configured fees: fixed fee plus percentage of order_amount." example: "2.65" total_fee: type: string description: "Total of all fees: gas_fee + payment_fee + conversion_fee + withdrawal_fee + total_developer_fee." example: "3.15" total_order_amount: type: string description: "Gross amount charged to the payer. When rebalance_fee is false, settlement_amount equals order_amount minus total_fee." example: "100.00" ata_fee_applied: type: boolean description: Whether a Solana Associated Token Account creation fee was applied to gas_fee. example: false - title: OKX type: object properties: data: type: object properties: quote_id: type: string format: uuid description: Unique quote identifier. Pass as quote_id when creating a payment to lock in the quoted fees. example: "e9d4c7b2-1a3f-4e85-90f2-c6d8a1b3e4f7" expire_at: type: integer description: Unix timestamp when this quote expires. Request a new quote after expiry. example: 1770916749 order_amount: type: string description: Order amount provided in the request, in USD. example: "100.00" integration_type: type: string example: "OKX" settlement_config: type: object properties: settlement_via: type: string example: "ONE_TO_ONE" rebalance_fee: type: boolean example: false destination_details: type: object properties: wallet_address: type: string example: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: type: string example: "USDC" rail: type: string example: "SOLANA" quote_estimation: type: object properties: payment_fee: type: string description: Fee charged by the exchange for processing the payment. example: "0.00" conversion_fee: type: string description: Fee charged for currency conversion where applicable. example: "0.00" withdrawal_fee: type: string description: Fee charged for withdrawing funds from the exchange. example: "0.00" gas_fee: type: string description: Blockchain network gas fee for the on-chain settlement transaction. example: "0.50" total_developer_fee: type: string description: "Sum of developer-configured fees: fixed fee plus percentage of order_amount." example: "2.65" total_fee: type: string description: "Total of all fees: gas_fee + payment_fee + conversion_fee + withdrawal_fee + total_developer_fee." example: "3.15" total_order_amount: type: string description: "Gross amount charged to the payer. When rebalance_fee is false, settlement_amount equals order_amount minus total_fee." example: "106.30" ata_fee_applied: type: boolean description: Whether a Solana Associated Token Account creation fee was applied to gas_fee. example: false examples: Bybit: summary: "Bybit" value: data: quote_id: "4081fa09-7761-42b6-8f66-24beae1a2ca5" expire_at: 1770916749 order_amount: "100.00" integration_type: "BYBIT" settlement_config: settlement_via: "MARKET_ORDER" rebalance_fee: true destination_details: wallet_address: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: "USDC" rail: "SOLANA" quote_estimation: payment_fee: "0.00" conversion_fee: "0.00" withdrawal_fee: "0.00" gas_fee: "0.50" total_fee: "0.50" total_order_amount: "100.00" ata_fee_applied: false "Pass Through": summary: "Pass Through" value: data: quote_id: "5831ce86-cd88-4aba-b1fd-32dcf6e1a030" expire_at: 1770916749 order_amount: "100.00" integration_type: "PASS_THROUGH" settlement_config: settlement_via: "FEE_RETENTION" rebalance_fee: false destination_details: wallet_address: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" currency: "BTC" rail: "BITCOIN" quote_estimation: payment_fee: "0.00" conversion_fee: "0.00" withdrawal_fee: "0.00" gas_fee: "0.50" total_developer_fee: "2.65" total_fee: "3.15" total_order_amount: "100.00" ata_fee_applied: false Kraken: summary: "Kraken" value: data: quote_id: "76e8bcc0-a6b4-41f7-b3d2-76cfbe910fe3" expire_at: 1770916749 order_amount: "100.00" integration_type: "KRAKEN" settlement_config: settlement_via: "ONE_TO_ONE" rebalance_fee: false destination_details: wallet_address: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: "PYUSD" rail: "SOLANA" quote_estimation: payment_fee: "0.00" conversion_fee: "0.00" withdrawal_fee: "0.00" gas_fee: "0.50" total_developer_fee: "2.65" total_fee: "3.15" total_order_amount: "100.00" ata_fee_applied: false OKX: summary: "OKX" value: data: quote_id: "e9d4c7b2-1a3f-4e85-90f2-c6d8a1b3e4f7" expire_at: 1770916749 order_amount: "100.00" integration_type: "OKX" settlement_config: settlement_via: "ONE_TO_ONE" rebalance_fee: false destination_details: wallet_address: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: "USDC" rail: "SOLANA" quote_estimation: payment_fee: "0.00" conversion_fee: "0.00" withdrawal_fee: "0.00" gas_fee: "0.50" total_developer_fee: "2.65" total_fee: "3.15" total_order_amount: "106.30" ata_fee_applied: false "401": $ref: "#/components/responses/AuthenticationError" "/v1/wallet/balances": get: summary: Fetch Prefunded Balance description: Retrieve the current prefunded wallet balances x-mint: content: | To enable prefundable wallets, you must first reach out to the fin.com team to enable wallets for you for both **sandbox** and **production** tags: - Balances security: - bearerAuth: [] responses: "200": description: Wallet balances retrieved successfully content: application/json: schema: type: object properties: data: type: array items: type: object properties: currency: type: string enum: - USD example: "USD" amount: type: integer description: Amount in cents (multiplied by 100) example: 150000 "401": $ref: "#/components/responses/AuthenticationError" # ───────────────────────────────────────────────────────────────────────── # VIRTUAL ACCOUNTS V2 (new, added above V1) # ───────────────────────────────────────────────────────────────────────── "/v3/customers/{customer_id}/virtual-accounts": post: operationId: createVirtualAccountV3 summary: Create Virtual Account description: >- Create a virtual bank account for a specific customer to convert fiat deposits to crypto. The `customer_id` path parameter identifies the customer for whom the virtual account is being created. V3 adds `source.bank` so you can choose the banking partner that issues the account, and returns the destination and banking partner on the create response. tags: - Virtual Accounts security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid description: Unique identifier of the customer to create the virtual account for. example: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" requestBody: required: true content: application/json: schema: type: object required: - destination - source - developer_fee properties: destination: type: object required: - wallet - currency - rail properties: wallet: type: string description: >- Destination wallet address. The address format depends on the rail. Ethereum, Base, and Polygon use hexadecimal (0x...), and Solana uses base58. example: "0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39" currency: type: string enum: [USDC, USDT] description: >- Token delivered to the destination wallet. Availability depends on both the rail and the source rail. See [Supported rails and currencies](https://developer.fin.com/guides/others/supported-rails-and-currencies) for valid combinations. example: "USDC" rail: type: string enum: [POLYGON, ETHEREUM, SOLANA, BASE] description: >- Blockchain network for the destination wallet. Not every token is issued on every network. See [Supported rails and currencies](https://developer.fin.com/guides/others/supported-rails-and-currencies) for valid combinations. example: "ETHEREUM" source: type: object required: - currency - rail - bank properties: currency: type: string enum: [USD, EUR, MXN] description: Fiat currency of the incoming deposit. Each source rail settles in a single currency. example: "USD" rail: type: string enum: [ACH, SWIFT, FEDWIRE, SPEI] description: >- Fiat payment rail used to fund the virtual account. ACH and Fedwire settle USD domestically, SWIFT settles USD internationally, and SPEI settles MXN. example: "FEDWIRE" bank: type: string enum: [SSB, PORTAGE] description: >- Banking partner that issues the virtual account and receives the fiat deposit. The banks available to you depend on your configuration, and not every bank supports every source rail. Contact support to find out which banks are enabled for your account. example: "SSB" developer_fee: type: object required: - percentage - fixed properties: fixed: type: number example: 0 percentage: type: number example: 0 example: destination: wallet: "0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39" currency: "USDC" rail: "ETHEREUM" source: currency: "USD" rail: "FEDWIRE" bank: "SSB" developer_fee: fixed: 0 percentage: 0 responses: "200": description: Virtual account created successfully content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid description: Unique identifier of the virtual account. example: "9d2b7f41-6c8a-45e3-b071-2fa93c5e8d16" status: type: string enum: [PROCESSING, IN_COMPLIANCE, REQUEST_FOR_INFORMATION, ACTIVE, INACTIVE, DECLINED] description: >- Current state of the virtual account. A newly created account is always returned as `PROCESSING`, and `deposit_instructions` stays null, until the banking partner issues the account. Once the bank issues it, the status moves to `ACTIVE` and the deposit instructions are populated. Poll [List Virtual Accounts](https://developer.fin.com/api-reference/virtual-accounts/list-virtual-accounts-v3) or listen for the virtual account webhooks to pick up the change. example: "PROCESSING" deposit_instructions: type: object nullable: true description: >- Bank details the customer deposits into. Null until the account becomes `ACTIVE`, so it is always null on the create response. properties: currency: type: string example: "USD" bank_name: type: string example: "Bank of Nowhere" bank_address: type: string example: "1800 North Pole St., Orlando, FL 32801" bank_routing_number: type: string example: "101019644" bank_account_number: type: string example: "2611508020" payment_rails: type: array items: type: string example: ["ACH", "FEDWIRE"] bank_country: type: string nullable: true example: null account_type: type: string nullable: true example: null bank_code: type: string nullable: true example: null destination: type: object description: Crypto destination the deposits settle to, echoed back from the request. properties: currency: type: string enum: [USDC, USDT] example: "USDC" destination_chain: type: string enum: [POLYGON, ETHEREUM, SOLANA, BASE] example: "ETHEREUM" address: type: string example: "0x4E91c07aB35d2F6810b94Ce7d13A5f826c0D4b7E" bank: type: string enum: [SSB, PORTAGE] description: Banking partner that issues the virtual account, echoed back from the request. example: "SSB" rfi: type: object nullable: true description: Populated only when the status is `REQUEST_FOR_INFORMATION`. example: null examples: OK: summary: OK value: data: id: "9d2b7f41-6c8a-45e3-b071-2fa93c5e8d16" status: "PROCESSING" deposit_instructions: null destination: currency: "USDC" destination_chain: "ETHEREUM" address: "0x4E91c07aB35d2F6810b94Ce7d13A5f826c0D4b7E" bank: "SSB" rfi: null "401": $ref: "#/components/responses/AuthenticationError" "422": description: >- The request failed validation. This includes the case where a virtual account already exists for the same customer and source combination. content: application/json: schema: type: object required: - message properties: errors: type: array description: >- Context for the failure. When a virtual account already exists, this holds the customer and source that collided, followed by the identifier of the account that already covers them. items: type: object properties: customer_id: type: string format: uuid description: Customer the request was made for. example: "c1f4a8e2-3b57-4d09-9a61-7e2b5c8d4f30" source: type: object description: Source currency and rail that already has a virtual account. properties: currency: type: string example: "USD" rail: type: string example: "FEDWIRE" virtual_account_id: type: string format: uuid description: >- Identifier of the virtual account that already exists. Use this account rather than creating another one. example: "9d2b7f41-6c8a-45e3-b071-2fa93c5e8d16" message: type: string description: Summary of why the request failed. example: "Virtual account already exists for the given parameters." examples: DuplicateVirtualAccount: summary: Virtual account already exists value: errors: - customer_id: "c1f4a8e2-3b57-4d09-9a61-7e2b5c8d4f30" source: currency: "USD" rail: "FEDWIRE" - virtual_account_id: "9d2b7f41-6c8a-45e3-b071-2fa93c5e8d16" message: "Virtual account already exists for the given parameters." get: operationId: listVirtualAccountsV3 summary: List Virtual Accounts description: Retrieve a paginated list of all virtual accounts belonging to a specific customer. tags: - Virtual Accounts security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid description: Unique identifier of the customer whose virtual accounts you want to list. example: "c1f4a8e2-3b57-4d09-9a61-7e2b5c8d4f30" - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/CurrentPageParam" responses: "200": description: Virtual accounts retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: virtual_accounts: type: array items: $ref: "#/components/schemas/VirtualAccountV3" pagination: type: object properties: current_page: type: integer example: 1 per_page: type: integer example: 10 total_page: type: integer example: 1 total: type: integer example: 1 examples: OK: summary: OK value: data: virtual_accounts: - id: "b84f17e1-96a8-4034-8394-e902ed403d96" status: "ACTIVE" developer_fee_percent: 2 developer_fee_fixed: 2 customer_id: "f60b6730-1bf1-4efa-a49e-be5ef5e75bb8" created_at: "2026-09-09T12:27:57.657953Z" updated_at: "2026-09-09T12:28:11.061185Z" deposit_instructions: currency: "USD" bank_name: "Portage Bank" bank_address: "880 108th Ave NE, Bellevue, WA 98004, US" bank_routing_number: null bank_account_number: "531912465" bank_beneficiary_name: "WeiMing Tan" bank_beneficiary_address: null payment_rails: - "SWIFT" bank_country: null account_type: null bank_code: type: "BIC" code: "PORGUS62XXX" bic_swift: "PORGUS62XXX" destination: currency: "USDC" destination_chain: "ETHEREUM" address: "0xE6F46b9Fa4Bc867816f78323EC92887E9d325DbE" rfi: null bank: "PORTAGE" pagination: current_page: 1 per_page: 10 total_page: 1 total: 1 "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" "/v3/customers/{customer_id}/virtual-accounts/{va_id}": get: operationId: getVirtualAccountDetailsV3 summary: Get Virtual Account Details description: >- Retrieve the full record for a single virtual account, including the deposit instructions the customer funds the account with and the crypto destination the deposits settle to. tags: - Virtual Accounts security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid description: Unique identifier of the customer the virtual account belongs to. example: "c1f4a8e2-3b57-4d09-9a61-7e2b5c8d4f30" - name: va_id in: path required: true schema: type: string format: uuid description: Unique identifier of the virtual account to retrieve. example: "9d2b7f41-6c8a-45e3-b071-2fa93c5e8d16" responses: "200": description: Virtual account retrieved successfully content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/VirtualAccountV3" examples: OK: summary: OK value: data: id: "b84f17e1-96a8-4034-8394-e902ed403d96" status: "ACTIVE" developer_fee_percent: 2 developer_fee_fixed: 2 customer_id: "f60b6730-1bf1-4efa-a49e-be5ef5e75bb8" created_at: "2026-09-09T12:27:57.657953Z" updated_at: "2026-09-09T12:28:11.061185Z" deposit_instructions: currency: "USD" bank_name: "SSB Bank" bank_address: null bank_routing_number: "" bank_account_number: "235464829825" bank_beneficiary_name: "WeiMing Tan" bank_beneficiary_address: null payment_rails: - "ACH" bank_country: "USA" account_type: "BankSwift" bank_code: type: "SWIFT" code: "SSBAUS32" bic_swift: "SSBAUS32" destination: currency: "USDC" destination_chain: "ETHEREUM" address: "0xE6F46b9Fa4Bc867816f78323EC92887E9d325DbE" rfi: null bank: "SSB" "401": $ref: "#/components/responses/AuthenticationError" "422": $ref: "#/components/responses/ValidationError" "/v1/virtual-account/{virtual_account_id}/transactions": get: summary: Fetch Virtual Account Transactions description: Retrieve a paginated list of all transactions for a specific virtual account tags: - Virtual Accounts security: - bearerAuth: [] parameters: - name: virtual_account_id in: path required: true schema: type: string format: uuid example: "3e7ce5ef-09bc-4e80-97f1-651ac483546f" - name: page in: query required: false schema: type: integer default: 1 - name: limit in: query required: false schema: type: integer default: 10 responses: "200": description: Virtual account transactions retrieved successfully content: application/json: schema: type: object required: - data properties: data: type: object properties: transactions: type: array items: type: object properties: id: type: string format: uuid example: "e34a382f-f0b6-40f2-b53b-97cb31f0506c" transaction_type: type: string example: "ONRAMP" beneficiary_id: type: string format: uuid nullable: true hash: type: string nullable: true transaction_ref_id: type: string format: uuid from_amount: type: number example: 0 payout_amount: type: number example: 0 processing_amount: type: number nullable: true status: type: string example: "COMPLETED" fx_rate: type: number example: 0 developer_fee: type: number example: 0 developer_fee_percentage: type: number example: 0 developer_fee_fixed: type: number nullable: true from_currency: type: string example: "USD" payout_currency: type: string example: "USDC" virtual_account_id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time pagination: type: object properties: current_page: type: integer example: 1 per_page: type: integer example: 10 total_page: type: integer example: 1 total: type: integer example: 4 "401": $ref: "#/components/responses/AuthenticationError" "404": $ref: "#/components/responses/NotFoundError" "422": $ref: "#/components/responses/ValidationError" # ───────────────────────────────────────────────────────────────────────── # FEES & FX RATES # ───────────────────────────────────────────────────────────────────────── "/v1/fx-rate": get: summary: Fetch Exchange Rates description: Retrieve exchange rates for a specific country or currency. x-mint: content: | Provide either `country_code` or `currency_code`, but not both. tags: - Fees & FX Rates security: - bearerAuth: [] parameters: - name: country_code in: query required: false schema: $ref: "#/components/schemas/CountryCode" - name: currency_code in: query required: false schema: type: string pattern: "^[A-Z]{3}$" example: "EUR" responses: "200": description: Exchange rates retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: from_currency: type: string example: "USD" to_currency: type: string example: "EUR" exchange_rate: type: number format: float example: 0.88 valid_from: type: string format: date-time example: "2026-05-20T19:34:03Z" valid_till: type: string format: date-time example: "2026-05-20T20:34:03Z" example: data: from_currency: "USD" to_currency: "EUR" exchange_rate: 0.88 valid_from: "2026-05-20T19:34:03Z" valid_till: "2026-05-20T20:34:03Z" "401": $ref: "#/components/responses/AuthenticationError" "/v1/fee-calculation": post: summary: Calculate Exchange Rates description: Calculate exchange rates and applicable fees for a transaction. x-mint: content: | Pass either `source_amount` or `destination_amount`. Use `beneficiary_id` instead of `destination_currency` to get developer-fee-aware calculations. tags: - Fees & FX Rates security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: source_currency: type: string pattern: "^[A-Z]{3}$" example: "USD" source_amount: type: number example: 3508679 destination_amount: type: number example: 59456 destination_currency: type: string pattern: "^[A-Z]{3}$" example: "CAD" beneficiary_id: type: string format: uuid example: "ceb7e6c9-ef2a-41c2-8459-38d67ec3c655" examples: With source amount: value: source_currency: "USD" source_amount: 3508679 destination_currency: "CAD" beneficiary_id: "ceb7e6c9-ef2a-41c2-8459-38d67ec3c655" With destination amount: value: source_currency: "USD" destination_amount: 59456 destination_currency: "CAD" beneficiary_id: "ceb7e6c9-ef2a-41c2-8459-38d67ec3c655" responses: "200": description: Fee calculation completed successfully content: application/json: schema: type: object properties: data: type: object properties: source_currency: type: string example: "USD" destination_currency: type: string example: "CAD" source_amount: type: number example: 3508679 exchange_rate: type: number format: float example: 1.45 destination_amount: type: number example: 508679 valid_till: type: string format: date-time example: "2026-01-19T09:59:29Z" fee: type: object properties: fixed: type: number example: 25 percentage: type: number example: 4 total: type: number example: 29 is_fee_applied: type: boolean example: true "401": $ref: "#/components/responses/AuthenticationError" # ───────────────────────────────────────────────────────────────────────── # CATALOGUE # ───────────────────────────────────────────────────────────────────────── "/v1/industries": get: summary: List Industries description: Retrieve a list of available industries x-mint: content: | This endpoint is used for the deprecated V1 business customer creation flow only. It is not applicable for Create Business Customer. tags: - Catalogue security: - bearerAuth: [] parameters: - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/CurrentPageParam" responses: "200": description: List of industries retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: $ref: "#/components/schemas/Pagination" industries: type: array items: type: object properties: id: type: integer example: 1 title: type: string example: "Oilseed Except Soybean Farming" "401": $ref: "#/components/responses/AuthenticationError" "/v1/occupations": get: summary: List Occupations description: Retrieve a list of available occupations tags: - Catalogue security: - bearerAuth: [] parameters: - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/CurrentPageParam" responses: "200": description: List of occupations retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: $ref: "#/components/schemas/Pagination" occupations: type: array items: type: object properties: id: type: integer example: 1 title: type: string example: "Software Engineer" "401": $ref: "#/components/responses/AuthenticationError" "/v1/source-of-funds": get: summary: List Source of Funds description: Retrieve a list of available source of funds tags: - Catalogue security: - bearerAuth: [] parameters: - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/CurrentPageParam" - name: type in: query description: Filter source of funds by type required: true schema: type: string enum: - INDIVIDUAL - BUSINESS responses: "200": description: List of source of funds retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: $ref: "#/components/schemas/Pagination" source_of_funds: type: array items: type: object properties: id: type: integer example: 1 title: type: string example: "Employment Income" "401": $ref: "#/components/responses/AuthenticationError" "/v1/source-of-wealth": get: summary: List Source of Wealth description: Retrieve a list of available source of wealth options tags: - Catalogue security: - bearerAuth: [] parameters: - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/CurrentPageParam" - name: type in: query description: Filter source of wealth by type required: true schema: type: string enum: - INDIVIDUAL - BUSINESS responses: "200": description: List of source of wealth retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: $ref: "#/components/schemas/Pagination" source_of_wealth: type: array items: type: object properties: id: type: integer example: 1 title: type: string example: "Business dividends or profits" example: data: pagination: current_page: 1 per_page: 10 total_page: 1 total: 7 source_of_wealth: - id: 1 title: "Business dividends or profits" - id: 2 title: "Investment income" - id: 3 title: "Real estate" - id: 4 title: "Inheritance" - id: 5 title: "Salary" - id: 6 title: "Sale of business" - id: 7 title: "Other" "401": $ref: "#/components/responses/AuthenticationError" "/v1/purposes": get: summary: List Account Purposes description: Retrieve a list of available account purposes tags: - Catalogue security: - bearerAuth: [] parameters: - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/CurrentPageParam" - name: type in: query description: Filter account purposes by type required: true schema: type: string enum: - INDIVIDUAL - BUSINESS responses: "200": description: List of account purposes retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: $ref: "#/components/schemas/Pagination" purposes: type: array items: type: object properties: id: type: integer example: 1 title: type: string example: "Personal Savings" "401": $ref: "#/components/responses/AuthenticationError" "/v1/countries": get: summary: "List Generic Country Codes" description: Retrieve a list of country specific codes following ISO 3166-1 alpha-3 standard tags: - Catalogue security: - bearerAuth: [] parameters: - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/CurrentPageParam" responses: "200": description: List of countries retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: $ref: "#/components/schemas/Pagination" countries: type: array items: type: object properties: code: type: string example: "BLR" name: type: string example: "Belarus" currency_code: type: string example: "BYN" phone_code: type: string example: "+375" flag_url: type: string format: uri example: "https://flagcdn.com/by.svg" postal_code: type: object properties: required: type: boolean example: true regex: type: string nullable: true example: "\\A\\d{6}\\Z" example: data: pagination: current_page: 1 per_page: 20 total_page: 13 total: 248 countries: - code: "AFG" name: "Afghanistan" currency_code: "AFN" phone_code: "+93" flag_url: "https://flagcdn.com/af.svg" postal_code: required: true regex: "\\A\\d{4}\\Z" - code: "ALA" name: "Åland Islands" currency_code: "EUR" phone_code: "+358" flag_url: "https://flagcdn.com/ax.svg" postal_code: required: true regex: "\\A22\\d{3}\\Z" - code: "ALB" name: "Albania" currency_code: "ALL" phone_code: "+355" flag_url: "https://flagcdn.com/al.svg" postal_code: required: true regex: "\\A\\d{4}\\Z" - code: "DZA" name: "Algeria" currency_code: "DZD" phone_code: "+213" flag_url: "https://flagcdn.com/dz.svg" postal_code: required: true regex: "\\A\\d{5}\\Z" - code: "ASM" name: "American Samoa" currency_code: "USD" phone_code: "+1-684" flag_url: "https://flagcdn.com/as.svg" postal_code: required: true regex: "\\A(96799)(?:[ \\-](\\d{4}))?\\Z" - code: "AND" name: "Andorra" currency_code: "EUR" phone_code: "+376" flag_url: "https://flagcdn.com/ad.svg" postal_code: required: true regex: "\\AAD[1-7]0\\d\\Z" - code: "AGO" name: "Angola" currency_code: "AOA" phone_code: "+244" flag_url: "https://flagcdn.com/ao.svg" postal_code: required: false regex: null - code: "AIA" name: "Anguilla" currency_code: "XCD" phone_code: "+1-264" flag_url: "https://flagcdn.com/ai.svg" postal_code: required: true regex: "\\A(?:AI-)?2640\\Z" - code: "ATA" name: "Antarctica" flag_url: "https://flagcdn.com/aq.svg" postal_code: required: false regex: null - code: "ATG" name: "Antigua and Barbuda" currency_code: "XCD" phone_code: "+1-268" flag_url: "https://flagcdn.com/ag.svg" postal_code: required: false regex: null - code: "ARG" name: "Argentina" currency_code: "ARS" phone_code: "+54" flag_url: "https://flagcdn.com/ar.svg" postal_code: required: true regex: "\\A((?:[A-HJ-NP-Z])?\\d{4})([A-Z]{3})?\\Z" - code: "ARM" name: "Armenia" currency_code: "AMD" phone_code: "+374" flag_url: "https://flagcdn.com/am.svg" postal_code: required: true regex: "\\A(?:37)?\\d{4}\\Z" - code: "ABW" name: "Aruba" currency_code: "AWG" phone_code: "+297" flag_url: "https://flagcdn.com/aw.svg" postal_code: required: false regex: null - code: "AUS" name: "Australia" currency_code: "AUD" phone_code: "+61" flag_url: "https://flagcdn.com/au.svg" postal_code: required: true regex: "\\A\\d{4}\\Z" - code: "AUT" name: "Austria" currency_code: "EUR" phone_code: "+43" flag_url: "https://flagcdn.com/at.svg" postal_code: required: true regex: "\\A\\d{4}\\Z" - code: "AZE" name: "Azerbaijan" currency_code: "AZN" phone_code: "+994" flag_url: "https://flagcdn.com/az.svg" postal_code: required: true regex: "\\A\\d{4}\\Z" - code: "BHS" name: "Bahamas" currency_code: "BSD" phone_code: "+1-242" flag_url: "https://flagcdn.com/bs.svg" postal_code: required: false regex: null - code: "BHR" name: "Bahrain" currency_code: "BHD" phone_code: "+973" flag_url: "https://flagcdn.com/bh.svg" postal_code: required: true regex: "\\A(?:\\d|1[0-2])\\d{2}\\Z" - code: "BGD" name: "Bangladesh" currency_code: "BDT" phone_code: "+880" flag_url: "https://flagcdn.com/bd.svg" postal_code: required: true regex: "\\A\\d{4}\\Z" - code: "BRB" name: "Barbados" currency_code: "BBD" phone_code: "+1-246" flag_url: "https://flagcdn.com/bb.svg" postal_code: required: true regex: "\\ABB\\d{5}\\Z" "401": $ref: "#/components/responses/AuthenticationError" "/v1/countries/{country_code}/subdivisions": get: summary: "List Subdivision Codes: ISO 3166-1 alpha-2" description: Retrieve a list of subdivision codes for a specific country following ISO 3166-2 standard tags: - Catalogue security: - bearerAuth: [] parameters: - $ref: "#/components/parameters/CountryCodeParam" responses: "200": description: List of subdivisions retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: subdivisions: type: array items: type: object properties: name: type: string example: "Bandarban" code: type: string example: "BD-01" "401": $ref: "#/components/responses/AuthenticationError" "/v1/transaction-purposes": get: summary: List Transaction Purposes description: Retrieve a list of available transaction purposes tags: - Catalogue security: - bearerAuth: [] parameters: - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/CurrentPageParam" - name: type in: query description: Filter transaction purposes by type required: true schema: type: string enum: - INDIVIDUAL - BUSINESS responses: "200": description: List of transaction purposes retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: $ref: "#/components/schemas/Pagination" transaction_purposes: type: array items: type: object properties: id: type: integer example: 1 title: type: string example: "Personal Transfer" "401": $ref: "#/components/responses/AuthenticationError" components: parameters: PerPageParam: name: per_page in: query description: Number of items to return per page required: false schema: type: integer default: 10 minimum: 1 maximum: 512 CurrentPageParam: name: current_page in: query description: The page number to retrieve required: false schema: type: integer default: 1 minimum: 1 CountryCodeParam: name: country_code in: path description: ISO 3166-1 alpha-3 country code required: true schema: $ref: "#/components/schemas/CountryCode" schemas: CountryCode: type: string description: ISO 3166-1 alpha-3 country code example: USA enum: - AFG - ALB - DZA - ASM - AND - AGO - AIA - ATA - ATG - ARG - ARM - ABW - AUS - AUT - AZE - BHS - BHR - BGD - BRB - BLR - BEL - BLZ - BEN - BMU - BTN - BOL - BES - BIH - BWA - BVT - BRA - IOT - BRN - BGR - BFA - BDI - CPV - KHM - CMR - CAN - CYM - CAF - TCD - CHL - CHN - CXR - CCK - COL - COM - COD - COG - COK - CRI - HRV - CUB - CUW - CYP - CZE - CIV - DNK - DJI - DMA - DOM - ECU - EGY - SLV - GNQ - ERI - EST - SWZ - ETH - FLK - FRO - FJI - FIN - FRA - GUF - PYF - ATF - GAB - GMB - GEO - DEU - GHA - GIB - GRC - GRL - GRD - GLP - GUM - GTM - GGY - GIN - GNB - GUY - HTI - HMD - VAT - HND - HKG - HUN - ISL - IND - IDN - IRN - IRQ - IRL - IMN - ISR - ITA - JAM - JPN - JEY - JOR - KAZ - KEN - KIR - PRK - KOR - KWT - KGZ - LAO - LVA - LBN - LSO - LBR - LBY - LIE - LTU - LUX - MAC - MDG - MWI - MYS - MDV - MLI - MLT - MHL - MTQ - MRT - MUS - MYT - MEX - FSM - MDA - MCO - MNG - MNE - MSR - MAR - MOZ - MMR - NAM - NRU - NPL - NLD - NCL - NZL - NIC - NER - NGA - NIU - NFK - MNP - NOR - OMN - PAK - PLW - PSE - PAN - PNG - PRY - PER - PHL - PCN - POL - PRT - PRI - QAT - MKD - ROU - RUS - RWA - REU - BLM - SHN - KNA - LCA - MAF - SPM - VCT - WSM - SMR - STP - SAU - SEN - SRB - SYC - SLE - SGP - SXM - SVK - SVN - SLB - SOM - ZAF - SGS - SSD - ESP - LKA - SDN - SUR - SJM - SWE - CHE - SYR - TWN - TJK - TZA - THA - TLS - TGO - TKL - TON - TTO - TUN - TUR - TKM - TCA - TUV - UGA - UKR - ARE - GBR - UMI - USA - URY - UZB - VUT - VEN - VNM - VGB - VIR - WLF - ESH - YEM - ZMB - ZWE - ALA TokenResponse: type: object properties: access_token: type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... access_token_ttl: type: string format: date-time example: "2025-12-28 10:34:45+00" refresh_token: type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... refresh_token_ttl: type: string format: date-time example: "2025-12-28 10:34:45+00" current_time: type: string format: date-time example: "2025-12-21 10:34:45+00" # ───────────────────────────────────────── # V2 Business Customer schemas (new) # ───────────────────────────────────────── CreateBusinessCustomerV2Input: type: object required: - verification_type - industry_codes - basic_info - financial_profile - addresses - associated_parties properties: verification_type: type: string enum: - STANDARD - RELIANCE description: >- Verification level. Defaults to STANDARD if omitted. RELIANCE must be explicitly enabled for your client. example: STANDARD industry_codes: type: array description: >- NAICS 2022 6-digit industry codes. Min 1 item. See the full list at [Business-industry-codes](https://developer.fin.com/business-industry-codes). minItems: 1 items: type: string example: - "523130" basic_info: $ref: "#/components/schemas/V2BasicInfo" financial_profile: $ref: "#/components/schemas/V2FinancialProfile" addresses: $ref: "#/components/schemas/V2Addresses" associated_parties: type: array description: >- UBOs (≥25% ownership), directors, and authorized signatories. Min 1 item required. minItems: 1 items: $ref: "#/components/schemas/V2AssociatedParty" holding_structure: $ref: "#/components/schemas/V2HoldingStructure" public_listings: type: array description: Stock exchange listings. Required for publicly traded companies. items: $ref: "#/components/schemas/V2PublicListing" compliance: $ref: "#/components/schemas/V2Compliance" meta_data: type: object description: Client-defined key-value metadata for internal tracking. properties: reference: type: string description: Client-defined external reference identifier. example: REF-20250123-ACME additionalProperties: true V2BasicInfo: type: object required: - legal_name - legal_name_en - trade_name - description - entity_type - email - phone - incorporation_date - country_of_incorporation - registration_number - tax_info - websites properties: legal_name: type: string maxLength: 255 description: Official registered business name. Must match incorporation documents. example: Fin.com legal_name_en: type: string description: English translation of the legal name. Required if legal_name contains non-ASCII characters. example: Fin.com trade_name: type: string description: Common operating name or DBA (Doing Business As). example: Toronggo trade_name_en: type: string description: English translation of the trade name. example: Toronggo description: type: string maxLength: 500 description: Description of the company's business activities and purpose. example: Bangladesh-based technology company providing cross-border B2B payment and financial technology services entity_type: type: string enum: - LIMITED_LIABILITY_COMPANY - PUBLICLY_LISTED_COMPANY - SOLE_PROPRIETOR - PARTNERSHIP - CORPORATION - PRIVATE_FOUNDATION - CHARITY - NONPROFIT_ORGANIZATION - PUBLIC_AGENCY_OR_AUTHORITY description: Legal entity type of the business. example: LIMITED_LIABILITY_COMPANY email: type: string format: email description: Business email address. Must be all lowercase. example: m@tech.com phone: type: string description: Business phone number in E.164 format. example: "+8801529876543" incorporation_date: type: string format: date description: Date of incorporation in YYYY-MM-DD format. Cannot be a future date. example: "2018-06-15" country_of_incorporation: $ref: "#/components/schemas/CountryCode" registration_number: type: string description: Business registration or company number. Required. example: "12-3456789" legal_entity_identifier: type: string minLength: 20 maxLength: 20 description: LEI code (20-character alphanumeric). Optional. example: 549300EXAMPLE0001X23 is_dao: type: boolean description: Whether the entity is a Decentralized Autonomous Organization. example: false tax_info: type: array description: Tax and identifying documents for the business. Min 1 item. minItems: 1 items: $ref: "#/components/schemas/V2IdentifyingDocument" websites: type: array description: Business website URLs. Min 1 item. minItems: 1 items: type: string format: uri example: - https://fin.com V2IdentifyingDocument: type: object required: - country_code - document_type - document_id properties: country_code: $ref: "#/components/schemas/CountryCode" document_type: type: string description: >- Business tax ID document type, validated per country. Examples: EIN, TIN, VAT_ID, TAX_ID, etc. See all available types at [Business tax id documents by region](https://developer.fin.com/guides/customers-and-compliance/business-tax-id-documents-by-region). example: EIN document_id: type: string description: The document ID or number. Format validated per country and document type. example: "12-3456789" V2IndividualIdentifyingDocument: type: object required: - country_code - document_type - document_id properties: country_code: $ref: "#/components/schemas/CountryCode" document_type: type: string description: >- Individual tax ID document type, validated per country. See all available types at [Individual Tax ID documents](https://developer.fin.com/guides/customers-and-compliance/individual-tax-id-documents). example: TIN document_id: type: string description: The document ID or number. Format validated per country and document type. example: "1234567890123" V2FinancialProfile: type: object required: - purpose_id - source_of_fund_ids - source_of_wealth_ids - estimated_annual_revenue_usd - expected_monthly_deposits_usd - expected_monthly_withdrawals_usd - third_party_fund_usage properties: purpose_id: type: integer description: >- Account purpose. Foreign key to purposes reference table. Fetch valid values from [List Account Purposes](https://developer.fin.com/api-reference/catalogue/list-account-purposes) endpoint. example: 3 purpose_remarks: type: string description: Additional context for the account purpose. Required if purpose represents "Other". example: Cross-border B2B payments for international suppliers source_of_fund_ids: type: array description: >- Source(s) of business funds. FK array to source_of_funds reference table. Min 1 item. Fetch valid values from [List Source of Funds](https://developer.fin.com/api-reference/catalogue/list-source-of-funds). Order items from the largest to smallest contributor. The ID representing the primary source of funds must come first, followed by secondary sources in descending order. minItems: 1 items: type: integer example: - 1 - 4 source_of_funds_description: type: string description: Additional context for source of funds. example: Revenue from software licensing and SaaS subscriptions source_of_wealth_ids: type: array description: >- Source(s) of owner's wealth. FK array to source_of_wealth reference table. Min 1 item. Fetch valid values from [List Source of Wealth](https://developer.fin.com/api-reference/catalogue/list-source-of-wealth). Order items from the largest to smallest contributor. The primary source must come first. minItems: 1 items: type: integer example: - 2 estimated_annual_revenue_usd: type: integer minimum: 0 description: Estimated annual revenue in USD (not cents). Must be >= 0. example: 5000000 expected_monthly_deposits_usd: type: integer minimum: 0 description: Expected monthly deposit volume in USD (not cents). Must be >= 0. example: 400000 expected_monthly_withdrawals_usd: type: integer minimum: 0 description: Expected monthly withdrawal volume in USD (not cents). Must be >= 0. example: 350000 expected_transaction_value_usd: type: integer minimum: 0 description: Typical single transaction value in USD (not cents). Optional. example: 50000 expected_monthly_transaction_count: type: integer minimum: 0 description: Expected number of transactions per month. Optional. example: 20 third_party_fund_usage: type: boolean description: >- Whether this business will process, hold, or move funds on behalf of other parties. Set to true only for MSBs and payment processors. Triggers enhanced compliance review. example: false V2Addresses: type: object required: - is_incorporated_address_same - incorporated_address properties: is_incorporated_address_same: type: boolean description: Whether the physical operating address is the same as the incorporated address. If false, physical_address is required. example: false incorporated_address: $ref: "#/components/schemas/V2Address" physical_address: allOf: - $ref: "#/components/schemas/V2Address" description: Physical operating address. Required when is_incorporated_address_same is false. V2Address: type: object required: - street_line_1 - street_line_1_en - city - state - subdivision_code - postal_code - country properties: street_line_1: type: string description: Primary street address. P.O. Box addresses are not accepted. example: 123 Main Street street_line_1_en: type: string description: English translation of street_line_1. Required if address contains non-ASCII characters. example: 123 Main Street street_line_2: type: string description: Secondary address (suite, floor, unit, etc.). Optional. example: Suite 400 street_line_2_en: type: string description: English translation of street_line_2. Optional. example: Suite 400 city: type: string maxLength: 100 description: City or municipality name. example: San Francisco state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: US-CA subdivision_code: type: string description: >- State/province code from [List Subdivisions](https://developer.fin.com/api-reference/catalogue/list-subdivisions). Same value as state field. example: US-CA postal_code: type: string description: ZIP or postal code. Format validated per country. example: "94105" country: $ref: "#/components/schemas/CountryCode" V2AssociatedParty: type: object required: - basic_info - address - roles properties: ref: type: string description: Client-defined reference identifier for this party. Used for internal tracking only. example: owner-001 basic_info: $ref: "#/components/schemas/V2APBasicInfo" address: $ref: "#/components/schemas/V2Address" roles: type: array description: >- Roles held by this party. At least one role is required. A party may hold both roles simultaneously. At least one party must hold both shareholder and ubo. minItems: 1 items: type: string enum: - shareholder - ubo example: - shareholder - ubo ownership_info: $ref: "#/components/schemas/V2OwnershipInfo" V2APBasicInfo: type: object required: - first_name - first_name_en - last_name - last_name_en - dob - email - phone - country_of_residence - primary_nationality - tax_info properties: first_name: type: string maxLength: 50 description: First name. example: John first_name_en: type: string description: English transliteration of first name. Required if name contains non-ASCII characters. example: John middle_name: type: string description: Middle name(s). Optional. example: Michael middle_name_en: type: string description: English transliteration of middle name. Optional. example: Michael last_name: type: string maxLength: 50 description: Last or family name. example: Doe last_name_en: type: string description: English transliteration of last name. Required if name contains non-ASCII characters. example: Doe dob: type: string format: date description: Date of birth in YYYY-MM-DD format. Party must be at least 18 years old. example: "1985-03-20" email: type: string format: email description: Personal email address. Must be unique across all associated parties in the same request. example: john.doe@acmecorp.com phone: type: string description: Personal phone number in E.164 format. example: "+14155551234" country_of_residence: $ref: "#/components/schemas/CountryCode" primary_nationality: $ref: "#/components/schemas/CountryCode" secondary_nationality: allOf: - $ref: "#/components/schemas/CountryCode" description: Secondary nationality for dual citizens. Optional. tax_info: type: array description: >- Tax and identifying documents for this individual. See all available individual tax ID document types at [Individual Tax ID documents](https://developer.fin.com/guides/customers-and-compliance/individual-tax-id-documents). items: $ref: "#/components/schemas/V2IndividualIdentifyingDocument" V2OwnershipInfo: type: object description: Required when roles includes ubo. required: - designation - percentage_of_ownership - relationship_establishment_date - has_control - is_signer - is_director properties: designation: type: string maxLength: 100 description: Title or position in the company (e.g., CEO, CFO, Founder). example: CEO percentage_of_ownership: type: number format: float minimum: 0 maximum: 100 description: >- Ownership stake as a percentage (0 to 100). Individual parties may have 0% ownership. Total across all parties must be < 100%. example: 75.0 relationship_establishment_date: type: string format: date description: "Date when the relationship with the business began. Format: YYYY-MM-DD. Cannot be a future date." example: "2018-06-15" has_control: type: boolean description: Whether this party has significant control over the entity. example: true is_signer: type: boolean description: Whether this party is an authorized signatory. example: true is_director: type: boolean description: Whether this party serves as a director. example: true V2PublicListing: type: object properties: mic: type: string description: ISO 10383 Market Identifier Code (e.g., XNAS for NASDAQ). example: XNAS isin: type: string minLength: 12 maxLength: 12 description: International Securities Identification Number (12 chars). example: US0231351067 ticker_symbol: type: string description: Stock exchange ticker symbol. example: ACME V2HoldingStructure: type: object properties: has_material_intermediary_ownership: type: boolean description: Whether any intermediary holds a material ownership stake. example: true corporate_shareholders: type: array description: List of corporate (non-individual) shareholders. items: $ref: "#/components/schemas/V2CorporateShareholder" foreign_branches: type: array description: List of foreign branch registrations. items: $ref: "#/components/schemas/V2ForeignBranch" V2CorporateShareholder: type: object required: - entity_name - entity_name_en - registration_country_code - ownership_percentage properties: entity_name: type: string description: Corporate shareholder's legal name. example: Acme Ventures LLC entity_name_en: type: string description: English translation of entity name. Required if entity_name contains non-ASCII characters. example: Acme Ventures LLC registration_country_code: $ref: "#/components/schemas/CountryCode" ownership_percentage: type: number format: float minimum: 0 maximum: 100 description: Ownership stake as a percentage (0 to 100). example: 60.0 registration_number: type: string description: Entity registration number. Optional. example: "98-7654321" entity_type: type: string enum: - LIMITED_LIABILITY_COMPANY - PUBLICLY_LISTED_COMPANY - SOLE_PROPRIETOR - PARTNERSHIP - CORPORATION - PRIVATE_FOUNDATION - CHARITY - NONPROFIT_ORGANIZATION - PUBLIC_AGENCY_OR_AUTHORITY description: Legal entity type of the corporate shareholder. Optional. example: LIMITED_LIABILITY_COMPANY incorporation_date: type: string format: date description: Incorporation date in YYYY-MM-DD format. Optional. example: "2015-03-01" V2ForeignBranch: type: object required: - registration_country_code properties: registration_country_code: $ref: "#/components/schemas/CountryCode" name: type: string description: Branch name. Optional. example: Acme Corp UK Branch registration_number: type: string description: Branch registration number. Optional. example: BR000123 V2Compliance: type: object properties: operates_in_prohibited_countries: type: boolean description: Whether the business operates in OFAC/sanctioned countries. example: false additional_description_for_compliance_screening: type: string description: Free-text compliance notes for manual review. example: We do not operate in any OFAC-sanctioned jurisdictions. risk_profile: $ref: "#/components/schemas/V2RiskProfile" regulated_activity: $ref: "#/components/schemas/V2RegulatedActivity" aml: $ref: "#/components/schemas/V2AML" V2RiskProfile: type: object properties: high_risk_activities: type: array description: High-risk activities the business engages in. If non-empty, high_risk_activities_explanation is required. items: type: string enum: - adult_entertainment - crypto_exchange - gambling - cannabis - weapons - money_services - cross_border_payments example: - cross_border_payments high_risk_activities_explanation: type: string description: Explanation of declared high-risk activities. Required when high_risk_activities is non-empty. example: We facilitate cross-border B2B payments, subject to enhanced due diligence procedures. conducts_money_services: type: boolean description: Whether the business provides money services. example: true conducts_money_services_via_fin: type: boolean description: Whether money services are provided via financial intermediaries. example: false conducts_money_services_description: type: string description: Details about the money services offered. example: Licensed money transmitter providing international wire transfer services. V2RegulatedActivity: type: object required: - description - primary_authority_country_code - primary_authority_name - license_number properties: description: type: string description: Description of the regulated activity. example: Licensed money transmitter operating under FinCEN registration and state-level MSB licenses primary_authority_country_code: $ref: "#/components/schemas/CountryCode" primary_authority_name: type: string description: Name of the primary regulatory authority. example: FinCEN license_number: type: string description: Regulatory license or registration number. example: MSB-12345678 V2AML: type: object properties: supervisory_authority_name: type: string description: Name of the AML supervisory authority. example: FinCEN license_number: type: string description: AML license number. example: MSB-12345678 has_appointed_mlro: type: boolean description: Whether a Money Laundering Reporting Officer has been appointed. example: true customer_risk_split: $ref: "#/components/schemas/V2CustomerRiskSplit" prohibits_anonymous_or_fictitious_accounts: type: boolean description: Policy on anonymous or fictitious accounts. example: true prohibits_accounts_for_unlicensed_or_shell_customers: type: boolean description: Policy on unlicensed or shell customers. example: true customer_identity_verification: $ref: "#/components/schemas/V2VerificationMethod" pep_and_sanctions_screening: $ref: "#/components/schemas/V2VerificationMethod" sanction_lists: type: array description: Names of sanction lists screened against. items: type: string example: - OFAC - EU - UN - HMT customer_risk_classification_from_due_diligence: type: boolean example: true enhanced_due_diligence_process: type: boolean example: true transaction_monitoring: $ref: "#/components/schemas/V2VerificationMethod" procedures_for_transaction_monitoring: type: boolean example: true subject_to_ml_or_tf_investigation: type: string description: Current ML/TF investigation status. example: none subject_to_regulatory_enforcement_past_2_years: type: string description: Regulatory enforcement history over the last 2 years. example: none confirms_no_service_to_sanctioned_countries: type: boolean example: true client_funds_accessibility: type: string description: Policy on client fund accessibility. example: closed_loop aml_ctf_audit_completed: type: boolean example: true planned_audit_date: type: string format: date description: Planned next audit date in YYYY-MM-DD format. example: "2026-12-01" V2CustomerRiskSplit: type: object description: Breakdown of customer risk classifications. Percentages must sum to 100. required: - low_risk - medium_risk - high_risk properties: low_risk: type: integer minimum: 0 maximum: 100 description: Percentage of low-risk customers. example: 70 medium_risk: type: integer minimum: 0 maximum: 100 description: Percentage of medium-risk customers. example: 25 high_risk: type: integer minimum: 0 maximum: 100 description: Percentage of high-risk customers. example: 5 V2VerificationMethod: type: object description: Used for customer_identity_verification, pep_and_sanctions_screening, and transaction_monitoring. required: - method - system properties: method: type: string description: Verification method (e.g., automated, manual, third_party). example: automated system: type: string description: System or vendor used (e.g., Jumio, Onfido, Internal). example: Jumio # ───────────────────────────────────────── # V1 Business Customer schema (existing, preserved) # ───────────────────────────────────────── CreateBusinessCustomerInput: type: object required: - basic_info - financial_profile - addresses - associated_parties properties: verification_type: type: string enum: - STANDARD - RELIANCE description: >- Type of verification to perform (optional, defaults to STANDARD). Note that RELIANCE verification must be enabled for your client, or you will receive a 423 error. example: RELIANCE basic_info: type: object required: - business_name - description - entity_type - website - email - incorporation_date - phone - country_of_incorporation - registration_number - tax_id properties: business_name: type: string description: Legal name of the business example: Acme Corp Ltd business_trade_name: type: string description: Trading name or DBA (Doing Business As) name example: Acme description: type: string description: Description of the company's business example: International software and payments company entity_type: type: string enum: - LIMITED_LIABILITY_COMPANY - PUBLICLY_LISTED_COMPANY - SOLE_PROPRIETOR - PARTNERSHIP - CORPORATION - PRIVATE_FOUNDATION - CHARITY - NONPROFIT_ORGANIZATION - PUBLIC_AGENCY_OR_AUTHORITY - PRIVATE_LIMITED description: Legal entity type of the business example: LIMITED_LIABILITY_COMPANY website: type: string format: uri description: Company website URL example: https://fin.com email: type: string format: email description: Business email address. Must be all lowercase or a validation error will occur. example: contact@acmecorp.com incorporation_date: type: string format: date description: Date of incorporation in YYYY-MM-DD format example: "2018-06-15" phone: type: string description: Business phone number example: "+14155552671" country_of_incorporation: $ref: "#/components/schemas/CountryCode" registration_number: type: string description: Business registration number example: "12-3456789" tax_id: type: string description: Tax identification number or EIN (must be EIN for USA) example: "12-3456789" financial_profile: type: object required: - purpose_id - business_industry_id - monthly_volume - source_of_fund_id - third_party_fund_usage properties: purpose_id: type: integer description: Unique identifier for account purpose retrieved from the catalogue API [List Account Purposes](https://developer.fin.com/api-reference/catalogue/list-account-purposes). example: 10 other_purpose: type: string description: Custom purpose description (only when purpose_id represents "Other") example: custom other purpose business_industry_id: type: integer description: Unique identifier for business industry retrieved from the catalogue API [List Industries](https://developer.fin.com/api-reference/catalogue/list-industries) example: 1 monthly_volume: type: integer minimum: 0 description: Expected monthly transaction volume in USD (not cents) example: 100000 source_of_fund_id: type: integer description: Unique identifier for source of funds retrieved from the catalogue API [List Source of Funds](https://developer.fin.com/api-reference/catalogue/list-source-of-funds) example: 13 third_party_fund_usage: type: boolean description: Indicates whether this customer will be moving other people's money (third-party funds) example: false addresses: type: object required: - is_incorporated_address_same - incorporated_address properties: is_incorporated_address_same: type: boolean description: Whether the physical address is the same as the incorporated address example: true incorporated_address: type: object required: - street - city - state - postal_code - country properties: street: type: string description: Street address example: "10 Anson Road #26-04 International Plaza" city: type: string description: City name example: Singapore state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: SG-01 postal_code: type: string description: Postal or ZIP code example: "079903" country: $ref: "#/components/schemas/CountryCode" physical_address: type: object description: Physical operating address (required only if is_incorporated_address_same is false) required: - street - city - state - postal_code - country properties: street: type: string example: "456 Market Street Floor 3" city: type: string example: San Francisco state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: US-CA postal_code: type: string example: "94103" country: $ref: "#/components/schemas/CountryCode" associated_parties: type: array description: Array of associated parties (UBOs, directors, shareholders, etc.) minItems: 1 items: type: object required: - basic_info - address - ownership_info properties: basic_info: type: object required: - first_name - last_name - dob - email - phone - country_of_residence - nationality - tin properties: first_name: type: string example: John last_name: type: string example: Doe dob: type: string format: date example: "1985-03-20" email: type: string format: email example: john.doe@acmecorp.com phone: type: string example: "+14155551234" country_of_residence: $ref: "#/components/schemas/CountryCode" nationality: $ref: "#/components/schemas/CountryCode" tin: type: string description: Tax Identification Number example: "123-45-6789" address: type: object required: - street - city - state - postal_code - country properties: street: type: string example: "456 Oak Avenue" city: type: string example: San Francisco state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: US-CA postal_code: type: string example: "94102" country: $ref: "#/components/schemas/CountryCode" ownership_info: type: object required: - designation - percentage_of_ownership - relationship_establishment_date properties: designation: type: string description: Role or position in the company (e.g., CEO, Director, UBO) example: CEO percentage_of_ownership: type: number format: float minimum: 0 description: Percentage of ownership in the business. Total must be < 100. example: 75.0 relationship_establishment_date: type: string format: date description: Date when the relationship was established in YYYY-MM-DD format example: "2018-06-15" meta_data: type: object additionalProperties: true description: Additional custom metadata as key-value pairs example: reference: ref-20250910-XYZ # ───────────────────────────────────────── # Shared Individual Customer schemas (unchanged from original) # ───────────────────────────────────────── CreateIndividualCustomerV2Input: type: object required: - verification_type - basic_info - address - financial_profile properties: verification_type: type: string enum: - STANDARD - RELIANCE example: STANDARD basic_info: type: object required: - first_name - last_name - dob - email - phone - country_of_residence - primary_nationality - tax_info properties: first_name: type: string example: "Maria" first_name_en: type: string description: English transliteration. Required if first_name contains non-ASCII characters. example: "Maria" middle_name: type: string example: "Elena" middle_name_en: type: string description: English transliteration. Required if middle_name contains non-ASCII characters. example: "Elena" last_name: type: string example: "Garcia" last_name_en: type: string description: English transliteration. Required if last_name contains non-ASCII characters. example: "Garcia" dob: type: string format: date description: Date of birth in YYYY-MM-DD format. Age must be between 18 and 120 years. example: "1990-04-15" email: type: string format: email description: Must be all lowercase. example: "maria.garcia@example.com" phone: type: string description: E.164 format. example: "+14155552671" country_of_residence: $ref: "#/components/schemas/CountryCode" primary_nationality: $ref: "#/components/schemas/CountryCode" secondary_nationality: $ref: "#/components/schemas/CountryCode" gender: type: string enum: - MALE - FEMALE example: FEMALE tax_info: type: array minItems: 1 description: Tax identification documents. Each entry must have a unique document_id. items: type: object required: - country_code - document_type - document_id properties: country_code: $ref: "#/components/schemas/CountryCode" document_type: type: string description: Tax document type (e.g. SSN, TIN). example: SSN document_id: type: string example: "123-45-6789" address: type: object required: - street_line_1 - city - subdivision_code - postal_code - country properties: street_line_1: type: string example: "123 Market Street" street_line_1_en: type: string description: English transliteration. Required if street_line_1 contains non-ASCII characters. example: "123 Market Street" street_line_2: type: string example: "Apt 4B" street_line_2_en: type: string description: English transliteration. Required if street_line_2 contains non-ASCII characters. example: "Apt 4B" city: type: string example: "San Francisco" subdivision_code: type: string description: ISO 3166-2 subdivision code (e.g. US-CA). example: "US-CA" postal_code: type: string example: "94103" country: $ref: "#/components/schemas/CountryCode" financial_profile: type: object required: - employment_status - occupation_id - purpose_id - source_of_fund_ids - monthly_volume_usd properties: employment_status: type: string enum: - EMPLOYED - SELF_EMPLOYED - RETIRED - STUDENT - UNEMPLOYED description: Employment status of the individual. example: EMPLOYED occupation_id: type: integer description: Occupation. FK to occupations reference table. Fetch valid values from GET /v1/occupations?type=INDIVIDUAL. example: 42 purpose_id: type: integer description: Account purpose. FK to purposes reference table. Fetch valid values from GET /v1/purposes?type=INDIVIDUAL. example: 3 purpose_remarks: type: string example: "Personal remittances to family" source_of_fund_ids: type: array minItems: 1 items: type: integer description: Source(s) of funds. FK array to source_of_funds reference table. Fetch valid values from GET /v1/source-of-funds?type=INDIVIDUAL. example: [1, 5] source_of_funds_description: type: string example: "Monthly salary from employment" monthly_volume_usd: type: integer minimum: 0 example: 5000 meta_data: type: object additionalProperties: true example: reference: "client-ref-abc-001" CreateIndividualCustomerInput: type: object required: - verification_type - basic_info - address - financial_profile properties: verification_type: type: string enum: - STANDARD - RELIANCE example: STANDARD basic_info: type: object required: - first_name - last_name - dob - email - phone - country_of_residence - nationality - tin properties: first_name: type: string example: "John" last_name: type: string example: "Doe" dob: type: string format: date example: "1990-01-15" email: type: string format: email example: "john.doe@example.com" phone: type: string example: "+14155551234" country_of_residence: $ref: "#/components/schemas/CountryCode" nationality: $ref: "#/components/schemas/CountryCode" tin: type: string example: "123-45-6789" address: type: object required: - street - city - state - postal_code - country properties: street: type: string example: "123 Main St" city: type: string example: "New York" state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: "US-NY" postal_code: type: string example: "10001" country: $ref: "#/components/schemas/CountryCode" financial_profile: type: object required: - occupation_id - source_of_fund_id - purpose_id - monthly_volume_usd properties: occupation_id: type: integer example: 1 source_of_fund_id: type: integer example: 1 purpose_id: type: integer example: 1 monthly_volume_usd: type: integer minimum: 0 example: 5000 meta_data: type: object additionalProperties: true example: customer_reference: "REF-12345" IndividualCustomerDetailV2: title: Individual type: object properties: customer_id: type: string format: uuid example: "56c41b8e-e650-4f55-94f6-26a888a9b64d" type: type: string enum: [INDIVIDUAL] first_name: type: string example: "John" last_name: type: string example: "Doe" email: type: string format: email example: "john.doe@example.com" phone: type: string example: "+14155551234" country_of_residence: type: string example: "USA" verification_type: type: string example: "STANDARD" customer_status: type: string example: "ACTION_REQUIRED" tos_policies_url: type: string format: uri example: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=1f45e58d-0420-4ad8-a790-413169bfab28&tos_policies_value=ffefb0cd-4f0a-4585-ad1c-f4ea76ba41b8" created_at: type: string format: date-time example: "2026-05-04T12:40:03Z" updated_at: type: string format: date-time example: "2026-05-04T12:47:50Z" last_status_updated_at: type: string format: date-time example: "2026-05-04T12:44:42.707598Z" rejection_reason: type: object nullable: true description: >- Populated when customer_status is REJECTED or ACTION_REQUIRED. Contains applicant-level and document-level rejection details. Null when no rejection exists. properties: applicant: type: object nullable: true description: Applicant-level rejection reason. properties: moderation_comment: type: string example: "" reject_labels: type: array items: type: string example: ["EXPIRATION_DATE", "PROBLEMATIC_APPLICANT_DATA"] documents: type: array description: Document-level rejection reasons. items: type: object properties: uri: type: string example: "/SuElNZpi_approved_passport.jpg" category: type: string example: "PROOF_OF_IDENTITY" moderation_comment: type: string example: "Your identity document has expired and can't be used for verification. Please upload a different identity document." reject_labels: type: array items: type: string example: ["EXPIRATION_DATE"] example: null request_for_information: type: array description: >- List of open requests for additional information. Populated when customer_status is ACTION_REQUIRED. Same structure as customer.rfi webhook payload. items: type: object properties: scope: type: string enum: [CUSTOMER, ASSOCIATED_PARTY] example: "CUSTOMER" section: type: string example: "proof_of_identity" categories: type: array items: type: object properties: document_type: type: string example: "PASSPORT" fields: type: array items: type: object properties: field_name: type: string example: "files" data_type: type: string enum: [URI, DATE, TEXT, ENUM] example: "URI" status: type: string enum: [MISSING, EXPIRED, INVALID] example: "INVALID" reason: type: string nullable: true example: "Expired Identity document. A new document has been requested." options: type: array items: type: string example: [] example: [] BusinessCustomerDetailV2: title: Business type: object properties: customer_id: type: string format: uuid example: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" type: type: string enum: [BUSINESS] business_name: type: string example: "Fin.com" email: type: string format: email example: "m@tech.com" phone: type: string example: "+8801529876543" country_of_incorporation: type: string example: "BGD" verification_type: type: string example: "STANDARD" customer_status: type: string description: >- The following statuses have been changed from V1. QUEUED (V1) → PROCESSING (V2). ON_HOLD (V1) → IN_COMPLIANCE (V2). REINITIATE (V1) → ACTION_REQUIRED (V2). enum: - INCOMPLETE - PROCESSING - REVIEWING - APPROVED - ASSOCIATED_PARTIES_REMAINING - IN_COMPLIANCE - ACTION_REQUIRED - REJECTED example: "IN_COMPLIANCE" tos_policies_url: type: string format: uri associated_parties: type: array items: type: object properties: id: type: string format: uuid example: "f6b13e01-044a-4f74-a70b-d5f66b6449af" type: type: string example: "INDIVIDUAL" ownership_percent: type: number example: 60 email: type: string format: email example: "fatima.rahman22@acmecorp.com.bd" verification: type: object properties: status: type: string enum: - INITIATED - PENDING_REVIEW - APPROVED - REJECTED - ON_HOLD example: "APPROVED" reason: type: object properties: for_customer: type: string nullable: true for_developer: type: string nullable: true updated_at: type: string format: date-time example: "2026-04-13T11:40:49Z" created_at: type: string format: date-time example: "2026-04-01T12:03:03Z" updated_at: type: string format: date-time example: "2026-04-01T12:03:03Z" rejection_reason: type: object nullable: true description: >- Populated when customer_status is REJECTED or ACTION_REQUIRED. Contains applicant-level, document-level, and associated party-level rejection details. Null when no rejection exists. properties: applicant: type: object nullable: true description: Applicant-level rejection reason. properties: moderation_comment: type: string example: "If you're a sole entrepreneur, upload corporate documents confirming your company's legal status." reject_labels: type: array items: type: string example: ["DOCUMENT_MISSING"] documents: type: array description: Document-level rejection reasons. items: type: object properties: uri: type: string example: "/7zlLPvlx_testdoc6.jpg" category: type: string example: "SUPPORTING_DOCUMENTS" moderation_comment: type: string example: "This document is not accepted. The document should be of good quality." reject_labels: type: array items: type: string example: ["LOW_QUALITY"] associated_parties: type: array description: Associated party-level rejection reasons. items: type: object example: null request_for_information: type: array description: >- List of open requests for additional information. Populated when customer_status is ACTION_REQUIRED. Same structure as customer.rfi webhook payload. items: type: object properties: section: type: string example: "ownership_documents" categories: type: array items: type: object properties: document_type: type: string example: "SHAREHOLDER_REGISTRY" fields: type: array items: type: object properties: field_name: type: string example: "files" data_type: type: string enum: [URI, DATE, TEXT, ENUM] example: "URI" status: type: string enum: [MISSING, EXPIRED, INVALID] example: "INVALID" reason: type: string nullable: true example: "Unacceptable document." example: [] IndividualCustomerDetail: type: object title: Individual properties: customer_id: type: string format: uuid example: "56c41b8e-e650-4f55-94f6-26a888a9b64d" type: type: string enum: [INDIVIDUAL] first_name: type: string example: "John" last_name: type: string example: "Doe" email: type: string format: email example: "john.doe@fin.com" phone: type: string example: "+14724480512" country_of_residence: type: string example: "USA" verification_type: type: string example: "STANDARD" customer_status: type: string example: "ON_HOLD" tos_policies_url: type: string format: uri example: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=56c41b8e-e650-4f55-94f6-26a888a9b64d&tos_policies_value=e9414388-fbdf-4407-b5c2-bc39eae3645b" created_at: type: string format: date-time example: "2026-04-15T11:49:27Z" updated_at: type: string format: date-time example: "2026-04-15T11:52:48Z" last_status_updated_at: type: string format: date-time example: "2026-04-15T11:52:48Z" capabilities: type: object description: On-ramp and off-ramp capabilities for the customer properties: on_ramp: type: array items: type: object properties: currency: type: string example: "USD" status: type: boolean example: false methods: type: array items: type: string example: ["ACH", "FEDWIRE"] reason: type: object properties: for_customer: type: string nullable: true for_developer: type: string nullable: true off_ramp: type: array items: type: object properties: currency: type: string example: "USD" status: type: boolean example: false methods: type: array items: type: string example: ["BANK"] reason: type: object properties: for_customer: type: string nullable: true for_developer: type: string nullable: true example: "Customer is under review" rejection_reason: type: object nullable: true description: Populated when customer_status is REJECTED. Null otherwise. example: null request_for_information: type: array description: List of open requests for additional information. Empty when none are outstanding. items: type: object example: [] BusinessCustomerDetail: type: object title: Business properties: customer_id: type: string format: uuid example: "94e6b847-4e19-49e3-b3ab-ffa95872eda9" type: type: string enum: [BUSINESS] business_name: type: string example: "Fin.com" email: type: string format: email example: "contact@fin.com" phone: type: string example: "+6591234567" country_of_incorporation: type: string example: "SGP" verification_type: type: string example: "STANDARD" customer_status: type: string example: "APPROVED" tos_policies_url: type: string format: uri example: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=94e6b847-4e19-49e3-b3ab-ffa95872eda9&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24" associated_parties: type: array items: type: object properties: id: type: string format: uuid example: "42daffd3-09a0-4d48-8e73-2680a953d0e1" type: type: string example: "INDIVIDUAL" ownership_percent: type: number example: 10 email: type: string format: email example: "john.doe@fin.com" verification: type: object properties: status: type: string enum: - INITIATED - PENDING_REVIEW - APPROVED - REJECTED - ON_HOLD example: "APPROVED" reason: type: object properties: for_customer: type: string nullable: true for_developer: type: string nullable: true updated_at: type: string format: date-time example: "2026-04-15T11:29:08Z" created_at: type: string format: date-time example: "2026-04-15T11:26:12Z" updated_at: type: string format: date-time example: "2026-04-15T11:31:18Z" last_status_updated_at: type: string format: date-time example: "2026-04-15T11:29:09Z" capabilities: type: object description: On-ramp and off-ramp capabilities for the customer properties: on_ramp: type: array items: type: object properties: currency: type: string example: "USD" status: type: boolean example: false methods: type: array items: type: string example: ["ACH", "FEDWIRE"] reason: type: object properties: for_customer: type: string nullable: true for_developer: type: string nullable: true off_ramp: type: array items: type: object properties: currency: type: string example: "USD" status: type: boolean example: true methods: type: array items: type: string example: ["BANK"] reason: type: object properties: for_customer: type: string nullable: true for_developer: type: string nullable: true rejection_reason: type: object nullable: true description: Populated when customer_status is REJECTED. Null otherwise. request_for_information: type: array description: List of pending information requests. Empty when none are outstanding. items: type: object # Document schemas (unchanged from original) ProofOfIdentity: type: object required: - type - number - country - issue_date - expiry_date - files properties: type: type: string enum: - PASSPORT - NATIONAL_ID - DRIVERS_LICENSE - RESIDENCE_PERMIT description: | - `PASSPORT`: Passport - `NATIONAL_ID`: National ID card - `DRIVERS_LICENSE`: Driver's license - `RESIDENCE_PERMIT` - Residence permit example: "PASSPORT" number: type: string example: "A12345678" country: $ref: "#/components/schemas/CountryCode" issue_date: type: string format: date example: "2020-01-15" expiry_date: type: string format: date example: "2030-01-15" files: type: array items: type: object required: - uri properties: side: type: string enum: - FRONT - BACK example: "FRONT" uri: type: string example: "/AbAcQ4hn_0652746727637.pdf" ProofOfAddressBusiness: type: object required: - type - country - files properties: type: type: string enum: - UTILITY_BILL - GOVERNMENT_LETTER - BANK_STATEMENT example: "UTILITY_BILL" country: $ref: "#/components/schemas/CountryCode" files: type: array items: type: object required: - uri properties: uri: type: string example: "/AbAcQ4hn_0652746727638.pdf" ProofOfAddressIndividual: type: object description: "The proof of address document must not be older than three months." required: - type - country - files properties: type: type: string enum: - UTILITY_BILL - GOVERNMENT_LETTER - BANK_STATEMENT example: "UTILITY_BILL" country: $ref: "#/components/schemas/CountryCode" files: type: array items: type: object required: - uri properties: uri: type: string example: "/AbAcQ4hn_0652746727638.pdf" AttachDocumentForIndividualCustomerInput: type: object required: - customer_id - proof_of_identity - proof_of_address - tos_policies_value properties: customer_id: type: string format: uuid example: "55bd6b4e-c20a-4cc8-9535-91d5557a67d9" proof_of_identity: $ref: "#/components/schemas/ProofOfIdentity" proof_of_address: $ref: "#/components/schemas/ProofOfAddressIndividual" tos_policies_value: type: string example: "e9414388-fbdf-4407-b5c2-bc39eae3645b" AttachDocumentToAssociatedPartyInput: type: object required: - customer_id - associated_party_attachments properties: customer_id: type: string format: uuid example: "2d0a9df3-e1e5-4955-9759-ce0522e0ddc9" associated_party_attachments: type: array items: type: object required: - associated_party_id - proof_of_identity - proof_of_address properties: associated_party_id: type: string format: uuid example: "42daffd3-09a0-4d48-8e73-2680a953d0e1" proof_of_identity: $ref: "#/components/schemas/ProofOfIdentity" proof_of_address: $ref: "#/components/schemas/ProofOfAddressBusiness" AttachDocumentsToBusinessCustomerInput: type: object required: - customer_id - ownership_structure - company_details - legal_presence - tos_policies_value properties: customer_id: type: string format: uuid example: "2d0a9df3-e1e5-4955-9759-ce0522e0ddc9" ownership_structure: type: array items: type: object required: - type - files properties: type: type: string enum: - SHAREHOLDER_REGISTRY example: "SHAREHOLDER_REGISTRY" files: type: array items: type: object required: - uri properties: uri: type: string example: "/AbAcQ4hn_0652746727639.pdf" company_details: type: array items: type: object required: - type - files properties: type: type: string enum: - CERT_OF_INCORPORATION - MEMORANDUM_OF_ASSOCIATION example: "CERT_OF_INCORPORATION" files: type: array items: type: object required: - uri properties: uri: type: string example: "/AbAcQ4hn_0652746727640.pdf" legal_presence: type: array items: type: object required: - type - files properties: type: type: string enum: - PROOF_OF_ADDRESS example: "PROOF_OF_ADDRESS" files: type: array items: type: object required: - uri properties: uri: type: string example: "/AbAcQ4hn_0652746727641.pdf" tos_policies_value: type: string example: "e9414388-fbdf-4407-b5c2-bc39eae3645b" # ───────────────────────────────────────── # V2 Attach schemas (new) # ───────────────────────────────────────── AttachDocumentsToBusinessCustomerV2Input: type: object required: - tos_policies_value properties: formation_documents: type: array description: >- Documents proving the legal existence of the business (e.g., Certificate of Incorporation, Articles of Incorporation, Tax registration certificate). items: $ref: "#/components/schemas/V2FormationDocumentItem" ownership_documents: type: array description: >- Documents proving who controls and owns the business (e.g., Shareholder Register, Org Chart, Power of Attorney, Directors Registry). items: $ref: "#/components/schemas/V2OwnershipDocumentItem" supporting_documents: type: array description: >- Additional compliance and operational documents (e.g., Proof of Address, Proof of Source of Funds, AML Comfort Letter, Marketing Materials). items: $ref: "#/components/schemas/V2SupportingDocumentItem" tos_policies_value: type: string description: >- Parsed from the tos_policies_value query parameter in the tos_policies_url returned by POST /v2/customers/business. Signifies the customer has accepted the Terms of Service. example: "f11e77c6-8dc0-4d4b-a3f2-ed84c8ccfc69" V2FormationDocumentItem: type: object required: - files properties: type: type: string enum: - REGISTRATION_DOCUMENT - CONSTITUTIONAL_DOCUMENT - FORMATION_DOCUMENT - PROOF_OF_TAX_IDENTIFICATION - EVIDENCE_OF_DIRECTORS_AND_CONTROLLERS description: Formation document type. example: REGISTRATION_DOCUMENT description: type: string description: Optional human-readable description of this specific document. example: "Certificate of Incorporation" files: type: array description: One or more file URIs obtained from [Upload Document](https://developer.fin.com/api-reference/customers/upload-document) endpoint. minItems: 1 items: type: object required: - uri properties: uri: type: string description: File URI returned by the upload endpoint. example: "/AbAcQ4hn_0652746727639.pdf" V2OwnershipDocumentItem: type: object required: - files properties: type: type: string enum: - OWNERSHIP_INFORMATION - OWNERSHIP_CHART - PROOF_OF_SIGNATORY_AUTHORITY description: Ownership document type. example: OWNERSHIP_INFORMATION description: type: string description: Optional human-readable description of this specific document. example: "Ownership information document" files: type: array description: One or more file URIs obtained from [Upload Document](https://developer.fin.com/api-reference/customers/upload-document) endpoint. minItems: 1 items: type: object required: - uri properties: uri: type: string description: File URI returned by the upload endpoint. example: "/AbAcQ4hn_0652746727639.pdf" V2SupportingDocumentItem: type: object required: - files properties: type: type: string enum: - SHAREHOLDER_REGISTER - PROOF_OF_NATURE_OF_BUSINESS - PROOF_OF_ENTITY_NAME_CHANGE - CERT_OF_INCUMBENCY - PROOF_OF_SOURCE_OF_FUNDS - PROOF_OF_SOURCE_OF_WEALTH - AML_COMFORT_LETTER - MARKETING_MATERIALS - TAX_EXEMPT_ENTITY_CONFIRMATION - E_SIGNATURE_CERTIFICATE - FLOW_OF_FUNDS - PROOF_OF_NATURE_OF_BUSINESS_LICENSE - PROOF_OF_NATURE_OF_BUSINESS_AML_POLICY - EVIDENCE_OF_GOOD_STANDING - PROOF_OF_ACCOUNT_PURPOSE - PROOF_OF_ADDRESS - OTHER description: Supporting document type. example: PROOF_OF_SOURCE_OF_FUNDS description: type: string description: Optional human-readable description of this specific document. example: "Bank statements for the past 6 months" files: type: array description: One or more file URIs obtained from [Upload Document](https://developer.fin.com/api-reference/customers/upload-document) endpoint. minItems: 1 items: type: object required: - uri properties: uri: type: string description: File URI returned by the upload endpoint. example: "/AbAcQ4hn_0652746727639.pdf" AttachDocumentsToAssociatedPartyV2Input: type: object required: - associated_party_attachments properties: associated_party_attachments: type: array description: >- Array of document attachments, one entry per associated party. Multiple parties can be submitted in a single request. minItems: 1 items: $ref: "#/components/schemas/V2AssociatedPartyAttachment" V2AssociatedPartyAttachment: type: object required: - associated_party_id - identifying_documents - address_documents properties: associated_party_id: type: string format: uuid description: >- Unique identifier for the associated party, returned in GET /v2/customers/:customer-id. example: "f6b13e01-044a-4f74-a70b-d5f66b6449af" identifying_documents: type: array description: >- Government-issued identity documents for this party. Multiple documents may be provided (e.g., passport + driver license). NATIONAL_ID and DRIVERS_LICENSE require both FRONT and BACK sides. items: $ref: "#/components/schemas/V2IdentifyingDocumentAttachment" address_documents: type: array description: Proof of address documents. Must be issued within the last 90 days. items: $ref: "#/components/schemas/V2AddressDocumentAttachment" V2IdentifyingDocumentAttachment: type: object required: - type - number - country - issue_date - expiry_date - files properties: type: type: string enum: - PASSPORT - NATIONAL_ID - DRIVERS_LICENSE - RESIDENCE_PERMIT description: | Type of government-issued identity document. At least one identifying document is required. Double-sided documents must include both front and back images. Supported types: - `PASSPORT`: Passport - `NATIONAL_ID`: National ID card - `DRIVERS_LICENSE`: Driver's license - `RESIDENCE_PERMIT`: Residence permit example: PASSPORT number: type: string description: Document number. example: "A12345678" country: $ref: "#/components/schemas/CountryCode" issue_date: type: string format: date description: "Document issue date in YYYY-MM-DD format." example: "2020-01-15" expiry_date: type: string format: date description: "Document expiry date in YYYY-MM-DD format. Must not be expired." example: "2030-01-15" files: type: array description: >- One or more file URIs from [Upload Document](https://developer.fin.com/api-reference/customers/upload-document) endpoint. For NATIONAL_ID and DRIVERS_LICENSE, provide both FRONT and BACK. minItems: 1 items: type: object required: - uri properties: side: type: string enum: - FRONT - BACK description: >- Required for NATIONAL_ID and DRIVERS_LICENSE. Optional for PASSPORT and RESIDENCE_PERMIT. example: FRONT uri: type: string description: File URI returned by the upload endpoint. example: "/AbAcQ4hn_0652746727637.pdf" V2AddressDocumentAttachment: type: object required: - type - files properties: type: type: string enum: - UTILITY_BILL - GOVERNMENT_LETTER - BANK_STATEMENT description: Type of address proof document. Must be within the last 90 days. example: BANK_STATEMENT files: type: array description: One or more file URIs from [Upload Document](https://developer.fin.com/api-reference/customers/upload-document) endpoint. minItems: 1 items: type: object required: - uri properties: uri: type: string description: File URI returned by the upload endpoint. example: "/AbAcQ4hn_0652746727638.pdf" AttachDocumentsToIndividualCustomerV2Input: type: object required: - identifying_documents - address_documents - tos_policies_value properties: identifying_documents: type: array minItems: 1 description: >- Government-issued identity documents. Include at most one non-SELFIE primary document (PASSPORT, NATIONAL_ID, DRIVERS_LICENSE, or RESIDENCE_PERMIT) plus an optional SELFIE entry. NATIONAL_ID, DRIVERS_LICENSE, and RESIDENCE_PERMIT require both FRONT and BACK files. items: $ref: "#/components/schemas/V2IndividualAttachIdentifyingDocument" address_documents: type: array minItems: 1 maxItems: 1 description: Proof of address. Exactly one entry is required. items: $ref: "#/components/schemas/V2IndividualAddressDocument" tos_policies_value: type: string description: >- Parsed from the tos_policies_value query parameter in the tos_policies_url returned by POST /v2/customers/individual. Signifies the customer has accepted the Terms of Service. example: "e9414388-fbdf-4407-b5c2-bc39eae3645b" V2IndividualAttachIdentifyingDocument: type: object required: - type - files allOf: - if: properties: type: const: DRIVERS_LICENSE country: const: USA required: - type - country then: required: - state properties: type: type: string enum: - PASSPORT - NATIONAL_ID - DRIVERS_LICENSE - RESIDENCE_PERMIT - SELFIE description: >- Type of identity document. At most one non-SELFIE document may be included per request. A SELFIE entry carries only `type` and `files`; all other fields are ignored for SELFIE. example: PASSPORT number: type: string description: Document number. Required for all types except SELFIE. example: "A12345678" country: $ref: "#/components/schemas/CountryCode" state: type: string maxLength: 64 description: Document issuing state. Max 64 characters. Required when the type is DRIVERS_LICENSE and country is USA. example: "US-CA" issue_date: type: string format: date description: >- Optional issue date in YYYY-MM-DD format. When provided together with expiry_date, expiry_date must be strictly later. example: "2020-01-15" expiry_date: type: string format: date description: >- Expiry date in YYYY-MM-DD format. Required for all types except SELFIE. Must be in the future. example: "2030-01-15" files: type: array minItems: 1 description: >- File URIs from the [Upload Document](https://developer.fin.com/api-reference/customers/upload-document) endpoint. PASSPORT and SELFIE take a single file; NATIONAL_ID, DRIVERS_LICENSE, and RESIDENCE_PERMIT require one FRONT and one BACK file. File URIs must be unique across the entire request (SELFIE files excluded). items: type: object required: - uri properties: side: type: string enum: - FRONT - BACK description: >- Required for NATIONAL_ID, DRIVERS_LICENSE, and RESIDENCE_PERMIT. Optional for PASSPORT and SELFIE. example: FRONT uri: type: string description: File URI returned by the upload endpoint. example: "/AbAcQ4hn_0652746727637.pdf" V2IndividualAddressDocument: type: object required: - type - country - files properties: type: type: string enum: - UTILITY_BILL - GOVERNMENT_LETTER - BANK_STATEMENT description: Type of address proof document. example: BANK_STATEMENT country: allOf: - $ref: "#/components/schemas/CountryCode" description: >- Country the address document was issued in. Must match the customer's country_of_residence. issue_date: type: string format: date description: Optional issue date in YYYY-MM-DD format. example: "2024-06-15" files: type: array minItems: 1 maxItems: 1 description: >- Exactly one file URI from the [Upload Document](https://developer.fin.com/api-reference/customers/upload-document) endpoint. items: type: object required: - uri properties: side: type: string enum: - FRONT - BACK description: Optional. example: FRONT uri: type: string description: File URI returned by the upload endpoint. example: "/XyZ123mn_0652746727639.pdf" IndividualCustomerData: type: object properties: customer_id: type: string format: uuid example: "c3309534-1517-4d15-b244-be8f943c3823" type: type: string enum: [INDIVIDUAL] customer_status: type: string description: >- V1 statuses: INCOMPLETE, QUEUED, REVIEWING, APPROVED, ON_HOLD, REINITIATE, REJECTED. V2 statuses: INCOMPLETE, PROCESSING, REVIEWING, APPROVED, ACTION_REQUIRED, REJECTED. QUEUED (V1) → PROCESSING (V2). ON_HOLD (V1) → IN_COMPLIANCE (V2). REINITIATE (V1) → ACTION_REQUIRED (V2). enum: - INCOMPLETE - QUEUED - PROCESSING - REVIEWING - APPROVED - ON_HOLD - IN_COMPLIANCE - REINITIATE - ACTION_REQUIRED - REJECTED example: "INCOMPLETE" email: type: string format: email example: "john.doe@email.com" first_name: type: string example: "John" last_name: type: string example: "Doe" phone: type: string example: "+12597751234" country_of_residence: type: string example: "USA" verification_type: type: string enum: - RELIANCE - STANDARD example: "STANDARD" tos_policies_url: type: string example: "25764ef6-0f4f-4846-b7c6-9df0598358e9" created_at: type: string format: date-time updated_at: type: string format: date-time BusinessCustomerData: type: object properties: customer_id: type: string format: uuid example: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" type: type: string enum: [BUSINESS] customer_status: type: string description: >- V1 statuses: INCOMPLETE, QUEUED, REVIEWING, APPROVED, ASSOCIATED_PARTIES_REMAINING, ON_HOLD, REINITIATE, REJECTED. V2 statuses: INCOMPLETE, PROCESSING, REVIEWING, APPROVED, ASSOCIATED_PARTIES_REMAINING, IN_COMPLIANCE, ACTION_REQUIRED, REJECTED. QUEUED (V1) → PROCESSING (V2). ON_HOLD (V1) → IN_COMPLIANCE (V2). REINITIATE (V1) → ACTION_REQUIRED (V2). enum: - INCOMPLETE - QUEUED - PROCESSING - REVIEWING - APPROVED - ASSOCIATED_PARTIES_REMAINING - ON_HOLD - IN_COMPLIANCE - REINITIATE - ACTION_REQUIRED - REJECTED example: "INCOMPLETE" business_name: type: string example: "Fin.com" email: type: string format: email example: "m@tech.com" phone: type: string example: "+8801529876543" country_of_incorporation: type: string example: "BGD" verification_type: type: string enum: - RELIANCE - STANDARD example: "RELIANCE" tos_policies_url: type: string associated_parties: type: array items: type: object properties: id: type: string format: uuid email: type: string format: email type: type: string enum: [INDIVIDUAL] ownership_percent: type: number example: 52 verification: type: object properties: status: type: string enum: - INITIATED - PENDING_REVIEW - APPROVED - REJECTED - ON_HOLD updated_at: type: string format: date-time reason: type: object properties: for_customer: type: string nullable: true for_developer: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time VirtualAccountV2StatusWebhookData: type: object properties: id: type: string format: uuid example: "ed96d65a-5fb1-49f2-8715-0c6aa32220ca" rfi: type: object nullable: true example: null status: type: string enum: [PROCESSING, IN_COMPLIANCE, REQUEST_FOR_INFORMATION, ACTIVE, INACTIVE, DECLINED] example: "ACTIVE" created_at: type: string format: date-time example: "2026-03-17T14:27:49.073891Z" updated_at: type: string format: date-time example: "2026-03-17T14:42:55.788231316Z" customer_id: type: string format: uuid example: "c3088a8d-50de-48cf-a137-8d46815394f8" destination: type: object properties: address: type: string example: "0x7f1568190e318da16a9ef5a46cba19d5b97d9b29" currency: type: string example: "USDC" destination_chain: type: string example: "POLYGON" developer_fee_fixed: type: number example: 0.22 deposit_instructions: type: object nullable: true properties: currency: type: string example: "USD" bank_code: type: object properties: code: type: string example: "SSBAUS32" type: type: string example: "SWIFT" bank_name: type: string example: "SSB Bank" account_type: type: string example: "BankSwift" bank_address: type: string nullable: true example: null bank_country: type: string example: "USA" payment_rails: type: array items: type: string example: ["ACH"] bank_account_number: type: string example: "235464829825" bank_routing_number: type: string example: "" developer_fee_percent: type: number example: 0 VirtualAccountV3: type: object description: >- A virtual account and the instructions needed to fund it. Returned by both List Virtual Accounts and Get Virtual Account Details. properties: id: type: string format: uuid description: Unique identifier of the virtual account. example: "b84f17e1-96a8-4034-8394-e902ed403d96" status: type: string enum: [PROCESSING, IN_COMPLIANCE, REQUEST_FOR_INFORMATION, ACTIVE, INACTIVE, DECLINED] description: >- Current state of the virtual account. `deposit_instructions` stays null until the banking partner issues the account and the status becomes `ACTIVE`. example: "ACTIVE" developer_fee_percent: type: number nullable: true description: Percentage fee applied on top of each deposit. example: 2 developer_fee_fixed: type: number nullable: true description: Fixed fee applied on top of each deposit. example: 2 customer_id: type: string format: uuid description: Customer the virtual account belongs to. example: "f60b6730-1bf1-4efa-a49e-be5ef5e75bb8" created_at: type: string format: date-time example: "2026-09-09T12:27:57.657953Z" updated_at: type: string format: date-time example: "2026-09-09T12:28:11.061185Z" deposit_instructions: $ref: "#/components/schemas/VirtualAccountDepositInstructions" destination: $ref: "#/components/schemas/VirtualAccountDestination" rfi: type: object nullable: true description: Populated only when the status is `REQUEST_FOR_INFORMATION`. example: null bank: type: string enum: [SSB, PORTAGE] description: Banking partner that issued the virtual account. example: "PORTAGE" VirtualAccountDepositInstructions: type: object nullable: true description: >- Bank details the customer deposits into. Null until the banking partner issues the account. Which fields are populated depends on the payment rail, so fields that do not apply to the rail are returned as null. properties: currency: type: string description: Fiat currency the account accepts. example: "USD" bank_name: type: string example: "Portage Bank" bank_address: type: string nullable: true example: "880 108th Ave NE, Bellevue, WA 98004, US" bank_routing_number: type: string nullable: true description: Domestic routing number. Null for rails that do not use one, such as SWIFT. example: null bank_account_number: type: string example: "531912465" bank_beneficiary_name: type: string nullable: true description: Name the deposit must be made out to. example: "WeiMing Tan" bank_beneficiary_address: type: string nullable: true example: null payment_rails: type: array description: Fiat rails the account can be funded over. items: type: string enum: [ACH, FEDWIRE, SWIFT] example: ["SWIFT"] bank_country: type: string nullable: true description: Country of the receiving bank, ISO 3166-1 alpha-3. example: null account_type: type: string nullable: true example: null bank_code: type: object nullable: true description: Clearing or identifier code for the receiving bank. properties: type: type: string enum: [ACH, FEDWIRE, SWIFT, BIC] description: Code scheme the value in `code` belongs to. example: "BIC" code: type: string example: "PORGUS62XXX" bic_swift: type: string nullable: true description: BIC of the receiving bank. Used for SWIFT deposits. example: "PORGUS62XXX" VirtualAccountDestination: type: object description: Crypto destination the deposits settle to. properties: currency: type: string enum: [USDC, USDT] description: Token delivered to the destination wallet. example: "USDC" destination_chain: type: string enum: [POLYGON, ETHEREUM, SOLANA, BASE] description: Blockchain network the destination wallet is on. example: "ETHEREUM" address: type: string description: Destination wallet address. example: "0xE6F46b9Fa4Bc867816f78323EC92887E9d325DbE" BeneficiaryWebhookData: type: object properties: beneficiary_id: type: string format: uuid example: "e8fccaeb-fb9d-4fae-846e-ea7c97c70b31" customer_id: type: string format: uuid example: "ecbd3a73-3bcb-40ae-be06-0e71f9b27c2f" type: type: string enum: - INDIVIDUAL - BUSINESS example: "INDIVIDUAL" active: type: boolean example: true status: type: string enum: - PROCESSING - ACTIVE - INACTIVE - REJECTED example: "ACTIVE" Pagination: type: object properties: current_page: type: integer example: 1 per_page: type: integer example: 10 total_page: type: integer example: 1 total: type: integer example: 10 VirtualAccount: type: object required: - id - status - developer_fee_percent - customer_id - created_at - updated_at - deposit_instructions - destination properties: id: type: string format: uuid example: "92eceee4-ec6a-4fe3-a224-f5914cabe001" status: type: string example: "ACTIVE" developer_fee_percent: type: number example: 1.65 customer_id: type: string format: uuid example: "196ce546-900d-4294-90ca-5546a5923f35" created_at: type: string format: date-time example: "2025-12-22T06:09:23.456895Z" updated_at: type: string format: date-time example: "2025-12-22T06:09:23.456895Z" deposit_instructions: type: object properties: currency: type: string example: "USD" bank_name: type: string example: "Bank of Nowhere" bank_address: type: string example: "1800 North Pole St., Orlando, FL 32801" bank_routing_number: type: string example: "101019644" bank_account_number: type: string example: "900336047672" bank_beneficiary_name: type: string example: "Portgas D Ace" bank_beneficiary_address: type: string example: "321 British Columbia City, British Columbia, BC V0C 1Y0, CA" payment_rails: type: array items: type: string example: ["ACH", "FEDWIRE"] destination: type: object properties: currency: type: string enum: - USDC default: USDC destination_chain: type: string enum: - POLYGON - ETHEREUM address: type: string example: "0x7f1568190e318da16a9ef5a46cba19d5b97d9b29" responses: AuthenticationError: description: Authentication failed due to invalid credentials content: application/json: schema: type: object properties: message: type: string example: "Authentication failed" ValidationError: description: Failed due to a formatting error. content: application/json: schema: type: object required: - message properties: message: type: string errors: type: array items: type: object additionalProperties: type: string NotFoundError: description: Resource not found content: application/json: schema: type: object properties: message: type: string example: "Resource not found" securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Bearer token authentication. Obtain token from [Issue a Token](https://developer.fin.com/api-reference/authentication/issue-a-token) endpoint # ───────────────────────────────────────────────────────────────────────────── # WEBHOOKS # # Each event defines its own "event" envelope inline, with a type enum holding # exactly one value: that event's own name. Do not replace these with a $ref to a # shared envelope schema. A shared envelope has to list every event name in its # type enum, so every webhook page then advertises all of them as available # options for its own event.type. That was the case until 2026-09-14; the old # shared schema is parked in _scratch/disabled-operations.yaml. # # The five envelope fields (id, event_reference_id, type, created_at, # sandbox_mode) are therefore repeated per event. If one of them changes, it has # to change in every event below. # ───────────────────────────────────────────────────────────────────────────── webhooks: customer.created: post: summary: Customer Created description: Triggered when a customer is successfully created. x-mint: metadata: title: customer.created content: | Triggered when a customer is successfully created. Supports both `INDIVIDUAL` and `BUSINESS` customer types. All webhook requests include HMAC signatures for verification. Learn how to [verify webhook signatures](/guides/webhooks/verifying-webhooks). tags: - Webhooks requestBody: required: true content: application/json: schema: type: object properties: event: type: object required: - id - event_reference_id - type - created_at - sandbox_mode properties: id: type: string format: uuid example: "60bef15c-4e30-4eb4-bc4d-aa697a7e0857" event_reference_id: type: string format: uuid example: "c3309534-1517-4d15-b244-be8f943c3823" type: type: string enum: - customer.created example: "customer.created" created_at: type: string format: date-time example: "2025-11-30T07:40:06.853938Z" sandbox_mode: type: boolean example: true data: oneOf: - $ref: "#/components/schemas/IndividualCustomerData" - $ref: "#/components/schemas/BusinessCustomerData" examples: individualCreated: summary: Individual Customer Created value: event: id: "60bef15c-4e30-4eb4-bc4d-aa697a7e0857" event_reference_id: "c3309534-1517-4d15-b244-be8f943c3823" type: "customer.created" created_at: "2025-11-30T07:40:06.853938Z" sandbox_mode: true data: country_of_residence: "USA" created_at: "2025-11-30T07:40:06Z" customer_id: "c3309534-1517-4d15-b244-be8f943c3823" customer_status: "INCOMPLETE" email: "john.doe@email.com" first_name: "John" last_name: "Doe" phone: "+12597751234" tos_policies_url: "25764ef6-0f4f-4846-b7c6-9df0598358e9" type: "INDIVIDUAL" verification_type: "RELIANCE" businessCreated: summary: Business Customer Created value: event: id: "d2a592e4-5703-46aa-b1ac-fa1fa6359abf" event_reference_id: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" type: "customer.created" created_at: "2026-04-13T11:38:57.819938Z" sandbox_mode: false data: associated_parties: - email: "fatima.rahman22@acmecorp.com.bd" id: "f6b13e01-044a-4f74-a70b-d5f66b6449af" ownership_percent: 60 type: "INDIVIDUAL" verification: reason: for_customer: null for_developer: null status: "INITIATED" updated_at: "2026-04-13T11:38:57.824452053Z" - email: "karim.islam22@acmecorp.com.bd" id: "f71dc19f-b9a0-49fb-bd2d-5add3c01626e" ownership_percent: 40 type: "INDIVIDUAL" verification: reason: for_customer: null for_developer: null status: "INITIATED" updated_at: "2026-04-13T11:38:57.824452053Z" business_name: "Fin.com" country_of_incorporation: "BGD" created_at: "2026-04-13T11:38:57Z" customer_id: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" customer_status: "INCOMPLETE" email: "m@tech.com" phone: "+8801529876543" type: "BUSINESS" verification_type: "STANDARD" responses: "200": description: Webhook received successfully customer.status: post: summary: Customer Status description: Triggered when a customer's status changes during verification. x-mint: metadata: title: customer.status content: | ### Customer Status Values The status values in the payload depend on which API version was used to create the customer. V1 and V2 use different status names for the same underlying states. V1 has not been deprecated and both sets of statuses are active. | Status | V1 Name | V2 Name | Description | |--------|---------|---------|-------------| | Awaiting processing | `QUEUED` | `PROCESSING` | Verification request sent to the work processor | | Under review | `REVIEWING` | `REVIEWING` | Customer verification is currently under review | | Verified | `APPROVED` | `APPROVED` | Successfully verified and approved | | Parties pending | `ASSOCIATED_PARTIES_REMAINING` | `ASSOCIATED_PARTIES_REMAINING` | Additional associated parties need verification | | Paused | `ON_HOLD` | `IN_COMPLIANCE` | Verification paused for compliance review | | Action needed | `REINITIATE` | `ACTION_REQUIRED` | New document upload required | | Rejected | `REJECTED` | `REJECTED` | Customer verification rejected | `ACTION_REQUIRED` (V2) is also set by the `customer.rfi` webhook, which includes a structured payload describing exactly which documents or fields are missing or invalid. All webhook requests include HMAC signatures for verification. tags: - Webhooks requestBody: required: true content: application/json: schema: type: object properties: event: type: object required: - id - event_reference_id - type - created_at - sandbox_mode properties: id: type: string format: uuid example: "60bef15c-4e30-4eb4-bc4d-aa697a7e0857" event_reference_id: type: string format: uuid example: "c3309534-1517-4d15-b244-be8f943c3823" type: type: string enum: - customer.status example: "customer.status" created_at: type: string format: date-time example: "2025-11-30T07:40:06.853938Z" sandbox_mode: type: boolean example: true data: oneOf: - $ref: "#/components/schemas/IndividualCustomerData" - $ref: "#/components/schemas/BusinessCustomerData" examples: v1IndividualQueued: summary: "V1: Individual Customer Queued" value: event: id: "29ceb6c4-4849-4312-9b2b-5e8360647da0" event_reference_id: "f9e1b162-8a05-4611-9e13-f38e0eb24a29" type: "customer.status" created_at: "2026-01-18T09:08:18.66348Z" sandbox_mode: true data: customer_id: "f9e1b162-8a05-4611-9e13-f38e0eb24a29" customer_status: "QUEUED" email: "john.doe@acmecorp.com" first_name: "John" last_name: "Doe" type: "INDIVIDUAL" verification_type: "STANDARD" v1BusinessOnHold: summary: "V1: Business Customer On Hold" value: event: id: "0deacdde-cd58-42ea-8a1c-dde8668a92e4" event_reference_id: "98665e7d-7736-4762-a57a-cc1e6706302f" type: "customer.status" created_at: "2026-01-18T10:32:59.434557Z" sandbox_mode: true data: business_name: "Acme Corp Ltd" country_of_incorporation: "USA" customer_id: "98665e7d-7736-4762-a57a-cc1e6706302f" customer_status: "ON_HOLD" email: "contact@acmecorp.com" type: "BUSINESS" verification_type: "STANDARD" v1BusinessReinitiate: summary: "V1: Business Customer Reinitiate" value: event: id: "c8f2a5b1-3e4d-4a9c-b7e2-d1f3c8a9b0e5" event_reference_id: "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" type: "customer.status" created_at: "2026-01-20T14:15:30.123456Z" sandbox_mode: true data: business_name: "Acme Corp Ltd" country_of_incorporation: "USA" customer_id: "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" customer_status: "REINITIATE" email: "contact@acmecorp.com" type: "BUSINESS" verification_type: "STANDARD" v2IndividualProcessing: summary: "V2: Individual Customer Processing" value: event: id: "3a4b5c6d-7e8f-9012-abcd-ef1234567890" event_reference_id: "f9e1b162-8a05-4611-9e13-f38e0eb24a29" type: "customer.status" created_at: "2026-04-04T09:08:18.66348Z" sandbox_mode: false data: customer_id: "f9e1b162-8a05-4611-9e13-f38e0eb24a29" customer_status: "PROCESSING" email: "john.doe@acmecorp.com" first_name: "John" last_name: "Doe" type: "INDIVIDUAL" verification_type: "STANDARD" v2BusinessInCompliance: summary: "V2: Business Customer In Compliance" value: event: id: "0deacdde-cd58-42ea-8a1c-dde8668a92e4" event_reference_id: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" type: "customer.status" created_at: "2026-04-13T11:40:51.434557Z" sandbox_mode: false data: business_name: "Fin.com" country_of_incorporation: "BGD" customer_id: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" customer_status: "IN_COMPLIANCE" email: "m@tech.com" type: "BUSINESS" verification_type: "STANDARD" v2BusinessActionRequired: summary: "V2: Business Customer Action Required" value: event: id: "f1e2d3c4-b5a6-7890-cdef-123456789012" event_reference_id: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" type: "customer.status" created_at: "2026-04-13T11:40:51.000000Z" sandbox_mode: false data: business_name: "Fin.com" country_of_incorporation: "BGD" customer_id: "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" customer_status: "ACTION_REQUIRED" email: "m@tech.com" type: "BUSINESS" verification_type: "STANDARD" responses: "200": description: Webhook received successfully customer.rfi: post: summary: Customer RFI description: >- 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. x-mint: metadata: title: customer.rfi content: | ### When This Fires This webhook fires when compliance flags one or more documents or fields as missing, expired, or invalid. The customer status will be set to `ACTION_REQUIRED`. An RFI can also be triggered after a customer is already `APPROVED`. In that case the customer status remains unchanged. Only the `rrequest_for_information` object in the payload will contain data and this webhook will be received. ### RFI Available Scope - **CUSTOMER**: The issue is with the customer's own documents or data - **ASSOCIATED PARTY**: The issue is with a specific associated party (identified by `associated_party_id`) ### Field Status Values - **MISSING**: Document or field was not provided - **EXPIRED**: Document has passed its expiry date - **INVALID**: Document or field value does not meet requirements (see `reason`) ### Section Values by Customer Type | Customer Type | Sections | |---------------|----------| | Individual | `proof_of_identity`, `proof_of_address`, `tos_policies_value` | | Business V1 | `company_details`, `ownership_structure`, `legal_presence` | | Business V2 | `formation_documents`, `ownership_documents`, `supporting_documents` | | Associated Party (V1) | `proof_of_identity`, `proof_of_address` | | Associated Party (V2) | `identifying_documents`, `tax_info`, `address_documents` | All webhook requests include HMAC signatures for verification. tags: - Webhooks requestBody: required: true content: application/json: schema: type: object properties: event: type: object required: - id - event_reference_id - type - created_at - sandbox_mode properties: id: type: string format: uuid example: "60bef15c-4e30-4eb4-bc4d-aa697a7e0857" event_reference_id: type: string format: uuid example: "c3309534-1517-4d15-b244-be8f943c3823" type: type: string enum: - customer.rfi example: "customer.rfi" created_at: type: string format: date-time example: "2025-11-30T07:40:06.853938Z" sandbox_mode: type: boolean example: true data: type: object required: - customer_id - request_for_information properties: customer_id: type: string format: uuid description: The customer for whom information is requested. example: "cust-uuid-1234" request_for_information: type: array description: List of document or field issues that must be resolved. items: type: object required: - section - categories properties: section: type: string description: >- The document section with the issue. 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. example: "proof_of_identity" categories: type: array items: type: object required: - document_type - fields properties: document_type: type: string description: The type of document with the issue. example: "GOVERNMENT_ID" fields: type: array items: type: object required: - field_name - data_type - status properties: field_name: type: string description: The specific field with the issue. example: "files" data_type: type: string enum: [URI, DATE, TEXT, ENUM] description: The data type of the field. example: "URI" status: type: string enum: [MISSING, EXPIRED, INVALID] description: The nature of the issue. example: "EXPIRED" side: type: string enum: [FRONT, BACK] nullable: true description: >- For file fields only. Indicates which side of the document is affected. Null for non-file fields. example: "FRONT" reason: type: string nullable: true description: Human-readable explanation. Null when status is MISSING. example: "Document has expired" examples: individual: summary: Individual Customer RFI value: event: id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" event_reference_id: "cust-uuid-1234" type: "customer.rfi" created_at: "2026-04-04T10:00:00.000000Z" sandbox_mode: false data: customer_id: "cust-uuid-1234" request_for_information: - section: "proof_of_identity" categories: - document_type: "GOVERNMENT_ID" fields: - field_name: "files" data_type: "URI" status: "EXPIRED" reason: "Document has expired" side: "FRONT" - field_name: "files" data_type: "URI" status: "INVALID" reason: "Back side damaged" side: "BACK" - field_name: "issue_date" data_type: "DATE" status: "MISSING" reason: null - field_name: "expiry_date" data_type: "DATE" status: "MISSING" reason: null - field_name: "text" data_type: "TEXT" status: "INVALID" reason: "Name mismatch" - section: "proof_of_address" categories: - document_type: "PROOF_OF_ADDRESS" fields: - field_name: "files" data_type: "URI" status: "MISSING" reason: null - section: "tos_policies_value" categories: - document_type: "TOS" fields: - field_name: "tos_policies_value" data_type: "TEXT" status: "MISSING" reason: null businessV1: summary: Business Customer V1 RFI value: event: id: "b2c3d4e5-f6a7-8901-bcde-f12345678901" event_reference_id: "biz-uuid-5678" type: "customer.rfi" created_at: "2026-04-04T10:00:00.000000Z" sandbox_mode: false data: customer_id: "biz-uuid-5678" request_for_information: - section: "company_details" categories: - document_type: "CERT_OF_INCORPORATION" fields: - field_name: "files" data_type: "URI" status: "INVALID" reason: "Document is illegible" side: "FRONT" - field_name: "text" data_type: "TEXT" status: "INVALID" reason: "Business name mismatch" - section: "ownership_structure" categories: - document_type: "SHAREHOLDER_REGISTRY" fields: - field_name: "files" data_type: "URI" status: "MISSING" reason: null - section: "legal_presence" categories: - document_type: "PROOF_OF_ADDRESS" fields: - field_name: "files" data_type: "URI" status: "MISSING" reason: null - section: "proof_of_identity" categories: - document_type: "GOVERNMENT_ID" fields: - field_name: "files" data_type: "URI" status: "EXPIRED" reason: "Document expired" side: "FRONT" - field_name: "files" data_type: "URI" status: "INVALID" reason: "Back side blurry" side: "BACK" - field_name: "issue_date" data_type: "DATE" status: "MISSING" reason: null - field_name: "expiry_date" data_type: "DATE" status: "MISSING" reason: null - field_name: "text" data_type: "TEXT" status: "INVALID" reason: "Name mismatch" - section: "proof_of_address" categories: - document_type: "PROOF_OF_ADDRESS" fields: - field_name: "files" data_type: "URI" status: "MISSING" reason: null businessV2: summary: Business Customer V2 RFI value: event: id: "c3d4e5f6-a7b8-9012-cdef-123456789012" event_reference_id: "biz-uuid-9999" type: "customer.rfi" created_at: "2026-04-04T10:00:00.000000Z" sandbox_mode: false data: customer_id: "biz-uuid-9999" request_for_information: - section: "formation_documents" categories: - document_type: "CERT_OF_INCORPORATION" fields: - field_name: "files" data_type: "URI" status: "INVALID" reason: "Document illegible" side: "FRONT" - field_name: "text" data_type: "TEXT" status: "INVALID" reason: "Registration number mismatch" - section: "ownership_documents" categories: - document_type: "SHAREHOLDER_REGISTRY" fields: - field_name: "files" data_type: "URI" status: "MISSING" reason: null - section: "supporting_documents" categories: - document_type: "PROOF_OF_ADDRESS" fields: - field_name: "files" data_type: "URI" status: "MISSING" reason: null - section: "identifying_documents" categories: - document_type: "GOVERNMENT_ID" fields: - field_name: "files" data_type: "URI" status: "EXPIRED" reason: "ID expired" side: "FRONT" - field_name: "files" data_type: "URI" status: "INVALID" reason: "Back side damaged" side: "BACK" - field_name: "issue_date" data_type: "DATE" status: "MISSING" reason: null - field_name: "expiry_date" data_type: "DATE" status: "MISSING" reason: null - field_name: "text" data_type: "TEXT" status: "INVALID" reason: "Name mismatch" - section: "tax_info" categories: - document_type: "GOVERNMENT_ID" fields: - field_name: "files" data_type: "URI" status: "MISSING" reason: null - field_name: "text" data_type: "TEXT" status: "INVALID" reason: "Tax ID mismatch" - section: "address_documents" categories: - document_type: "PROOF_OF_ADDRESS" fields: - field_name: "files" data_type: "URI" status: "MISSING" reason: null responses: "200": description: Webhook received successfully transaction.status: post: summary: Transaction Status description: Triggered when a transaction's status changes. x-mint: metadata: title: transaction.status content: | Transaction types: `ONRAMP`, `OFFRAMP`, `CRYPTO_DEPOSIT`, `CRYPTO_WITHDRAWAL` Common status values: `FUNDS_RECEIVED`, `PROCESSING`, `COMPLETED`, `FAILED`, `REFUNDED` All webhook requests include HMAC signatures for verification. tags: - Webhooks requestBody: required: true content: application/json: schema: type: object properties: event: type: object required: - id - event_reference_id - type - created_at - sandbox_mode properties: id: type: string format: uuid example: "60bef15c-4e30-4eb4-bc4d-aa697a7e0857" event_reference_id: type: string format: uuid example: "c3309534-1517-4d15-b244-be8f943c3823" type: type: string enum: - transaction.status example: "transaction.status" created_at: type: string format: date-time example: "2025-11-30T07:40:06.853938Z" sandbox_mode: type: boolean example: true data: type: object properties: id: type: string format: uuid example: "53003b38-8f34-468d-9a40-1ec9abd0b0da" status: type: string enum: - FUNDS_RECEIVED - PROCESSING - COMPLETED - FAILED - CANCELLED example: "COMPLETED" beneficiary_id: type: string format: uuid example: null from_amount: type: number example: 6 from_currency: type: string example: "USD" payout_amount: type: number example: 3.934 payout_currency: type: string example: "USDC" processing_amount: type: number example: 6 fx_rate: type: number example: 1 developer_fee: type: number example: 1.06 developer_fee_fixed: type: number example: 1 developer_fee_percentage: type: number example: 1 hash: type: string example: "0xbe69b3602a5abc54d9616b13114060ec029b66afd3f3c156e5979b9434b4b48c" transaction_ref_id: type: string example: "b23cf755-bc0a-4cef-a5cb-939f651dc0c6" virtual_account_id: type: string format: uuid nullable: true description: Virtual account that received the deposit. Populated on ONRAMP transactions. example: "1ce59fee-a6ed-476f-9952-1719ea38ed91" batch_info: type: object description: Batch this transaction belongs to. Both fields are null when it is not part of a batch. properties: batch_id: type: string format: uuid nullable: true batch_item_id: type: string format: uuid nullable: true transaction_type: type: string description: "Possible values: `ONRAMP`, `OFFRAMP`, `CRYPTO_DEPOSIT`, `CRYPTO_WITHDRAWAL`" example: "ONRAMP" created_at: type: string format: date-time example: "2026-09-14T11:55:08.717927Z" updated_at: type: string format: date-time example: "2026-09-14T11:59:38.024335243Z" examples: completed: summary: Completed value: data: id: "53003b38-8f34-468d-9a40-1ec9abd0b0da" hash: "0xbe69b3602a5abc54d9616b13114060ec029b66afd3f3c156e5979b9434b4b48c" status: "COMPLETED" fx_rate: 1 batch_info: batch_id: null batch_item_id: null created_at: "2026-09-14T11:55:08.717927Z" updated_at: "2026-09-14T11:59:38.024335243Z" from_amount: 6 developer_fee: 1.06 from_currency: "USD" payout_amount: 3.934 beneficiary_id: null payout_currency: "USDC" transaction_type: "ONRAMP" processing_amount: 6 transaction_ref_id: "b23cf755-bc0a-4cef-a5cb-939f651dc0c6" virtual_account_id: "1ce59fee-a6ed-476f-9952-1719ea38ed91" developer_fee_fixed: 1 developer_fee_percentage: 1 event: id: "e16fa3ca-fb51-4e64-8fc2-7e3c8cc101af" type: "transaction.status" created_at: "2026-09-14T11:59:38.081148Z" sandbox_mode: true event_reference_id: "53003b38-8f34-468d-9a40-1ec9abd0b0da" responses: "200": description: Webhook received successfully virtual_account.created.v2: post: summary: Virtual Account Created V2 description: Triggered when a new V2 virtual account is created for a customer. x-mint: metadata: title: virtual_account.created V2 content: | The account starts in `PROCESSING` status. `deposit_instructions` will be null until the account becomes active. Register this webhook if you are using the **Create Virtual Account** endpoint. All webhook requests include HMAC signatures for verification. tags: - Webhooks requestBody: required: true content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/VirtualAccountV2StatusWebhookData" event: type: object required: - id - event_reference_id - type - created_at - sandbox_mode properties: id: type: string format: uuid example: "60bef15c-4e30-4eb4-bc4d-aa697a7e0857" event_reference_id: type: string format: uuid example: "c3309534-1517-4d15-b244-be8f943c3823" type: type: string enum: - virtual_account.created.v2 example: "virtual_account.created.v2" created_at: type: string format: date-time example: "2025-11-30T07:40:06.853938Z" sandbox_mode: type: boolean example: true examples: created: summary: Virtual Account Created value: data: id: "86b7730c-1a8b-43f9-83f6-60a60dfcb513" rfi: null status: "PROCESSING" created_at: "2026-04-03T16:46:22.089047Z" updated_at: "2026-04-03T16:46:22.089047Z" customer_id: "b22667c0-3e75-467f-9dc6-9739c348bc1a" destination: address: "0x6e41e83d406185b358bd72111ab1206cb82eb67f" currency: "USDC" destination_chain: "POLYGON" developer_fee_fixed: 0.1 deposit_instructions: null developer_fee_percent: 0.1 event: id: "7b86dec8-34eb-4c48-9780-6a69037d4c05" type: "virtual_account.created.v2" created_at: "2026-04-03T16:46:22.117583Z" sandbox_mode: true event_reference_id: "86b7730c-1a8b-43f9-83f6-60a60dfcb513" responses: "200": description: Webhook received successfully virtual_account.status.v2: post: summary: Virtual Account Status V2 description: Triggered when a V2 virtual account’s status changes. x-mint: metadata: title: virtual_account.status V2 content: | Possible status values: `PROCESSING`, `IN_COMPLIANCE`, `REQUEST_FOR_INFORMATION`, `ACTIVE`, `INACTIVE`, `DECLINED` Register this webhook if you are using the **Create Virtual Account** endpoint. All webhook requests include HMAC signatures for verification. tags: - Webhooks requestBody: required: true content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/VirtualAccountV2StatusWebhookData" event: type: object required: - id - event_reference_id - type - created_at - sandbox_mode properties: id: type: string format: uuid example: "60bef15c-4e30-4eb4-bc4d-aa697a7e0857" event_reference_id: type: string format: uuid example: "c3309534-1517-4d15-b244-be8f943c3823" type: type: string enum: - virtual_account.status.v2 example: "virtual_account.status.v2" created_at: type: string format: date-time example: "2025-11-30T07:40:06.853938Z" sandbox_mode: type: boolean example: true examples: statusChanged: summary: Virtual Account Status Changed value: data: id: "ed96d65a-5fb1-49f2-8715-0c6aa32220ca" rfi: null status: "ACTIVE" created_at: "2026-03-17T14:27:49.073891Z" updated_at: "2026-03-17T14:42:55.788231316Z" customer_id: "c3088a8d-50de-48cf-a137-8d46815394f8" destination: address: "0x7f1568190e318da16a9ef5a46cba19d5b97d9b29" currency: "USDC" destination_chain: "POLYGON" developer_fee_fixed: 0.22 deposit_instructions: currency: "USD" bank_code: code: "SSBAUS32" type: "SWIFT" bank_name: "SSB Bank" account_type: "BankSwift" bank_address: null bank_country: "USA" payment_rails: - "ACH" bank_account_number: "235464829825" bank_routing_number: "" developer_fee_percent: 0 event: id: "8c236a87-4ab2-49af-b22f-02d1d8e12cfa" type: "virtual_account.status.v2" created_at: "2026-03-17T14:42:55.813225Z" sandbox_mode: true event_reference_id: "ed96d65a-5fb1-49f2-8715-0c6aa32220ca" responses: "200": description: Webhook received successfully beneficiary.created: post: summary: Beneficiary Created description: Triggered when a new beneficiary is created in the system. x-mint: metadata: title: beneficiary.created content: | All webhook requests include HMAC signatures for verification. tags: - Webhooks requestBody: required: true content: application/json: schema: type: object properties: event: type: object required: - id - event_reference_id - type - created_at - sandbox_mode properties: id: type: string format: uuid example: "60bef15c-4e30-4eb4-bc4d-aa697a7e0857" event_reference_id: type: string format: uuid example: "c3309534-1517-4d15-b244-be8f943c3823" type: type: string enum: - beneficiary.created example: "beneficiary.created" created_at: type: string format: date-time example: "2025-11-30T07:40:06.853938Z" sandbox_mode: type: boolean example: true data: $ref: "#/components/schemas/BeneficiaryWebhookData" examples: individualCreated: summary: Individual Beneficiary Created value: event: id: "85804b3a-bf18-4d87-94f3-f7c45e66868e" event_reference_id: "4d715f20-f704-45e0-af56-19ade318e852" type: "beneficiary.created" created_at: "2025-12-10T10:36:18.279837Z" sandbox_mode: true data: active: true beneficiary_id: "4d715f20-f704-45e0-af56-19ade318e852" customer_id: "efb54adf-b7f4-4716-80e3-806e11f20b7b" type: "INDIVIDUAL" responses: "200": description: Webhook received successfully beneficiary.status: post: summary: Beneficiary Status description: Triggered when a beneficiary's status changes. x-mint: metadata: title: beneficiary.status content: | ### Beneficiary Status Values - **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 All webhook requests include HMAC signatures for verification. tags: - Webhooks requestBody: required: true content: application/json: schema: type: object properties: event: type: object required: - id - event_reference_id - type - created_at - sandbox_mode properties: id: type: string format: uuid example: "60bef15c-4e30-4eb4-bc4d-aa697a7e0857" event_reference_id: type: string format: uuid example: "c3309534-1517-4d15-b244-be8f943c3823" type: type: string enum: - beneficiary.status example: "beneficiary.status" created_at: type: string format: date-time example: "2025-11-30T07:40:06.853938Z" sandbox_mode: type: boolean example: true data: $ref: "#/components/schemas/BeneficiaryWebhookData" examples: processing: summary: Beneficiary Processing value: event: id: "40061557-f125-4b39-97d6-c16a0f1230c1" event_reference_id: "e8fccaeb-fb9d-4fae-846e-ea7c97c70b31" type: "beneficiary.status" created_at: "2026-04-04T17:38:26.843132Z" sandbox_mode: true data: type: "INDIVIDUAL" active: false status: "PROCESSING" customer_id: "ecbd3a73-3bcb-40ae-be06-0e71f9b27c2f" beneficiary_id: "e8fccaeb-fb9d-4fae-846e-ea7c97c70b31" active: summary: Beneficiary Active value: event: id: "50072668-a236-5c40-08e7-d27b1g2341d2" event_reference_id: "e8fccaeb-fb9d-4fae-846e-ea7c97c70b31" type: "beneficiary.status" created_at: "2026-04-04T17:39:10.123456Z" sandbox_mode: true data: type: "INDIVIDUAL" active: true status: "ACTIVE" customer_id: "ecbd3a73-3bcb-40ae-be06-0e71f9b27c2f" beneficiary_id: "e8fccaeb-fb9d-4fae-846e-ea7c97c70b31" inactive: summary: Beneficiary Inactive value: event: id: "60083779-b347-6d51-19f8-e38c2h3452e3" event_reference_id: "e8fccaeb-fb9d-4fae-846e-ea7c97c70b31" type: "beneficiary.status" created_at: "2026-04-05T08:00:00.000000Z" sandbox_mode: false data: type: "INDIVIDUAL" active: false status: "INACTIVE" customer_id: "ecbd3a73-3bcb-40ae-be06-0e71f9b27c2f" beneficiary_id: "e8fccaeb-fb9d-4fae-846e-ea7c97c70b31" rejected: summary: Beneficiary Rejected value: event: id: "70094880-c458-7e62-20g9-f49d3i4563f4" event_reference_id: "e8fccaeb-fb9d-4fae-846e-ea7c97c70b31" type: "beneficiary.status" created_at: "2026-04-05T09:00:00.000000Z" sandbox_mode: false data: type: "INDIVIDUAL" active: false status: "REJECTED" customer_id: "ecbd3a73-3bcb-40ae-be06-0e71f9b27c2f" beneficiary_id: "e8fccaeb-fb9d-4fae-846e-ea7c97c70b31" responses: "200": description: Webhook received successfully beneficiary.liquidation.deposit: post: summary: Beneficiary Liquidation Deposit description: Triggered when any transfer hits a beneficiary's liquidation address. x-mint: metadata: title: beneficiary.liquidation.deposit content: | All webhook requests include HMAC signatures for verification. tags: - Webhooks requestBody: required: true content: application/json: schema: type: object properties: event: type: object required: - id - event_reference_id - type - created_at - sandbox_mode properties: id: type: string format: uuid example: "60bef15c-4e30-4eb4-bc4d-aa697a7e0857" event_reference_id: type: string format: uuid example: "c3309534-1517-4d15-b244-be8f943c3823" type: type: string enum: - beneficiary.liquidation.deposit example: "beneficiary.liquidation.deposit" created_at: type: string format: date-time example: "2025-11-30T07:40:06.853938Z" sandbox_mode: type: boolean example: true data: type: object properties: active: type: boolean example: true amount: type: number example: 3 beneficiary_id: type: string format: uuid example: "5b4ea7ee-9d40-44b3-b857-dd5a890b9313" customer_id: type: string format: uuid example: "bea5a6c1-0611-44c6-8c29-a6608e76916c" liquidation_address: type: string example: "0xade8141fd1aef58dc0a5365a32a6cfe95904c08f" txn_hash: type: string example: "0x7808238a69057600f0c8e291ffbfde87a74fb81b32fc583231352147770e2751" type: type: string enum: - INDIVIDUAL - BUSINESS example: "INDIVIDUAL" examples: deposit: summary: Beneficiary Liquidation Deposit value: event: id: "60bef15c-4e30-4eb4-bc4d-aa697a7e0857" event_reference_id: "5b4ea7ee-9d40-44b3-b857-dd5a890b9313" type: "beneficiary.liquidation.deposit" created_at: "2025-11-30T07:40:06.853938Z" sandbox_mode: true data: active: true amount: 3 beneficiary_id: "5b4ea7ee-9d40-44b3-b857-dd5a890b9313" customer_id: "bea5a6c1-0611-44c6-8c29-a6608e76916c" liquidation_address: "0xade8141fd1aef58dc0a5365a32a6cfe95904c08f" txn_hash: "0x7808238a69057600f0c8e291ffbfde87a74fb81b32fc583231352147770e2751" type: "INDIVIDUAL" responses: "200": description: Webhook received successfully batch.transaction.item.status: post: summary: Batch Transaction Item Status description: Triggered when a batch transaction item's status changes after committing a batch. x-mint: metadata: title: batch.transaction.item.status content: | Currently fired only when a transaction item reaches `PENDING` status. All webhook requests include HMAC signatures for verification. tags: - Webhooks requestBody: required: true content: application/json: schema: type: object properties: event: type: object required: - id - event_reference_id - type - created_at - sandbox_mode properties: id: type: string format: uuid example: "60bef15c-4e30-4eb4-bc4d-aa697a7e0857" event_reference_id: type: string format: uuid example: "c3309534-1517-4d15-b244-be8f943c3823" type: type: string enum: - batch.transaction.item.status example: "batch.transaction.item.status" created_at: type: string format: date-time example: "2025-11-30T07:40:06.853938Z" sandbox_mode: type: boolean example: true data: type: object properties: batch_id: type: string format: uuid batch_item_id: type: string format: uuid status: type: string enum: [PENDING] transaction_id: type: string format: uuid examples: pending: summary: Batch Transaction Item Pending value: event: id: "b576fcfd-981f-4abd-81d8-14b2a0a8cb39" event_reference_id: "ea8184e5-4250-486e-8a45-7718896c82b0" type: "batch.transaction.item.status" created_at: "2026-01-08T16:57:20.266158Z" sandbox_mode: true data: batch_id: "8f23036c-3dc8-445a-aad9-61564e028e56" batch_item_id: "05ed90f4-da44-4a56-bbd9-c65a42f925e6" status: "PENDING" transaction_id: "ea8184e5-4250-486e-8a45-7718896c82b0" responses: "200": description: Webhook received successfully transit.payment.status: post: summary: Transit Payment Status description: Triggered when a transit payment's status changes through the payment and settlement flow. x-mint: metadata: title: transit.payment.status content: | ## 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**: On hold due to insufficient rebalancing funds. Fin will auto-proceed once funds are available. - **SETTLEMENT_FAILED**: Settlement failed after 3 retry attempts The `settlement_info` field will be `null` for PAY_* statuses and populated for SETTLEMENT_* statuses. All webhook requests include HMAC signatures for verification. tags: - Webhooks requestBody: required: true content: application/json: schema: type: object required: - event - data properties: event: type: object required: - id - type - event_reference_id - created_at properties: id: type: string format: uuid example: "550e8400-e29b-41d4-a716-446655440000" type: type: string enum: [transit.payment.status] example: "transit.payment.status" event_reference_id: type: string format: uuid description: Reference to the payment_id example: "FIN_PROVIDED_UUID" created_at: type: string format: date-time example: "2025-10-10T15:40:56Z" data: type: object required: - payment_id - integration_type - status - create_time - payment_info properties: payment_id: type: string format: uuid example: "FIN_PROVIDED_UUID" integration_type: type: string example: "BYBIT" quote_id: type: string format: uuid example: "FIN_PROVIDED_UUID" status: type: string enum: - PAY_INIT - PAY_PROCESS - PAY_SUCCESS - PAY_FAILED - PAY_TIMEOUT - PAY_CANCEL - SETTLEMENT_INIT - SETTLEMENT_HOLD - SETTLEMENT_SUCCESS - SETTLEMENT_FAILED example: "PAY_INIT" create_time: type: integer example: 1740748353 payment_info: type: object properties: pay_id: type: string example: "01JN6AZVEMAC8H9SED6JES3QH8" merchant_trade_no: type: string example: "841e4ba2-...-a2a45de7bd00" amount: type: string example: "100" status: type: string enum: [PAY_INIT, PAY_PROCESS, PAY_SUCCESS, PAY_FAILED, PAY_TIMEOUT, PAY_CANCEL] example: "PAY_INIT" currency: type: string example: "USDT" currency_type: type: string example: "crypto" expire_time: type: integer example: 1740751953 payment_time: type: integer description: 0 until PAY_SUCCESS example: 0 settlement_info: type: object nullable: true description: null for PAY_* statuses, populated for SETTLEMENT_* statuses properties: settlement_via: type: string enum: [ONE_TO_ONE, MARKET_ORDER, FEE_RETENTION] example: "MARKET_ORDER" wallet_address: type: string example: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: type: string enum: [USDC, USDT, BTC, ETH] example: "USDC" rail: type: string enum: [SOLANA, BITCOIN, ETHEREUM, BASE] example: "SOLANA" amount: type: string example: "100" trx_hash: type: string nullable: true settle_time: type: integer example: 0 status: type: string enum: [SETTLEMENT_INIT, SETTLEMENT_HOLD, SETTLEMENT_SUCCESS, SETTLEMENT_FAILED] example: "SETTLEMENT_INIT" retry_attempts: type: integer minimum: 0 maximum: 3 example: 0 examples: paymentInitiated: summary: Payment Initiated value: event: id: "550e8400-e29b-41d4-a716-446655440000" type: "transit.payment.status" event_reference_id: "FIN_PROVIDED_UUID" created_at: "2025-10-10T15:40:56Z" data: payment_id: "FIN_PROVIDED_UUID" integration_type: "BYBIT" status: "PAY_INIT" create_time: 1740748353 payment_info: pay_id: "01JN6AZVEMAC8H9SED6JES3QH8" merchant_trade_no: "841e4ba2-...-a2a45de7bd00" amount: "100" status: "PAY_INIT" currency: "USDT" currency_type: "crypto" expire_time: 1740751953 payment_time: 0 settlement_info: null settlementSuccess: summary: Settlement Success value: event: id: "550e8400-e29b-41d4-a716-446655440003" type: "transit.payment.status" event_reference_id: "FIN_PROVIDED_UUID" created_at: "2025-10-10T15:47:00Z" data: payment_id: "FIN_PROVIDED_UUID" integration_type: "BYBIT" status: "SETTLEMENT_SUCCESS" create_time: 1740748353 payment_info: pay_id: "01JN6AZVEMAC8H9SED6JES3QH8" merchant_trade_no: "841e4ba2-...-a2a45de7bd00" amount: "100" status: "PAY_SUCCESS" currency: "USDT" currency_type: "crypto" expire_time: 1740751953 payment_time: 1740748353 settlement_info: settlement_via: "MARKET_ORDER" wallet_address: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" currency: "USDC" rail: "SOLANA" amount: "100" trx_hash: "0x580..." settle_time: 1740748353 status: "SETTLEMENT_SUCCESS" retry_attempts: 0 responses: "200": description: Webhook received successfully