Card Settings API

Tenant-level configuration of the credit-card family: the operating mode (one card per client, or a company card with credit lines) and the default terms a new plan starts from — the settings that vary by country rather than by product, such as the VAT rate on finance charges or the currency.

The CMS Base URL is used (see introduction).

The Card Settings Object

{
  "mode": "company-lines",
  "paymentAllocation": "charges-first",
  "creditRestoration": "on-close",
  "interestTax": "16",
  "penaltyTax": "16",
  "currency": "MXN"
}

Attributes

Attribute	Description	Type
`mode`	`single` (one card per client, the default) or `company-lines` (a company card with credit lines)	String
`paymentAllocation`	Default for new plans. See Payment policies	String
`creditRestoration`	Default for new plans	String
`lineRestoration`	Default for new plans	String
`interestTax` / `penaltyTax`	Default VAT on interest / late fees, as a %	String
`currency`	Default currency for new plans (ISO 4217)	String

Every attribute except mode is optional: an absent one means "no tenant default", and the plan keeps the system default.

Endpoints

Get the Settings

GET /v1/card-settings

Always returns the effective mode: a tenant that never configured anything reads {"mode": "single"}, not {}.

Update the Settings

PUT /v1/card-settings

Same body as the object. PUT replaces the whole set of defaults — a key you leave out clears its default — except mode: an absent mode means "leave the mode as it is". To go back to one card per client, send "mode": "single" explicitly.

How the defaults apply

Defaults are stamped, not read live

Creating or updating a plan fills in only the terms the caller left out, and the resolved value is written onto the plan. Changing a tenant default never re-prices a plan that already exists, nor a card already issued.

Absent and zero are different. A plan that explicitly sends "interestTax": "0" stays untaxed even when the tenant default is 16%.
An invalid value is rejected here, when the tenant is configured, rather than months later when someone tries to create a plan.

The operating mode

Mode	What it means
`single`	One live card per client. Opening a second one for the same client answers `422 card_client_has_card`. Credit lines cannot be opened.
`company-lines`	A company holds one card and opens credit lines under it, one per holder or vehicle. See Credit Lines.

mode is read live, never stamped onto a plan or a card: it is not a price, so re-reading it cannot re-price anything.

Switching single → company-lines is always allowed. The way back is refused while any credit line is still open (422 card_lines_still_open, saying how many lines on how many cards): close them first.

Permissions

Permission	Grants
`card.settings.read`	read the settings
`card.settings.write`	update them

Error Handling

Status	When
`400`	An invalid value, an unknown key, or a non-ISO currency
`422 card_lines_still_open`	Going back to `single` while credit lines are still open

On this page