Import existing sub-accounts

Bring sub-accounts created directly with SafeHaven (before you used Veyqo) under this project environment, so their deposits are forwarded as provider_service.updated events and they can be read, debited and used for statements through Veyqo. Each account is re-read from SafeHaven with this connection's credentials. Requires accounts:write.

Use with AI

Download Claude instructions Download Codex instructions All AI integration resources

Markdown

POSThttps://api.veyqo.org/api/v1/safehaven/accounts/importIntegration guide

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

Import existing sub-accounts

curl --request POST "https://api.veyqo.org/api/v1/safehaven/accounts/import" \
  --header "Authorization: Bearer $VEYQO_SECRET_KEY" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: $OPERATION_IDEMPOTENCY_KEY"

{
  "success": true,
  "data": {
    "imported": [
      {
        "account_id": "64f1c2e9a1b2c3d4e5f60789",
        "account_number": "5011722956",
        "account_name": "Ada Obi",
        "status": "imported"
      },
      {
        "account_id": "64f1c2e9a1b2c3d4e5f6078a",
        "account_number": "5011722957",
        "account_name": "Bayo Ade",
        "status": "already_imported"
      }
    ],
    "failed": []
  }
}

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/accounts/import

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

accountsarrayrequired: Up to 100 accounts per request. Give account_id (SafeHaven internal _id, fastest) or the ten-digit account_number.
accounts[].account_idstringoptional: See the JSON example.
accounts[].account_numberstringoptional: See the JSON example.

Response fields

importedarrayrequired: See the JSON example.
imported[].account_idstringrequired: See the JSON example.
imported[].account_numberstringrequired: See the JSON example.
imported[].account_namestring | nulloptional: See the JSON example.
imported[].statusstringrequired: Values: imported, already_imported.
failedarrayrequired: See the JSON example.
failed[].account_idstringoptional: See the JSON example.
failed[].account_numberstringoptional: See the JSON example.
failed[].reasonstringrequired: Values: not_found, mismatch, not_a_subaccount, main_account, owned_elsewhere.
failed[].messagestringrequired: 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.
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.

Complete error catalogue

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