Virtual Account Transfer Status

Virtual Account Transfer Status through this project environment’s SafeHaven account. Uses snake_case fields and NGN minor units. Requires accounts:read.

Use with AI

Download Claude instructions Download Codex instructions All AI integration resources

Markdown

POSThttps://api.veyqo.org/api/v1/safehaven/virtual-accounts/statusIntegration guide

Use your sandbox environment to start. Understand error codes and payment statuses before handling a live payment.

Virtual Account Transfer Status

curl --request POST "https://api.veyqo.org/api/v1/safehaven/virtual-accounts/status" \
  --header "Authorization: Bearer $VEYQO_SECRET_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
  "session_id": "000000000000000000000001"
}'

{
  "success": true,
  "data": {
    "_id": "000000000000000000000001",
    "client": "example",
    "virtual_account": {
      "_id": "000000000000000000000001",
      "client": "example",
      "bank_code": "090286",
      "account_number": "0000000000",
      "account_name": "example",
      "currency_code": "example",
      "bvn": "example",
      "valid_for": 0,
      "external_reference": "order-1001",
      "amount_control": "example",
      "amount": 50000,
      "expiry_date": "example",
      "callback_url": "https://example.com",
      "settlement_account": {
        "_id": "000000000000000000000001",
        "bank_code": "090286",
        "account_number": "0000000000"
      },
      "status": "Created",
      "is_deleted": false,
      "created_at": "example",
      "updated_at": "example",
      "__v": 0
    },
    "session_id": "000000000000000000000001",
    "name_enquiry_reference": "order-1001",
    "payment_reference": "order-1001",
    "is_reversed": false,
    "reversal_reference": "order-1001",
    "provider": "example",
    "provider_channel": "example",
    "provider_channel_code": "example",
    "destination_institution_code": "example",
    "credit_account_name": "example",
    "credit_account_number": "example",
    "credit_bank_verification_number": [],
    "credit_k_y_c_level": "example",
    "debit_account_name": "example",
    "debit_account_number": "example",
    "debit_bank_verification_number": [],
    "debit_k_y_c_level": "example",
    "transaction_location": "example",
    "narration": "example",
    "amount": 50000,
    "fees": 0,
    "vat": 0,
    "stamp_duty": 0,
    "response_code": "example",
    "response_message": "example",
    "status": "Created",
    "is_deleted": false,
    "created_at": "example",
    "declined_at": "example",
    "updated_at": "example",
    "__v": 0
  }
}

Illustrative examples. Replace IDs and environment variables with your own values. Keep secret keys on your server.

Headers

Authorizationstringrequired: Bearer <secret-key>. This key determines your project environment and must stay on your server.
Content-Typestringrequired: application/json
Acceptstringoptional: application/json

Endpoint

POST https://api.veyqo.org/api/v1/safehaven/virtual-accounts/status

Server secret key required. Scope: accounts:read. The key determines the project and environment; no project-selection header is accepted.

Request body

session_idstringrequired: See the JSON example.

Response fields

_idstringoptional: See the JSON example.
clientstringoptional: See the JSON example.
virtual_accountobjectoptional: See the JSON example.
virtual_account._idstringoptional: See the JSON example.
virtual_account.clientstringoptional: See the JSON example.
virtual_account.bank_codestringoptional: See the JSON example.
virtual_account.account_numberstringoptional: See the JSON example.
virtual_account.account_namestringoptional: See the JSON example.
virtual_account.currency_codestringoptional: See the JSON example.
virtual_account.bvnstringoptional: See the JSON example.
virtual_account.valid_forintegeroptional: See the JSON example.
virtual_account.external_referencestringoptional: See the JSON example.
virtual_account.amount_controlstringoptional: See the JSON example.
virtual_account.amountintegeroptional: Amount in NGN minor units (kobo).
virtual_account.expiry_datestringoptional: See the JSON example.
virtual_account.callback_urlstringoptional: See the JSON example.
virtual_account.settlement_accountobjectoptional: See the JSON example.
virtual_account.settlement_account._idstringoptional: See the JSON example.
virtual_account.settlement_account.bank_codestringoptional: See the JSON example.
virtual_account.settlement_account.account_numberstringoptional: See the JSON example.
virtual_account.statusstringoptional: See the JSON example.
virtual_account.is_deletedbooleanoptional: See the JSON example.
virtual_account.created_atstringoptional: See the JSON example.
virtual_account.updated_atstringoptional: See the JSON example.
virtual_account.__vintegeroptional: See the JSON example.
session_idstringoptional: See the JSON example.
name_enquiry_referencestringoptional: See the JSON example.
payment_referencestringoptional: See the JSON example.
is_reversedbooleanoptional: See the JSON example.
reversal_referencestringoptional: See the JSON example.
providerstringoptional: See the JSON example.
provider_channelstringoptional: See the JSON example.
provider_channel_codestringoptional: See the JSON example.
destination_institution_codestringoptional: See the JSON example.
credit_account_namestringoptional: See the JSON example.
credit_account_numberstringoptional: See the JSON example.
credit_bank_verification_numberJSONoptional: See the JSON example.
credit_k_y_c_levelstringoptional: See the JSON example.
debit_account_namestringoptional: See the JSON example.
debit_account_numberstringoptional: See the JSON example.
debit_bank_verification_numberJSONoptional: See the JSON example.
debit_k_y_c_levelstringoptional: See the JSON example.
transaction_locationstringoptional: See the JSON example.
narrationstringoptional: See the JSON example.
amountintegeroptional: Amount in NGN minor units (kobo).
feesintegeroptional: Amount in NGN minor units (kobo).
vatintegeroptional: Amount in NGN minor units (kobo).
stamp_dutyintegeroptional: Amount in NGN minor units (kobo).
response_codestringoptional: See the JSON example.
response_messagestringoptional: See the JSON example.
statusstringoptional: See the JSON example.
is_deletedbooleanoptional: See the JSON example.
created_atstringoptional: See the JSON example.
declined_atstringoptional: See the JSON example.
updated_atstringoptional: See the JSON example.
__vintegeroptional: See the JSON example.

Errors and recovery

Code	HTTP	Recovery	Retry policy
VALIDATION_FAILED	422	Read error.details when present, correct the named fields and retry only after correction. Validation messages may describe state/capability errors without field details.	No automatic retry.
INVALID_API_KEY	401	Use a current kc_test_ or kc_live_ secret key on /api/v1. Use a pk_test_ or pk_live_ publishable key only on browser checkout.	After fixing credentials.
INSUFFICIENT_PERMISSION	403	Grant the required scope or use a suitably scoped key. Dashboard organization roles and staff permissions are separate.	After permission changes.
RESOURCE_NOT_FOUND	404	Check the ID, project and environment. Do not guess another project’s IDs. An inactive payment link is also not-found.	No blind retry.
PROVIDER_NOT_CONNECTED	422	Connect a provider, choose the project default, or explicitly pass provider. An account shared with another project still needs its own assignment here.	After configuration changes.
PROVIDER_AUTHENTICATION_FAILED	502	The merchant must check/rotate the provider credentials in the dashboard. Do not expose those secrets to your application users.	After credential correction; reconcile existing payment first.
PROVIDER_REQUEST_FAILED	422	Read the safe message, inspect the payment’s failure details and correct the request or provider account. Never repeatedly retry a business rejection.	Only after resolving the cause.
PROVIDER_UNAVAILABLE	503	Check the existing payment and verify its state before starting another attempt. Retry safe reads with backoff; preserve operation identity for retried writes.	Conditional: reconcile unknown outcomes first.
RATE_LIMIT_EXCEEDED	429	Honor Retry-After, use bounded exponential backoff with jitter, and reduce concurrent requests. Read X-RateLimit headers.	Yes, after Retry-After; preserve write idempotency.
IDEMPOTENCY_KEY_REUSED	409	Reuse the exact original request to recover that operation, or use a new key only for a genuinely different operation.	Do not retry a changed body with that key.
IDEMPOTENCY_IN_PROGRESS	409	Wait briefly, retry with the same key and unchanged request, then reconcile by reference if the result remains uncertain.	Back off with jitter; preserve key/body.

Complete error catalogue

Every Veyqo error code, including which surface emits it and how to recover.