Virtual account details

📘
Customer account is required. See onboarding customer for more information.

Once a customer has been successfully approved, a virtual account is automatically created for them.

To be notified when the virtual account becomes active, subscribe to the relevant webhook event. This ensures your system can react immediately once the account is ready for use.

Deposits made in USD are settled into the customer’s USDC wallet.

Retrieve Virtual Account Details

Use the endpoint below to fetch a customer’s virtual account information, including account number, bank details, and supported payment methods.

See API reference.

curl --request GET \
  --url https://api.sandbox.keyrails.com/api/v1/customers/{customerId}/virtual-accounts \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'

Response

[
  {
    "id": "string",
    "status": "Active",
    "rails": [
      "fedwire", "swift"
    ],
    "asset": "USD",
    "bank": {
      "bankName": "string",
      "accountNumber": "string",
      "routingNumber": "string",
      "swiftCode": "string",
      "address": {
        "street1": "string",
        "city": "string",
        "state": "string",
        "postalCode": "string",
        "country": "string"
      }
    },
    "accountOwner": {
      "name": "string",
      "address": {
        "street1": "string",
        "city": "string",
        "state": "string",
        "postalCode": "string",
        "country": "string"
      }
    }
  }
]

Webhooks Example

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

Webhook types: VirtualAccount

Active:

{
  "tenantId": "e9de9366-88db-4dcf-9dec-637c6339987e",
  "action": "Update",
  "id": "efd3818b-8d26-4bda-8ef9-09bdd5ca67fb",
  "resourceId": "262bb0c2-4c4a-475a-911a-398b33890da3",
  "resourceType": "VirtualAccount",
  "createdAtUtc": "2026-04-16T06:07:38.7574654Z",
  "changes": { 
    "customerId": "09d1a671-5f97-4ec8-b488-65808bdee037", 
    "status": "active"
  }
}

Simulate a Wire Deposit (Sandbox Only)

In the sandbox environment, you can simulate a wire deposit into a customer’s virtual account. This is useful for testing deposit flows and webhook handling without initiating a real transfer.

See API reference.

curl --request GET \
  --url https://api.sandbox.keyrails.com/api/v1/customers/{customerId}/simulate-account-deposit \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}' \
  --data '{ 
    "amount": 1000
  }
'

Deposit Webhook example

{
    "tenantId": "a210302b-d182-4aa7-9583-7fcbb92d0cf4",
    "action": "Update",
    "id": "dffa1723-2ab3-4279-bf60-32ee03f6bc56",
    "resourceId": "79468249-c31d-4b27-ab7b-52efa3411257",
    "resourceType": "Transaction",
    "createdAtUtc": "2026-03-07T14:15:06.6355302Z",
    "changes": {
        "transactionStatus": "Processing",
        "transactionType": "WireDepositUsdc",
        "createdAt": "2026-03-07T14:15:04.8185210Z",
        "updatedAt": "2026-03-07T14:15:06.4398171Z"
    }
}

Monitor Transfer Status

See API reference.

curl --request GET \
  --url https://api.sandbox.keyrails.com/api/v1/transactions/{transactionId} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'

Response

{
  "id": "79468249-c31d-4b27-ab7b-52efa3411257",
  "type": "WireDepositUsdc",
  "status": "Processing",
  "source": {
    "originator": {
      "name": "Originator Name",
      "bankData": {
        "accountNumber": "BE34001216371411",
        "routingNumber": "000000123"
      }
    }
  },
  "destination": {
    "customerId": "aefb44a3-6a68-428f-b8b6-93ba8c558cbb",
    "accountId": "4e6526f3-79e7-40a1-bfc4-5281f2271ec5"
  },
  "sourceCurrency": "USDC",
  "destinationCurrency": "USD",
  "network": "Sepolia",
  "amount": 5000,
  "transactionFee": 0,
  "totalAmount": 5000,
  "comment": "",
  "memo": "",
  "purposeOfPayment": "",
  "createdAt": "2026-03-06T16:15:04.124365+00:00",
  "updatedAt": "2026-03-06T16:15:05.245644+00:00"
}