Guides
Start typing to search…

Virtual Accounts

Virtual accounts provides a unique routing and account number that accepts ACH deposits or Wire transfers.

Before proceeding, ensure that you've onboarded the client. Refer to the Individual or Business client onboarding guide for detailed instructions.

Create a Virtual Account for a client

See API Reference 
curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/virtual-accounts \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}' \
  --data '{
  "clientId": "5e505642-9024-474d-9434-e5a44f505cc5"
}'

Example response:

{
  "accountNumber": "200000000273",
  "receiverBankAddressRaw": "1 Main St, ABC, MO 1111",
  "receiverBankName": "ABC Bank",
  "receiverName": "ABC Business",
  "routingNumber": "100010600"
}

Get Virtual Account Instructions

See API Reference 
curl --request GET \
  --url https://api.sandbox.keyrails.com/api/v1/virtual-accounts/{clientId} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'
import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.sandbox.keyrails.com/api/v1/virtual-accounts/{clientId}',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer {{AccessToken}}'
  }
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Example response:

{
  "accountNumber": "200000000273",
  "receiverBankAddressRaw": "1 Main St, ABC, MO 1111",
  "receiverBankName": "ABC Bank",
  "receiverName": "ABC Business",
  "routingNumber": "100010600"
}

Deactivate Virtual Account

This endpoint allows you to deactivate a Virtual Account. Once deactivated, the account cannot receive new transactions, and all incoming funds will be returned to the sender. Transactions that were already in progress before the deactivation will be processed as normal.

See API Reference 
curl --request PUT \
  --url https://api.sandbox.keyrails.com/api/v1/virtual-accounts/{clientId}/deactivate \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'
import axios from 'axios';

const options = {
  method: 'PUT',
  url: 'https://api.sandbox.keyrails.com/api/v1/virtual-accounts/{clientId}/deactivate',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer {{AccessToken}}'
  }
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Reactivate Virtual Account

Reactivate a previously deactivated Virtual Account to resume processing new incoming transactions as normal. Any transactions that were returned while the Virtual Account was deactivated will need to be reinitiated.

See API Reference 
curl --request PUT \
  --url https://api.sandbox.keyrails.com/api/v1/virtual-accounts/{clientId}/reactivate \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'
import axios from 'axios';

const options = {
  method: 'PUT',
  url: 'https://api.sandbox.keyrails.com/api/v1/virtual-accounts/{clientId}/reactivate',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer {{AccessToken}}'
  }
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

📘

Payment fee quotes

For payment fee quotes - use the

Webhooks Examples

Before proceeding, ensure that your webhook configuration is set up. Refer to the setup guide for detailed instructions.

Webhook types: - Payment Transaction

Virtual Account Withdrawal Examples

Processing

{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Create",
  "id": "c304a2c8-2bae-45fb-b4a2-746e86761000",
  "resourceId": "6bc6a251-4e84-4e14-b7a2-60edb10ce7d4",
  "resourceType": "Payment",
  "createdAtUtc": "2025-02-07T11:47:52.849917Z",
  "changes": {
    "paymentStatus": "New",
    "paymentType": "WireWithdrawalUsdc", // Or AchWithdrawalUsdc
    "createdAt": "2025-02-07T11:47:52.4688663Z"
  }
}
{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Create",
  "id": "2ab0e4d4-8287-492c-a784-a2ce25ea00dc",
  "resourceId": "b156fa71-8296-4453-bf35-84c5ea76e748",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-02-07T11:47:52.4893825Z",
  "changes": {
    "transactionStatus": "Processing",
    "transactionType": "WireWithdrawalUsdc",
    "createdAt": "2025-02-07T11:47:52.4688665Z",
    "paymentId": "6bc6a251-4e84-4e14-b7a2-60edb10ce7d4",
    "amount": null,
    "cryptoAmount": "2.00"
  }
}

Completed

{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Update",
  "id": "a824b382-e184-4713-ac47-e4b8129a68c4",
  "resourceId": "09a1ad23-a703-4e87-9ef5-533ad5f6b1cb",
  "resourceType": "Payment",
  "createdAtUtc": "2025-02-07T11:59:33.5607779Z",
  "changes": {
    "paymentStatus": "Completed",
    "paymentType": "WireWithdrawalUsdc", // Or AchWithdrawalUsdc
    "createdAt": "2025-02-07T11:58:07.6810020Z",
    "updatedAt": "2025-02-07T11:59:33.2081656Z"
  }
}
{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Update",
  "id": "fd518b73-b8db-473a-8362-d861fcfce620",
  "resourceId": "05fd2939-fb47-4c38-8187-366486045208",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-02-07T11:59:33.2136984Z",
  "changes": {
    "transactionStatus": "Completed",
    "transactionType": "WireWithdrawalUsdc",
    "createdAt": "2025-02-07T11:58:07.6810020Z",
    "paymentId": "09a1ad23-a703-4e87-9ef5-533ad5f6b1cb",
    "amount": "1.00",
    "cryptoAmount": "1.00",
    "updatedAt": "2025-02-07T11:59:33.2081655Z",
    "transactionHash": "0xe26085a3f8a7db357b661fc54c83b112d7e98fbbaeca8ab40cac421775932544"
  }
}

Failed

{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Update",
  "id": "c304a2c8-2bae-45fb-b4a2-746e86761000",
  "resourceId": "6bc6a251-4e84-4e14-b7a2-60edb10ce7d4",
  "resourceType": "Payment",
  "createdAtUtc": "2025-02-07T11:47:52.849917Z",
  "changes": {
    "paymentStatus": "Failed",
    "paymentType": "WireWithdrawalUsdc", // Or AchWithdrawalUsdc
    "createdAt": "2025-02-07T11:47:52.4688663Z"
  }
}
{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Update",
  "id": "2ab0e4d4-8287-492c-a784-a2ce25ea00dc",
  "resourceId": "b156fa71-8296-4453-bf35-84c5ea76e748",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-02-07T11:47:52.4893825Z",
  "changes": {
    "transactionStatus": "Failed",
    "transactionType": "WireWithdrawalUsdc",
    "createdAt": "2025-02-07T11:47:52.4688665Z",
    "paymentId": "6bc6a251-4e84-4e14-b7a2-60edb10ce7d4",
    "amount": null,
    "cryptoAmount": "2.00"
  }
}

Virtual Account Deposits Examples

Processing

{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Update",
  "id": "4d37b60c-edf9-4e3d-9ca0-40459f8de130",
  "resourceId": "6d73df92-3b1e-437d-8c5e-8c9e37db323c",
  "resourceType": "Payment",
  "createdAtUtc": "2025-02-07T11:36:29.2184827Z",
  "changes": {
    "paymentStatus": "New",
    "paymentType": "WireDepositUsdc", // Or AchDepositUsdc
    "createdAt": "2025-02-07T11:35:24.0000000Z",
    "updatedAt": "2025-02-07T11:36:29.2099635Z"
  }
}
{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Update",
  "id": "1e552980-dd6c-4dc1-a39a-9831825a0a78",
  "resourceId": "832317b1-04bd-4819-90e5-273898e13a29",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-02-07T11:36:29.6021693Z",
  "changes": {
    "transactionStatus": "Processing",
    "transactionType": "WireDepositUsdc",
    "createdAt": "2025-02-07T11:35:24.0000000Z",
    "paymentId": "6d73df92-3b1e-437d-8c5e-8c9e37db323c",
    "amount": null,
    "cryptoAmount": "2.0",
    "updatedAt": "2025-02-07T11:36:29.2099636Z"
  }
}

Completed

{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Update",
  "id": "e5dd9ac1-28ad-4639-9821-fffd8dcf1cc5",
  "resourceId": "6d73df92-3b1e-437d-8c5e-8c9e37db323c",
  "resourceType": "Payment",
  "createdAtUtc": "2025-02-07T11:46:26.6350922Z",
  "changes": {
    "paymentStatus": "Completed",
    "paymentType": "WireDepositUsdc", // Or AchDepositUsdc
    "createdAt": "2025-02-07T11:35:24.0000000Z",
    "updatedAt": "2025-02-07T11:45:05.1514080Z"
  }
}
{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Update",
  "id": "36cd379e-5d02-4ae5-aa13-2c4edf8b2d4e",
  "resourceId": "832317b1-04bd-4819-90e5-273898e13a29",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-02-07T11:46:26.9971768Z",
  "changes": {
    "transactionStatus": "Completed",
    "transactionType": "WireDepositUsdc",
    "createdAt": "2025-02-07T11:35:24.0000000Z",
    "paymentId": "6d73df92-3b1e-437d-8c5e-8c9e37db323c",
    "amount": null,
    "cryptoAmount": "2.0",
    "updatedAt": "2025-02-07T11:46:26.6293436Z"
  }
}

Failed

{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Update",
  "id": "e5dd9ac1-28ad-4639-9821-fffd8dcf1cc5",
  "resourceId": "6d73df92-3b1e-437d-8c5e-8c9e37db323c",
  "resourceType": "Payment",
  "createdAtUtc": "2025-02-07T11:46:26.6350922Z",
  "changes": {
    "paymentStatus": "Failed",
    "paymentType": "WireDepositUsdc", // Or AchDepositUsdc
    "createdAt": "2025-02-07T11:35:24.0000000Z",
    "updatedAt": "2025-02-07T11:45:05.1514080Z"
  }
}
{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Update",
  "id": "36cd379e-5d02-4ae5-aa13-2c4edf8b2d4e",
  "resourceId": "832317b1-04bd-4819-90e5-273898e13a29",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-02-07T11:46:26.9971768Z",
  "changes": {
    "transactionStatus": "Failed",
    "transactionType": "WireDepositUsdc",
    "createdAt": "2025-02-07T11:35:24.0000000Z",
    "paymentId": "6d73df92-3b1e-437d-8c5e-8c9e37db323c",
    "amount": null,
    "cryptoAmount": "2.0",
    "updatedAt": "2025-02-07T11:46:26.6293436Z"
  }
}

Updated 2 months ago