Credit Cards API

This API manages revolving credit cards: a credit limit, billing cycles with a cut-off date, statements with a due date, configurable daily interest on unpaid balances, a minimum payment with a late fee, and purchase reversals.

It is a product line of its own, separate from DPA flows and debts — the only shared entity is the client. The CMS Base URL is used (see introduction).

The Card Account Object

{
  "id": "fd44532b-f5f6-493b-baab-8dda053c9cff",
  "clientId": "0187f2d0-471e-40ea-90a2-64d559a40577",
  "productId": "dbb59052-955c-456c-9be5-6041df34f60e",
  "referenceId": "partner-acct-001",
  "status": "enabled",
  "creditLimit": { "amount": "10000.00", "currency": "USD" },
  "currency": "USD",
  "currentStatementId": "712043dc-24c6-45b1-9a58-fd72548fe4dc",
  "outstanding": { "amount": "6255.09", "currency": "USD" },
  "creditBalance": { "amount": "0.00", "currency": "USD" },
  "availableCredit": { "amount": "3744.91", "currency": "USD" },
  "expiresOn": "2029-02-06",
  "terms": { "billingPeriod": { "unit": "day", "count": 1, "monthDays": [15] }, "termDays": 10 },
  "version": 7
}

Attributes

Card Status

Billing Cycles

• The account always has exactly one open statement. Purchases land there and are never due mid-cycle — that is the grace period.
• At the cut-off (closeDate, inclusive) the statement is billed: its dueAmount and minDue freeze, and the next cycle opens. Cycle dates always chain from the previous cut-off, so cycles stay contiguous even if a sweep runs late.
• The due date is closeDate + termDays.
• Unpaid balances are not re-billed into later cycles: every statement keeps its own dueAmount/paidAmount. Interest and late fees charged against a statement post on the current open statement (they appear on the next bill, like a real card) and therefore never compound.

Statement Status

Money Rules

• Credit is revolving: a payment reduces outstanding immediately, so the available credit is restored in the same transaction — no waiting for the cut-off.
• Payments apply oldest-unpaid-first across billed statements; the remainder becomes creditBalance. The payment records the split in applications.
• Purchases over the available credit are rejected with 422 insufficient_credit, checked under a row lock so concurrent purchases cannot jointly overrun the limit.
• Interest is daily, from the day after a statement's due date on its unpaid balance, until it is paid. The base is the statement's own remaining due, so interest never accrues on interest.
• The late fee is one-shot per statement, charged only when payments through the due date did not reach minDue. Paying at or above the minimum avoids the fee; interest still accrues on the rest.

Idempotency

Every write is idempotent — a replay returns the existing record with 200 instead of creating a twin.

The Idempotency-Key header is additionally honored on purchases, payments and reversals.

Endpoints

Open a Card Account

Creates the account in pending with its first open statement.

POST /v1/card-accounts

Body:

Returns 201 with the Card Account; a replay of the same referenceId returns 200 with the existing one.

Get / List Card Accounts

GET /v1/card-accounts?clientId=&status=&limit=&offset=
GET /v1/card-accounts/{id}

Change the Credit Limit

PUT /v1/card-accounts/{id}/credit-limit

Body: { "creditLimit": { "amount": "15000.00", "currency": "USD" } }. Lowering it below the current usage is allowed — the available credit goes negative and purchases are rejected until the cardholder pays down.

Activate, Suspend or Close

POST /v1/card-accounts/{id}/enable
POST /v1/card-accounts/{id}/disable    {"reason": "..."}
POST /v1/card-accounts/{id}/close      {"reason": "..."}

A suspended card still accepts payments. Closing requires a settled book.

Register a Purchase

POST /v1/card-accounts/{id}/purchases

412 if the card is not enabled; 422 insufficient_credit if it exceeds the available credit.

Reverse a Purchase

POST /v1/card-accounts/{id}/purchases/{txId}/reverse

Body: optional amount (omit for a full reversal) and reason. Transactions are immutable, so the reversal is a new compensating transaction — one per purchase, full or partial:

• If the purchase's statement is still open, the reversal voids it inside the cycle and the purchase never gets billed.
• If the statement was already billed, the reversal applies against that statement like a targeted payment (and can mark it paid, stopping its daily interest). Any excess becomes credit balance.

Interest or late fees already charged for past days are not retro-reverted.

Register a Payment

POST /v1/card-accounts/{id}/payments

Same body as a purchase. Applies oldest-unpaid-first; statements it zeroes become paid, which stops their daily interest from that date. The response carries the split:

{
  "transactionId": "…",
  "type": "payment",
  "amount": { "amount": "800.00", "currency": "USD" },
  "applications": [
    { "statementId": "…jul", "amount": { "amount": "300.00", "currency": "USD" } },
    { "statementId": "…aug", "amount": { "amount": "400.00", "currency": "USD" } }
  ]
}

(the remaining 100.00 became credit balance).

Account Summary

GET /v1/card-accounts/{id}/summary

The cardholder's position right now: creditLimit, outstanding, creditBalance, availableCredit, dueNow, minDueNow, oldestDueDate, daysPastDue, cycleStartDate, nextCutoffDate, nextDueDate, cycleSpend (this period's consumption) and expiresOn.

Statements and Transactions

GET /v1/card-accounts/{id}/statements
GET /v1/card-accounts/{id}/statements/current
GET /v1/card-accounts/{id}/transactions
GET /v1/card-statements/{id}
GET /v1/card-statements/{id}/transactions

Transaction types: purchase, payment, interest, penalty (late fee) and reversal. Interest and late fees carry metadata.sourceStatementId pointing at the cycle that owed the money; reversals carry metadata.sourceTransactionId.

Statement Document (estado de cuenta)

GET /v1/card-statements/{id}/document
GET /v1/card-statements/{id}/document.csv

The composed statement of one cycle in a single payload — issuer, cardholder, card, period, totals and the itemized lines — so a renderer never has to stitch calls or re-derive money. .csv returns the same document as a downloadable attachment (debits positive, credits negative, so summing the amount column reconciles).

{
  "issuer":     { "tenant": "…", "name": "…", "taxId": "…" },
  "cardholder": { "clientId": "…", "name": "…", "taxId": "…", "address": "…" },
  "card":       { "tail": "0539", "creditLimit": {}, "availableCredit": {}, "expiresOn": "2029-02-06" },
  "period":     { "startDate": "2026-06-15", "closeDate": "2026-07-14", "dueDate": "2026-07-24", "minDueMet": false },
  "totals":     { "previousBalance": {}, "purchases": {}, "interest": {}, "penalties": {},
                  "payments": {}, "reversals": {}, "dueAmount": {}, "paidAmount": {},
                  "remainingDue": {}, "minDue": {}, "minDueRemaining": {} },
  "lines":      [ { "date": "2026-06-19", "type": "purchase", "concept": "…", "amount": {}, "debit": true } ]
}

previousBalance is what the older cycles still owed as of this cut-off. It is computed when the document is built (unpaid balances are never re-billed) and it is informational — it is not part of this cycle's dueAmount.

Tax (VAT) on interest and late fees

When the plan sets interestTax (and optionally penaltyTax), every interest or late-fee charge stores its own tax and the document breaks it out:

Each interest/late-fee line also carries its own tax; a line's net charge is amount − tax. Every other line (purchases, payments, reversals) carries a zero tax.

Permissions

Sending X-Test-Mode: true operates on the tenant's sandbox, fully partitioned from production data.

Error Handling