openapi: 3.1.0 info: title: Fin.com API version: 1.0.0 description: A simple API specificationFo 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 paths: /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' /v2/customers: get: summary: List Customers V2 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' /v1/customers: get: summary: List Customers description: Retrieve a list of customers filtered by type x-mint: content: | This endpoint was deprecated on May 20, 2026. Use [List Customers V2](https://developer.fin.com/api-reference/customers/list-customers-v2) instead. 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: 10 total_page: type: integer example: 1 total: type: integer example: 2 customers: type: array items: oneOf: - 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: '+14724480512' country_of_residence: type: string example: USA customer_status: type: string example: INCOMPLETE tos_policies_url: type: string format: uri created_at: type: string format: date-time updated_at: type: string format: date-time - type: object properties: customer_id: type: string format: uuid example: 94e6b847-4e19-49e3-b3ab-ffa95872eda9 type: type: string enum: - BUSINESS business_name: type: string example: Acme Corp Ltd email: type: string format: email example: contact@acmecorp.com phone: type: string example: '+14155552671' country_of_incorporation: type: string example: USA customer_status: type: string example: INCOMPLETE tos_policies_url: type: string format: uri created_at: type: string format: date-time updated_at: type: string format: date-time '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' /v2/customers/{customer_id}: get: summary: Get Customer Details V2 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). 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. - 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. - The document is not authentic reject_labels: - UNFILLED_ID - uri: /ZuyUaH3a_testdoc1.png category: OWNERSHIP_DOCUMENTS moderation_comment: |- This document is not accepted. - 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. - 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_sumsub.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: atkeyafahmida290@gmail.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_sumsub.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' /v1/customers/{customer_id}: get: summary: Get Customer Details description: Retrieve detailed information for a specific customer x-mint: content: | Use this endpoint to fetch individual customer details. For business customer details, use [Get Customer Details V2](https://developer.fin.com/api-reference/customers/get-customer-details-v2). tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid example: 55bd6b4e-c20a-4cc8-9535-91d5557a67d9 responses: '200': description: Customer details retrieved successfully content: application/json: schema: type: object properties: data: oneOf: - $ref: '#/components/schemas/IndividualCustomerDetail' - $ref: '#/components/schemas/BusinessCustomerDetail' examples: Individual Customer: summary: Individual Customer value: data: customer_id: 56c41b8e-e650-4f55-94f6-26a888a9b64d type: INDIVIDUAL first_name: John last_name: Doe email: john.doe@fin.com phone: '+14724480512' country_of_residence: USA verification_type: STANDARD customer_status: ON_HOLD 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-15T11:49:27Z' updated_at: '2026-04-15T11:52:48Z' last_status_updated_at: '2026-04-15T11:52:48Z' capabilities: on_ramp: - currency: USD status: false methods: - ACH - FEDWIRE reason: for_customer: null for_developer: null off_ramp: - currency: USD status: false methods: - ACH - FEDWIRE - ACH_SAME_DAY reason: for_customer: null for_developer: Customer is under review - currency: EUR status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: BDT status: false methods: - BANK - E_WALLET reason: for_customer: null for_developer: Customer is under review - currency: AUD status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: INR status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: JPY status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: NPR status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: CAD status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: PKR status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: PHP status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: SGD status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: GBP status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review rejection_reason: null request_for_information: [] Business Customer: summary: Business Customer value: data: customer_id: 94e6b847-4e19-49e3-b3ab-ffa95872eda9 type: BUSINESS business_name: Fin.com email: contact@fin.com phone: '+6591234567' country_of_incorporation: SGP verification_type: STANDARD customer_status: APPROVED tos_policies_url: >- https://orchestration.fin.com/orchestration-customer-tos?customer_id=94e6b847-4e19-49e3-b3ab-ffa95872eda9&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24 associated_parties: - id: 42daffd3-09a0-4d48-8e73-2680a953d0e1 type: INDIVIDUAL ownership_percent: 10 email: john.doe@fin.com verification: status: APPROVED reason: for_customer: null for_developer: null updated_at: '2026-04-15T11:29:08Z' created_at: '2026-04-15T11:26:12Z' updated_at: '2026-04-15T11:31:18Z' last_status_updated_at: '2026-04-15T11:29:09Z' capabilities: on_ramp: - currency: USD status: false methods: - ACH - FEDWIRE reason: for_customer: null for_developer: null off_ramp: - currency: USD status: false methods: - ACH - FEDWIRE - ACH_SAME_DAY reason: for_customer: null for_developer: Unsupported at the moment - currency: EUR status: true methods: - BANK reason: for_customer: null for_developer: null - currency: BDT status: true methods: - BANK - E_WALLET reason: for_customer: null for_developer: null - currency: AUD status: true methods: - BANK reason: for_customer: null for_developer: null - currency: INR status: true methods: - BANK reason: for_customer: null for_developer: null - currency: JPY status: true methods: - BANK reason: for_customer: null for_developer: null - currency: NPR status: true methods: - BANK reason: for_customer: null for_developer: null - currency: CAD status: true methods: - BANK reason: for_customer: null for_developer: null - currency: PKR status: true methods: - BANK reason: for_customer: null for_developer: null - currency: PHP status: true methods: - BANK reason: for_customer: null for_developer: null - currency: SGD status: true methods: - BANK reason: for_customer: null for_developer: null - currency: GBP status: true methods: - BANK reason: for_customer: null for_developer: null rejection_reason: null request_for_information: [] '401': $ref: '#/components/responses/AuthenticationError' '404': description: Customer not found content: application/json: schema: type: object properties: message: type: string example: Customer not found '422': $ref: '#/components/responses/ValidationError' patch: summary: Update Customer 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 Business Customer V2 - Attach Document To Associated Party - Attach Document To Associated Party V2 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 supporting_documents: type: array items: type: object 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 supporting_documents: [] - 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}/wallets: post: summary: Create Customer Wallets description: >- Provisions one or more crypto wallets for a customer across supported chains and tokens. x-mint: content: | Fin.com issued crypto wallets require pre-configuration. Contact support to learn more. Wallets start with a status of `PENDING`. They move to `ACTIVE` (or `INACTIVE`) asynchronously once the wallet address has been issued, so creation is not synchronous. Poll [Get Customer Wallets](/api-reference/crypto-orchestration/get-customer-wallets) to check on status. Supported rails and currencies: | Rail | Currency | | -------- | -------- | | POLYGON | USDC | | ETHEREUM | USDC | | SOLANA | USDC | If any requested wallet (same `rail` + `currency` pair) already exists for the customer, the request fails with a `409` and lists the colliding pairs; none of the requested wallets are created. tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string example: 765d498e-a267-4154-9d2f-9e411a0b50dd requestBody: required: true content: application/json: schema: type: object required: - wallets properties: wallets: type: array minItems: 1 description: Wallets to provision, one entry per rail. items: type: object required: - rail - currency properties: rail: type: string description: Blockchain network to provision the wallet(s) on. example: SOLANA currency: type: array minItems: 1 description: Token(s) to provision a wallet for on this rail. items: type: string example: - USDC example: wallets: - rail: SOLANA currency: - USDC - rail: ETHEREUM currency: - USDC responses: '200': description: >- Wallet creation request accepted for processing. Note the nested `data`: the outer envelope wraps a `message` plus the inner `data` array of wallets being provisioned. content: application/json: schema: type: object properties: data: type: object properties: message: type: string example: Request is being processed data: type: array items: $ref: '#/components/schemas/CustomerWallet' example: data: message: Request is being processed data: - id: b1e2c3d4-4d5e-6f70-8a90-1b2c3d4e5f60 rail: SOLANA currency: USDC status: PENDING - id: d3a4e5f6-4d5e-6f70-8a90-1b2c3d4e5f62 rail: ETHEREUM currency: USDC status: PENDING '401': $ref: '#/components/responses/AuthenticationError' '409': description: >- One or more of the requested wallets already exist for this customer. content: application/json: schema: type: object properties: message: type: string example: one or more wallets already exist for this customer collisions: type: array items: type: object properties: rail: type: string example: SOLANA currency: type: string example: USDC example: message: one or more wallets already exist for this customer collisions: - rail: SOLANA currency: USDC '422': $ref: '#/components/responses/ValidationError' get: summary: Get Customer Wallets description: >- Returns all crypto wallets linked to a customer across supported chains and tokens. x-mint: content: > Fin.com issued crypto wallets require pre-configuration. Contact support to learn more. Upon approval, the customer is provisioned wallet addresses for the following rails and currencies: | Rail | Currency | | -------- | -------- | | POLYGON | USDC | | ETHEREUM | USDC | | SOLANA | USDC | `address` is `null` until the wallet finishes provisioning (see `status` on [Create Customer Wallets](/api-reference/crypto-orchestration/create-customer-wallets)). tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string example: 765d498e-a267-4154-9d2f-9e411a0b50dd responses: '200': description: Customer wallets retrieved successfully content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/CustomerWallet' example: data: - id: 27dbc0f2-e5ae-444b-b4ab-0764252aedf6 status: ACTIVE currency: USDC rail: ETHEREUM address: '0xc42a5f7083c7e8f1d9820c7660867277289cd998' balance: 10.000001 - id: e1dcce59-0309-43de-ab6c-a0bd3497b9c3 status: ACTIVE currency: USDC rail: SOLANA address: BCSZEokfpVsSpUuuZJMScLiUpYjvvUmrrAJkNbrTTnng balance: 25.000001 - id: c92dfe1d-220e-4446-a5e4-cd7d46031ba5 status: PENDING currency: USDC rail: POLYGON address: null balance: 0 '401': $ref: '#/components/responses/AuthenticationError' '404': $ref: '#/components/responses/NotFoundError' /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 example: USD rail: type: string example: ACH status: type: boolean example: true off_ramp: type: array items: type: object properties: corridor: type: string example: BGD currency_wise_rail: type: array items: type: object properties: currency: type: string example: BDT rails: type: array items: type: object properties: rail: type: string example: LOCAL status: type: boolean example: true examples: OK: summary: OK value: data: on_ramp: - currency: USD rail: ACH status: false - currency: USD rail: FEDWIRE status: true - currency: USD rail: SWIFT status: true off_ramp: - corridor: BGD currency_wise_rail: - currency: BDT rails: - rail: LOCAL status: true - currency: USD rails: - rail: SWIFT status: true - corridor: AUS currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - corridor: GBR currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - currency: GBP rails: - rail: LOCAL status: true - corridor: CAN currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - corridor: DEU currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - currency: EUR rails: - rail: LOCAL status: true - corridor: POL currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - corridor: IND currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - currency: INR rails: - rail: LOCAL status: true - corridor: PAK currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - corridor: NPL currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - corridor: PHL currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - corridor: SGP currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - currency: SGD rails: - rail: LOCAL status: true '401': $ref: '#/components/responses/AuthenticationError' '404': $ref: '#/components/responses/NotFoundError' '422': $ref: '#/components/responses/ValidationError' /v2/customers/individual: post: summary: Create Individual Customer V2 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 /v1/customers/individual: post: summary: Create Individual Customer description: Create a new individual customer with verification details x-mint: content: > Only English (Latin) characters are allowed as inputs for all fields. ## Important Requirements - **Email Address**: Must be all lowercase or you will receive a validation error - **RELIANCE Verification**: If you attempt to use `RELIANCE` verification type but it's not enabled for your client, you will receive a 423 error with message: "RELIANCE is not available for your client" tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateIndividualCustomerInput' 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: 55bd6b4e-c20a-4cc8-9535-91d5557a67d9 tos_policies_url: type: string format: uri example: >- https://orchestration.fin.com/orchestration-customer-tos?customer_id=55bd6b4e-c20a-4cc8-9535-91d5557a67d9&tos_policies_value=e9414388-fbdf-4407-b5c2-bc39eae3645b '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 V2 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 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 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 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/business: post: summary: Create Business Customer description: >- Create a new business customer with verification details, addresses, and associated parties x-mint: content: > This endpoint was deprecated on May 20, 2026. Use [Create Business Customer V2](https://developer.fin.com/api-reference/customers/create-business-customer-v2) instead. ## Important Requirements - **Email Address**: Must be all lowercase or you will receive a validation error - **RELIANCE Verification**: If you attempt to use `RELIANCE` verification type but it's not enabled for your client, you will receive a 423 error with message: "RELIANCE is not available for your client" - **Third-party Fund Usage**: The `third_party_fund_usage` field indicates whether this customer will be moving other people's money - **Ownership Percentages**: The total ownership percentages of all associated parties must add up to more than 0 and less than 100 tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBusinessCustomerInput' responses: '200': description: Business customer created successfully content: application/json: schema: type: object properties: data: type: object properties: customer_id: type: string format: uuid description: Unique identifier for the created customer example: 2d0a9df3-e1e5-4955-9759-ce0522e0ddc9 tos_policies_url: type: string format: uri description: URL for customer to accept Terms of Service policies example: >- https://orchestration.fin.com/orchestration-customer-tos?customer_id=2d0a9df3-e1e5-4955-9759-ce0522e0ddc9&tos_policies_value=f11e77c6-8dc0-4d4b-a3f2-ed84c8ccfc69 '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 /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' /v2/customers/{customer_id}/individual/attach: post: summary: Attach Documents to Individual Customer V2 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 /v1/customers/individual/attach: post: summary: Attach Documents to Individual Customer description: >- Attach proof of identity and proof of address documents to an existing individual customer x-mint: content: | Before calling this endpoint, upload documents using the [Upload document](https://developer.fin.com/api-reference/customers/upload-document) endpoint to obtain the URIs needed for the `files` arrays. The `tos_policies_value` should be parsed from the `tos_policies_url` query parameter returned from the Create Individual Customer endpoint. tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AttachDocumentForIndividualCustomerInput' responses: '200': description: Documents attached successfully content: application/json: schema: type: object properties: data: type: object properties: customer_id: type: string format: uuid example: 55bd6b4e-c20a-4cc8-9535-91d5557a67d9 '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' /v1/customers/associated-parties/individual/attach: post: summary: Attach Document To Associated Party description: >- Attach proof of identity and proof of address documents to associated parties of an existing customer x-mint: content: | This endpoint was deprecated on May 20, 2026. Use [Attach Documents to Associated Party V2](https://developer.fin.com/api-reference/customers/attach-documents-to-associated-party-v2) instead. Before calling this endpoint, upload documents using the [Upload document](https://developer.fin.com/api-reference/customers/upload-document) endpoint to obtain the URIs needed for the `files` arrays. This endpoint allows attaching documents for multiple associated parties in a single request. tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AttachDocumentToAssociatedPartyInput' responses: '200': description: Documents attached successfully content: application/json: schema: type: object properties: data: type: object description: Generic response object '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' /v1/customers/business/attach: post: summary: Attach Documents to Business Customer description: >- Attach ownership structure, company details, and legal presence documents to an existing business customer x-mint: content: | This endpoint was deprecated on May 20, 2026. Use [Attach Documents to Business Customer V2](https://developer.fin.com/api-reference/customers/attach-documents-to-business-customer-v2) instead. - Before calling this endpoint, upload documents using the [Upload document](https://developer.fin.com/api-reference/customers/upload-document) endpoint to obtain the URIs needed for the `files` arrays. - The `tos_policies_value` should be parsed from the `tos_policies_url` query parameter returned from the Create Business Customer endpoint. tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AttachDocumentsToBusinessCustomerInput' responses: '200': description: Documents attached successfully content: application/json: schema: type: object properties: data: type: object description: Generic response object '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' /v1/customers/enable-preference: post: summary: Enable USD Features description: Enable USD features for an existing customer x-mint: content: | This endpoint is deprecated and will be removed in a future release. Do not use it in new integrations. You can skip this step entirely and call [Create Virtual Account V2](https://developer.fin.com/api-reference/virtual-accounts/create-virtual-account-v2) directly, which handles USD feature enablement as part of account creation. tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - customer_id properties: customer_id: type: string format: uuid example: 55bd6b4e-c20a-4cc8-9535-91d5557a67d9 responses: '200': description: USD features enabled successfully content: application/json: schema: type: object properties: data: type: object description: Generic response object '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' /v2/customers/{customer_id}/business/attach: post: summary: Attach Documents to Business Customer V2 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/compliance-and-regulatory/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 V2 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 supporting_documents: [] - 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' /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 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' /v3/beneficiaries: post: summary: Create Beneficiary V3 description: >- Create a new beneficiary for payments and transfers. Supports bank accounts, e-wallets, and external crypto 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` | | External Crypto Wallet | `destination_wallet.address`, `destination_wallet.rail` | 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' 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 - CURRENT 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 required: - currency - rail properties: currency: type: string enum: - USDC example: USDC rail: type: string enum: - POLYGON example: POLYGON refund_instruction: type: object required: - wallet_address - currency - rail properties: wallet_address: type: string example: '0x1b577931C1cC2765024bFbafad97bCe14FF2e87F' currency: type: string enum: - USDC example: USDC rail: type: string enum: - POLYGON 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 required: - currency - rail properties: currency: type: string enum: - USDC example: USDC rail: type: string enum: - POLYGON example: POLYGON refund_instruction: type: object required: - wallet_address - currency - rail properties: wallet_address: type: string example: '0x1b577931C1cC2765024bFbafad97bCe14FF2e87F' currency: type: string enum: - USDC example: USDC rail: type: string enum: - POLYGON example: POLYGON settlement_config: type: object properties: auto_settlement: type: boolean example: true - title: External Crypto Wallet type: object required: - destination_wallet properties: destination_wallet: type: object required: - address - rail - currency properties: address: type: string description: On-chain wallet address of the recipient. example: '0xD2Ba7d0DaBd36498df5906fC7B054Fa9EfA9843E' rail: type: string enum: - POLYGON - ETHEREUM - SOLANA description: >- Blockchain network for the destination wallet. Supported values are POLYGON, ETHEREUM, and SOLANA. example: POLYGON currency: type: string enum: - USDC description: >- Token to be sent to the destination wallet. Currently only USDC is supported. example: USDC examples: Bank / Ewallet: summary: Bank or e-wallet beneficiary value: customer_id: 6fa1ccd4-ffbd-4b20-a113-ccc286b35443 country: BGD currency: BDT counter_party: FIRST_PARTY account_holder: type: INDIVIDUAL first_name: John last_name: Doe email: john.doe@example.com phone: '+8801912244626' bank_account: bank_name: Commonwealth Bank of Australia number: '1234572211' scheme: LOCAL type: SAVINGS bank_address: street_line_1: Ground Floor Tower 1, 201 Sussex Street city: Dhaka state: BD-13 postcode: '1212' country: BGD account_holder_address: street_line_1: 42 Wallaby Way city: Dhaka state: BD-13 postcode: '1212' country: BGD receiver_meta_data: nationality: AUS transaction_purpose_id: 1 occupation_id: 5 relationship: FAMILY_MEMBER relationship_remarks: Family & Friends bank_routing: - scheme: SWIFT number: CLNOUS66BRX - scheme: BANK_IDENTIFIER number: 160 - scheme: BRANCH_IDENTIFIER number: 8 developer_fee: fixed: 0.02 percentage: 0.01 deposit_instruction: currency: USDC rail: POLYGON refund_instruction: wallet_address: '0x1b577931C1cC2765024bFbafad97bCe14FF2e87F' currency: USDC rail: POLYGON settlement_config: auto_settlement: true External Crypto Wallet: summary: External crypto wallet beneficiary value: customer_id: '{{customer_id}}' counter_party: THIRD_PARTY currency: USDC country: BGD account_holder: type: INDIVIDUAL first_name: Daphne last_name: Elliot email: daphneelliot@email.com phone: '+8801646767354' account_holder_address: street_line_1: 42 Chamelibag Shantinagar city: Dhaka state: BD-13 postcode: '1217' country: BGD destination_wallet: address: '0xD2Ba7d0DaBd36498df5906fC7B054Fa9EfA9843E' rail: POLYGON currency: USDC developer_fee: fixed: 0 percentage: 0 receiver_meta_data: nationality: BGD transaction_purpose_id: 7 transaction_purpose_remarks: POLYGON USDC test occupation_id: 8 relationship: FAMILY_MEMBER relationship_remarks: Family and Friends 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' /v2/beneficiaries: post: summary: Create Beneficiary description: Create a new beneficiary account for payments and transfers x-mint: content: > This endpoint was deprecated on May 20, 2026. Use [Create Beneficiary V3](https://developer.fin.com/api-reference/beneficiaries/create-beneficiary-v3) instead. ## Rules - Beneficiary creation requires the customer to be in the `APPROVED` status. - Two beneficiaries with the same destination are not allowed. ## De-Duplication Logic For _bank accounts_, the system checks: `bank_account.scheme`, `bank_account.number`, `bank_routing.scheme`, `bank_routing.number`. For _e-wallets_: `e_wallet.scheme`, `e_wallet.number`. ## Country-Specific Validation ### GBR (United Kingdom) - **Bank account number**: Must match `^[0-9]{4,9}$` for both `LOCAL` and `SWIFT` schemes. tags: - Beneficiaries security: - bearerAuth: [] requestBody: required: true content: application/json: schema: allOf: - type: object required: - customer_id - country - currency - account_holder - account_holder_address - receiver_meta_data - developer_fee - deposit_instruction - refund_instruction properties: customer_id: type: string example: cust_123456 country: type: string example: USA pattern: ^[A-Z]{3}$ currency: type: string example: USD counter_party: type: string enum: - FIRST_PARTY - THIRD_PARTY description: >- Indicates whether the beneficiary is a first-party or third-party account. Optional. 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: '+1234567890' - 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: '+1234567890' account_holder_address: type: object required: - street_line_1 - city - state - postcode - country properties: street_line_1: type: string example: 456 Main Street street_line_2: type: string example: Apt 5B city: type: string example: Brooklyn 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 postcode: type: string example: '11201' country: type: string example: USA pattern: ^[A-Z]{3}$ receiver_meta_data: type: object required: - transaction_purpose_id - occupation_remarks - relationship - nationality properties: transaction_purpose_id: type: integer example: 1 transaction_purpose_remarks: type: string example: Monthly salary payment 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 relationship_remarks: type: string example: Long-term contractor nationality: type: string example: USA pattern: ^[A-Z]{3}$ 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' developer_fee: type: object required: - fixed - percentage properties: fixed: type: number example: 5 percentage: type: number example: 2.5 deposit_instruction: type: object required: - currency - rail properties: currency: type: string enum: - USDC rail: type: string enum: - POLYGON refund_instruction: type: object required: - wallet_address - currency - rail properties: wallet_address: type: string example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb' currency: type: string enum: - USDC rail: type: string enum: - POLYGON settlement_config: type: object required: - auto_settlement properties: auto_settlement: type: boolean example: true - oneOf: - title: Bank Account type: object required: - bank_account - bank_routing - bank_address properties: bank_account: type: object required: - bank_name - number - scheme - type properties: bank_name: type: string example: Chase Bank number: type: string example: '1234567890' scheme: type: string enum: - LOCAL - SWIFT type: type: string enum: - CHECKING - SAVINGS - CURRENT bank_routing: type: array 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 number: oneOf: - type: string - type: integer example: '021000021' bank_address: type: object required: - street_line_1 - city - state - postcode - country properties: street_line_1: type: string example: 123 Bank Street street_line_2: type: string example: Suite 100 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 postcode: type: string example: '10001' country: type: string example: USA pattern: ^[A-Z]{3}$ - title: E Wallet type: object required: - e_wallet properties: e_wallet: type: object required: - scheme - number properties: scheme: type: string example: BKASH number: type: string example: '+8801688502814' responses: '200': description: Beneficiary created successfully content: application/json: schema: type: object properties: data: type: object properties: id: type: string example: ben_123456 status: type: string example: active '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: d9868585-78ba-4723-b0af-8f5b1cc5f9e2 '422': $ref: '#/components/responses/ValidationError' /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' /v2/beneficiaries/details: get: summary: Fetch Beneficiary Details v2 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 destination_wallet: type: object nullable: true properties: address: type: string example: '0xD2Ba7d0DaBd36498df5906fC7B054Fa9EfA9843E' currency: type: string example: USDC rail: type: string example: POLYGON 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 destination_wallet: null created_at: '2025-12-31T14:29:07.100041Z' updated_at: '2025-12-31T14:29:08.675022Z' External Crypto Wallet: summary: External crypto wallet beneficiary value: data: id: 6af8d598-36a5-477d-9320-d7c5ba309107 customer_id: 1a8e3bdc-05c9-4486-bdef-93464d24c9af active: true status: ACTIVE counter_party: THIRD_PARTY currency: USDC country: BGD account_holder: type: INDIVIDUAL first_name: Daphne last_name: Elliot email: abc.cdc@gmail.com phone: '+8801912244626' bank_account: bank_name: '' number: '' scheme: '' type: '' bank_routing: null receiver_meta_data: transaction_purpose_id: 7 transaction_purpose_remarks: Send to Family and Friends occupation_id: 8 relationship: FAMILY_MEMBER relationship_remarks: Family and Friends nationality: BGD bank_address: null account_holder_address: street_line_1: 42 Dhanmondi Road city: Dhaka state: BD-13 postcode: '1212' country: BGD developer_fee: fixed: 0.01 percentage: 0.01 deposit_instruction: currency: '' rail: '' liquidation_address: '' refund_instruction: wallet_address: '' currency: '' rail: '' e_wallet: null settlement_config: auto_settlement: false destination_wallet: address: '0xD2Ba7d0DaBd36498df5906fC7B054Fa9EfA9843E' currency: USDC rail: POLYGON created_at: '2026-04-25T15:49:24.56855Z' updated_at: '2026-04-25T15:49:24.56855Z' '401': $ref: '#/components/responses/AuthenticationError' '404': $ref: '#/components/responses/NotFoundError' /v1/beneficiaries/details: get: summary: Fetch Beneficiary Details v1 description: Retrieve detailed information for a specific beneficiary x-mint: content: | This endpoint was deprecated on May 20, 2026. Use [Fetch Beneficiary Details V2](https://developer.fin.com/api-reference/beneficiaries/fetch-beneficiary-details-v2) instead. tags: - Beneficiaries security: - bearerAuth: [] parameters: - name: customer_id in: query required: true schema: type: string format: uuid example: ad41fac1-e406-445b-aea4-69381c39ca5d - name: beneficiary_id in: query required: true schema: type: string format: uuid example: f653e109-6c62-4aa4-869c-418c874e0a6c responses: '200': description: Beneficiary details retrieved successfully content: application/json: schema: type: object properties: data: 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 first_name: type: string example: John last_name: type: string example: Doe business_name: type: string example: Investment bank type: type: string enum: - INDIVIDUAL - BUSINESS example: INDIVIDUAL nationality: type: string example: AUS email: type: string format: email example: john.doe@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' '404': $ref: '#/components/responses/NotFoundError' /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' /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 `true`. 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 `true`. **Amount Specification:** - Each transaction must include exactly one of `source_amount` or `destination_amount` (not both) - `source_amount`: Minimum 500 cents (e.g. 500 = $5.00) - Only `PREFUNDED_BALANCE` transactions are eligible for refunds if they fail 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 V2 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/transactions/{transaction_id}: get: operationId: getTransactionById summary: Fetch Transaction Details V1 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. x-mint: content: | For **CRYPTO_DEPOSIT** and **CRYPTO_WITHDRAWAL** transaction types, you must use [Fetch Transaction Details V2](/api-reference/transactions/fetch-transaction-details-v2). We also recommend migrating all transaction detail lookups to V2, as V1 will be deprecated soon. tags: - Transactions security: - bearerAuth: [] parameters: - name: transaction_id in: path required: true schema: type: string format: uuid example: 7f0124cd-6845-47d3-8b39-43f80cd50274 responses: '200': description: Transaction details retrieved successfully content: application/json: schema: type: object required: - data properties: data: type: object properties: id: type: string format: uuid example: 7f0124cd-6845-47d3-8b39-43f80cd50274 transaction_type: type: string enum: - ONRAMP - OFFRAMP - CRYPTO_WITHDRAWAL - CRYPTO_DEPOSIT example: OFFRAMP customer_id: type: string format: uuid nullable: true example: null beneficiary_id: type: string format: uuid example: e6200609-1ebb-41bb-a4d3-fd9e3bae8419 hash: type: string example: >- 796b21c4412f1208918cf744e38b62c95aa55674baf62a0a3b8b189c212d0b7e transaction_ref_id: type: string nullable: true example: 7f0124cd-6845-47d3-8b39-43f80cd50274 status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - REFUNDED example: COMPLETED batch_info: type: object nullable: true example: null from_amount: type: number example: 1.1 payout_amount: type: number example: 94.919 processing_amount: type: number example: 1.1 from_currency: type: string example: USD payout_currency: type: string example: INR fx_rate: type: number example: 86.29 developer_fee: type: number example: 1.25495 developer_fee_percentage: type: number example: 0.45 developer_fee_fixed: type: number example: 1.25 virtual_account_id: type: string nullable: true example: null fiat_details: type: object nullable: true example: null crypto_details: type: object nullable: true example: null fees: type: object nullable: true example: null created_at: type: string format: date-time example: '2026-01-08T08:27:22.345304Z' updated_at: type: string format: date-time example: '2026-01-08T08:27:33.76357Z' examples: OFFRAMP: summary: OFFRAMP transaction value: data: id: 7f0124cd-6845-47d3-8b39-43f80cd50274 transaction_type: OFFRAMP customer_id: null beneficiary_id: e6200609-1ebb-41bb-a4d3-fd9e3bae8419 hash: >- 796b21c4412f1208918cf744e38b62c95aa55674baf62a0a3b8b189c212d0b7e transaction_ref_id: 7f0124cd-6845-47d3-8b39-43f80cd50274 from_amount: 1.1 payout_amount: 94.919 processing_amount: 1.1 status: COMPLETED fx_rate: 86.29 developer_fee: 1.25495 developer_fee_percentage: 0.45 developer_fee_fixed: 1.25 from_currency: USD payout_currency: INR virtual_account_id: null batch_info: null fiat_details: null crypto_details: null fees: null created_at: '2026-01-08T08:27:22.345304Z' updated_at: '2026-01-08T08:27:33.76357Z' '401': $ref: '#/components/responses/AuthenticationError' '404': description: Transaction not found content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: TRANSACTION_NOT_FOUND message: type: string example: The requested transaction could not be found '500': description: Internal server error content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: INTERNAL_SERVER_ERROR message: type: string example: >- An unexpected error occurred while processing your request /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' /v2/customers/{customer_id}/virtual-accounts: post: operationId: createVirtualAccountV2 summary: Create Virtual Account V2 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. 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 in hexadecimal format (0x...) example: '0x6e41e83d406185b358bd72111ab1206cb82eb67f' currency: type: string enum: - USDC example: USDC rail: type: string enum: - POLYGON example: POLYGON source: type: object required: - currency - rail properties: currency: type: string enum: - USD - EUR - MXN example: USD rail: type: string enum: - ACH - SWIFT - FEDWIRE - FEDNOW - SEPA - SPEI example: FEDWIRE developer_fee: type: object required: - percentage - fixed properties: percentage: type: number example: 0.1 fixed: type: number example: 0.1 example: destination: wallet: '0x6e41e83d406185b358bd72111ab1206cb82eb67f' currency: USDC rail: POLYGON source: currency: USD rail: FEDWIRE developer_fee: percentage: 0.1 fixed: 0.1 responses: '200': description: Virtual account created successfully content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid example: 024e784b-bc27-4a4c-82ee-80000fbf53c5 status: type: string enum: - PROCESSING - IN_COMPLIANCE - REQUEST_FOR_INFORMATION - ACTIVE - INACTIVE - DECLINED example: PROCESSING customer_id: type: string format: uuid example: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44 created_at: type: string format: date-time example: '2026-04-04T11:05:20.963676Z' rfi: type: object nullable: true example: null examples: OK: summary: OK value: data: id: 024e784b-bc27-4a4c-82ee-80000fbf53c5 status: PROCESSING customer_id: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44 created_at: '2026-04-04T11:05:20.963676Z' rfi: null '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' get: operationId: listVirtualAccountsV2 summary: List Virtual Accounts V2 description: Retrieve a list of all virtual accounts for a specific customer tags: - Virtual Accounts security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid description: Unique identifier for the customer example: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44 - $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: type: object properties: id: type: string format: uuid example: 024e784b-bc27-4a4c-82ee-80000fbf53c5 status: type: string enum: - PROCESSING - IN_COMPLIANCE - REQUEST_FOR_INFORMATION - ACTIVE - INACTIVE - DECLINED example: ACTIVE developer_fee_percent: type: number nullable: true example: 0 developer_fee_fixed: type: number nullable: true example: 0.3 customer_id: type: string format: uuid example: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44 created_at: type: string format: date-time example: '2026-04-04T11:05:20.963676Z' updated_at: type: string format: date-time example: '2026-04-04T11:05:20.963676Z' deposit_instructions: type: object nullable: true description: null when status is PROCESSING 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 properties: currency: type: string enum: - USDC example: USDC destination_chain: type: string enum: - POLYGON example: POLYGON address: type: string example: '0x6e41e83d406185b358bd72111ab1206cb82eb67f' rfi: type: object nullable: true example: null 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 examples: OK: summary: OK value: data: virtual_accounts: - id: 024e784b-bc27-4a4c-82ee-80000fbf53c5 status: PROCESSING developer_fee_percent: 0 developer_fee_fixed: 0.3 customer_id: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44 created_at: '2026-04-04T11:05:20.963676Z' updated_at: '2026-04-04T11:05:20.963676Z' deposit_instructions: null destination: currency: USDC destination_chain: POLYGON address: '0x6e41e83d406185b358bd72111ab1206cb82eb67f' rfi: null - id: 1c1919e3-ce2e-4728-9efe-12b8be8e964d status: ACTIVE developer_fee_percent: 0 developer_fee_fixed: null customer_id: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44 created_at: '2026-04-04T11:04:16.156771Z' updated_at: '2026-04-04T11:04:16.156771Z' deposit_instructions: currency: USD bank_name: Bank of Nowhere bank_address: 1800 North Pole St., Orlando, FL 32801 bank_routing_number: '101019644' bank_account_number: '2611508020' payment_rails: - ACH - FEDWIRE bank_country: null account_type: null bank_code: null destination: currency: USDC destination_chain: POLYGON address: '0x6e41e83d406185b358bd72111ab1206cb82eb67f' rfi: null pagination: current_page: 1 per_page: 10 total_page: 1 total: 2 '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' /v1/customers/virtual-account: get: summary: List Virtual Accounts V1 description: Retrieve a list of all virtual accounts for a specific customer x-mint: content: | This endpoint was deprecated on May 20, 2026. Use [List Virtual Accounts V2](https://developer.fin.com/api-reference/virtual-accounts/list-virtual-accounts-v2) instead. tags: - Virtual Accounts security: - bearerAuth: [] parameters: - name: customer_id in: query required: true schema: type: string format: uuid example: 196ce546-900d-4294-90ca-5546a5923f35 responses: '200': description: Virtual accounts retrieved successfully content: application/json: schema: type: object required: - data properties: data: type: object required: - virtual_accounts - pagination properties: virtual_accounts: type: array items: $ref: '#/components/schemas/VirtualAccount' 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: 6 '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' post: summary: Create Virtual Account description: >- Create a virtual bank account for a customer to convert USD deposits to USDC on Polygon x-mint: content: | This endpoint was deprecated on May 20, 2026. Use [Create Virtual Account V2](https://developer.fin.com/api-reference/virtual-accounts/create-virtual-account-v2) instead. tags: - Virtual Accounts security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - customer_id - destination_currency - destination_chain - source_rail - source_currency - destination_wallet_address - developer_fee_percentage properties: customer_id: type: string format: uuid example: 5a6f47f7-7326-409f-a4da-90e409133fb8 destination_currency: type: string enum: - USDC default: USDC destination_chain: type: string enum: - POLYGON default: POLYGON source_rail: type: string example: ACH source_currency: type: string example: USD destination_wallet_address: type: string example: '0x7f1568190e318da16a9ef5a46cba19d5b97d9b29' developer_fee_percentage: type: number example: 1.5 responses: '200': description: Virtual account created successfully content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/VirtualAccount' '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' put: summary: Update Virtual Account description: >- Update an existing virtual bank account's developer fee percentage and destination wallet address tags: - Virtual Accounts security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - id - customer_id properties: id: type: string format: uuid example: f8715e46-f46a-41dc-94ec-bd9797683510 customer_id: type: string format: uuid example: 22c6b566-5ecc-49b7-b812-076c64735596 developer_fee_percentage: type: number example: 1.25 destination_wallet_address: type: string example: '0x7f1568190e318da16a9ef5a46cba19d5b97d9b29' responses: '200': description: Virtual account updated successfully content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/VirtualAccount' '401': $ref: '#/components/responses/AuthenticationError' '404': $ref: '#/components/responses/NotFoundError' '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' /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' /v1/industries: get: summary: List Industries description: Retrieve a list of available industries x-mint: content: | This endpoint is used for **Create Business Customer V1** only. It is not applicable for Create Business Customer V2. 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' 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 - TRUST - 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/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/compliance-and-regulatory/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/compliance-and-regulatory/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 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 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 - TRUST - 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 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 - TRUST - 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 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 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_sumsub.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 - REVIEWING - APPROVED - REJECTED 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 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 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: - PASSPORT - NATIONAL_ID - DRIVERS_LICENSE - RESIDENCE_PERMIT - UTILITY_BILL - GOVERNMENT_LETTER - BANK_STATEMENT - COMPANY_DOC 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: - PASSPORT - NATIONAL_ID - DRIVERS_LICENSE - RESIDENCE_PERMIT - 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 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, Trust Agreement, 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 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' supporting_documents: type: array description: >- Any additional supporting documents for this party. Optional. Pass empty array if not applicable. items: $ref: '#/components/schemas/V2AssociatedPartySupportingDocumentAttachment' V2IdentifyingDocumentAttachment: type: object required: - type - number - country - issue_date - expiry_date - files properties: type: type: string enum: - PASSPORT - NATIONAL_ID - DRIVERS_LICENSE - RESIDENCE_PERMIT - PERMANENT_RESIDENCY_ID description: > Type of government-issued identity document. At least one identifying document is required. Double-sided documents must include both front and back images. **USA residents**: all ID types are supported: - `PASSPORT`: Passport - `NATIONAL_ID`: National ID card - `DRIVERS_LICENSE`: Driver's license - `PERMANENT_RESIDENCY_ID`: Permanent Residency / Green Card **Non-USA residents**: only the following are accepted: - `PASSPORT`: Passport - `NATIONAL_ID`: National ID card - `DRIVERS_LICENSE`: Driver's license `PERMANENT_RESIDENCY_ID` is **not supported** for non-USA residents and will be rejected. 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 V2AssociatedPartySupportingDocumentAttachment: type: object required: - type - files properties: type: type: string enum: - MILITARY_ID - MATRICULATE_ID - STATE_OR_PROVINCIAL_ID - VISA - OTHER description: Type of additional supporting document for the associated party. example: MILITARY_ID 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 V2AddressDocumentAttachment: type: object required: - type - files properties: type: type: string enum: - UTILITY_BILL - GOVERNMENT_LETTER - BANK_STATEMENT - PROOF_OF_TAX_IDENTIFICATION - COURT_DOCUMENT - INSURANCE_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 WebhookEventEnvelope: 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 - customer.status - customer.rfi - transaction.status - virtual_account.created - virtual_account.created.v2 - virtual_account.status - virtual_account.status.v2 - beneficiary.created - beneficiary.status - beneficiary.liquidation.deposit - batch.transaction.item.status example: customer.created created_at: type: string format: date-time example: '2025-11-30T07:40:06.853938Z' sandbox_mode: type: boolean example: true 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 - REVIEWING - APPROVED - REJECTED 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 VirtualAccountWebhookData: type: object properties: id: type: string format: uuid example: 900f750d-6868-457e-a777-1a35566a6b5f customer_id: type: string format: uuid example: a41a6d76-4545-47ab-93d1-696a3221d39c status: type: string enum: - ACTIVE - INACTIVE - SUSPENDED example: ACTIVE deposit_instructions: type: object properties: bank_account_number: type: string example: '900937198167' bank_routing_number: type: string example: '101019644' bank_name: type: string example: Bank of Nowhere bank_address: type: string example: 1800 North Pole St., Orlando, FL 32801 bank_beneficiary_name: type: string example: Fin.com bank_beneficiary_address: type: string example: 250 Innovation Way, Houston, TX 77002, US currency: type: string example: USD payment_rails: type: array items: type: string enum: - ACH - FEDWIRE - WIRE example: - ACH - FEDWIRE destination: type: object properties: address: type: string example: '0x1d1f9801d6d98e49438cda3a3b8e0c9f5e6f8c44' currency: type: string example: USDC destination_chain: type: string example: POLYGON developer_fee_percent: type: number example: 0.5 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 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 CustomerWallet: type: object properties: id: type: string format: uuid description: Unique wallet identifier. example: 27dbc0f2-e5ae-444b-b4ab-0764252aedf6 status: type: string enum: - PENDING - ACTIVE - INACTIVE description: >- Wallet provisioning status. Wallets start PENDING and move to ACTIVE (or INACTIVE) asynchronously once the wallet address has been issued; creation is not synchronous. example: ACTIVE currency: type: string description: Token held in this wallet. example: USDC rail: type: string description: Blockchain network for this wallet. example: ETHEREUM address: type: string nullable: true description: On-chain wallet address. Null until the wallet is provisioned. example: '0xc42a5f7083c7e8f1d9820c7660867277289cd998' balance: type: number description: Current wallet balance. example: 10.000001 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: 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 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: $ref: '#/components/schemas/WebhookEventEnvelope' 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: $ref: '#/components/schemas/WebhookEventEnvelope' 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: $ref: '#/components/schemas/WebhookEventEnvelope' 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: $ref: '#/components/schemas/WebhookEventEnvelope' data: type: object properties: id: type: string format: uuid example: ca9a04d8-4e68-4557-b9c6-3881e9d6b26d status: type: string enum: - FUNDS_RECEIVED - PROCESSING - COMPLETED - FAILED - CANCELLED example: FUNDS_RECEIVED beneficiary_id: type: string format: uuid from_amount: type: number example: 6 from_currency: type: string example: USDC payout_amount: type: number example: 5.55595028 payout_currency: type: string example: CAD processing_amount: type: number example: 4.2164 fx_rate: type: number example: 1.3177 developer_fee: type: number example: 1.7836 developer_fee_fixed: type: number example: 1.75 developer_fee_percentage: type: number example: 0.56 hash: type: string example: >- 0x3a282c0d2364632bdf9224eadf06b463190795bce24e46d3235e44d22f953461 transaction_ref_id: type: string transaction_type: type: string description: >- Possible values: `ONRAMP`, `OFFRAMP`, `CRYPTO_DEPOSIT`, `CRYPTO_WITHDRAWAL` created_at: type: string format: date-time updated_at: type: string format: date-time examples: fundsReceived: summary: Funds Received value: event: id: 2632ebb1-55ab-470a-9b24-accdb50aeb75 event_reference_id: ca9a04d8-4e68-4557-b9c6-3881e9d6b26d type: transaction.status created_at: '2025-12-01T09:14:34.651913Z' sandbox_mode: true data: beneficiary_id: 47fcb2ca-9ed2-4188-a154-c83a04d9d34d from_amount: 6 from_currency: USDC fx_rate: 1.3177 id: ca9a04d8-4e68-4557-b9c6-3881e9d6b26d payout_amount: 5.55595028 payout_currency: CAD status: FUNDS_RECEIVED transaction_type: ONRAMP responses: '200': description: Webhook received successfully virtual_account.created: post: summary: Virtual Account Created V1 description: Triggered when a new virtual account is created for a customer. x-mint: metadata: title: virtual_account.created V1 content: | Register this webhook if you are using the **Create Virtual Account V1** endpoint. All webhook requests include HMAC signatures for verification. tags: - Webhooks requestBody: required: true content: application/json: schema: type: object properties: event: $ref: '#/components/schemas/WebhookEventEnvelope' data: $ref: '#/components/schemas/VirtualAccountWebhookData' examples: created: summary: Virtual Account Created value: event: id: 3fb02b56-911e-42c0-843c-c08785bdde56 event_reference_id: 900f750d-6868-457e-a777-1a35566a6b5f type: virtual_account.created created_at: '2025-12-10T08:11:25.269644Z' sandbox_mode: true data: id: 900f750d-6868-457e-a777-1a35566a6b5f customer_id: a41a6d76-4545-47ab-93d1-696a3221d39c status: ACTIVE developer_fee_percent: 0.5 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 V2** 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: $ref: '#/components/schemas/WebhookEventEnvelope' 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: post: summary: Virtual Account Status V1 description: Triggered when a virtual account's status changes. x-mint: metadata: title: virtual_account.status V1 content: | Common status values: `ACTIVE`, `INACTIVE`, `SUSPENDED` Register this webhook if you are using the **Create Virtual Account V1** endpoint. All webhook requests include HMAC signatures for verification. tags: - Webhooks requestBody: required: true content: application/json: schema: type: object properties: event: $ref: '#/components/schemas/WebhookEventEnvelope' data: $ref: '#/components/schemas/VirtualAccountWebhookData' 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 V2** 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: $ref: '#/components/schemas/WebhookEventEnvelope' 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: $ref: '#/components/schemas/WebhookEventEnvelope' 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: $ref: '#/components/schemas/WebhookEventEnvelope' 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: $ref: '#/components/schemas/WebhookEventEnvelope' 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 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: $ref: '#/components/schemas/WebhookEventEnvelope' 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