Get promotions for multiple saved cards (bulk)

Returns available promotions for up to 50 saved cards in a single request. Designed for wallet/card-listing pages.

Optimisation Pipeline

1. BIN pre-filter — All active BINs for the currency are loaded in one query. Cards whose masked_card_number[:6] is not in any active promotion skip the TapPay call entirely.

2. Parallel TapPay resolution — Matching cards are resolved in parallel (≤10 concurrent workers; 5 s per-card timeout; 30 s overall timeout).

3. Batch DB queries — All promotions for matched BINs are fetched in one query and grouped in memory. Usage counts use a single annotate(Count) query.

4. Per-card limit filtering — Promotions where current usage_count ≥ per_card_limit (within the active reset window) are excluded.

Partial Results

The endpoint always returns HTTP 200. Per-card failures appear in results[].error and are aggregated in the top-level errors array. Successful cards are unaffected.

Deduplication

Duplicate card_token values in the input are silently removed (order preserved).

Per-Card Error Values

Error	Cause
"Invalid token format"	Token does not contain ||
"Card not found"	TapPay returned no card for this token
"Card lookup timeout"	Per-card 5 s timeout exceeded
"Request timeout exceeded"	Overall 30 s timeout exceeded
"Card lookup failed"	Unexpected TapPay error
"Rate limit exceeded, retry later"	TapPay returned HTTP 429

post

Body

currencystring · enumOptional

ISO 4217 currency codes supported by Bankaci

Example: aedPossible values:

Responses

200

Promotion results for each card

application/json

422

Request-level validation error

application/json

post/promotions/saved-cards/

POST /api/v1/promotions/saved-cards/ HTTP/1.1
Host: your-bankaci-instance.example.com
Content-Type: application/json
Accept: */*
Content-Length: 196

{
  "cards": [
    {
      "card_token": "card_E6VV262511||cus_TS03A272",
      "masked_card_number": "512345******0008"
    },
    {
      "card_token": "card_ABC123||cus_XYZ789",
      "masked_card_number": "411111******5678"
    }
  ],
  "currency": "aed"
}

{
  "results": [
    {
      "card_token": "card_E6VV262511||cus_TS03A272",
      "bin_6": "512345",
      "promotions": [
        {
          "title": "Summer Sale 10%",
          "basket_offer_ids": [
            "123",
            "456"
          ],
          "priority": 10,
          "per_card_limit": 3,
          "end_date": "2025-12-31T23:59:59Z",
          "usable_with_voucher_code": false
        }
      ],
      "error": null
    },
    {
      "card_token": "card_ABC123||cus_XYZ789",
      "bin_6": null,
      "promotions": [],
      "error": "Card not found"
    }
  ],
  "errors": [
    {
      "card_token": "card_ABC123||cus_XYZ789",
      "error": "Card not found"
    }
  ],
  "meta": {
    "total": 2,
    "success_count": 1,
    "error_count": 1
  }
}