Create Virtual Account V3

POST

customers

{customer_id}

virtual-accounts

curl --request POST \
  --url https://sandbox.api.fin.com/v3/customers/{customer_id}/virtual-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination": {
    "wallet": "0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39",
    "currency": "USDC",
    "rail": "ETHEREUM"
  },
  "source": {
    "currency": "USD",
    "rail": "FEDWIRE",
    "bank": "PORTAGE"
  },
  "developer_fee": {
    "fixed": 0,
    "percentage": 0
  }
}
'

const url = 'https://sandbox.api.fin.com/v3/customers/{customer_id}/virtual-accounts';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    destination: {
      wallet: '0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39',
      currency: 'USDC',
      rail: 'ETHEREUM'
    },
    source: {currency: 'USD', rail: 'FEDWIRE', bank: 'PORTAGE'},
    developer_fee: {fixed: 0, percentage: 0}
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://sandbox.api.fin.com/v3/customers/{customer_id}/virtual-accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"destination\": {\n    \"wallet\": \"0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39\",\n    \"currency\": \"USDC\",\n    \"rail\": \"ETHEREUM\"\n  },\n  \"source\": {\n    \"currency\": \"USD\",\n    \"rail\": \"FEDWIRE\",\n    \"bank\": \"PORTAGE\"\n  },\n  \"developer_fee\": {\n    \"fixed\": 0,\n    \"percentage\": 0\n  }\n}")
  .asString();

import requests

url = "https://sandbox.api.fin.com/v3/customers/{customer_id}/virtual-accounts"

payload = {
    "destination": {
        "wallet": "0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39",
        "currency": "USDC",
        "rail": "ETHEREUM"
    },
    "source": {
        "currency": "USD",
        "rail": "FEDWIRE",
        "bank": "PORTAGE"
    },
    "developer_fee": {
        "fixed": 0,
        "percentage": 0
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.api.fin.com/v3/customers/{customer_id}/virtual-accounts"

	payload := strings.NewReader("{\n  \"destination\": {\n    \"wallet\": \"0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39\",\n    \"currency\": \"USDC\",\n    \"rail\": \"ETHEREUM\"\n  },\n  \"source\": {\n    \"currency\": \"USD\",\n    \"rail\": \"FEDWIRE\",\n    \"bank\": \"PORTAGE\"\n  },\n  \"developer_fee\": {\n    \"fixed\": 0,\n    \"percentage\": 0\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "data": {
    "id": "9d2b7f41-6c8a-45e3-b071-2fa93c5e8d16",
    "status": "PROCESSING",
    "deposit_instructions": null,
    "destination": {
      "currency": "USDC",
      "destination_chain": "ETHEREUM",
      "address": "0x4E91c07aB35d2F6810b94Ce7d13A5f826c0D4b7E"
    },
    "bank": "PORTAGE",
    "rfi": null
  }
}

{
  "message": "Authentication failed"
}

{
  "errors": [
    {
      "customer_id": "c1f4a8e2-3b57-4d09-9a61-7e2b5c8d4f30",
      "source": {
        "currency": "USD",
        "rail": "FEDWIRE"
      }
    },
    {
      "virtual_account_id": "9d2b7f41-6c8a-45e3-b071-2fa93c5e8d16"
    }
  ],
  "message": "Virtual account already exists for the given parameters."
}

Check all the supported fiat and crypto rails and currencies, along with the valid combinations, in Supported rails and currencies.
The available rails and currencies depend on the configuration set up for you. Contact support to know more.
The minimum deposit amount for USD virtual accounts is 50 USD.

What changed from V2

Change	Detail
`source.bank` added	Required. Selects the banking partner that issues the account.
Response body	Now returns `deposit_instructions`, `destination`, and `bank`. `customer_id` and `created_at` are no longer returned on create.

V2 remains available at Create Virtual Account V2 for existing integrations. Use V3 for new integrations.

Choosing a banking partner

source.bank selects the banking partner that issues the virtual account and receives the customer’s fiat deposit. The only accepted value is PORTAGE.

Duplicate accounts

A customer can hold only one virtual account per source currency and rail. Requesting one that already exists returns 422 with the colliding customer_id and source in errors, along with the virtual_account_id of the existing account. Use that account instead of retrying the create call.

Authorizations

Authorization

string

header

required

Bearer token authentication. Obtain token from Issue a Token endpoint

Path Parameters

customer_id

string<uuid>

required

Unique identifier of the customer to create the virtual account for.

Body

application/json

destination

object

required

Show child attributes

source

object

required

Show child attributes

developer_fee

object

required

Show child attributes

Response

Virtual account created successfully

data

object

Show child attributes

⌘I

Create Virtual Account V3

curl --request POST \
  --url https://sandbox.api.fin.com/v3/customers/{customer_id}/virtual-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination": {
    "wallet": "0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39",
    "currency": "USDC",
    "rail": "ETHEREUM"
  },
  "source": {
    "currency": "USD",
    "rail": "FEDWIRE",
    "bank": "PORTAGE"
  },
  "developer_fee": {
    "fixed": 0,
    "percentage": 0
  }
}
'

const url = 'https://sandbox.api.fin.com/v3/customers/{customer_id}/virtual-accounts';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    destination: {
      wallet: '0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39',
      currency: 'USDC',
      rail: 'ETHEREUM'
    },
    source: {currency: 'USD', rail: 'FEDWIRE', bank: 'PORTAGE'},
    developer_fee: {fixed: 0, percentage: 0}
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://sandbox.api.fin.com/v3/customers/{customer_id}/virtual-accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"destination\": {\n    \"wallet\": \"0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39\",\n    \"currency\": \"USDC\",\n    \"rail\": \"ETHEREUM\"\n  },\n  \"source\": {\n    \"currency\": \"USD\",\n    \"rail\": \"FEDWIRE\",\n    \"bank\": \"PORTAGE\"\n  },\n  \"developer_fee\": {\n    \"fixed\": 0,\n    \"percentage\": 0\n  }\n}")
  .asString();

import requests

url = "https://sandbox.api.fin.com/v3/customers/{customer_id}/virtual-accounts"

payload = {
    "destination": {
        "wallet": "0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39",
        "currency": "USDC",
        "rail": "ETHEREUM"
    },
    "source": {
        "currency": "USD",
        "rail": "FEDWIRE",
        "bank": "PORTAGE"
    },
    "developer_fee": {
        "fixed": 0,
        "percentage": 0
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.api.fin.com/v3/customers/{customer_id}/virtual-accounts"

	payload := strings.NewReader("{\n  \"destination\": {\n    \"wallet\": \"0x7A3f5C21b9E04d8a6C15fB3e920D74Ac815b6E39\",\n    \"currency\": \"USDC\",\n    \"rail\": \"ETHEREUM\"\n  },\n  \"source\": {\n    \"currency\": \"USD\",\n    \"rail\": \"FEDWIRE\",\n    \"bank\": \"PORTAGE\"\n  },\n  \"developer_fee\": {\n    \"fixed\": 0,\n    \"percentage\": 0\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "data": {
    "id": "9d2b7f41-6c8a-45e3-b071-2fa93c5e8d16",
    "status": "PROCESSING",
    "deposit_instructions": null,
    "destination": {
      "currency": "USDC",
      "destination_chain": "ETHEREUM",
      "address": "0x4E91c07aB35d2F6810b94Ce7d13A5f826c0D4b7E"
    },
    "bank": "PORTAGE",
    "rfi": null
  }
}

{
  "message": "Authentication failed"
}

{
  "errors": [
    {
      "customer_id": "c1f4a8e2-3b57-4d09-9a61-7e2b5c8d4f30",
      "source": {
        "currency": "USD",
        "rail": "FEDWIRE"
      }
    },
    {
      "virtual_account_id": "9d2b7f41-6c8a-45e3-b071-2fa93c5e8d16"
    }
  ],
  "message": "Virtual account already exists for the given parameters."
}

Authentication

Customers

Beneficiaries

Virtual Accounts

Transactions

Balances

Fees & FX Rates

Catalogue

Crypto Orchestration

Webhooks

Create Virtual Account V3

What changed from V2

Choosing a banking partner

Duplicate accounts

Authorizations

Path Parameters

Body

Response

​What changed from V2

​Choosing a banking partner

​Duplicate accounts

Authorizations

Path Parameters

Body

Response

What changed from V2

Choosing a banking partner

Duplicate accounts