Fin

Fin Virtual Accounts API

Create and manage virtual accounts for USD to USDC conversions

GitHub OpenAPI

Documentation

📖
Authentication
https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/authentication/fin-authentication.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/openapi/fin-virtual-accounts-api-openapi.yml

Other Resources

🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/asyncapi/fin-webhooks.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/errors/fin-problem-types.yml
🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/conventions/fin-conventions.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/data-model/fin-data-model.yml

OpenAPI Specification

fin-virtual-accounts-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Fin.com Authentication Virtual Accounts API
  version: 1.0.0
  description: A simple API specificationFo
servers:
- url: https://sandbox.api.fin.com
  description: Sandbox server
- url: https://api.fin.com
  description: Production server
tags:
- name: Virtual Accounts
  description: Create and manage virtual accounts for USD to USDC conversions
paths:
  /v2/customers/{customer_id}/virtual-accounts:
    post:
      operationId: createVirtualAccountV2
      summary: Create Virtual Account V2
      description: Create a virtual bank account for a specific customer to convert fiat deposits to crypto. The `customer_id` path parameter identifies the customer for whom the virtual account is being created.
      tags:
      - Virtual Accounts
      security:
      - bearerAuth: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the customer to create the virtual account for.
        example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - destination
              - source
              - developer_fee
              properties:
                destination:
                  type: object
                  required:
                  - wallet
                  - currency
                  - rail
                  properties:
                    wallet:
                      type: string
                      description: Destination wallet address in hexadecimal format (0x...)
                      example: '0x6e41e83d406185b358bd72111ab1206cb82eb67f'
                    currency:
                      type: string
                      enum:
                      - USDC
                      example: USDC
                    rail:
                      type: string
                      enum:
                      - POLYGON
                      example: POLYGON
                source:
                  type: object
                  required:
                  - currency
                  - rail
                  properties:
                    currency:
                      type: string
                      enum:
                      - USD
                      - EUR
                      - MXN
                      example: USD
                    rail:
                      type: string
                      enum:
                      - ACH
                      - SWIFT
                      - FEDWIRE
                      - FEDNOW
                      - SEPA
                      - SPEI
                      example: FEDWIRE
                developer_fee:
                  type: object
                  required:
                  - percentage
                  - fixed
                  properties:
                    percentage:
                      type: number
                      example: 0.1
                    fixed:
                      type: number
                      example: 0.1
            example:
              destination:
                wallet: '0x6e41e83d406185b358bd72111ab1206cb82eb67f'
                currency: USDC
                rail: POLYGON
              source:
                currency: USD
                rail: FEDWIRE
              developer_fee:
                percentage: 0.1
                fixed: 0.1
      responses:
        '200':
          description: Virtual account created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        example: 024e784b-bc27-4a4c-82ee-80000fbf53c5
                      status:
                        type: string
                        enum:
                        - PROCESSING
                        - IN_COMPLIANCE
                        - REQUEST_FOR_INFORMATION
                        - ACTIVE
                        - INACTIVE
                        - DECLINED
                        example: PROCESSING
                      customer_id:
                        type: string
                        format: uuid
                        example: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44
                      created_at:
                        type: string
                        format: date-time
                        example: '2026-04-04T11:05:20.963676Z'
                      rfi:
                        type: object
                        nullable: true
                        example: null
              examples:
                OK:
                  summary: OK
                  value:
                    data:
                      id: 024e784b-bc27-4a4c-82ee-80000fbf53c5
                      status: PROCESSING
                      customer_id: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44
                      created_at: '2026-04-04T11:05:20.963676Z'
                      rfi: null
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
    get:
      operationId: listVirtualAccountsV2
      summary: List Virtual Accounts V2
      description: Retrieve a list of all virtual accounts for a specific customer
      tags:
      - Virtual Accounts
      security:
      - bearerAuth: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier for the customer
        example: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/CurrentPageParam'
      responses:
        '200':
          description: Virtual accounts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      virtual_accounts:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              example: 024e784b-bc27-4a4c-82ee-80000fbf53c5
                            status:
                              type: string
                              enum:
                              - PROCESSING
                              - IN_COMPLIANCE
                              - REQUEST_FOR_INFORMATION
                              - ACTIVE
                              - INACTIVE
                              - DECLINED
                              example: ACTIVE
                            developer_fee_percent:
                              type: number
                              nullable: true
                              example: 0
                            developer_fee_fixed:
                              type: number
                              nullable: true
                              example: 0.3
                            customer_id:
                              type: string
                              format: uuid
                              example: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44
                            created_at:
                              type: string
                              format: date-time
                              example: '2026-04-04T11:05:20.963676Z'
                            updated_at:
                              type: string
                              format: date-time
                              example: '2026-04-04T11:05:20.963676Z'
                            deposit_instructions:
                              type: object
                              nullable: true
                              description: null when status is PROCESSING
                              properties:
                                currency:
                                  type: string
                                  example: USD
                                bank_name:
                                  type: string
                                  example: Bank of Nowhere
                                bank_address:
                                  type: string
                                  example: 1800 North Pole St., Orlando, FL 32801
                                bank_routing_number:
                                  type: string
                                  example: '101019644'
                                bank_account_number:
                                  type: string
                                  example: '2611508020'
                                payment_rails:
                                  type: array
                                  items:
                                    type: string
                                  example:
                                  - ACH
                                  - FEDWIRE
                                bank_country:
                                  type: string
                                  nullable: true
                                  example: null
                                account_type:
                                  type: string
                                  nullable: true
                                  example: null
                                bank_code:
                                  type: string
                                  nullable: true
                                  example: null
                            destination:
                              type: object
                              properties:
                                currency:
                                  type: string
                                  enum:
                                  - USDC
                                  example: USDC
                                destination_chain:
                                  type: string
                                  enum:
                                  - POLYGON
                                  example: POLYGON
                                address:
                                  type: string
                                  example: '0x6e41e83d406185b358bd72111ab1206cb82eb67f'
                            rfi:
                              type: object
                              nullable: true
                              example: null
                      pagination:
                        type: object
                        properties:
                          current_page:
                            type: integer
                            example: 1
                          per_page:
                            type: integer
                            example: 10
                          total_page:
                            type: integer
                            example: 1
                          total:
                            type: integer
                            example: 2
              examples:
                OK:
                  summary: OK
                  value:
                    data:
                      virtual_accounts:
                      - id: 024e784b-bc27-4a4c-82ee-80000fbf53c5
                        status: PROCESSING
                        developer_fee_percent: 0
                        developer_fee_fixed: 0.3
                        customer_id: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44
                        created_at: '2026-04-04T11:05:20.963676Z'
                        updated_at: '2026-04-04T11:05:20.963676Z'
                        deposit_instructions: null
                        destination:
                          currency: USDC
                          destination_chain: POLYGON
                          address: '0x6e41e83d406185b358bd72111ab1206cb82eb67f'
                        rfi: null
                      - id: 1c1919e3-ce2e-4728-9efe-12b8be8e964d
                        status: ACTIVE
                        developer_fee_percent: 0
                        developer_fee_fixed: null
                        customer_id: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44
                        created_at: '2026-04-04T11:04:16.156771Z'
                        updated_at: '2026-04-04T11:04:16.156771Z'
                        deposit_instructions:
                          currency: USD
                          bank_name: Bank of Nowhere
                          bank_address: 1800 North Pole St., Orlando, FL 32801
                          bank_routing_number: '101019644'
                          bank_account_number: '2611508020'
                          payment_rails:
                          - ACH
                          - FEDWIRE
                          bank_country: null
                          account_type: null
                          bank_code: null
                        destination:
                          currency: USDC
                          destination_chain: POLYGON
                          address: '0x6e41e83d406185b358bd72111ab1206cb82eb67f'
                        rfi: null
                      pagination:
                        current_page: 1
                        per_page: 10
                        total_page: 1
                        total: 2
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/customers/virtual-account:
    get:
      summary: List Virtual Accounts V1
      description: Retrieve a list of all virtual accounts for a specific customer
      x-mint:
        content: "<Warning>\n  This endpoint was deprecated on May 20, 2026. Use [List Virtual Accounts V2](https://developer.fin.com/api-reference/virtual-accounts/list-virtual-accounts-v2) instead.\n</Warning>\n"
      tags:
      - Virtual Accounts
      security:
      - bearerAuth: []
      parameters:
      - name: customer_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
        example: 196ce546-900d-4294-90ca-5546a5923f35
      responses:
        '200':
          description: Virtual accounts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - virtual_accounts
                    - pagination
                    properties:
                      virtual_accounts:
                        type: array
                        items:
                          $ref: '#/components/schemas/VirtualAccount'
                      pagination:
                        type: object
                        properties:
                          current_page:
                            type: integer
                            example: 1
                          per_page:
                            type: integer
                            example: 10
                          total_page:
                            type: integer
                            example: 1
                          total:
                            type: integer
                            example: 6
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
    post:
      summary: Create Virtual Account
      description: Create a virtual bank account for a customer to convert USD deposits to USDC on Polygon
      x-mint:
        content: "<Warning>\n  This endpoint was deprecated on May 20, 2026. Use [Create Virtual Account V2](https://developer.fin.com/api-reference/virtual-accounts/create-virtual-account-v2) instead.\n</Warning>\n"
      tags:
      - Virtual Accounts
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customer_id
              - destination_currency
              - destination_chain
              - source_rail
              - source_currency
              - destination_wallet_address
              - developer_fee_percentage
              properties:
                customer_id:
                  type: string
                  format: uuid
                  example: 5a6f47f7-7326-409f-a4da-90e409133fb8
                destination_currency:
                  type: string
                  enum:
                  - USDC
                  default: USDC
                destination_chain:
                  type: string
                  enum:
                  - POLYGON
                  default: POLYGON
                source_rail:
                  type: string
                  example: ACH
                source_currency:
                  type: string
                  example: USD
                destination_wallet_address:
                  type: string
                  example: '0x7f1568190e318da16a9ef5a46cba19d5b97d9b29'
                developer_fee_percentage:
                  type: number
                  example: 1.5
      responses:
        '200':
          description: Virtual account created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/VirtualAccount'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
    put:
      summary: Update Virtual Account
      description: Update an existing virtual bank account's developer fee percentage and destination wallet address
      tags:
      - Virtual Accounts
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              - customer_id
              properties:
                id:
                  type: string
                  format: uuid
                  example: f8715e46-f46a-41dc-94ec-bd9797683510
                customer_id:
                  type: string
                  format: uuid
                  example: 22c6b566-5ecc-49b7-b812-076c64735596
                developer_fee_percentage:
                  type: number
                  example: 1.25
                destination_wallet_address:
                  type: string
                  example: '0x7f1568190e318da16a9ef5a46cba19d5b97d9b29'
      responses:
        '200':
          description: Virtual account updated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/VirtualAccount'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/virtual-account/{virtual_account_id}/transactions:
    get:
      summary: Fetch Virtual Account Transactions
      description: Retrieve a paginated list of all transactions for a specific virtual account
      tags:
      - Virtual Accounts
      security:
      - bearerAuth: []
      parameters:
      - name: virtual_account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: 3e7ce5ef-09bc-4e80-97f1-651ac483546f
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
      responses:
        '200':
          description: Virtual account transactions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    properties:
                      transactions:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              example: e34a382f-f0b6-40f2-b53b-97cb31f0506c
                            transaction_type:
                              type: string
                              example: ONRAMP
                            beneficiary_id:
                              type: string
                              format: uuid
                              nullable: true
                            hash:
                              type: string
                              nullable: true
                            transaction_ref_id:
                              type: string
                              format: uuid
                            from_amount:
                              type: number
                              example: 0
                            payout_amount:
                              type: number
                              example: 0
                            processing_amount:
                              type: number
                              nullable: true
                            status:
                              type: string
                              example: COMPLETED
                            fx_rate:
                              type: number
                              example: 0
                            developer_fee:
                              type: number
                              example: 0
                            developer_fee_percentage:
                              type: number
                              example: 0
                            developer_fee_fixed:
                              type: number
                              nullable: true
                            from_currency:
                              type: string
                              example: USD
                            payout_currency:
                              type: string
                              example: USDC
                            virtual_account_id:
                              type: string
                              format: uuid
                            created_at:
                              type: string
                              format: date-time
                            updated_at:
                              type: string
                              format: date-time
                      pagination:
                        type: object
                        properties:
                          current_page:
                            type: integer
                            example: 1
                          per_page:
                            type: integer
                            example: 10
                          total_page:
                            type: integer
                            example: 1
                          total:
                            type: integer
                            example: 4
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  responses:
    AuthenticationError:
      description: Authentication failed due to invalid credentials
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Authentication failed
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Resource not found
    ValidationError:
      description: Failed due to a formatting error.
      content:
        application/json:
          schema:
            type: object
            required:
            - message
            properties:
              message:
                type: string
              errors:
                type: array
                items:
                  type: object
                  additionalProperties:
                    type: string
  schemas:
    VirtualAccount:
      type: object
      required:
      - id
      - status
      - developer_fee_percent
      - customer_id
      - created_at
      - updated_at
      - deposit_instructions
      - destination
      properties:
        id:
          type: string
          format: uuid
          example: 92eceee4-ec6a-4fe3-a224-f5914cabe001
        status:
          type: string
          example: ACTIVE
        developer_fee_percent:
          type: number
          example: 1.65
        customer_id:
          type: string
          format: uuid
          example: 196ce546-900d-4294-90ca-5546a5923f35
        created_at:
          type: string
          format: date-time
          example: '2025-12-22T06:09:23.456895Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-12-22T06:09:23.456895Z'
        deposit_instructions:
          type: object
          properties:
            currency:
              type: string
              example: USD
            bank_name:
              type: string
              example: Bank of Nowhere
            bank_address:
              type: string
              example: 1800 North Pole St., Orlando, FL 32801
            bank_routing_number:
              type: string
              example: '101019644'
            bank_account_number:
              type: string
              example: '900336047672'
            bank_beneficiary_name:
              type: string
              example: Portgas D Ace
            bank_beneficiary_address:
              type: string
              example: 321 British Columbia City, British Columbia, BC V0C 1Y0, CA
            payment_rails:
              type: array
              items:
                type: string
              example:
              - ACH
              - FEDWIRE
        destination:
          type: object
          properties:
            currency:
              type: string
              enum:
              - USDC
              default: USDC
            destination_chain:
              type: string
              enum:
              - POLYGON
              - ETHEREUM
            address:
              type: string
              example: '0x7f1568190e318da16a9ef5a46cba19d5b97d9b29'
  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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication. Obtain token from [Issue a Token](https://developer.fin.com/api-reference/authentication/issue-a-token) endpoint