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: "\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\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: "\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\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