API Documentation

The Saldo.tech REST API enables financial institutions to integrate card-linked offers into their banking applications. All endpoints use JSON over HTTPS and authenticate via API key.

Overview

The API is organized around four core resource areas:

Transactions Webhook

POST /api/v1/transactions

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

Reporting — Redemptions

GET /api/v1/reporting/redemptions

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

Reporting — Settlements

GET /api/v1/reporting/settlements

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

Reporting — Funnel

GET /api/v1/reporting/funnel

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

Transaction Webhook

The transaction webhook is the core integration for financial institutions. Post transaction events as they occur, and Saldo.tech's matching engine will determine if a qualifying offer exists.

POST /api/v1/transactions

{
  "cardholder_token": "tok_ch_abc123",
  "card_token": "tok_card_xyz789",
  "merchant_id": "merch_456",
  "amount": 225.00,
  "currency": "USD",
  "timestamp": "2025-03-15T14:30:00Z",
  "transaction_id": "txn_unique_id"
}

Request Fields

cardholder_tokenstringOpaque identifier for the cardholder, generated by your institution using HMAC or similar.

card_tokenstringTokenized PAN for the card used in the transaction. Never send the real card number.

merchant_idstringSaldo.tech merchant identifier. Use the merchant mapping endpoint to resolve MCC/acquirer IDs.

amountnumberTransaction amount in the specified currency.

currencystringISO 4217 currency code (e.g., USD, MXN).

timestampstringISO 8601 timestamp of the transaction.

transaction_idstringYour unique identifier for this transaction, used for idempotency.

Authentication

Saldo uses two authentication modes depending on the endpoint.

API key (Reporting endpoints)

Generate from the Institution Portal under Dashboard → API Keys. Plaintext is shown once at creation; only the SHA-256 hash is stored. Each key is scoped to its institution.

Authorization: Bearer slk_<random>

Generate a key →

HMAC signature (Webhooks)

Transaction webhook posts are signed with a shared secret using HMAC-SHA256. Saldo verifies the signature in the X-Saldo-Signature header against the raw request body.

X-Saldo-Signature: <hex hmac-sha256>

Reporting API

Pull your institution's redemption, settlement, and engagement data programmatically — for finance reconciliation, BI dashboards, or custom internal tools. All endpoints return JSON, are scoped to the institution that owns the API key, and rate-limited to 60 requests per minute per key.

GET/api/v1/reporting/redemptions

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://api.saldo.tech/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..."
  }
}

GET/api/v1/reporting/settlements

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

GET/api/v1/reporting/funnel

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
  }
}

Pagination

List endpoints return a pagination.next_cursor string when more rows are available. Pass it back as the cursor query param to fetch the next page. The cursor is opaque — treat it as an arbitrary string. When next_cursor is null, you have reached the end.

Connecting from a BI tool?

Copy-paste recipes for cURL, Python, Node.js, Google Sheets, Power BI, and Metabase.

See integration recipes →

Errors

401 — missing or invalid Bearer token
403 — token revoked
429 — rate limit exceeded (60 / minute / key)
500 — upstream error; safe to retry with backoff

Privacy and Data Handling

The Saldo.tech API is designed around tokenized identifiers. Your institution generates cardholder_token and card_token values using your own cryptographic keys. Saldo.tech never receives, processes, or stores cardholder PII (names, emails, addresses, or real card numbers). See our Privacy Policy for full details.

Development Environment

Use the simulation endpoint to test transaction matching without real payment data:

POST /api/v1/transactions/simulate

This endpoint accepts the same payload as the production transaction webhook but skips settlement processing. Use it to verify your integration handles match/no-match responses correctly.

Ready to integrate?

Contact our team to get your API credentials and start building.

Contact Sales Learn About Institution Integration