--- title: "List available card packages." method: GET path: "/ledger/card-packages" tags: ["ledger-card terms"] --- # List available card packages. `GET /ledger/card-packages` ## Request - Base URL: `https://external.dev.onboardpay.co` - URL: `https://external.dev.onboardpay.co/ledger/card-packages` - Auth: API key in header `x-api-key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Lists the card provider "packages" a business can create a card against, each with its current fee schedule embedded. Only `onb-cards` is registered today - a package appears here purely by registering another CardProviderService bean, with no change to this endpoint. The root path is /card-packages (not nested under /terms) to avoid stuttering, but sibling package-scoped resources (e.g. requirements, terms-of-service acceptance) can still be added as sub-resources later without a breaking restructure. Each package also embeds the calling business's lifetime card-creation limit (`lifetimeLimit`) - the same figure across every package in the list, since the cap applies to the business across all providers combined, not per package. ## Response `200` Card packages fetched successfully - CardPackageList - `packages` CardPackage[], required - `id` string, required: Stable card provider/package ID (e.g. `onb-cards`). Pass this as `packageId` to GET /card-packages/{packageId}/terms. - `currency` string, required: The currency this card package issues cards in. - `fees` CardFeeSchedule, required: Fees and funding limits for a card package. Fees may be flat or a percentage of the transaction (see CardUsageFee); FLAT fee amounts and the funding limits are provider-level, currency-agnostic figures (not scaled per currency). Computed and owned entirely by the ledger - never fetched from the card provider directly. - `packageId` string, required - `creationFee` CardUsageFee, required: A single card fee. A flat amount, or a percentage of the transaction with an optional fixed add-on and min/max caps. e.g. "3.5% + $0.50, min $1, max $20" is amountType=PERCENT, amount=3.5, fixedValue=0.5, minValue=1, maxValue=20. Computed and owned entirely by the ledger - never fetched from the card provider directly. - `amount` number, required: The fee amount - in card currency when amountType is FLAT, or a percentage when PERCENT. - `amountType` 'FLAT' | 'PERCENT': How a fee amount is applied. * FLAT: a flat amount charged, in the same currency as the card. * PERCENT: the amount is a percentage (usually less than 100) of the transaction amount. - `frequency` 'RECURRING' | 'ONE_TIME' | 'AD_HOC': When a fee is charged. Carried for parity with onboard-wallet-cards; the ledger only charges one-time/ad-hoc card fees and does not enforce RECURRING scheduling. * RECURRING: charged at regular intervals over the account's life. * ONE_TIME: charged only once, e.g. at card creation. * AD_HOC: charged when a particular action happens, e.g. a top-up or withdrawal. - `recurrenceCount` integer: The number of times a RECURRING fee recurs within its cycle. Carried for parity; unused. - `recurrenceFrequency` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY': Frequency of a RECURRING fee. Carried for parity only; not enforced by the ledger. - `minValue` number: Floor on the computed fee. - `maxValue` number: Cap on the computed fee. - `fixedValue` number: An amount always charged in addition to a percentage. e.g. for a fee of 3.5% + $0.5: amountType will be PERCENT, amount will be 3.5, and fixedValue will be 0.5. - `fundingFee` CardUsageFee, required: A single card fee. A flat amount, or a percentage of the transaction with an optional fixed add-on and min/max caps. e.g. "3.5% + $0.50, min $1, max $20" is amountType=PERCENT, amount=3.5, fixedValue=0.5, minValue=1, maxValue=20. Computed and owned entirely by the ledger - never fetched from the card provider directly. - `amount` number, required: The fee amount - in card currency when amountType is FLAT, or a percentage when PERCENT. - `amountType` 'FLAT' | 'PERCENT': How a fee amount is applied. * FLAT: a flat amount charged, in the same currency as the card. * PERCENT: the amount is a percentage (usually less than 100) of the transaction amount. - `frequency` 'RECURRING' | 'ONE_TIME' | 'AD_HOC': When a fee is charged. Carried for parity with onboard-wallet-cards; the ledger only charges one-time/ad-hoc card fees and does not enforce RECURRING scheduling. * RECURRING: charged at regular intervals over the account's life. * ONE_TIME: charged only once, e.g. at card creation. * AD_HOC: charged when a particular action happens, e.g. a top-up or withdrawal. - `recurrenceCount` integer: The number of times a RECURRING fee recurs within its cycle. Carried for parity; unused. - `recurrenceFrequency` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY': Frequency of a RECURRING fee. Carried for parity only; not enforced by the ledger. - `minValue` number: Floor on the computed fee. - `maxValue` number: Cap on the computed fee. - `fixedValue` number: An amount always charged in addition to a percentage. e.g. for a fee of 3.5% + $0.5: amountType will be PERCENT, amount will be 3.5, and fixedValue will be 0.5. - `withdrawalFee` CardUsageFee, required: A single card fee. A flat amount, or a percentage of the transaction with an optional fixed add-on and min/max caps. e.g. "3.5% + $0.50, min $1, max $20" is amountType=PERCENT, amount=3.5, fixedValue=0.5, minValue=1, maxValue=20. Computed and owned entirely by the ledger - never fetched from the card provider directly. - `amount` number, required: The fee amount - in card currency when amountType is FLAT, or a percentage when PERCENT. - `amountType` 'FLAT' | 'PERCENT': How a fee amount is applied. * FLAT: a flat amount charged, in the same currency as the card. * PERCENT: the amount is a percentage (usually less than 100) of the transaction amount. - `frequency` 'RECURRING' | 'ONE_TIME' | 'AD_HOC': When a fee is charged. Carried for parity with onboard-wallet-cards; the ledger only charges one-time/ad-hoc card fees and does not enforce RECURRING scheduling. * RECURRING: charged at regular intervals over the account's life. * ONE_TIME: charged only once, e.g. at card creation. * AD_HOC: charged when a particular action happens, e.g. a top-up or withdrawal. - `recurrenceCount` integer: The number of times a RECURRING fee recurs within its cycle. Carried for parity; unused. - `recurrenceFrequency` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY': Frequency of a RECURRING fee. Carried for parity only; not enforced by the ledger. - `minValue` number: Floor on the computed fee. - `maxValue` number: Cap on the computed fee. - `fixedValue` number: An amount always charged in addition to a percentage. e.g. for a fee of 3.5% + $0.5: amountType will be PERCENT, amount will be 3.5, and fixedValue will be 0.5. - `fxTransactionFee` CardUsageFee, required: A single card fee. A flat amount, or a percentage of the transaction with an optional fixed add-on and min/max caps. e.g. "3.5% + $0.50, min $1, max $20" is amountType=PERCENT, amount=3.5, fixedValue=0.5, minValue=1, maxValue=20. Computed and owned entirely by the ledger - never fetched from the card provider directly. - `amount` number, required: The fee amount - in card currency when amountType is FLAT, or a percentage when PERCENT. - `amountType` 'FLAT' | 'PERCENT': How a fee amount is applied. * FLAT: a flat amount charged, in the same currency as the card. * PERCENT: the amount is a percentage (usually less than 100) of the transaction amount. - `frequency` 'RECURRING' | 'ONE_TIME' | 'AD_HOC': When a fee is charged. Carried for parity with onboard-wallet-cards; the ledger only charges one-time/ad-hoc card fees and does not enforce RECURRING scheduling. * RECURRING: charged at regular intervals over the account's life. * ONE_TIME: charged only once, e.g. at card creation. * AD_HOC: charged when a particular action happens, e.g. a top-up or withdrawal. - `recurrenceCount` integer: The number of times a RECURRING fee recurs within its cycle. Carried for parity; unused. - `recurrenceFrequency` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY': Frequency of a RECURRING fee. Carried for parity only; not enforced by the ledger. - `minValue` number: Floor on the computed fee. - `maxValue` number: Cap on the computed fee. - `fixedValue` number: An amount always charged in addition to a percentage. e.g. for a fee of 3.5% + $0.5: amountType will be PERCENT, amount will be 3.5, and fixedValue will be 0.5. - `transactionFee` CardUsageFee, required: A single card fee. A flat amount, or a percentage of the transaction with an optional fixed add-on and min/max caps. e.g. "3.5% + $0.50, min $1, max $20" is amountType=PERCENT, amount=3.5, fixedValue=0.5, minValue=1, maxValue=20. Computed and owned entirely by the ledger - never fetched from the card provider directly. - `amount` number, required: The fee amount - in card currency when amountType is FLAT, or a percentage when PERCENT. - `amountType` 'FLAT' | 'PERCENT': How a fee amount is applied. * FLAT: a flat amount charged, in the same currency as the card. * PERCENT: the amount is a percentage (usually less than 100) of the transaction amount. - `frequency` 'RECURRING' | 'ONE_TIME' | 'AD_HOC': When a fee is charged. Carried for parity with onboard-wallet-cards; the ledger only charges one-time/ad-hoc card fees and does not enforce RECURRING scheduling. * RECURRING: charged at regular intervals over the account's life. * ONE_TIME: charged only once, e.g. at card creation. * AD_HOC: charged when a particular action happens, e.g. a top-up or withdrawal. - `recurrenceCount` integer: The number of times a RECURRING fee recurs within its cycle. Carried for parity; unused. - `recurrenceFrequency` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY': Frequency of a RECURRING fee. Carried for parity only; not enforced by the ledger. - `minValue` number: Floor on the computed fee. - `maxValue` number: Cap on the computed fee. - `fixedValue` number: An amount always charged in addition to a percentage. e.g. for a fee of 3.5% + $0.5: amountType will be PERCENT, amount will be 3.5, and fixedValue will be 0.5. - `maintenanceFee` CardUsageFee, required: A single card fee. A flat amount, or a percentage of the transaction with an optional fixed add-on and min/max caps. e.g. "3.5% + $0.50, min $1, max $20" is amountType=PERCENT, amount=3.5, fixedValue=0.5, minValue=1, maxValue=20. Computed and owned entirely by the ledger - never fetched from the card provider directly. - `amount` number, required: The fee amount - in card currency when amountType is FLAT, or a percentage when PERCENT. - `amountType` 'FLAT' | 'PERCENT': How a fee amount is applied. * FLAT: a flat amount charged, in the same currency as the card. * PERCENT: the amount is a percentage (usually less than 100) of the transaction amount. - `frequency` 'RECURRING' | 'ONE_TIME' | 'AD_HOC': When a fee is charged. Carried for parity with onboard-wallet-cards; the ledger only charges one-time/ad-hoc card fees and does not enforce RECURRING scheduling. * RECURRING: charged at regular intervals over the account's life. * ONE_TIME: charged only once, e.g. at card creation. * AD_HOC: charged when a particular action happens, e.g. a top-up or withdrawal. - `recurrenceCount` integer: The number of times a RECURRING fee recurs within its cycle. Carried for parity; unused. - `recurrenceFrequency` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY': Frequency of a RECURRING fee. Carried for parity only; not enforced by the ledger. - `minValue` number: Floor on the computed fee. - `maxValue` number: Cap on the computed fee. - `fixedValue` number: An amount always charged in addition to a percentage. e.g. for a fee of 3.5% + $0.5: amountType will be PERCENT, amount will be 3.5, and fixedValue will be 0.5. - `minFundingAmount` number, required: Minimum initial funding amount accepted when creating a card. - `minTopUpAmount` number, required: Minimum amount accepted for a top-up on an already-issued card. - `maxTopUpAmount` number, required: Maximum amount accepted for a top-up on an already-issued card. - `minimumBalance` number, required: Floor this provider requires the card's balance to never drop below (e.g. Miden requires $1 for onb-cards). A withdrawal that would breach this is rejected (400) - terminate the card instead to withdraw its full balance. Zero means the provider has no such requirement. - `lifetimeLimit` CardLifetimeLimit, required: The calling business's lifetime cap on the number of card accounts it may ever create (ONBW-2868), across every provider/package combined - not scoped to this one package. This is a lifetime cap, not a concurrent/active-card limit: closing a card does not free up a new slot, so `currentCount` only decreases if a create attempt is rejected or fails outright. - `limit` integer, required: Maximum number of card accounts this business may ever create. - `currentCount` integer, required: Number of card accounts already created by this business that count against the limit. - `remaining` integer, required: `limit` minus `currentCount`, floored at 0. ## Other responses - `401`: Client is not authorized to make request - `403`: Expected permission is not available. - `default`: Internal Server Error ## Changes - **2026-09-22** `596ca42aa76f`: 3 breaking, 6 info - the `packages/items/fees/creationFee` response's property type changed from `number` to no type for status `200` - the `packages/items/fees/fundingFee` response's property type changed from `number` to no type for status `200` - the `packages/items/fees/withdrawalFee` response's property type changed from `number` to no type for status `200` - added `#/components/schemas/CardUsageFee` to the `packages/items/fees/creationFee` response property `allOf` list for the response status `200` - …5 more - **2026-09-18** `e45a393a81eb`: 1 info - the response property `packages/items/fees/minimumBalance` became required for the status `200` - **2026-09-17** `6aec1590a678`: 1 info - added the optional property `packages/items/fees/minimumBalance` to the response with the `200` status - **2026-09-16** `877f09d54c7d`: 1 info - added the required property `packages/items/lifetimeLimit` to the response with the `200` status - **2026-09-11** `5ff3e810d459`: 1 info - endpoint added [Operation history](https://skmtc.dev/nestechops/apis/onboard-external-api-gateway/changes/ledger/card-packages/get.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)