---
title: "Fund a card account."
method: POST
path: "/ledger/card-accounts/{cardAccountId}/fund"
tags: ["ledger-card accounts"]
---

# Fund a card account.

`POST /ledger/card-accounts/{cardAccountId}/fund`

## Request

- Base URL: `https://external.dev.onboardpay.co`
- URL: `https://external.dev.onboardpay.co/ledger/card-accounts/{cardAccountId}/fund`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/nestechops/apis/onboard-external-api-gateway/docs/ledger/card-accounts/:cardAccountId/fund/post.ts> (a function with typed inputs; its response is checked against the schema)

Moves funds from the business's MAIN account into the card's dedicated account, then tops up
the card on the provider. The card must be ACTIVE.

## Path parameters

- `cardAccountId` string, uuid, required

## Request body

- FundCardAccountRequest
  - `amount` number, required
  - `clientReference` string: Optional idempotency key. A retry with the same reference is recognized as the same funding attempt and is not double-processed; omit only for callers that handle their own retry safety.

## Response `200`

Card account funded successfully

- CardAccount
  - `id` string, uuid, required: Unique card account ID.
  - `accountId` string, uuid, required: The MAIN account this card is funded from.
  - `currency` string, required
  - `status` 'PENDING_KYC' | 'PENDING_PROVISIONING' | 'ACTIVE' | 'FROZEN' | 'TERMINATED' | 'KYC_REJECTED' | 'CREATION_FAILED', required: Lifecycle of a card account. PENDING_KYC and PENDING_PROVISIONING are transient - a card only starts moving money once it reaches ACTIVE. KYC_REJECTED and CREATION_FAILED are terminal with no funds ever moved (the dedicated ledger account is only created once KYC is approved).
  - `balance` number, required: The card's live spendable balance.
  - `failureReason` string: Populated when status is KYC_REJECTED or CREATION_FAILED.
  - `spendControls` CardSpendControls
    - `dailyLimit` number
    - `transactionLimit` number
    - `whitelistedMccs` string[]
    - `blacklistedMccs` string[]
    - `contactlessPaymentEnabled` boolean
  - `createdDate` string, date-time, required
  - `cardDetails` CardDetails: Physical/visual card attributes, kept separate from the account-level fields above.
    - `displayName` string
    - `cardBrand` 'VISA' | 'MASTERCARD' | 'VERVE'
    - `cardType` string: Always VIRTUAL in this release.
    - `cardHolderName` string: The name embossed on the card, as assigned by the card provider.
    - `maskedCardNumber` string
    - `expiryMonth` string
    - `expiryYear` string
    - `billingAddress` CardBillingAddress: The card's billing address, as returned by the card provider. Response-only - fields are populated only when the provider supplies them, so none are required here (contrast CardHolderAddress, which validates a request body where every field must be present).
      - `address` string
      - `city` string
      - `state` string
      - `country` string
      - `postalCode` string
      - `zipCode` string
      - `houseNo` string
    - `encryptedCardDetails` string: Base64 RSA-encrypted {pan, cvv, expiryMonth, expiryYear} blob, populated only when fetched via GET /card-accounts/{cardAccountId}/details with a public key.

## Other responses

- `400`: Request could not be validated
- `401`: Client is not authorized to make request
- `403`: Expected permission is not available.
- `404`: Entity was not found
- `default`: Internal Server Error

## Changes

- **2026-09-08** `5b7b2c163546`: 2 info
  - added the optional property `cardDetails/billingAddress` to the response with the `200` status
  - added the optional property `cardDetails/cardHolderName` to the response with the `200` status
- **2026-09-03** `1805362fe220`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nestechops/apis/onboard-external-api-gateway/changes/ledger/card-accounts/:cardAccountId/fund/post.md)

---

[API](https://skmtc.dev/nestechops/apis/onboard-external-api-gateway.md) - [All operations](https://skmtc.dev/nestechops/apis/onboard-external-api-gateway/llms.txt) - [OpenAPI document](https://skmtc.dev/nestechops/apis/onboard-external-api-gateway/revisions/5da9ec1b2573?raw)