API Documentation

Submit cardholder transaction events for real-time offer matching. The primary integration point for financial institutions.

Submit many transaction events in one signed request — for legacy or high-volume feeds.

Prefer a daily file? Upload a CSV of transactions from the Institution Portal — validated and matched like the webhook.

Fetch a cardholder's eligible offers to render in your app or the embeddable widget.

Enroll a cardholder in an offer so their transactions start matching against it.

Cursor-paginated redemption history for BI/data warehouse integration. Authenticated via institution API key.

Cursor-paginated settlement ledger with merchant funded amount, Saldo revenue, and institution payout.

Engagement funnel for a date window: widget views, unique cardholders, impressions, adds, and redemptions.

Returns active, budget-available offers for the cardholder, honoring your program's sort order and per-cardholder eligibility.

Query parameters

• cardholder_token Required. The opaque cardholder token.
• locale Optional. en, es or pt-BR — localizes each offer's title and description. If your program doesn't offer that language, the feed uses your program's first supported language.
• segment Optional. The cardholder's segment code from your own systems (e.g. premium). Offers you limited to segments only appear when it matches; unrestricted offers always appear. Used for this request only — Saldo never stores a cardholder's segment.
• limit Optional. 1–100 (also capped by your widget configuration).
• personalize Optional. Set to true to rank the feed by cardholder affinity; adds a reason to each offer.
• prefer_merchants, prefer_categories Optional. prefer_merchants and prefer_categories accept comma-separated hints, used in-memory only and never stored.

curl "https://saldo-consumer-api-git-staging-kalantech.vercel.app/api/v1/offers?cardholder_token=tok_ch_abc123&locale=es&limit=20" \
  -H "Authorization: Bearer slk_..."

{
  "offers": [
    {
      "id": "0b1...",
      "title": "Spend $200 at Acme, get $15 back",
      "description": "Gasta $200 en Acme y recibe $15",
      "merchant_id": "aaaa...",
      "min_spend": 200.00,
      "cashback_amount": 13.20,
      "currency": "USD",
      "starts_at": "2026-04-01T00:00:00Z",
      "expires_at": "2026-06-30T00:00:00Z",
      "added": false
    }
  ],
  "total": 12,
  "personalized": false
}

Creates the cardholder–offer link so matching can begin. Idempotent — re-adding returns already_added.

Request body

curl -X POST "https://saldo-consumer-api-git-staging-kalantech.vercel.app/api/v1/offers/0b1.../add" \
  -H "Authorization: Bearer slk_..." \
  -H "Content-Type: application/json" \
  -d '{ "cardholder_token": "tok_ch_abc123", "card_token": "tok_card_xyz789" }'

// 201 Created
{ "status": "added", "cardholder_offer_id": "c0f..." }

// 200 OK (idempotent re-add)
{ "status": "already_added", "cardholder_offer_id": "c0f..." }

Pass the same segment when adding an offer limited to segments (403 segment_not_eligible otherwise). If the cardholder already holds your program's maximum number of active offers, the add returns 409 max_active_offers.

Cursor-paginated list of redemptions for the calling institution. Cardholder tokens are masked to first/last 4 characters.

Query parameters

• from, to — ISO 8601 timestamps (optional)
• cursor — opaque value from the previous response (optional)
• limit — 1 to 1000 (default 100)

Example

curl https://saldo-consumer-api-git-staging-kalantech.vercel.app/api/v1/reporting/redemptions?limit=2 \
  -H "Authorization: Bearer slk_..."

{
  "data": [
    {
      "id": "8f3...",
      "created_at": "2026-04-29T14:32:11.000Z",
      "status": "settled",
      "merchant_funded_amount": 15.00,
      "institution_payout_amount": 13.20,
      "offer": {
        "id": "0b1...",
        "title": "Spend $200 at Acme, get $15 back",
        "merchant_name": "Acme Inc."
      },
      "cardholder_token_masked": "tok_...c123"
    }
  ],
  "pagination": {
    "limit": 2,
    "next_cursor": "2026-04-29T14:32:11.000Z|8f3..."
  }
}

Cursor-paginated settlement ledger entries with merchant funded amount, Saldo take revenue, institution payout, and status.

Query parameters

• status — pending | settled | reversed (optional)
• from, to, cursor, limit — same semantics as redemptions

Engagement funnel aggregated for a date window. Defaults to the last 30 days when from / to are omitted.

{
  "window": { "from": "...", "to": "..." },
  "data": {
    "widget_views": 12834,
    "unique_cardholders": 4291,
    "offer_impressions": 38420,
    "offer_add_successes": 5102,
    "redemptions": 612
  }
}