Create Virtual Account V3 (Coming soon)

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": "SSB"
  },
  "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: 'SSB'},
    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\": \"SSB\"\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": "SSB"
    },
    "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\": \"SSB\"\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": "SSB",
    "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."
}

This endpoint is not available in production yet. It is documented so you can plan your integration ahead of release. Contact support for availability.

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.

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.

Create Virtual Account V2 continues to work and is unchanged. Use V3 for new integrations once it is available.

Choosing a banking partner

source.bank selects the banking partner that issues the virtual account and receives the customer’s fiat deposit. The accepted values are SSB and 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 (Coming soon)

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": "SSB"
  },
  "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: 'SSB'},
    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\": \"SSB\"\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": "SSB"
    },
    "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\": \"SSB\"\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": "SSB",
    "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

Webhooks

Create Virtual Account V3 (Coming soon)

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