openapi: 3.1.0 info: title: Fin.com API version: 1.0.0 description: A simple API specification 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 endpoint 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 paths: # AUTHENTICATION "/v1/oauth/token": post: summary: Issue a Token description: Generate an access token using client credentials x-mint: content: | Grab your `client_id` and `client_secret` from the [API Keys](https://orchestration.fin.com/api-keys) section of the [Orchestration Dashboard](https://orchestration.fin.com/) The TTLs returned from this API are actually the time that the the token will expire; i.e. not validity in number of seconds since creation. The timestamps, i.e. TTLs returned from this endpoint are NOT in ISO 8601 format. Rather it is in the format `YYYY-MM-DD HH:MM:SS+00` tags: - Authentication requestBody: required: true content: application/json: schema: type: object required: - client_id - client_secret properties: client_id: type: string description: Client ID client_secret: type: string description: Client Secret format: password responses: '200': description: Token issued successfully content: application/json: schema: $ref: '#/components/schemas/TokenResponse' '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' "/v1/oauth/refresh-token": post: summary: Refresh a Token description: Generate a new token pair based from 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 `/v1/oauth/token` endpoint. responses: '200': description: Token issued successfully content: application/json: schema: $ref: '#/components/schemas/TokenResponse' '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' # CUSTOMERS "/v1/customers": get: summary: List Customers description: Retrieve a list of customers filtered by type tags: - Customers security: - bearerAuth: [] parameters: - name: type in: query description: Filter customers by type required: true schema: type: string enum: - INDIVIDUAL - BUSINESS - $ref: '#/components/parameters/PerPageParam' - $ref: '#/components/parameters/CurrentPageParam' responses: '200': description: List of customers retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: type: object properties: current_page: type: integer description: The current page number example: 1 per_page: type: integer description: Number of items per page example: 10 total_page: type: integer description: Total number of pages example: 1 total: type: integer description: Total number of items example: 2 customers: type: array items: oneOf: - type: object properties: customer_id: type: string format: uuid description: Unique identifier for the customer example: "56c41b8e-e650-4f55-94f6-26a888a9b64d" type: type: string enum: [INDIVIDUAL] description: Customer type first_name: type: string description: Customer's first name example: "Omran" last_name: type: string description: Customer's last name example: "Jamal" email: type: string format: email description: Customer's email address example: "omran@omranjamal.me" phone: type: string description: Customer's phone number example: "+14724480512" country_of_residence: type: string description: Country of residence code example: "USA" customer_status: type: string description: Current status of the customer example: "INCOMPLETE" tos_policies_url: type: string format: uri description: URL for Terms of Service policies example: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=56c41b8e-e650-4f55-94f6-26a888a9b64d&tos_policies_value=a93d34a1-fc39-48a1-afdb-fd5c4607c5df" created_at: type: string format: date-time description: Timestamp when customer was created example: "2025-12-22T06:41:18Z" updated_at: type: string format: date-time description: Timestamp when customer was last updated example: "2025-12-22T06:41:28Z" - type: object properties: customer_id: type: string format: uuid description: Unique identifier for the customer example: "94e6b847-4e19-49e3-b3ab-ffa95872eda9" type: type: string enum: [BUSINESS] description: Customer type business_name: type: string description: Business name example: "Rocy Pte Ltd Business c2" email: type: string format: email description: Business email address example: "rocy@jane.com" phone: type: string description: Business phone number example: "+8801912200000" country_of_incorporation: type: string description: Country of incorporation code example: "BGD" customer_status: type: string description: Current status of the customer example: "INCOMPLETE" tos_policies_url: type: string format: uri description: URL for Terms of Service policies example: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=94e6b847-4e19-49e3-b3ab-ffa95872eda9&tos_policies_value=ecbbfdf0-2138-4877-8a7d-280b2ee02008" created_at: type: string format: date-time description: Timestamp when customer was created example: "2025-12-24T07:55:42Z" updated_at: type: string format: date-time description: Timestamp when customer was last updated example: "2025-12-24T07:55:43Z" '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' "/v1/customers/{customer_id}": get: summary: Get Customer Details description: Retrieve detailed information for a specific customer tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid description: Unique identifier for the customer example: "55bd6b4e-c20a-4cc8-9535-91d5557a67d9" responses: '200': description: Customer details retrieved successfully content: application/json: schema: type: object properties: data: oneOf: - type: object properties: customer_id: type: string format: uuid description: Unique identifier for the customer example: "56c41b8e-e650-4f55-94f6-26a888a9b64d" type: type: string enum: [INDIVIDUAL] description: Customer type first_name: type: string description: Customer's first name example: "Omran" last_name: type: string description: Customer's last name example: "Jamal" email: type: string format: email description: Customer's email address example: "omran@omranjamal.me" phone: type: string description: Customer's phone number example: "+14724480512" country_of_residence: type: string description: Country of residence code example: "USA" verification_type: type: string description: Type of verification example: "STANDARD" customer_status: type: string description: Current status of the customer example: "INCOMPLETE" tos_policies_url: type: string format: uri description: URL for Terms of Service policies example: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=56c41b8e-e650-4f55-94f6-26a888a9b64d&tos_policies_value=a93d34a1-fc39-48a1-afdb-fd5c4607c5df" created_at: type: string format: date-time description: Timestamp when customer was created example: "2025-12-22T06:41:18Z" updated_at: type: string format: date-time description: Timestamp when customer was last updated example: "2025-12-22T06:41:28Z" capabilities: type: object properties: on_ramp: type: array items: type: object properties: currency: type: string description: Currency code example: "USD" status: type: boolean description: Whether the capability is enabled example: false methods: type: array items: type: string description: Available methods example: ["ACH", "FEDWIRE"] reason: type: object properties: for_customer: type: string nullable: true description: Reason message for customer for_developer: type: string nullable: true description: Reason message for developer off_ramp: type: array items: type: object properties: currency: type: string description: Currency code example: "USD" status: type: boolean description: Whether the capability is enabled example: false methods: type: array items: type: string description: Available methods example: ["ACH", "FEDWIRE", "ACH_SAME_DAY"] reason: type: object properties: for_customer: type: string nullable: true description: Reason message for customer for_developer: type: string nullable: true description: Reason message for developer example: "Complete verification" - type: object properties: customer_id: type: string format: uuid description: Unique identifier for the customer example: "94e6b847-4e19-49e3-b3ab-ffa95872eda9" type: type: string enum: [BUSINESS] description: Customer type business_name: type: string description: Business name example: "Rocy Pte Ltd Business c2" email: type: string format: email description: Business email address example: "rocy@jane.com" phone: type: string description: Business phone number example: "+8801912200000" country_of_incorporation: type: string description: Country of incorporation code example: "BGD" verification_type: type: string description: Type of verification example: "STANDARD" customer_status: type: string description: Current status of the customer example: "INCOMPLETE" tos_policies_url: type: string format: uri description: URL for Terms of Service policies example: "https://orchestration.fin.com/orchestration-customer-tos?customer_id=94e6b847-4e19-49e3-b3ab-ffa95872eda9&tos_policies_value=ecbbfdf0-2138-4877-8a7d-280b2ee02008" associated_parties: type: array description: Array of associated parties for the business items: type: object properties: id: type: string format: uuid description: Unique identifier for the associated party example: "42daffd3-09a0-4d48-8e73-2680a953d0e1" type: type: string description: Type of associated party example: "INDIVIDUAL" ownership_percent: type: number description: Ownership percentage example: 10 email: type: string format: email description: Associated party email example: "john.ubo.c1@jane.com" verification: type: object properties: status: type: string description: Verification status example: "INITIATED" reason: type: object properties: for_customer: type: string nullable: true description: Reason message for customer for_developer: type: string nullable: true description: Reason message for developer updated_at: type: string format: date-time description: Timestamp when verification was last updated example: "2025-12-24T07:55:52Z" created_at: type: string format: date-time description: Timestamp when customer was created example: "2025-12-24T07:55:42Z" updated_at: type: string format: date-time description: Timestamp when customer was last updated example: "2025-12-24T07:55:43Z" capabilities: type: object properties: on_ramp: type: array items: type: object properties: currency: type: string description: Currency code example: "USD" status: type: boolean description: Whether the capability is enabled example: false methods: type: array items: type: string description: Available methods example: ["ACH", "FEDWIRE"] reason: type: object properties: for_customer: type: string nullable: true description: Reason message for customer for_developer: type: string nullable: true description: Reason message for developer off_ramp: type: array items: type: object properties: currency: type: string description: Currency code example: "USD" status: type: boolean description: Whether the capability is enabled example: false methods: type: array items: type: string description: Available methods example: ["ACH", "FEDWIRE", "ACH_SAME_DAY"] reason: type: object properties: for_customer: type: string nullable: true description: Reason message for customer for_developer: type: string nullable: true description: Reason message for developer example: "Complete verification" '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' "/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. 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 description: Unique identifier for the created customer example: "55bd6b4e-c20a-4cc8-9535-91d5557a67d9" 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=55bd6b4e-c20a-4cc8-9535-91d5557a67d9&tos_policies_value=e9414388-fbdf-4407-b5c2-bc39eae3645b" '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' "/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., file1, file2, file3, 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., `file1`, `file2`, `document1`, etc.). tags: - Customers security: - bearerAuth: [] requestBody: required: true content: multipart/form-data: schema: type: object properties: customer_id: type: string format: uuid description: Unique identifier for the customer example: "659fd1e8-b7db-4276-8c0f-33b354fe68ef" file1: type: string format: binary description: Document files to upload (can use any field name) file_foo: type: string format: binary description: Document files to upload (can use any field name) file_bar: type: string format: binary description: Document files to upload (can use any field name) "[what_ever_you_want]": type: string format: binary description: Document files to upload (can use any field name) 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 description: File URI (useful for document attachment), keyed by the form field name used in upload example: file1: "/AbAcQ4hn_0652746727637.pdf" description: Array of uploaded file information with field names as keys and server paths as values '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' "/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 `/v1/customers/upload` 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 description: Unique identifier for the customer 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: | Before calling this endpoint, upload documents using the `/v1/customers/upload` 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: | Before calling this endpoint, upload documents using the `/v1/customers/upload` 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 tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - customer_id properties: customer_id: type: string format: uuid description: Unique identifier for the customer 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' # BENEFICIARIES "/v1/beneficiaries/dynamic-required-fields": get: summary: List Required Information For Beneficiaries description: Retrieve dynamic list of required fields and validation rules for creating a beneficiary based on country, currency, and payment method tags: - Beneficiaries security: - bearerAuth: [] parameters: - name: customer_id in: query required: true schema: type: string format: uuid description: Customer ID of a verified customer example: "5a6f47f7-7326-409f-a4da-90e409133fb8" - name: beneficiary_type in: query required: true schema: type: string enum: - INDIVIDUAL - BUSINESS description: Beneficiary type - name: country_code in: query required: true schema: type: string description: ISO Alpha-3 country code of any supported country from the 'Get countries' list example: "USA" - name: currency_code in: query required: true schema: type: string description: Currency code of the supported country example: "USD" - name: method in: query required: true schema: type: string description: Available method for a particular country (e.g., BANK, E_WALLET) example: "BANK" - name: method_id in: query required: true schema: type: string description: Available method ID of a particular country example: "1" - name: branch_id in: query required: false schema: type: string description: (Optional) Required if method contains branches example: "100" responses: '200': description: Required fields retrieved successfully content: application/json: schema: type: object properties: data: type: array items: type: object properties: info: type: string description: Human-readable description of the field example: "Customer ID of our system" key: type: string description: Field key name example: "customer_id" validation_rule: type: object description: Validation rules for this field properties: type: type: string description: Data type for the field enum: - UUID - TEXT - NUMBER - DECIMAL example: "UUID" max_length: type: integer description: Maximum length for text fields example: 36 min_length: type: integer description: Minimum length for text fields example: 36 min: type: number description: Minimum value for number/decimal fields example: 0 allowed_values: type: array description: List of allowed values (for enum-like fields) items: type: string example: ["POLYGON"] examples: OK: summary: OK value: data: - info: "Customer ID of our system" key: "customer_id" validation_rule: max_length: 36 min_length: 36 type: "UUID" - info: "Refund Wallet Address" key: "refund_wallet_address" validation_rule: max_length: 42 min_length: 42 type: "TEXT" - info: "Bank branch id" key: "receiver_destination_branch_id" validation_rule: min: 1 type: "NUMBER" - info: "Wallet ID" key: "receiver_destination_account_number" validation_rule: max_length: 20 min_length: 1 type: "TEXT" - info: "Name of the blockchain network (e.g., Ethereum, Polygon)" key: "source_chain_name" validation_rule: allowed_values: - "POLYGON" type: "TEXT" - info: "Payment Mode" key: "receiver_destination_method" validation_rule: allowed_values: - "BANK" - "E_WALLET" max_length: 50 type: "TEXT" - info: "Enter Dev Fee (Fixed)" key: "developer_fee_fixed" validation_rule: min: 0 type: "DECIMAL" - info: "Can be a bank or e_wallet id" key: "receiver_destination_method_id" validation_rule: min: 1 type: "NUMBER" - info: "Id of the crypto token (e.g., USDC, USDT)" key: "source_token_id" validation_rule: allowed_values: - "USDC" - "USDT" type: "TEXT" - info: "Receiver First Name" key: "receiver_first_name" validation_rule: max_length: 100 min_length: 1 type: "TEXT" - info: "Enter Dev Fee (Percentage)" key: "developer_fee_percentage" validation_rule: min: 0 type: "DECIMAL" - info: "Enter Beneficiary Type" key: "beneficiary_type" validation_rule: allowed_values: - "INDIVIDUAL" - "BUSINESS" type: "TEXT" - info: "Receiver Country" key: "receiver_country_code" validation_rule: max_length: 3 min_length: 3 type: "TEXT" - info: "Purpose Of Remittance" key: "purpose_of_remittance" validation_rule: max_length: 2 min_length: 2 type: "TEXT" - info: "Receiver Last Name" key: "receiver_last_name" validation_rule: max_length: 100 min_length: 1 type: "TEXT" '401': $ref: '#/components/responses/AuthenticationError' "/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 description: Unique identifier for the country example: 4 code: type: string description: ISO Alpha-3 country code example: "AUS" name: type: string description: Country name example: "Australia" currency_code: type: string description: Currency code for the country example: "AUD" phone: type: object description: Phone validation rules for the country properties: code: type: string description: International phone dialing code example: "+61" max_length: type: integer description: Maximum phone number length example: 9 min_length: type: integer description: Minimum phone number length example: 9 available_methods: type: array description: Available payment methods for the country items: type: string enum: - BANK - E_WALLET example: ["BANK"] flag: type: string format: uri description: URL to the country's flag image example: "https://flagcdn.com/au.svg" examples: OK: summary: OK value: data: - id: 4 code: "AUS" name: "Australia" currency_code: "AUD" phone: code: "+61" max_length: 9 min_length: 9 available_methods: - "BANK" flag: "https://flagcdn.com/au.svg" - id: 26 code: "BGD" name: "Bangladesh" currency_code: "BDT" phone: code: "+880" max_length: 10 min_length: 10 available_methods: - "BANK" - "E_WALLET" flag: "https://flagcdn.com/bd.svg" - id: 5 code: "CAN" name: "Canada" currency_code: "CAD" phone: code: "+1" max_length: 10 min_length: 10 available_methods: - "BANK" flag: "https://flagcdn.com/ca.svg" - id: 51 code: "CHN" name: "China" currency_code: "CNY" phone: code: "+86" max_length: 11 min_length: 11 available_methods: - "BANK" flag: "https://flagcdn.com/cn.svg" - id: 8 code: "JPN" name: "Japan" currency_code: "JPY" phone: code: "+81" max_length: 11 min_length: 10 available_methods: - "BANK" flag: "https://flagcdn.com/jp.svg" - id: 1 code: "SGP" name: "Singapore" currency_code: "SGD" phone: code: "+65" max_length: 8 min_length: 8 available_methods: - "BANK" flag: "https://flagcdn.com/sg.svg" - id: 75 code: "ETH" name: "Ethiopia" currency_code: "ETB" phone: code: "+251" max_length: 9 min_length: 9 available_methods: - "BANK" - "E_WALLET" flag: "https://flagcdn.com/et.svg" - id: 86 code: "GHA" name: "Ghana" currency_code: "GHS" phone: code: "+233" max_length: 9 min_length: 9 available_methods: - "BANK" - "E_WALLET" flag: "https://flagcdn.com/gh.svg" - id: 104 code: "IND" name: "India" currency_code: "INR" phone: code: "+91" max_length: 10 min_length: 10 available_methods: - "BANK" flag: "https://flagcdn.com/in.svg" - id: 116 code: "KEN" name: "Kenya" currency_code: "KES" phone: code: "+254" max_length: 9 min_length: 9 available_methods: - "BANK" - "E_WALLET" flag: "https://flagcdn.com/ke.svg" - id: 119 code: "KOR" name: "Korea (South)" currency_code: "KRW" phone: code: "+82" max_length: 11 min_length: 10 available_methods: - "BANK" flag: "https://flagcdn.com/kr.svg" - id: 150 code: "MAR" name: "Morocco" currency_code: "MAD" phone: code: "+212" max_length: 9 min_length: 9 available_methods: - "BANK" flag: "https://flagcdn.com/ma.svg" - id: 152 code: "MMR" name: "Myanmar" currency_code: "MMK" phone: code: "+95" max_length: 9 min_length: 8 available_methods: - "BANK" flag: "https://flagcdn.com/mm.svg" - id: 155 code: "NPL" name: "Nepal" currency_code: "NPR" phone: code: "+977" max_length: 10 min_length: 7 available_methods: - "BANK" flag: "https://flagcdn.com/np.svg" - id: 219 code: "THA" name: "Thailand" currency_code: "THB" phone: code: "+66" max_length: 9 min_length: 9 available_methods: - "BANK" flag: "https://flagcdn.com/th.svg" - id: 161 code: "NGA" name: "Nigeria" currency_code: "NGN" phone: code: "+234" max_length: 10 min_length: 10 available_methods: - "BANK" - "E_WALLET" flag: "https://flagcdn.com/ng.svg" - id: 167 code: "PAK" name: "Pakistan" currency_code: "PKR" phone: code: "+92" max_length: 10 min_length: 10 available_methods: - "BANK" flag: "https://flagcdn.com/pk.svg" - id: 174 code: "PHL" name: "Philippines" currency_code: "PHP" phone: code: "+63" max_length: 10 min_length: 10 available_methods: - "BANK" flag: "https://flagcdn.com/ph.svg" - id: 230 code: "UGA" name: "Uganda" currency_code: "UGX" phone: code: "+256" max_length: 9 min_length: 9 available_methods: - "BANK" - "E_WALLET" flag: "https://flagcdn.com/ug.svg" - id: 3 code: "GBR" name: "United Kingdom" currency_code: "GBP" phone: code: "+44" max_length: 10 min_length: 10 available_methods: - "BANK" flag: "https://flagcdn.com/gb.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 description: ISO Alpha-3 country code based on available countries to offramp example: "BGD" - name: method in: query required: true schema: type: string enum: - BANK - E_WALLET description: Payment method based on available methods in a particular country 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 description: Unique identifier for the bank or e-wallet example: 1461 name: type: string description: Name of the bank or e-wallet provider example: "AB BANK LTD." method: type: string enum: - BANK - E_WALLET description: Method type example: "BANK" has_branch: type: boolean description: Whether this bank/provider has branches example: true examples: OK: summary: OK value: data: - id: 1461 name: "AB BANK LTD." method: "BANK" has_branch: true - id: 1462 name: "AGRANI BANK LTD." method: "BANK" has_branch: true - id: 1463 name: "AL-ARAFAH ISLAMI BANK LTD." method: "BANK" has_branch: true - id: 1464 name: "BANGLADESH BANK" method: "BANK" has_branch: true - id: 1465 name: "BANGLADESH COMMERCE BANK LTD." method: "BANK" has_branch: true - id: 1472 name: "BRAC BANK LTD." method: "BANK" has_branch: true - id: 1477 name: "DUTCH-BANGLA BANK LTD" method: "BANK" has_branch: true - id: 1478 name: "EASTERN BANK LTD." method: "BANK" has_branch: true - id: 1485 name: "ISLAMI BANK BANGLDESH LTD." method: "BANK" has_branch: true - id: 1487 name: "JANATA BANK LTD." method: "BANK" has_branch: true - id: 1493 name: "NATIONAL BANK LTD." method: "BANK" has_branch: true - id: 1501 name: "PRIME BANK LTD." method: "BANK" has_branch: true - id: 1502 name: "PUBALI BANK LTD." method: "BANK" has_branch: true - id: 1512 name: "STANDARD CHARTERED BANK" method: "BANK" has_branch: true - id: 1514 name: "THE CITY BANK LTD." method: "BANK" has_branch: 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 description: The method ID (bank ID) obtained from the List Bank Identifiers endpoint 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 description: Unique identifier for the branch example: 21513 name: type: string description: Name of the branch example: "SITAKUNDA" branch_code: type: string description: Branch code example: "020157391" examples: OK: summary: OK value: data: - id: 21513 name: "SITAKUNDA" branch_code: "020157391" - id: 21514 name: "JHENAIDAH" branch_code: "020440640" - id: 21515 name: "KAKRAIL" branch_code: "020273370" - id: 21516 name: "CHANDPUR" branch_code: "020130318" - id: 21517 name: "KAWRAN BAZAR" branch_code: "020262536" - id: 21518 name: "ISLAMPUR" branch_code: "020272984" - id: 21519 name: "JESSORE" branch_code: "020410946" - id: 21520 name: "CDA AVENUE" branch_code: "020151489" - id: 21522 name: "TAJPOOR" branch_code: "020913827" - id: 21523 name: "SAVAR" branch_code: "020264097" - id: 21533 name: "MOTIJHEEL" branch_code: "020274245" - id: 21535 name: "AGRABAD" branch_code: "020150130" - id: 21536 name: "DHANMONDI" branch_code: "020261182" - id: 21538 name: "GULSHAN" branch_code: "020261724" - id: 21540 name: "PRINCIPAL" branch_code: "020275352" '401': $ref: '#/components/responses/AuthenticationError' "/v2/beneficiaries": post: summary: Create Beneficiary description: Create a new beneficiary account for payments and transfers x-mint: content: | Beneficiary creation requires the customer to be in the `APPROVED` status. Ensure the customer has been approved before attempting to create beneficiaries. tags: - Beneficiaries security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - customer_id - country - currency - account_holder - bank_account - bank_routing - bank_address - account_holder_address - receiver_meta_data - developer_fee - deposit_instruction - refund_instruction properties: customer_id: type: string description: Unique identifier for the customer example: "cust_123456" country: type: string description: 3 letter country code from catalog example: "USA" currency: type: string description: 3 letter currency code example: "USD" account_holder: oneOf: - type: object required: - type - first_name - last_name - email - phone properties: type: type: string enum: [INDIVIDUAL] description: Account holder type first_name: type: string description: First name of the individual example: "John" last_name: type: string description: Last name of the individual example: "Doe" email: type: string format: email description: Email address example: "john.doe@example.com" phone: type: string description: Phone number example: "+1234567890" - type: object required: - type - business_name - email - phone properties: type: type: string enum: [BUSINESS] description: Account holder type business_name: type: string description: Name of the business example: "Acme Corp" email: type: string format: email description: Email address example: "contact@acmecorp.com" phone: type: string description: Phone number example: "+1234567890" discriminator: propertyName: type mapping: INDIVIDUAL: '#/components/schemas/IndividualAccountHolder' BUSINESS: '#/components/schemas/BusinessAccountHolder' bank_account: type: object required: - bank_name - number - scheme - type properties: bank_name: type: string description: Name of the bank example: "Chase Bank" number: type: string description: Bank account number example: "1234567890" scheme: type: string enum: [LOCAL, SWIFT] description: Banking scheme type: type: string enum: [CHECKING, SAVINGS, CURRENT] description: Account type bank_routing: type: array description: Array of bank routing information 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] description: Routing scheme type number: type: string description: Routing number example: "021000021" bank_address: type: object required: - street_line_1 - city - state - postcode - country properties: street_line_1: type: string description: Street address line 1 example: "123 Bank Street" street_line_2: type: string description: Street address line 2 (optional) example: "Suite 100" city: type: string description: City name example: "New York" state: type: string description: State code from catalog; must belong to the country example: "US-NY" postcode: type: string description: Postal code; must belong to the country and match the format of the country example: "10001" country: type: string description: 3 letter country code from catalog example: "USA" account_holder_address: type: object required: - street_line_1 - city - state - postcode - country properties: street_line_1: type: string description: Street address line 1 example: "456 Main Street" street_line_2: type: string description: Street address line 2 (optional) example: "Apt 5B" city: type: string description: City name example: "Brooklyn" state: type: string description: State code from catalog; must belong to the country example: "US-NY" postcode: type: string description: Postal code; must belong to the country and match the format of the country example: "11201" country: type: string description: 3 letter country code from catalog example: "USA" receiver_meta_data: type: object required: - transaction_purpose_id - occupation_remarks - relationship - nationality - govt_id_issuance_date - govt_id_number - govt_id_expiry_date properties: transaction_purpose_id: type: integer description: Transaction purpose ID from catalog example: 1 transaction_purpose_remarks: type: string description: Additional remarks for transaction purpose (optional) example: "Monthly salary payment" occupation_id: type: integer description: Occupation ID from catalog. Only required for individual beneficiaries, not for businesses. example: 5 occupation_remarks: type: string description: Additional remarks for occupation 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] description: Relationship to the beneficiary relationship_remarks: type: string description: Additional remarks for relationship (optional) example: "Long-term contractor" nationality: type: string description: Country code from catalog representing nationality example: "USA" govt_id_issuance_date: type: string format: date description: Government ID issuance date in YYYY-MM-DD format example: "2020-01-15" govt_id_number: type: string description: Government ID number (required for some currencies) example: "123456789" govt_id_expiry_date: type: string format: date description: Government ID expiry date in YYYY-MM-DD format example: "2030-01-15" developer_fee: type: object required: - fixed - percentage properties: fixed: type: number description: Fixed fee amount example: 5.00 percentage: type: string description: Percentage fee example: "2.5" deposit_instruction: type: object required: - currency - rail properties: currency: type: string enum: [USDC, USDT] description: Cryptocurrency for deposits rail: type: string enum: [POLYGON, ETHEREUM] description: Blockchain network refund_instruction: type: object required: - wallet_address - currency - rail properties: wallet_address: type: string description: Wallet address for refunds example: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" currency: type: string enum: [USDC] description: Currency for refunds rail: type: string enum: [POLYGON] description: Blockchain network for refunds settlement_config: type: object required: - auto_settlement properties: auto_settlement: type: boolean description: Enable automatic settlement example: true responses: '200': description: Beneficiary created successfully content: application/json: schema: type: object properties: data: type: object properties: id: type: string description: Unique identifier for the beneficiary example: "ben_123456" status: type: string description: Status of the beneficiary example: "active" '401': $ref: '#/components/responses/AuthenticationError' '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 description: Unique identifier for the customer 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 description: Unique identifier for the beneficiary example: "f653e109-6c62-4aa4-869c-418c874e0a6c" customer_id: type: string format: uuid description: Customer identifier example: "ad41fac1-e406-445b-aea4-69381c39ca5d" active: type: boolean description: Whether the beneficiary is active example: true country_code: type: string description: ISO Alpha-3 country code example: "AUS" business_name: type: string description: Business name (for BUSINESS type beneficiaries) example: "Investment bank" type: type: string enum: - INDIVIDUAL - BUSINESS description: Beneficiary type example: "BUSINESS" nationality: type: string description: Nationality country code example: "AUS" email: type: string format: email description: Beneficiary email example: "michael.oconnor@example.com" phone: type: string description: Beneficiary phone number example: "+61412345678" address: type: string description: Beneficiary address method: type: string enum: - BANK - E_WALLET description: Payment method example: "BANK" currency: type: string description: Payout currency example: "AUD" account_number: type: string description: Masked account number example: "*****6789" refund_wallet_address: type: string description: Refund wallet address example: "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F" developer_fee_fixed: type: number description: Fixed developer fee example: 1.25 developer_fee_percentage: type: number description: Percentage developer fee example: 0.45 liquidation_address: type: string description: Liquidation wallet address example: "0x185571d849dcfefff449bd1e9f847b1322f22834" auto_settlement: type: boolean description: Whether auto-settlement is enabled example: false source_currency: type: string description: Source cryptocurrency example: "USDC" source_chain: type: string description: Source blockchain example: "POLYGON" created_at: type: string format: date-time description: Timestamp when beneficiary was created example: "2025-12-09T14:56:47.916263Z" updated_at: type: string format: date-time description: Timestamp when beneficiary was last updated example: "2025-12-09T14:56:49.1308Z" examples: OK: summary: OK value: data: - id: "f653e109-6c62-4aa4-869c-418c874e0a6c" customer_id: "ad41fac1-e406-445b-aea4-69381c39ca5d" active: true country_code: "AUS" business_name: "Investment bank" type: "BUSINESS" nationality: "AUS" email: "michael.oconnor@example.com" phone: "+61412345678" address: "" method: "BANK" currency: "AUD" account_number: "*****6789" refund_wallet_address: "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F" developer_fee_fixed: 1.25 developer_fee_percentage: 0.45 liquidation_address: "0x185571d849dcfefff449bd1e9f847b1322f22834" auto_settlement: false source_currency: "USDC" source_chain: "POLYGON" created_at: "2025-12-09T14:56:47.916263Z" updated_at: "2025-12-09T14:56:49.1308Z" - id: "f653e109-6c62-4aa4-869c-418c874e0a6c" customer_id: "ad41fac1-e406-445b-aea4-69381c39ca5d" active: true country_code: "AUS" business_name: "Investment Money" type: "BUSINESS" nationality: "AUS" email: "michael.oconnor@example.com" phone: "+61412345678" address: "" method: "BANK" currency: "AUD" account_number: "*****6789" refund_wallet_address: "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F" developer_fee_fixed: 1.25 developer_fee_percentage: 0.45 liquidation_address: "0x185571d849dcfefff449bd1e9f847b1322f22834" auto_settlement: false source_currency: "USDC" source_chain: "POLYGON" created_at: "2025-12-09T14:56:47.916263Z" updated_at: "2025-12-09T14:56:49.1308Z" '401': $ref: '#/components/responses/AuthenticationError' "/v1/beneficiaries/details": get: summary: Fetch Beneficiary Details description: Retrieve detailed information for a specific beneficiary tags: - Beneficiaries security: - bearerAuth: [] parameters: - name: customer_id in: query required: true schema: type: string format: uuid description: Unique identifier for the customer example: "ad41fac1-e406-445b-aea4-69381c39ca5d" - name: beneficiary_id in: query required: true schema: type: string format: uuid description: Unique identifier for the beneficiary 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 description: Unique identifier for the beneficiary example: "f653e109-6c62-4aa4-869c-418c874e0a6c" customer_id: type: string format: uuid description: Customer identifier example: "ad41fac1-e406-445b-aea4-69381c39ca5d" active: type: boolean description: Whether the beneficiary is active example: true country_code: type: string description: ISO Alpha-3 country code example: "AUS" first_name: type: string description: First name (for INDIVIDUAL type) example: "Michael" last_name: type: string description: Last name (for INDIVIDUAL type) example: "O'Connor" business_name: type: string description: Business name (for BUSINESS type) example: "Investment bank" type: type: string enum: - INDIVIDUAL - BUSINESS description: Beneficiary type example: "INDIVIDUAL" nationality: type: string description: Nationality country code example: "AUS" email: type: string format: email description: Beneficiary email example: "michael.oconnor@example.com" phone: type: string description: Beneficiary phone number example: "+61412345678" address: type: string description: Beneficiary address method: type: string enum: - BANK - E_WALLET description: Payment method example: "BANK" currency: type: string description: Payout currency example: "AUD" account_number: type: string description: Masked account number example: "*****6789" refund_wallet_address: type: string description: Refund wallet address example: "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F" developer_fee_fixed: type: number description: Fixed developer fee example: 1.25 developer_fee_percentage: type: number description: Percentage developer fee example: 0.45 liquidation_address: type: string description: Liquidation wallet address example: "0x185571d849dcfefff449bd1e9f847b1322f22834" auto_settlement: type: boolean description: Defines whether incoming funds trigger instant auto-processing, or if the developer must explicitly confirm and process the transaction using follow-up API calls example: false source_currency: type: string description: Source cryptocurrency example: "USDC" source_chain: type: string description: Source blockchain example: "POLYGON" created_at: type: string format: date-time description: Timestamp when beneficiary was created example: "2025-12-09T14:56:47.916263Z" updated_at: type: string format: date-time description: Timestamp when beneficiary was last updated example: "2025-12-09T14:56:49.1308Z" examples: OK - Individual: summary: OK - Individual value: data: id: "f653e109-6c62-4aa4-869c-418c874e0a6c" customer_id: "ad41fac1-e406-445b-aea4-69381c39ca5d" active: true country_code: "AUS" first_name: "Michael" last_name: "O'Connor" type: "INDIVIDUAL" nationality: "AUS" email: "michael.oconnor@example.com" phone: "+61412345678" address: "" method: "BANK" currency: "AUD" account_number: "*****6789" refund_wallet_address: "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F" developer_fee_fixed: 1.25 developer_fee_percentage: 0.45 liquidation_address: "0x185571d849dcfefff449bd1e9f847b1322f22834" auto_settlement: false source_currency: "USDC" source_chain: "POLYGON" created_at: "2025-12-09T14:56:47.916263Z" updated_at: "2025-12-09T14:56:49.1308Z" OK - Business: summary: OK - Business value: data: id: "f653e109-6c62-4aa4-869c-418c874e0a6c" customer_id: "ad41fac1-e406-445b-aea4-69381c39ca5d" active: true country_code: "AUS" business_name: "Investment bank" type: "BUSINESS" nationality: "AUS" email: "michael.oconnor@example.com" phone: "+61412345678" address: "" method: "BANK" currency: "AUD" account_number: "*****6789" refund_wallet_address: "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F" developer_fee_fixed: 1.25 developer_fee_percentage: 0.45 liquidation_address: "0x185571d849dcfefff449bd1e9f847b1322f22834" auto_settlement: false source_currency: "USDC" source_chain: "POLYGON" created_at: "2025-12-09T14:56:47.916263Z" updated_at: "2025-12-09T14:56:49.1308Z" '404': description: Beneficiary not found content: application/json: schema: type: object properties: errors: type: array items: type: object message: type: string example: "beneficiary not found" examples: Not Found: summary: Not Found value: errors: [] message: "beneficiary not found" '401': $ref: '#/components/responses/AuthenticationError' "/v1/beneficiaries": patch: summary: Update Beneficiary Active Status description: Update the active status of a beneficiary to enable or disable it tags: - Beneficiaries security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - beneficiary_id - active properties: beneficiary_id: type: string format: uuid description: Unique identifier for the beneficiary example: "f653e109-6c62-4aa4-869c-418c874e0a6c" active: type: boolean description: Set to true to activate or false to deactivate the beneficiary example: true responses: '200': description: Beneficiary updated successfully content: application/json: schema: type: object properties: data: type: object properties: message: type: string description: Success message example: "Beneficiary updated successfully" examples: OK: summary: OK value: data: message: "Beneficiary updated successfully" '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' # TRANSACTIONS "/v1/beneficiaries/{beneficiary_id}/": get: summary: List Transactions for Beneficiary description: Retrieve paginated transaction history for a specific beneficiary tags: - Transactions security: - bearerAuth: [] parameters: - name: version in: path required: true schema: type: string description: API version example: "v1" - name: beneficiary_id in: path required: true schema: type: string format: uuid description: Unique identifier for the beneficiary - name: per_page in: query required: false schema: type: string default: "2" description: Number of transactions per page (default 10) - name: current_page in: query required: false schema: type: string default: "1" description: Page number to retrieve (starts from 1) - name: transaction_type in: query required: false schema: type: string enum: - DEBIT - CREDIT description: Filter by transaction type responses: '200': description: Transaction list retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: type: object properties: current_page: type: integer example: 1 default: 0 per_page: type: integer example: 5 default: 0 total_page: type: integer example: 1 default: 0 total: type: integer example: 1 default: 0 transactions: type: array items: type: object properties: id: type: string format: uuid example: "9ac6872b-8904-4ea5-beb7-d5a936ffee10" transaction_type: type: string example: "DEBIT" beneficiary_id: type: string format: uuid example: "d6ae4ea6-0482-47ab-a895-02e50ea6358b" hash: type: string example: "0x58083dc1851a288496263cc1a4688a5abead5fd4f66b80516afaa27e5b3879d2" transaction_ref_id: type: string example: "cd25866b-265a-4e39-9" from_amount: type: integer example: 3 default: 0 payout_amount: type: number example: 1.748682 default: 0 processing_amount: type: number example: 2.335 default: 0 status: type: string example: "PENDING" fx_rate: type: number example: 0.7489 default: 0 developer_fee: type: number example: 0.665 default: 0 developer_fee_percentage: type: number example: 0.5 default: 0 developer_fee_fixed: type: number example: 0.65 default: 0 from_currency: type: string example: "USDC" payout_currency: type: string example: "GBP" created_at: type: string format: date-time example: "2025-10-26T09:38:45.641823Z" updated_at: type: string format: date-time example: "2025-10-26T09:39:04.013728Z" examples: OK: summary: OK value: data: pagination: current_page: 1 per_page: 5 total_page: 1 total: 1 transactions: - id: "9ac6872b-8904-4ea5-beb7-d5a936ffee10" transaction_type: "DEBIT" beneficiary_id: "d6ae4ea6-0482-47ab-a895-02e50ea6358b" hash: "0x58083dc1851a288496263cc1a4688a5abead5fd4f66b80516afaa27e5b3879d2" transaction_ref_id: "cd25866b-265a-4e39-9" from_amount: 3 payout_amount: 1.748682 processing_amount: 2.335 status: "PENDING" fx_rate: 0.7489 developer_fee: 0.665 developer_fee_percentage: 0.5 developer_fee_fixed: 0.65 from_currency: "USDC" payout_currency: "GBP" created_at: "2025-10-26T09:38:45.641823Z" updated_at: "2025-10-26T09:39:04.013728Z" '401': $ref: '#/components/responses/AuthenticationError' "/v1/beneficiaries/{beneficiary_id}/transactions/{transaction_id}": get: summary: Fetch Transaction Details description: Retrieve detailed information for a specific transaction by transaction ID or hash tags: - Transactions security: - bearerAuth: [] parameters: - name: version in: path required: true schema: type: string description: API version example: "v1" - name: beneficiary_id in: path required: true schema: type: string format: uuid description: Unique identifier for the beneficiary - name: transaction_id in: path required: true schema: type: string description: Transaction identifier (can be transaction ID or hash depending on 'by' parameter) - name: by in: query required: true schema: type: string enum: - TRX_ID - TRX_HASH description: Specify whether to query by transaction ID or the deposit transaction hash responses: '200': description: OK - Transaction details retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid example: "9ac6872b-8904-4ea5-beb7-d5a936ffee10" transaction_type: type: string example: "DEBIT" beneficiary_id: type: string format: uuid example: "d6ae4ea6-0482-47ab-a895-02e50ea6358b" hash: type: string example: "0x58083dc1851a288496263cc1a4688a5abead5fd4f66b80516afaa27e5b3879d2" transaction_ref_id: type: string example: "cd25866b-265a-4e39-9" from_amount: type: integer example: 3 default: 0 payout_amount: type: number example: 1.748682 default: 0 processing_amount: type: number example: 2.335 default: 0 status: type: string example: "COMPLETED" fx_rate: type: number example: 0.7489 default: 0 developer_fee: type: number example: 0.665 default: 0 developer_fee_percentage: type: number example: 0.5 default: 0 developer_fee_fixed: type: number example: 0.65 default: 0 source_chain: type: string example: "POLYGON" from_currency: type: string example: "USDC" payout_currency: type: string example: "GBP" created_at: type: string format: date-time example: "2025-10-26T09:38:45.641823Z" updated_at: type: string format: date-time example: "2025-10-26T09:44:01.963307Z" examples: OK: summary: OK value: data: id: "9ac6872b-8904-4ea5-beb7-d5a936ffee10" transaction_type: "DEBIT" beneficiary_id: "d6ae4ea6-0482-47ab-a895-02e50ea6358b" hash: "0x58083dc1851a288496263cc1a4688a5abead5fd4f66b80516afaa27e5b3879d2" transaction_ref_id: "cd25866b-265a-4e39-9" from_amount: 3 payout_amount: 1.748682 processing_amount: 2.335 status: "COMPLETED" fx_rate: 0.7489 developer_fee: 0.665 developer_fee_percentage: 0.5 developer_fee_fixed: 0.65 source_chain: "POLYGON" from_currency: "USDC" payout_currency: "GBP" created_at: "2025-10-26T09:38:45.641823Z" updated_at: "2025-10-26T09:44:01.963307Z" '401': $ref: '#/components/responses/AuthenticationError' "/v1/transactions/transfer-payout": post: summary: Create a Transfer description: Initiate a transfer payout to a beneficiary 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 description: Unique identifier for the beneficiary example: "d6ae4ea6-0482-47ab-a895-02e50ea6358b" reference_id: type: string description: Unique identifier in your system example: "REF-12345-ABC" amount: type: integer description: Amount in cents (multiply by 100) example: 10000 remarks: type: string description: Message for compliance purposes, if the customer needs to explain anything example: "Monthly payment for services" responses: '200': description: Transfer created successfully content: application/json: schema: type: object '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 description: Unique identifier for the transfer to settle 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 description: Unique identifier for the settled transaction 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 tags: - Transactions security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: array items: type: object required: - beneficiary_id - source_amount - source_currency - deduct_from properties: beneficiary_id: type: string format: uuid description: Unique identifier for the beneficiary example: "d6ae4ea6-0482-47ab-a895-02e50ea6358b" source_amount: type: string description: Amount to transfer example: "100.50" source_currency: type: string description: Source currency code example: "USD" deduct_from: type: string enum: - PREFUNDED_BALANCE - LIQUIDATION_ADDRESS description: Source of funds for the transfer remarks: type: string description: Any remarks for the compliance team or notes for the transaction. If passing remarks are supported for a corridor then the system will automatically pass it along with the transaction example: "Monthly salary payment" responses: '201': description: Batch created successfully content: application/json: schema: type: object properties: data: type: object properties: batch_id: type: string format: uuid description: Unique identifier for the batch example: "16940644-438d-4134-ab19-d195dda46124" examples: Created: summary: Created value: data: batch_id: "16940644-438d-4134-ab19-d195dda46124" '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 description: Unique identifier for the batch 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 description: Unique identifier for the batch example: "ad1a0a29-5a7f-4982-98cc-3f4416724660" items: type: array items: type: object required: - source_currency - source_amount - deduct_from - remarks - transaction_id - status properties: id: type: string format: uuid description: Unique identifier for the batch item example: "04df867e-fc99-40b3-a159-04d6f586bb95" beneficiary_id: type: string format: uuid description: Unique identifier for the beneficiary example: "86236e92-b6a9-4775-9ae9-99654ba87fde" source_amount: type: number description: Source amount for the transaction example: 456 source_currency: type: string enum: - USD description: Source currency code deduct_from: type: string enum: - PREFUNDED_BALANCE - LIQUIDATION_ADDRESS description: Source of funds for the transaction remarks: type: string description: Transaction remarks example: "auto settle false CAN" reason: type: string nullable: true description: Reason for status (if applicable) status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - REFUNDED description: Current status of the transaction example: "PROCESSING" transaction_id: type: string format: uuid description: Unique identifier for the transaction example: "d6ae5ea0-3817-4740-bf04-05aec73e7b80" examples: OK: summary: OK value: data: batch_id: "ad1a0a29-5a7f-4982-98cc-3f4416724660" items: - id: "04df867e-fc99-40b3-a159-04d6f586bb95" beneficiary_id: "86236e92-b6a9-4775-9ae9-99654ba87fde" source_amount: 456 source_currency: "USD" deduct_from: "PREFUNDED_BALANCE" remarks: "auto settle false CAN" reason: null status: "PROCESSING" transaction_id: "d6ae5ea0-3817-4740-bf04-05aec73e7b80" - id: "d4247163-75d0-4ae0-90da-21cdedbc4453" beneficiary_id: "921ee210-4e5c-481e-b15a-69d036886598" source_amount: 289 source_currency: "USD" deduct_from: "PREFUNDED_BALANCE" remarks: "auto settle true CAN" reason: null status: "PROCESSING" transaction_id: "6b7e6286-a361-47e3-aef3-3385071b166b" - id: "a3847f4d-47b5-489a-8f4e-21ef67b7e78d" beneficiary_id: "12901f5e-2fd6-4cc7-9bd5-f7a4c092b87a" source_amount: 373 source_currency: "USD" deduct_from: "PREFUNDED_BALANCE" remarks: "auto settle true CAN" reason: null status: "PROCESSING" transaction_id: "1be9d918-77b1-448d-b97d-c309f4389721" - id: "3678c596-bf2e-486a-a09a-1124f6486e73" beneficiary_id: "8faa89dc-9528-4aa0-9331-89b8b81f6560" source_amount: 199 source_currency: "USD" deduct_from: "PREFUNDED_BALANCE" remarks: "auto settle false CAN" reason: null status: "PROCESSING" transaction_id: "116f4dc8-6288-43e2-b20e-5414a7f6d7b7" '401': $ref: '#/components/responses/AuthenticationError' # BALANCES "/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 description: Currency code example: "USD" amount: type: integer description: Amount in cents (multiplied by 100) example: 150000 '401': $ref: '#/components/responses/AuthenticationError' # VIRTUAL ACCOUNTS "/v1/customers/virtual-account": post: summary: Create Virtual Account description: Create a virtual bank account for a customer to convert USD deposits to USDC on Polygon 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 description: Unique identifier for the customer example: "5a6f47f7-7326-409f-a4da-90e409133fb8" destination_currency: type: string enum: - USDC default: USDC description: Destination cryptocurrency destination_chain: type: string enum: - POLYGON default: POLYGON description: Blockchain network for destination source_rail: type: string description: Payment rail for deposits example: "ACH" source_currency: type: string description: Source currency code example: "USD" destination_wallet_address: type: string description: Destination wallet address in hexadecimal format (0x...) example: "0x7f1568190e318da16a9ef5a46cba19d5b97d9b29" developer_fee_percentage: type: number description: Developer fee percentage example: 1.5 examples: New Example: summary: New Example value: customer_id: "5a6f47f7-7326-409f-a4da-90e409133fb8" destination_currency: "USDC" destination_chain: "POLYGON" source_rail: "ACH" source_currency: "USD" destination_wallet_address: "0x7f1568190e318da16a9ef5a46cba19d5b97d9b29" developer_fee_percentage: 1.5 responses: '200': description: Virtual account created successfully content: application/json: schema: type: object required: - data properties: data: type: object required: - id - status - developer_fee_percent - customer_id - created_at - updated_at - deposit_instructions - destination properties: id: type: string format: uuid description: Unique identifier for the virtual account example: "eb99dce4-d26d-442a-9873-47336e9936ca" status: type: string description: Status of the virtual account example: "ACTIVE" developer_fee_percent: type: number description: The developer fee percentage set when creating the virtual account example: 1.5 customer_id: type: string format: uuid description: Customer identifier example: "5a6f47f7-7326-409f-a4da-90e409133fb8" created_at: type: string format: date-time description: Timestamp when the account was created in ISO 8601 format example: "2025-12-17T10:57:19.113092Z" updated_at: type: string format: date-time description: Timestamp when the account was last updated in ISO 8601 format example: "2025-12-17T10:57:19.113092Z" deposit_instructions: type: object required: - currency - bank_name - bank_address - bank_routing_number - bank_account_number - bank_beneficiary_name - bank_beneficiary_address - payment_rails 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: "900801702004" bank_beneficiary_name: type: string example: "Stageusa Testva" bank_beneficiary_address: type: string example: "1200 Pennsylvania Avenue NW, Georgia, GA 20500, US" payment_rails: type: array items: type: string example: ["ACH", "FEDWIRE"] destination: type: object required: - currency - destination_chain - address properties: currency: type: string enum: - USDC default: USDC description: Destination cryptocurrency destination_chain: type: string enum: - POLYGON default: POLYGON description: Blockchain network address: type: string description: The destination wallet address in hexadecimal format (0x...) example: "0x7f1568190e318da16a9ef5a46cba19d5b97d9b29" examples: OK: summary: OK value: data: id: "eb99dce4-d26d-442a-9873-47336e9936ca" status: "ACTIVE" developer_fee_percent: 1.5 customer_id: "5a6f47f7-7326-409f-a4da-90e409133fb8" created_at: "2025-12-17T10:57:19.113092Z" updated_at: "2025-12-17T10:57:19.113092Z" 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: "900801702004" bank_beneficiary_name: "Stageusa Testva" bank_beneficiary_address: "1200 Pennsylvania Avenue NW, Georgia, GA 20500, US" payment_rails: - "ACH" - "FEDWIRE" destination: currency: "USDC" destination_chain: "POLYGON" address: "0x7f1568190e318da16a9ef5a46cba19d5b97d9b29" '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' # CATALOGUE "/v1/fx-rate": get: summary: Fetch Exchange Rates description: Retrieve exchange rates for a specific country tags: - Catalogue security: - bearerAuth: [] parameters: - name: country_code in: query required: true schema: $ref: '#/components/schemas/CountryCode' description: ISO 3166-1 alpha-3 country code responses: '200': description: Exchange rates retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: from_currency: type: string description: Source currency code example: "USD" to_currency: type: string description: Target currency code example: "BDT" exchange_rate: type: number format: float description: Exchange rate from source to target currency example: 117.19 country: type: string description: ISO 3166-1 alpha-3 country code example: "BGD" '401': $ref: '#/components/responses/AuthenticationError' "/v1/industries": get: summary: List Industries description: Retrieve a list of available industries 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: type: object properties: current_page: type: integer description: The current page number example: 1 per_page: type: integer description: Number of items per page example: 10 total_page: type: integer description: Total number of pages example: 104 total: type: integer description: Total number of items example: 1040 industries: type: array items: type: object properties: id: type: integer description: Unique identifier for the industry example: 1 title: type: string description: Name of the industry 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: type: object properties: current_page: type: integer description: The current page number example: 1 per_page: type: integer description: Number of items per page example: 10 total_page: type: integer description: Total number of pages example: 87 total: type: integer description: Total number of items example: 870 occupations: type: array items: type: object properties: id: type: integer description: Unique identifier for the occupation example: 1 title: type: string description: Name of the occupation 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: type: object properties: current_page: type: integer description: The current page number example: 1 per_page: type: integer description: Number of items per page example: 10 total_page: type: integer description: Total number of pages example: 5 total: type: integer description: Total number of items example: 50 source_of_funds: type: array items: type: object properties: id: type: integer description: Unique identifier for the source of funds example: 1 title: type: string description: Name of the source of funds example: "Employment Income" '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: type: object properties: current_page: type: integer description: The current page number example: 1 per_page: type: integer description: Number of items per page example: 10 total_page: type: integer description: Total number of pages example: 3 total: type: integer description: Total number of items example: 30 purposes: type: array items: type: object properties: id: type: integer description: Unique identifier for the account purpose example: 1 title: type: string description: Name of the account purpose example: "Personal Savings" '401': $ref: '#/components/responses/AuthenticationError' "/v1/countries": get: summary: List Generic Country Codes — ISO 3166-1 alpha-3 description: Retrieve a list of country 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: type: object properties: current_page: type: integer description: The current page number example: 1 per_page: type: integer description: Number of items per page example: 10 total_page: type: integer description: Total number of pages example: 25 total: type: integer description: Total number of items example: 246 countries: type: array items: type: object properties: code: type: string description: ISO 3166-1 alpha-3 country code example: "AFG" name: type: string description: Country name example: "Afghanistan" currency_code: type: string description: Currency code for the country example: "AFN" phone_code: type: string description: International phone dialing code example: "+93" flag_url: type: string format: uri description: URL to the country's flag image example: "https://flagcdn.com/af.svg" '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 description: Name of the subdivision example: "Bandarban" code: type: string description: ISO 3166-2 subdivision code 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: type: object properties: current_page: type: integer description: The current page number example: 1 per_page: type: integer description: Number of items per page example: 10 total_page: type: integer description: Total number of pages example: 5 total: type: integer description: Total number of items example: 50 transaction_purposes: type: array items: type: object properties: id: type: integer description: Unique identifier for the transaction purpose example: 1 title: type: string description: Name of the transaction purpose example: "Personal Transfer" '401': $ref: '#/components/responses/AuthenticationError' webhooks: customer.created: post: summary: Customer Created description: | This webhook event is triggered when a customer is successfully created. The event supports both `INDIVIDUAL` and `BUSINESS` customer types. For business customers, the payload includes associated parties with their ownership percentages and verification status. x-mint: metadata: title: customer.created content: | **Security:** All webhook requests include HMAC signatures for verification. Learn how to [verify webhook signatures](/guides/webhooks/verifying-webhooks) to ensure requests are authentic. tags: - Webhooks requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerCreatedWebhook' 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" updated_at: "2025-11-30T07:40:07Z" verification_type: "RELIANCE" businessCreated: summary: Business Customer Created value: event: id: "d2a592e4-5703-46aa-b1ac-fa1fa6359abf" event_reference_id: "b222b827-3ac7-4d20-bfd0-ebedc44435f7" type: "customer.created" created_at: "2025-11-30T08:01:03.819938Z" sandbox_mode: true data: associated_parties: - email: "john.doe@email.com" id: "07365877-f98f-4efa-acef-b15932fc3415" ownership_percent: 52 type: "INDIVIDUAL" verification: reason: for_customer: null for_developer: null status: "INITIATED" updated_at: "2025-11-30T08:01:02.824452053Z" business_name: "Acme Corp" country_of_incorporation: "USA" created_at: "2025-11-30T08:01:03Z" customer_id: "b222b827-3ac7-4d20-bfd0-ebedc44435f7" customer_status: "INCOMPLETE" email: "contact@acmecorp.com" phone: "+12125550123" tos_policies_url: "7e5bdf95-8dea-44d1-8810-987befbe2594" type: "BUSINESS" updated_at: "2025-11-30T08:01:03.797370576Z" verification_type: "RELIANCE" responses: '200': description: Webhook received successfully customer.status: post: summary: Customer Status description: | This webhook is triggered when a customer's status changes during the verification process. The event captures transitions between different customer states such as `REVIEWING`, `APPROVED`, `ASSOCIATED_PARTIES_REMAINING`, `ON_HOLD`, and others. This allows you to track the progression of customer verification and take appropriate actions based on status changes. x-mint: metadata: title: customer.status content: | **Security:** All webhook requests include HMAC signatures for verification. Learn how to [verify webhook signatures](/guides/webhooks/verifying-webhooks) to ensure requests are authentic. tags: - Webhooks requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerStatusWebhook' examples: individualReviewing: summary: Individual Customer Reviewing value: event: id: "d9851714-d65d-40c2-9bdb-917a2e053547" event_reference_id: "efb54adf-b7f4-4716-80e3-806e11f20b7b" type: "customer.status" created_at: "2025-12-10T10:30:20.591753Z" sandbox_mode: true data: country_of_residence: "CAN" created_at: "0001-01-01T00:00:00Z" customer_id: "efb54adf-b7f4-4716-80e3-806e11f20b7b" customer_status: "REVIEWING" email: "jane.doe@email.com" first_name: "Jane" last_name: "Doe" phone: "+14161234545" tos_policies_url: "ffa0d3f3-1db7-44b1-b676-254369086d98" type: "INDIVIDUAL" updated_at: "0001-01-01T00:00:00Z" verification_type: "STANDARD" individualApproved: summary: Individual Customer Approved value: event: id: "ea7e6e62-2cf6-4bd9-827e-b3fdfd0449c6" event_reference_id: "efb54adf-b7f4-4716-80e3-806e11f20b7b" type: "customer.status" created_at: "2025-12-10T10:30:20.83229Z" sandbox_mode: true data: country_of_residence: "CAN" created_at: "0001-01-01T00:00:00Z" customer_id: "efb54adf-b7f4-4716-80e3-806e11f20b7b" customer_status: "APPROVED" email: "jane.doe@email.com" first_name: "Jane" last_name: "Doe" phone: "+14161234545" tos_policies_url: "ffa0d3f3-1db7-44b1-b676-254369086d98" type: "INDIVIDUAL" updated_at: "0001-01-01T00:00:00Z" verification_type: "STANDARD" businessOnHold: summary: 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: "2025-12-10T10:32:59.434557Z" sandbox_mode: true data: business_name: "Acme Corp" country_of_incorporation: "BGD" created_at: "0001-01-01T00:00:00Z" customer_id: "98665e7d-7736-4762-a57a-cc1e6706302f" customer_status: "ON_HOLD" email: "contact@acmecorp.com" phone: "+8801912200000" tos_policies_url: "3cda07a1-2b47-4274-927a-cc840eaadd05" type: "BUSINESS" updated_at: "0001-01-01T00:00:00Z" verification_type: "STANDARD" responses: '200': description: Webhook received successfully transaction.status: post: summary: Transaction Status description: | This webhook event is triggered when a transaction's status changes. It provides real-time updates as transactions progress through different stages, including when funds are received, when processing begins, and if a transaction fails. Common status values include: - `FUNDS_RECEIVED` - Initial funds have been received from the sender - `PROCESSING` - Transaction is being processed - `COMPLETED` - Transaction has completed successfully - `FAILED` - Transaction has failed and will not complete x-mint: metadata: title: transaction.status content: | **Security:** All webhook requests include HMAC signatures for verification. Learn how to [verify webhook signatures](/guides/webhooks/verifying-webhooks) to ensure requests are authentic. tags: - Webhooks requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TransactionStatusWebhook' 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" created_at: "2025-12-01T09:14:34.623187982Z" developer_fee: 1.7836 developer_fee_fixed: 1.75 developer_fee_percentage: 0.56 from_amount: 6 from_currency: "USDC" fx_rate: 1.3177 hash: "0x3a282c0d2364632bdf9224eadf06b463190795bce24e46d3235e44d22f953461" id: "ca9a04d8-4e68-4557-b9c6-3881e9d6b26d" payout_amount: 5.55595028 payout_currency: "CAD" processing_amount: 4.2164 status: "FUNDS_RECEIVED" transaction_ref_id: "c494ac07-becd-4840-9" transaction_type: "DEBIT" updated_at: "2025-12-01T09:14:34.623187982Z" processing: summary: Transaction Processing value: event: id: "4dd8d1c2-6506-4d63-8475-aa9d72f25122" event_reference_id: "ca9a04d8-4e68-4557-b9c6-3881e9d6b26d" type: "transaction.status" created_at: "2025-12-01T09:14:47.165456Z" sandbox_mode: true data: beneficiary_id: "47fcb2ca-9ed2-4188-a154-c83a04d9d34d" created_at: "2025-12-01T09:14:34.623187Z" developer_fee: 1.7836 developer_fee_fixed: 1.75 developer_fee_percentage: 0.56 from_amount: 6 from_currency: "USDC" fx_rate: 1.3177 hash: "0x3a282c0d2364632bdf9224eadf06b463190795bce24e46d3235e44d22f953461" id: "ca9a04d8-4e68-4557-b9c6-3881e9d6b26d" payout_amount: 5.55595 payout_currency: "CAD" processing_amount: 4.2164 status: "PROCESSING" transaction_ref_id: "c494ac07-becd-4840-9" transaction_type: "DEBIT" updated_at: "2025-12-01T09:14:47.157863088Z" failed: summary: Transaction Failed value: event: id: "89787b87-bc27-43ac-a21d-da2606ac0a49" event_reference_id: "8a355a70-e17f-4ce7-a3e9-7d1a424dd284" type: "transaction.status" created_at: "2025-12-10T10:48:06.308805Z" sandbox_mode: true data: beneficiary_id: "dd2ca7e8-d321-4a5f-b5f8-ddcb4d979434" created_at: "2025-12-10T10:47:59.315118Z" developer_fee: 1.2725 developer_fee_fixed: 1.25 developer_fee_percentage: 0.45 from_amount: 5 from_currency: "USDC" fx_rate: 1.45 hash: "0x594892ea29ee750db107fc3ce52ccd1c34e8b6d6b4246da3f0921b58bfc1b859" id: "8a355a70-e17f-4ce7-a3e9-7d1a424dd284" payout_amount: 5.404875 payout_currency: "AUD" processing_amount: 3.7275 status: "FAILED" transaction_ref_id: "8f956be1-38d8-4d72-9ed6-2927b0fe7e17" transaction_type: "DEBIT" updated_at: "2025-12-10T10:48:06.300135576Z" responses: '200': description: Webhook received successfully virtual_account.created: post: summary: Virtual Account Created description: | This webhook event is triggered when a new virtual account is created for a customer. It provides comprehensive details about the virtual account, including deposit instructions (bank account details, routing numbers, supported payment rails), the destination blockchain address for converted funds, and the developer fee configuration. x-mint: metadata: title: virtual_account.created content: | **Security:** All webhook requests include HMAC signatures for verification. Learn how to [verify webhook signatures](/guides/webhooks/verifying-webhooks) to ensure requests are authentic. tags: - Webhooks requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VirtualAccountCreatedWebhook' 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: created_at: "2025-12-10T08:11:25.216572Z" customer_id: "a41a6d76-4545-47ab-93d1-696a3221d39c" deposit_instructions: bank_account_number: "900937198167" bank_address: "1800 North Pole St., Orlando, FL 32801" bank_beneficiary_address: "250 Innovation Way, Houston, TX 77002, US" bank_beneficiary_name: "Acme Corp" bank_name: "Bank of Nowhere" bank_routing_number: "101019644" currency: "USD" payment_rails: - "ACH" - "FEDWIRE" destination: address: "0x1d1f9801d6d98e49438cda3a3b8e0c9f5e6f8c44" currency: "USDC" destination_chain: "POLYGON" developer_fee_percent: 0.5 id: "900f750d-6868-457e-a777-1a35566a6b5f" status: "ACTIVE" updated_at: "2025-12-10T08:11:25.216572Z" responses: '200': description: Webhook received successfully virtual_account.status: post: summary: Virtual Account Status description: | This webhook event is triggered when a virtual account's status changes. It provides real-time updates about the virtual account's operational state. Common status values include: - `ACTIVE` - Virtual account is active and ready to receive deposits - `INACTIVE` - Virtual account is not currently active - `SUSPENDED` - Virtual account has been suspended x-mint: metadata: title: virtual_account.status content: | **Security:** All webhook requests include HMAC signatures for verification. Learn how to [verify webhook signatures](/guides/webhooks/verifying-webhooks) to ensure requests are authentic. tags: - Webhooks requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VirtualAccountStatusWebhook' examples: active: summary: Virtual Account Active value: event: id: "756ed2cd-b428-4c14-90b2-4f012dfe318a" event_reference_id: "900f750d-6868-457e-a777-1a35566a6b5f" type: "virtual_account.status" created_at: "2025-12-10T08:14:19.048063Z" sandbox_mode: true data: created_at: "2025-12-10T08:11:25.216572Z" customer_id: "a41a6d76-4545-47ab-93d1-696a3221d39c" deposit_instructions: bank_account_number: "900937198167" bank_address: "1800 North Pole St., Orlando, FL 32801" bank_beneficiary_address: "250 Innovation Way, Houston, TX 77002, US" bank_beneficiary_name: "Acme Corp" bank_name: "Bank of Nowhere" bank_routing_number: "101019644" currency: "USD" payment_rails: - "ACH" - "FEDWIRE" destination: address: "0x1d1f9801d6d98e49438cda3a3b8e0c9f5e6f8c44" currency: "USDC" destination_chain: "POLYGON" developer_fee_percent: 1.89 id: "900f750d-6868-457e-a777-1a35566a6b5f" status: "ACTIVE" updated_at: "2025-12-10T08:14:19.017554854Z" responses: '200': description: Webhook received successfully beneficiary.created: post: summary: Beneficiary Created description: | This webhook event is triggered when a new beneficiary is created in the system. It provides information about the newly created beneficiary, including the beneficiary ID, associated customer ID, and the beneficiary type (`INDIVIDUAL` or `BUSINESS`). x-mint: metadata: title: beneficiary.created content: | **Security:** All webhook requests include HMAC signatures for verification. Learn how to [verify webhook signatures](/guides/webhooks/verifying-webhooks) to ensure requests are authentic. tags: - Webhooks requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BeneficiaryCreatedWebhook' 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" businessCreated: summary: Business Beneficiary Created value: event: id: "22044316-e639-4638-b5d4-e23944875f44" event_reference_id: "e7656cc6-1a74-474f-9c9c-b502c10940e0" type: "beneficiary.created" created_at: "2025-12-10T08:30:31.264069Z" sandbox_mode: true data: active: true beneficiary_id: "e7656cc6-1a74-474f-9c9c-b502c10940e0" customer_id: "bea5a6c1-0611-44c6-8c29-a6608e76916c" type: "BUSINESS" responses: '200': description: Webhook received successfully beneficiary.status: post: summary: Beneficiary Status description: | This webhook event is triggered when a beneficiary's status changes. It provides updates on the active status of beneficiaries, allowing you to track when beneficiaries become active or inactive. x-mint: metadata: title: beneficiary.status content: | **Security:** All webhook requests include HMAC signatures for verification. Learn how to [verify webhook signatures](/guides/webhooks/verifying-webhooks) to ensure requests are authentic. tags: - Webhooks requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BeneficiaryStatusWebhook' examples: individualActive: summary: Individual Beneficiary Active value: event: id: "4f6e1c26-f4eb-460d-8aa4-067cebffc567" event_reference_id: "4d715f20-f704-45e0-af56-19ade318e852" type: "beneficiary.status" created_at: "2025-12-10T10:36:19.055159Z" sandbox_mode: true data: active: true beneficiary_id: "4d715f20-f704-45e0-af56-19ade318e852" customer_id: "efb54adf-b7f4-4716-80e3-806e11f20b7b" type: "INDIVIDUAL" businessActive: summary: Business Beneficiary Active value: event: id: "cc5587a6-a382-4ff5-b21f-99658e4df65c" event_reference_id: "e7656cc6-1a74-474f-9c9c-b502c10940e0" type: "beneficiary.status" created_at: "2025-12-10T08:30:31.959181Z" sandbox_mode: true data: active: true beneficiary_id: "e7656cc6-1a74-474f-9c9c-b502c10940e0" customer_id: "bea5a6c1-0611-44c6-8c29-a6608e76916c" type: "BUSINESS" responses: '200': description: Webhook received successfully 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 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 description: ISO 3166-1 alpha-3 country code TokenResponse: type: object properties: access_token: type: string description: The access token for API authentication example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... access_token_ttl: type: string format: date-time description: Access token expiration timestamp example: "2025-12-28 10:34:45+00" refresh_token: type: string description: The refresh token for obtaining new access tokens example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... refresh_token_ttl: type: string format: date-time description: Refresh token expiration timestamp example: "2025-12-28 10:34:45+00" current_time: type: string format: date-time description: Current server timestamp example: "2025-12-21 10:34:45+00" CreateIndividualCustomerInput: type: object required: - verification_type - basic_info - address - financial_profile properties: verification_type: type: string enum: - STANDARD - RELIANCE description: Type of verification to perform example: STANDARD basic_info: type: object required: - first_name - last_name - dob - email - phone - country_of_residence - nationality - tin properties: first_name: type: string description: Customer's first name example: "John" last_name: type: string description: Customer's last name example: "Doe" dob: type: string format: date description: Date of birth in YYYY-MM-DD format example: "1990-01-15" email: type: string format: email description: Customer's email address example: "john.doe@example.com" phone: type: string description: Phone number according to residence country example: "+1234567890" country_of_residence: $ref: '#/components/schemas/CountryCode' nationality: $ref: '#/components/schemas/CountryCode' tin: type: string description: Tax Identification Number. Must be SSN format for USA; for all other countries, the relevant document number format is acceptable. example: "123-45-6789" address: type: object required: - street - city - state - postal_code - country properties: street: type: string description: Street address example: "123 Main St" city: type: string description: City name example: "New York" state: type: string description: State or province subdivision code from the catalogue API (/v1/countries/{country_code}/subdivisions) example: "US-NY" postal_code: type: string description: Postal or ZIP code 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 description: Unique identifier for occupation retrieved from the catalogue API (/v1/occupations) example: 1 source_of_fund_id: type: integer description: Unique identifier for source of funds retrieved from the catalogue API (/v1/source-of-funds?type=INDIVIDUAL) example: 1 purpose_id: type: integer description: Unique identifier for account purpose retrieved from the catalogue API (/v1/purposes?type=INDIVIDUAL) example: 1 monthly_volume_usd: type: integer description: Expected monthly transaction volume in USD (not cents) example: 5000 meta_data: type: object additionalProperties: true description: Additional custom metadata as key-value pairs example: customer_reference: "REF-12345" internal_notes: "VIP customer" ProofOfIdentity: type: object required: - type - number - country - issue_date - expiry_date - files properties: type: type: string enum: - PASSPORT - NATIONAL_ID - DRIVERS_LICENSE description: Type of identity document 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 example: "2030-01-15" files: type: array description: Array of document file URIs with sides items: type: object required: - uri additionalProperties: false properties: side: type: string enum: - FRONT - BACK description: Side of the document (optional for passport, required for other document types) example: "FRONT" uri: type: string description: The URI received from the upload document endpoint example: "/AbAcQ4hn_0652746727637.pdf" ProofOfAddress: 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 description: Type of address proof document example: "UTILITY_BILL" country: $ref: '#/components/schemas/CountryCode' files: type: array description: Array of document file URIs (no sides needed) items: type: object required: - uri additionalProperties: false properties: uri: type: string description: The URI received from the upload document endpoint 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 description: Unique identifier for the customer example: "55bd6b4e-c20a-4cc8-9535-91d5557a67d9" proof_of_identity: $ref: '#/components/schemas/ProofOfIdentity' proof_of_address: $ref: '#/components/schemas/ProofOfAddress' tos_policies_value: type: string description: Terms of Service policies value parsed from the tos_policies_url query parameter returned from the Create Individual Customer endpoint. Providing this signifies that the user was shown the policies and have accepted the terms. example: "e9414388-fbdf-4407-b5c2-bc39eae3645b" AttachDocumentToAssociatedPartyInput: type: object required: - customer_id - associated_party_attachments properties: customer_id: type: string format: uuid description: Unique identifier for the customer example: "55bd6b4e-c20a-4cc8-9535-91d5557a67d9" associated_party_attachments: type: array description: Array of document attachments for associated parties items: type: object required: - associated_party_id - proof_of_identity - proof_of_address properties: associated_party_id: type: string format: uuid description: Unique identifier for the associated party example: "a7c3b4e2-d8f1-4a5c-9e7d-2f6b8c3a1e9f" proof_of_identity: $ref: '#/components/schemas/ProofOfIdentity' proof_of_address: $ref: '#/components/schemas/ProofOfAddress' AttachDocumentsToBusinessCustomerInput: type: object required: - customer_id - ownership_structure - company_details - legal_presence - tos_policies_value properties: customer_id: type: string format: uuid description: Unique identifier for the customer example: "55bd6b4e-c20a-4cc8-9535-91d5557a67d9" ownership_structure: type: array description: Array of ownership structure documents items: type: object required: - type - files properties: type: type: string enum: - SHAREHOLDER_REGISTRY description: Type of ownership structure document example: "SHAREHOLDER_REGISTRY" files: type: array description: Array of document file URIs items: type: object required: - uri properties: uri: type: string description: The URI received from the upload document endpoint example: "/AbAcQ4hn_0652746727639.pdf" company_details: type: array description: Array of company detail documents items: type: object required: - type - files properties: type: type: string enum: - CERT_OF_INCORPORATION - MEMORANDUM_OF_ASSOCIATION description: Type of company detail document example: "CERT_OF_INCORPORATION" files: type: array description: Array of document file URIs items: type: object required: - uri properties: uri: type: string description: The URI received from the upload document endpoint example: "/AbAcQ4hn_0652746727640.pdf" legal_presence: type: array description: Array of legal presence documents items: type: object required: - type - files properties: type: type: string enum: - PROOF_OF_ADDRESS description: Type of legal presence document example: "PROOF_OF_ADDRESS" files: type: array description: Array of document file URIs items: type: object required: - uri properties: uri: type: string description: The URI received from the upload document endpoint example: "/AbAcQ4hn_0652746727641.pdf" tos_policies_value: type: string description: Terms of Service policies value parsed from the tos_policies_url query parameter returned from the Create Business Customer endpoint. Providing this signifies that the user was shown the policies and have accepted the terms. example: "e9414388-fbdf-4407-b5c2-bc39eae3645b" # Webhook Schemas WebhookEvent: type: object description: Common structure for all webhook events required: - event - data properties: event: type: object required: - id - event_reference_id - type - created_at - sandbox_mode properties: id: type: string format: uuid description: Unique identifier for the webhook event example: "60bef15c-4e30-4eb4-bc4d-aa697a7e0857" event_reference_id: type: string format: uuid description: Reference ID of the entity that triggered the event example: "c3309534-1517-4d15-b244-be8f943c3823" type: type: string description: Type of webhook event enum: - customer.created - customer.status - transaction.status - virtual_account.created - virtual_account.status - beneficiary.created - beneficiary.status example: "customer.created" created_at: type: string format: date-time description: Timestamp when the event was created example: "2025-11-30T07:40:06.853938Z" sandbox_mode: type: boolean description: Indicates if the event was triggered in sandbox mode example: true data: type: object description: Event-specific payload data CustomerCreatedWebhook: allOf: - $ref: '#/components/schemas/WebhookEvent' - type: object description: Webhook triggered when a customer is successfully created properties: data: oneOf: - $ref: '#/components/schemas/IndividualCustomerData' - $ref: '#/components/schemas/BusinessCustomerData' IndividualCustomerData: type: object description: Individual customer data in webhook payload required: - customer_id - type - customer_status - email - first_name - last_name - phone - country_of_residence - verification_type properties: customer_id: type: string format: uuid description: Unique identifier for the customer example: "c3309534-1517-4d15-b244-be8f943c3823" type: type: string enum: [INDIVIDUAL] description: Customer type customer_status: type: string description: Current status of the customer enum: - INCOMPLETE - REVIEWING - APPROVED - ON_HOLD - REJECTED example: "INCOMPLETE" email: type: string format: email description: Customer email address example: "john.doe@email.com" first_name: type: string description: Customer's first name example: "John" last_name: type: string description: Customer's last name example: "Doe" phone: type: string description: Customer's phone number example: "+12597751234" country_of_residence: type: string description: Customer's country of residence (ISO 3166-1 alpha-3 code) example: "USA" verification_type: type: string enum: - RELIANCE - STANDARD description: Type of verification process example: "RELIANCE" tos_policies_url: type: string description: URL for terms of service policies example: "25764ef6-0f4f-4846-b7c6-9df0598358e9" created_at: type: string format: date-time description: Timestamp when the customer was created example: "2025-11-30T07:40:06Z" updated_at: type: string format: date-time description: Timestamp when the customer was last updated example: "2025-11-30T07:40:07Z" BusinessCustomerData: type: object description: Business customer data in webhook payload required: - customer_id - type - customer_status - business_name - email - phone - country_of_incorporation - verification_type properties: customer_id: type: string format: uuid description: Unique identifier for the customer example: "b222b827-3ac7-4d20-bfd0-ebedc44435f7" type: type: string enum: [BUSINESS] description: Customer type customer_status: type: string description: Current status of the customer enum: - INCOMPLETE - REVIEWING - APPROVED - ASSOCIATED_PARTIES_REMAINING - ON_HOLD - REJECTED example: "INCOMPLETE" business_name: type: string description: Name of the business example: "Acme Corp" email: type: string format: email description: Business email address example: "contact@acmecorp.com" phone: type: string description: Business phone number example: "+12125550123" country_of_incorporation: type: string description: Country where the business is incorporated (ISO 3166-1 alpha-3 code) example: "USA" verification_type: type: string enum: - RELIANCE - STANDARD description: Type of verification process example: "RELIANCE" tos_policies_url: type: string description: URL for terms of service policies example: "7e5bdf95-8dea-44d1-8810-987befbe2594" associated_parties: type: array description: List of associated parties (owners, directors, etc.) items: $ref: '#/components/schemas/AssociatedPartyWebhook' created_at: type: string format: date-time description: Timestamp when the customer was created example: "2025-11-30T08:01:03Z" updated_at: type: string format: date-time description: Timestamp when the customer was last updated example: "2025-11-30T08:01:03.797370576Z" AssociatedPartyWebhook: type: object description: Associated party information in webhook payload properties: id: type: string format: uuid description: Unique identifier for the associated party example: "07365877-f98f-4efa-acef-b15932fc3415" email: type: string format: email description: Email address of the associated party example: "john.doe@email.com" type: type: string enum: [INDIVIDUAL] description: Type of associated party ownership_percent: type: number description: Ownership percentage in the business example: 52 verification: type: object description: Verification status of the associated party properties: status: type: string enum: - INITIATED - REVIEWING - APPROVED - REJECTED description: Verification status example: "INITIATED" updated_at: type: string format: date-time description: Timestamp when verification was last updated example: "2025-11-30T08:01:02.824452053Z" reason: type: object description: Reasons for verification status properties: for_customer: type: string nullable: true description: Customer-facing reason for_developer: type: string nullable: true description: Developer-facing reason CustomerStatusWebhook: allOf: - $ref: '#/components/schemas/WebhookEvent' - type: object description: Webhook triggered when a customer's status changes during verification properties: data: oneOf: - $ref: '#/components/schemas/IndividualCustomerData' - $ref: '#/components/schemas/BusinessCustomerData' TransactionStatusWebhook: allOf: - $ref: '#/components/schemas/WebhookEvent' - type: object description: Webhook triggered when a transaction's status changes properties: data: $ref: '#/components/schemas/TransactionWebhookData' TransactionWebhookData: type: object description: Transaction data in webhook payload required: - id - status - beneficiary_id - from_amount - from_currency - transaction_type properties: id: type: string format: uuid description: Unique identifier for the transaction example: "ca9a04d8-4e68-4557-b9c6-3881e9d6b26d" status: type: string description: Current status of the transaction enum: - FUNDS_RECEIVED - PROCESSING - COMPLETED - FAILED - CANCELLED example: "FUNDS_RECEIVED" beneficiary_id: type: string format: uuid description: Identifier for the beneficiary example: "47fcb2ca-9ed2-4188-a154-c83a04d9d34d" from_amount: type: number description: Amount being sent example: 6 from_currency: type: string description: Currency of the amount being sent example: "USDC" payout_amount: type: number description: Amount to be paid out to beneficiary example: 5.55595028 payout_currency: type: string description: Currency of the payout example: "CAD" processing_amount: type: number description: Amount after fees deducted example: 4.2164 fx_rate: type: number description: Foreign exchange rate applied example: 1.3177 developer_fee: type: number description: Total developer fee charged example: 1.7836 developer_fee_fixed: type: number description: Fixed portion of developer fee example: 1.75 developer_fee_percentage: type: number description: Percentage portion of developer fee example: 0.56 hash: type: string description: Blockchain transaction hash example: "0x3a282c0d2364632bdf9224eadf06b463190795bce24e46d3235e44d22f953461" transaction_ref_id: type: string description: Reference ID for the transaction example: "c494ac07-becd-4840-9" transaction_type: type: string enum: - DEBIT - CREDIT description: Type of transaction example: "DEBIT" created_at: type: string format: date-time description: Timestamp when the transaction was created example: "2025-12-01T09:14:34.623187982Z" updated_at: type: string format: date-time description: Timestamp when the transaction was last updated example: "2025-12-01T09:14:34.623187982Z" VirtualAccountCreatedWebhook: allOf: - $ref: '#/components/schemas/WebhookEvent' - type: object description: Webhook triggered when a new virtual account is created properties: data: $ref: '#/components/schemas/VirtualAccountWebhookData' VirtualAccountStatusWebhook: allOf: - $ref: '#/components/schemas/WebhookEvent' - type: object description: Webhook triggered when a virtual account's status changes properties: data: $ref: '#/components/schemas/VirtualAccountWebhookData' VirtualAccountWebhookData: type: object description: Virtual account data in webhook payload required: - id - customer_id - status - deposit_instructions - destination properties: id: type: string format: uuid description: Unique identifier for the virtual account example: "900f750d-6868-457e-a777-1a35566a6b5f" customer_id: type: string format: uuid description: Identifier for the customer who owns the virtual account example: "a41a6d76-4545-47ab-93d1-696a3221d39c" status: type: string description: Current status of the virtual account enum: - ACTIVE - INACTIVE - SUSPENDED example: "ACTIVE" deposit_instructions: type: object description: Banking details for depositing funds required: - bank_account_number - bank_routing_number - bank_name - bank_address - bank_beneficiary_name - bank_beneficiary_address - currency - payment_rails properties: bank_account_number: type: string description: Bank account number for deposits example: "900937198167" bank_routing_number: type: string description: Bank routing number example: "101019644" bank_name: type: string description: Name of the bank example: "Bank of Nowhere" bank_address: type: string description: Physical address of the bank example: "1800 North Pole St., Orlando, FL 32801" bank_beneficiary_name: type: string description: Beneficiary name on the account example: "Acme Corp" bank_beneficiary_address: type: string description: Address of the beneficiary example: "250 Innovation Way, Houston, TX 77002, US" currency: type: string description: Currency for deposits example: "USD" payment_rails: type: array description: Supported payment methods items: type: string enum: - ACH - FEDWIRE - WIRE example: ["ACH", "FEDWIRE"] destination: type: object description: Destination blockchain address for converted funds required: - address - currency - destination_chain properties: address: type: string description: Blockchain wallet address example: "0x1d1f9801d6d98e49438cda3a3b8e0c9f5e6f8c44" currency: type: string description: Cryptocurrency to receive example: "USDC" destination_chain: type: string description: Blockchain network example: "POLYGON" developer_fee_percent: type: number description: Developer fee percentage example: 0.5 created_at: type: string format: date-time description: Timestamp when the virtual account was created example: "2025-12-10T08:11:25.216572Z" updated_at: type: string format: date-time description: Timestamp when the virtual account was last updated example: "2025-12-10T08:11:25.216572Z" BeneficiaryCreatedWebhook: allOf: - $ref: '#/components/schemas/WebhookEvent' - type: object description: Webhook triggered when a new beneficiary is created properties: data: $ref: '#/components/schemas/BeneficiaryWebhookData' BeneficiaryStatusWebhook: allOf: - $ref: '#/components/schemas/WebhookEvent' - type: object description: Webhook triggered when a beneficiary's status changes properties: data: $ref: '#/components/schemas/BeneficiaryWebhookData' BeneficiaryWebhookData: type: object description: Beneficiary data in webhook payload required: - beneficiary_id - customer_id - type - active properties: beneficiary_id: type: string format: uuid description: Unique identifier for the beneficiary example: "4d715f20-f704-45e0-af56-19ade318e852" customer_id: type: string format: uuid description: Identifier for the customer who owns the beneficiary example: "efb54adf-b7f4-4716-80e3-806e11f20b7b" type: type: string description: Type of beneficiary enum: - INDIVIDUAL - BUSINESS example: "INDIVIDUAL" active: type: boolean description: Whether the beneficiary is active example: true responses: AuthenticationError: description: Authentication failed due to invalid credentials content: application/json: schema: type: object properties: message: type: string description: The error message example: "Authentication failed" ValidationError: description: Failed due to a formatting error. content: application/json: schema: type: object required: - message properties: message: type: string description: An error message describing what went wrong. errors: type: array items: type: object additionalProperties: type: string example: Appropriate client_secret required. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Bearer token authentication. Obtain token from /v1/oauth/token endpoint