Card Products API

A card product is a plan: the financial contract a credit card is issued under — cut-off cadence, days to pay, interest and late-fee rates, minimum payment and card validity.

The CMS Base URL is used (see introduction).

Terms are frozen at issuance

When a card is opened, the plan's terms are copied onto the account. Editing a plan later never rewrites cards already issued, and disabling a plan only stops new cards from being opened under it.

The Card Product Object

{
  "id": "dbb59052-955c-456c-9be5-6041df34f60e",
  "name": "Tarjeta Clásica",
  "status": "enabled",
  "isDefault": true,
  "terms": {
    "billingPeriod": { "unit": "day", "count": 1, "monthDays": [15] },
    "termDays": 10,
    "interestRate": { "period": 360, "rate": "36" },
    "penaltyRate": { "period": 1, "rate": "5" },
    "minPaymentPercent": "10",
    "minPaymentFloor": { "amount": "50.00", "currency": "USD" },
    "interestTax": "21",
    "validityYears": 3,
    "currency": "USD"
  },
  "version": 2
}

Attributes

Attribute	Description	Type
`id`	Card product id	UUID
`name`	Commercial name of the plan	String
`status`	`enabled` or `disabled` — disabled plans cannot open new cards	String
`isDefault`	The plan used when a card is opened without `productId`	Boolean
`terms`	See Card Terms	Object

Card Terms

Field	Description	Type
`billingPeriod`	Cut-off cadence. `monthDays` (1–31) and/or `weekDays` (0=Sunday) constrain which days can close a cycle; `unit`+`count` set the length when unconstrained.	Object
`termDays`	Days from the cut-off to the due date	Integer
`interestRate`	Nominal rate charged daily on unpaid statement balances. `{"period":360,"rate":"36"}` = 36% nominal yearly ⇒ 0.1% per day.	Object
`penaltyRate`	One-shot late fee as a % of the remaining due as of the due date, charged only when the minimum payment was missed	Object
`minPaymentPercent`	Minimum payment as a % of the billed amount	String
`minPaymentFloor`	Optional absolute floor for the minimum (capped at the billed amount)	Money
`interestTax`	Tax (VAT) on each interest charge, as a % of it. Absent or zero = untaxed.	String
`penaltyTax`	Tax on the late fee. Absent inherits `interestTax`; set it explicitly — including to `"0"` — when the late fee is taxed differently.	String
`validityYears`	Card validity: the account's `expiresOn` = opening date + this. Defaults to 3.	Integer
`currency`	Currency of every card issued under the plan	String

The rate value travels as `rate`

Both interestRate and penaltyRate carry the value under the key rate, not value — the same shape DPA uses. Sending value is silently ignored and the rate is stored as zero.

A monthly card that closes on the 15th and gives 10 days to pay is {"billingPeriod": {"unit": "day", "count": 1, "monthDays": [15]}, "termDays": 10}: cycles run from the 15th to the 14th, and the due date is the 24th.

Endpoints

Create a Card Product

POST /v1/card-products

Field	Description	Type
`name`	Commercial name	String
`isDefault`	Make it the tenant's default plan	Boolean
`terms`	The plan's terms — required	Object

Returns 201 with the Card Product. 400 when the terms are inconsistent (for example a negative termDays, a minPaymentPercent outside 0–100, or a minPaymentFloor in a different currency than the plan).

List / Get Card Products

GET /v1/card-products
GET /v1/card-products/{id}

Update a Card Product

PATCH /v1/card-products/{id}

Same body as create. Existing cards keep the terms they were issued with.

Enable or Disable a Card Product

PUT /v1/card-products/{id}/status

Body: { "status": "enabled" } or { "status": "disabled" }.

Permissions

Permission	Grants
`card.settings.read`	list and read plans
`card.settings.write`	create, update, enable/disable

Error Handling

Status	When
`400`	Invalid terms, or a missing `name`
`404`	Unknown plan
`412`	Opening a card under a `disabled` plan
`409`	Concurrent modification of the same plan (retry with the fresh version)

On this page