List virtual accounts

GET/partner/v1/virtual-accounts

Auth Bearer tokenScope partner.read

Lists the bank details a payer uses to pay you, or one of your customers, in a fiat currency. Bank details only: no wallet and no balance.

Accounts are grouped by currency, then by purpose, oldest first within each group. Only active, long-lived accounts are listed, and only the one Ryno exposes on each wallet, so at most one per currency and purpose: standby accounts are never listed, so every account returned is one a payer can be given. A crypto or unknown currency returns an empty list, not an error.

Query

customerIduuidquery

Whose bank details to list: a customer you onboarded. Omit it for your own.

A customer that does not exist or is not under your partner account is 404 partner.sub_customer_not_found. A suspended or closed customer is still listed.

currencystringquery

Only this currency, for example NGN. Case does not matter. Omit it for every currency.

Response

valueobject[]

One entry per virtual account. Empty when there are none.

Show propertiesHide properties

virtualAccountIduuid

Ryno's id for the account.

currencystring

The currency a payer sends, for example NGN.

purposestring | null

The label of the collection wallet the account pays into, so two of your collection wallets in one currency can be told apart. null unless the account belongs to one of your labelled collection wallets.

providerNamestring

The bank partner that issued the account.

fundingRailstring

How the payer pays, for example BankTransfer.

statusstring

Active today. Only active accounts are listed; the field is kept for future states.

accountNumberstring | null

accountNamestring | null

bankNamestring | null

bankCodestring | null

sortCodestring | null

The UK sort code, where the bank partner issued one (GBP accounts). null otherwise.

ibanstring | null

The IBAN, where the bank partner issued one (for example EUR accounts). null otherwise.

isPrimaryboolean

Always true: only the account exposed on each wallet is listed. Kept for compatibility.

createdDateUtcstring

When the account was issued, in UTC.

Errors

Code	HTTP	Meaning
Request.Invalid	400	customerId is not a uuid.
Auth.Unauthorized	401	The token is missing or invalid.
Auth.Forbidden	403	The token is not a partner credential, or lacks partner.read.
partner.profile_not_active	403	Your partner account is not active. Contact support.
partner.profile_not_found	404	Your partner account could not be found. Contact support.
partner.sub_customer_not_found	404	customerId does not exist or is not under your partner account.

The 401, 429 and 503 responses from the API gateway use a different body. See Errors.

Request

curl "https://gateway.sandbox.rynopay.io/api/partner/v1/virtual-accounts?customerId=b3f1c2d4-8a5e-4d2b-9c71-6e0f3a2b1c58&currency=NGN" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response

200

{
  "value": [
    {
      "virtualAccountId": "7c2e9b14-3f6a-4d81-b5e0-9a1c4d2f6e83",
      "currency": "NGN",
      "purpose": null,
      "providerName": "Wema Bank",
      "fundingRail": "BankTransfer",
      "status": "Active",
      "accountNumber": "8123456789",
      "accountName": "Lagos Freight Ltd",
      "bankName": "Wema Bank",
      "bankCode": "035",
      "sortCode": null,
      "iban": null,
      "isPrimary": true,
      "createdDateUtc": "2026-11-01T09:00:00Z"
    }
  ],
  "isSuccess": true,
  "isFailure": false,
  "error": { "code": "", "name": "" },
  "title": null,
  "traceId": "0HN..."
}

404

{
  "value": null,
  "isSuccess": false,
  "isFailure": true,
  "error": {
    "code": "partner.sub_customer_not_found",
    "name": "No sub-customer with that id is associated with this partner"
  },
  "title": "Resource not found",
  "traceId": "0HN..."
}