Platform Concepts

Issuing & Cards

Understand card products, cardholders, cards, and their funding context.

Penny separates card configuration from the individual cards issued from it.

fundsscopes spendBusinessOWNERBusiness EntityENTITYProgramBOUNDARYBINBINBIN RangeRANGECard ProductPRODUCTCardholderHOLDERCapital AccountFUNDSControl AccountSPEND SCOPE · OPTIONALCardCARD

Card Products

A Card Product defines the configuration available when issuing cards, and is offered under a Program.

What it’s for: it’s the template a card is issued from. It determines the card’s form factor, its usage type, how its expiration date is set, and which BINs and BIN ranges it can be issued under, so an integration issues cards against a product rather than assembling BIN configuration each time.

How it behaves: card products are configured for your business by Penny; list the ones available to you (GET /products/, GET /products/{card_product_id}). Penny chooses the BIN and BIN range for each card from the product’s configuration.

BINs and BIN ranges

A BIN (Bank Identification Number) is the first digits of a card number (6–8 digits); it identifies the card’s issuer and network. A BIN Range is a sub-range of card numbers within a BIN, with its own currency and capabilities.

What it’s for: a BIN range’s capabilities (contactless payments, e-commerce, international acceptance, supported form factors, and supported usage types) tell you what a card issued from it can do. Look these up to see what a card issued from a given BIN or range can do.

How it behaves: cards are issued from a Card Product; you don’t select a BIN directly. Both a BIN and a BIN range carry their own status (reserved, active, deactivated, deprecated) alongside an independent active flag — avoid issuing new cards against anything but active.

Cardholders

A Cardholder represents the person or business associated with one or more cards.

What it’s for: every card is issued to a Cardholder. Create one first, or create it inline with the card. A cardholder is either individual (a natural person) or corporate (a business, for cards issued to an organization rather than a person).

How it behaves: cardholder PII (given_name, family_name, email, phone, and the street address and zip_code) is masked by default everywhere a single cardholder is returned; pass ?reveal_sensitive=true to get the real values. List results are always masked, so PII can’t be read in bulk. A cardholder moves between active, deactivated, and suspended; terminating it moves it to deleting and then deleted. A Spend Control can be assigned directly to a cardholder (on the Issuing API) so it applies across every card they hold.

See Cards & Cardholders.

Cards

A Card is an issued payment instrument.

A card is associated with:

  • a Card Product;
  • a Cardholder;
  • a Capital Account it draws funds from, and optionally a Control Account that scopes its spend;
  • its own lifecycle and status.

What it’s for: it’s where cardholder, configuration, and funding come together into something that can be used to spend.

How it behaves:

  • Cards are issued via POST /cards/virtual, with either an existing cardholder_id or an inline cardholder.
  • Card reads include the BIN, the last four digits, and the expiration_date, but never the full card number or CVV. The unmasked PAN is available only from the separate POST /cards/{card_id}/reveal endpoint.
  • Every card has a usage_type inherited from its card product, enforced on every authorization: single_use (one authorization, restored if it expires or is cancelled; the first settlement terminates the card), single_reload (a lifetime budget set with load_amount at issuance, which can’t be raised), or reloadable (reusable, subject to its spend controls). single_use and single_reload cards report their remaining allowance in usage_limits.
  • A card’s spend control is assigned or removed on the Issuing API (PUT/DELETE /cards/{card_id}/spend_control).
  • Lifecycle: active once issued (or deactivated if created with "active": false), and from there able to move between active, suspended (temporary), and deactivated. Terminating a card sets it to terminated, which is permanent: use it only when a card should never be used again, not for a temporary pause.

Funding context

A card draws funds from a Capital Account, which holds the balance. A card can also be assigned a Control Account, which holds no balance of its own: it scopes the card’s spend against the Capital Account’s funds.

For the account model, see Banking & Accounts.

For authorization rules, see Spend Controls.