Create Sub Account (Individual)

Create Sub Account (Individual) through this project environment’s SafeHaven account. Uses snake_case fields and NGN minor units. Requires accounts:write.

Use with AI

Download Claude instructions Download Codex instructions All AI integration resources

Markdown

POSThttps://api.veyqo.org/api/v1/safehaven/subaccounts/individualIntegration guide

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

Create Sub Account (Individual)

curl --request POST "https://api.veyqo.org/api/v1/safehaven/subaccounts/individual" \
  --header "Authorization: Bearer $VEYQO_SECRET_KEY" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: $OPERATION_IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "phone_number": "+2348000000000",
  "email_address": "customer@example.com",
  "external_reference": "order-1001",
  "identity_type": "vID",
  "identity_id": "000000000000000000000001"
}'

{
  "success": true,
  "data": {
    "_id": "000000000000000000000001",
    "client": "example",
    "account_product": "example",
    "account_number": "0000000000",
    "account_name": "example",
    "account_type": "example",
    "currency_code": "example",
    "bvn": "example",
    "identity_id": "000000000000000000000001",
    "account_balance": 0,
    "book_balance": 0,
    "callback_url": "https://example.com",
    "is_sub_account": false,
    "sub_account_details": {
      "_id": "000000000000000000000001",
      "first_name": "example",
      "last_name": "example",
      "email_address": "customer@example.com",
      "bvn": "example"
    },
    "external_reference": "order-1001",
    "created_at": "example",
    "updated_at": "example",
    "nin": "example",
    "__v": 0,
    "cba_account_id": "000000000000000000000001",
    "operation_id": "pso_01M6EB66SC61Q3RQYAN0693DGM"
  }
}

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
Idempotency-Keystringoptional: Persist one key for the operation and reuse it with the unchanged body on retries. Maximum 255 characters.

Endpoint

POST https://api.veyqo.org/api/v1/safehaven/subaccounts/individual

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

For each new operation, generate and persist one OPERATION_IDEMPOTENCY_KEY. Retry the unchanged request with that same key. Do not generate a new key on every retry.

Request body

phone_numberstringrequired: This is the phone number of the account holder. It should begin with the country code.
email_addressstringrequired: This is the email address.
external_referencestringrequired: This is an external reference to be attached to the account object.
identity_typestringrequired: Identification method the account holder, should be either NIN, vNIN, BVN, BVNUSSD, or vID (if you are using Safe Haven Verification Service)). Values: NIN, vNIN, BVN, BVNUSSD, vID.
identity_numberstringoptional: It is required when using `BVN`, `NIN`, and `BVNUSSD`. Not required if you are using `vID`
identity_idstringoptional: The `_id` from the Safe Haven Verification Endpoint. It is required when `vID`, `BVN`, or `NIN`
otpstringoptional: The OTP sent to the customer's phone number when you initiate verification using Safe Haven verification endpoint. This works for `BVN` and `NIN` or the OTP sent to customer's phone number when using
auto_sweepbooleanoptional: This should be set when creating a virtual account. It determines if auto sweep should be enabled or disabled.
auto_sweep_detailsobjectoptional: This contains the auto sweep details to be filled if creating a virtual account.
auto_sweep_details.schedulestringrequired: This is the schedule for the autosweep Values: Instant.
auto_sweep_details.account_numberstringrequired: This represents the account to auto sweep to.

Response fields

_idstringoptional: See the JSON example.
clientstringoptional: See the JSON example.
account_productstringoptional: See the JSON example.
account_numberstringoptional: See the JSON example.
account_namestringoptional: See the JSON example.
account_typestringoptional: See the JSON example.
currency_codestringoptional: See the JSON example.
bvnstringoptional: See the JSON example.
identity_idstringoptional: See the JSON example.
account_balanceintegeroptional: Amount in NGN minor units (kobo).
book_balanceintegeroptional: Amount in NGN minor units (kobo).
callback_urlstringoptional: See the JSON example.
is_sub_accountbooleanoptional: See the JSON example.
sub_account_detailsobjectoptional: See the JSON example.
sub_account_details._idstringoptional: See the JSON example.
sub_account_details.first_namestringoptional: See the JSON example.
sub_account_details.last_namestringoptional: See the JSON example.
sub_account_details.email_addressstringoptional: See the JSON example.
sub_account_details.bvnstringoptional: See the JSON example.
external_referencestringoptional: See the JSON example.
created_atstringoptional: See the JSON example.
updated_atstringoptional: See the JSON example.
ninstringoptional: See the JSON example.
__vintegeroptional: See the JSON example.
cba_account_idstringoptional: See the JSON example.
operation_idstringoptional: Veyqo pso_ operation ID. Save it to reconcile retries and match provider_service.updated events.
merchant_referencestringoptional: Your external_reference or payment_reference, if supplied. SafeHaven receives a globally unique Veyqo reference for supported writes.

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.