POST

Create a financial account

ENDPOINT/v1/financial-accounts

Opens a financial account on a wallet. kind is DDA, VIRTUAL, CREDIT, SAVINGS, or CRYPTO; purpose is ISSUING, OPERATING, RESERVE, or CHARGED_OFF. reserve_for is required for RESERVE. Optional nickname labels the financial account. Send Idempotency-Key so retries return the original financial account instead of opening a second one.

Authentication & Headers

Header	Type	Requirement	Description
Authorization	string	REQUIRED	API key passed as an HTTP Bearer token: `Bearer rk_live_...`
X-Program-ID	UUID	PROGRAM-SCOPED	Program boundary UUID that scopes the issuing card, wallet, or transfer.
Content-Type	string	REQUIRED	Must be `application/json`.
Idempotency-Key	string	OPTIONAL	Unique UUID to prevent duplicate execution of financial creations or mutations.

Request Body Schema

application/json

wallet_idstringuuid

REQUIRED

Wallet that will own the new financial account. Use the program wallet for `OPERATING` and `RESERVE`.

kindstring

REQUIRED

Kind of account that holds the funds, matching the vaulting capability enabled on the product. `DDA` is a demand-deposit account. `VIRTUAL` is a virtual account. `CREDIT` is a credit account (the receivable behind card spend). `SAVINGS` is a savings account. `CRYPTO` holds digital assets. A wallet holds at most one financial account per `currency`, `kind`, and `purpose`.

Enum values:DDAVIRTUALCREDITSAVINGSCRYPTO

purposestring

REQUIRED

Role of the financial account in the program. `ISSUING` holds card spend and the receivable that backs a wallet. `OPERATING` holds program float used for transfers and settlement. `RESERVE` holds collateral; see `reserve_for`. `CHARGED_OFF` holds receivables moved off the issuing financial account after charge-off. `OPERATING` and `RESERVE` financial accounts belong to the program wallet.

Enum values:ISSUINGOPERATINGRESERVECHARGED_OFF

reserve_forstringnull

optional

What a `RESERVE` financial account collateralizes. `PROGRAM` is the program reserve that covers negative balances, overdrafts, and fraud. A capability id (for example `cap-payin-ach`) is a capability reserve holding the percentage of volume set aside for that money-movement capability. Null unless `purpose` is `RESERVE`.

currencystring

optional

ISO 4217 currency. Omit to use the program default currency.

nicknamestring

optional

Human-readable label for this financial account. Omit to leave unset.

metadataobject

optional

Integrator-defined string map stored with the financial account. Keys are at most 40 characters. At most 50 keys. Send the full map on PATCH to replace it; omit the field to leave it unchanged; send `{}` to clear.

Response Codes & Schemas

201The financial account was created.

application/json

{
  "id": "9b3e1c70-4d2a-4f86-8c1b-5e7a2d9f0c14",
  "object": "financial_account",
  "wallet_id": "4d8f2a10-6c3e-4b91-9e5a-2f7c8d1e0b44",
  "program_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "kind": "CREDIT",
  "purpose": "ISSUING",
  "reserve_for": null,
  "status": "OPEN",
  "status_reason": null,
  "nickname": "Primary issuing",
  "metadata": {
    "cost_center": "retail",
    "book": "issuing"
  },
  "currency": "USD",
  "account_number_ids": [
    "6e1b4c80-9d25-4f37-a8c2-1b7e5d0f3948"
  ],
  "created_at": "2026-08-12T10:15:00Z",
  "updated_at": "2026-08-12T10:15:00Z"
}

400Bad Request: malformed JSON, failed schema validation, or conflicting parameters.

application/json

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "invalid order by: foo. Valid options are: [created_at updated_at]",
    "param": "order_by",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/invalid_request"
  }
}

401Unauthorized: missing, malformed, or unknown API key.

application/json

{
  "error": {
    "type": "authentication_error",
    "code": "authentication_error",
    "message": "A valid API key is required.",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/authentication_error"
  }
}

403Forbidden: the API key is denied by RBAC, or it cannot access this program. A resource that exists on another program or organization returns `404 not_found`, not `403`.

application/json

{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The API key cannot access this program.",
    "param": "X-Program-ID",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/permission_denied"
  }
}

404Not Found: unknown id, or the resource is not visible to this API key.

application/json

{
  "error": {
    "type": "not_found_error",
    "code": "not_found",
    "message": "No card found for the given id.",
    "param": "card_id",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/not_found"
  }
}

409Conflict: incompatible state, or Idempotency-Key reused with a different body.

application/json

{
  "error": {
    "type": "conflict_error",
    "code": "conflict",
    "message": "The card cannot be reissued from its current state.",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/conflict"
  }
}

422Unprocessable Entity: the document is valid JSON but violates a business rule.

application/json

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_funds",
    "message": "The source financial account does not have enough available balance.",
    "param": "amount",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/insufficient_funds"
  }
}

429Too Many Requests: the API key exceeded its rate limit.

application/json

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after the number of seconds in Retry-After.",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/rate_limited"
  }
}

500Internal Server Error: unexpected failure. Retry with the same Idempotency-Key.

application/json

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred. Retry with the same Idempotency-Key.",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/internal_error"
  }
}