Cards & Cardholders
Cards & Cardholders
Issuing a card involves three things working together: a Cardholder (who the card belongs to), a Card Product (the template it’s issued from), and the Card itself.
Cardholders
A cardholder is a person or a business you’re issuing cards to:
- Individual — a natural person, identified by name, email, and address
- Corporate — a business, for cards issued to an organization rather than a person
Create one with POST /cardholders/individual or POST /cardholders/corporate. Requests take an optional phone_number and an address with line_1, line_2 (optional), city, state_or_province (an ISO 3166-2 code such as CA, required for countries that use subdivisions), post_code, and country (ISO 3166-1 alpha-2). In responses, the phone number is returned as phone and the postal code as zip_code.
Cardholder PII — given_name, family_name, email, phone, and the address line_1, line_2, and zip_code — is masked by default everywhere a single cardholder is returned (create, get, update, activate, deactivate, terminate, and history). Pass ?reveal_sensitive=true to get the real values back:
GET /cardholders/ (list) doesn’t accept reveal_sensitive: list results are always masked, so cardholder PII can’t be read in bulk. Fetch a cardholder individually with reveal_sensitive=true when you need the real values.
A cardholder moves between active, deactivated, and suspended. Terminating a cardholder (DELETE /cardholders/{cardholder_id}) moves it to deleting and then deleted, which is permanent.
You can attach a Spend Control directly to a cardholder so it applies across every card they hold. Assign or replace it with PUT /cardholders/{cardholder_id}/spend_control (body {"spend_control_id": "..."}) and remove it with DELETE /cardholders/{cardholder_id}/spend_control, both on the Issuing API.
Card Products
A Card Product is 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. Card products are configured for your business by Penny; list the ones available to you:
Penny chooses the BIN and BIN range for each card from the product’s configuration. The card’s bin_id and bin_range_id show which were used.
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 its own capabilities: contactless payments, e-commerce, international acceptance, supported form factors, and supported usage types.
Look these up when you need to know what a card issued from a given BIN or range can do.
GET /products/{card_product_id}/bins/{bin_id} returns the BIN itself. number is the same value you see as bin on a card:
GET /products/{card_product_id}/bins/{bin_id}/ranges lists every range configured for that BIN on the product; GET .../ranges/{bin_range_id} returns a single one. Both return the same shape:
supported_form_factors lists the card form factors a range can issue. Today this is virtual.
status is one of reserved, active, deactivated, or deprecated for both a BIN and a BIN range, alongside an independent active flag. Issue new cards only against a BIN and range that are active.
Cards
A card is issued from a product to a cardholder and draws funds from a Capital Account. You can also scope its spend with a Control Account, which holds no balance of its own (see Accounts). Cards are created with POST /cards/virtual, and every card needs a cardholder: pass either an existing cardholder_id or an inline cardholder object to create the cardholder and the card in one call. See Issuing a Card for the full request shape.
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, highly sensitive POST /cards/{card_id}/reveal endpoint, which requires the card:reveal permission and returns card_id, pan, cvv, expiration_month, and expiration_year.
Assign or replace a card’s spend control with PUT /cards/{card_id}/spend_control (body {"spend_control_id": "..."}) and remove it with DELETE /cards/{card_id}/spend_control, both on the Issuing API.
Usage types
A card’s usage_type comes from its card product and can’t be changed after issuance. The product’s usage type must be listed in the BIN range’s supported_usage_types. Penny enforces each usage type on every authorization, alongside the card’s spend controls.
Cards with a single_use or single_reload usage type include a read-only usage_limits object:
On a single_use card, authorizations_maximum is 1 and authorizations_used shows whether the use is taken; the amount fields are null. Amounts are in the card’s currency.
Lifecycle
A new card is active as soon as it’s issued, or deactivated if you create it with "active": false. From there it can move between active, suspended (temporary), and deactivated. Terminating a card (DELETE /cards/{card_id}) sets it to terminated, which is permanent: use it only when a card should never be used again, not for a temporary pause.
See Issuing a Card for a full walkthrough from cardholder to first transaction.