SuperPay Checkout APIOne call, the right card.

The SuperPay Checkout API recommends the credit card that earns the most rewards on a given purchase. It powers the <script>-tag widget that turns your checkout into an instant "use this card" prompt — and it can be called server-to-server too.

Authentication

Every request needs a merchant API key issued by SuperPay. Send it in either of two headers:

Authorization: Bearer sp_live_xxxxxxxx_…
X-SuperPay-Key: sp_live_xxxxxxxx_…

Keys are sp_live_ + 8 hex characters + _ + 48 hex characters. Treat keys like passwords: never commit them to client-side source control. The drop-in widget script is the one exception — it's designed to ship the key in the page so a browser can call /v1/recommend directly.

Origin allowlist

When SuperPay issues your key we register the exact origins (e.g. https://shop.example.com) you'll mount the widget on. Browser requests from any other origin are rejected with HTTP 403 ORIGIN_NOT_ALLOWED. Server-to-server calls (no Origin header) are not subject to this check — the API key alone authorizes them.

POST /v1/recommend

Returns the best card from our ~320-card catalog for the requested category, plus 1–2 alternates, an estimated reward in cents, and a SuperPay signup_url the shopper can tap to claim it.

Request body

Example — curl

curl -X POST https://superpayrewards.com/v1/recommend \
  -H "Authorization: Bearer sp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 87.45,
    "mcc": "5411",
    "merchant_name": "Whole Foods Market"
  }'

Response

{
  "recommendation_id": "9f8…",
  "anonymous": true,
  "category": "groceries",
  "amount_cents": 8745,
  "top_card": {
    "source": "catalog",
    "id": "amex_blue_cash_preferred",
    "name": "Blue Cash Preferred® Card from American Express",
    "issuer": "American Express",
    "reward_rate": 6,
    "reward_type": "cashback",
    "estimated_reward_cents": 524,
    "estimated_reward_display": "$5.24",
    "reason": "6% on groceries",
    "apply_url": "https://…"
  },
  "alternates": [ { … }, { … } ],
  "signup_url": "https://superpayrewards.com/r/install/checkout_widget?utm_source=merchant&utm_medium=checkout_widget",
  "display": {
    "headline": "Earn ~$5.24 with SuperPay",
    "subline": "Top card: Blue Cash Preferred · 6% back"
  }
}

Drop-in widget

Paste this into your checkout page. Render the <div> wherever you want the recommendation pill to appear and load /v1/widget.js once, anywhere on the page:

<div data-superpay-recommend
     data-amount="87.45"
     data-mcc="5411"
     data-merchant="Whole Foods Market"
     data-theme="light"></div>
<script src="https://superpayrewards.com/v1/widget.js" data-key="sp_live_…" async></script>

The widget is ≤ 360px wide, themes light/dark via data-theme, never breaks the merchant's checkout (it silently no-ops on any error), and is CORS-allowed for browser calls. Pre-bundled SuperPay branding doubles as a sign-up CTA so anonymous shoppers can claim the recommended reward by joining SuperPay.

Errors & rate limits

Rate limits are per API key. Headers X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After are set on every response.

Brand assets

• Brand color (emerald): #00C896
• Brand color (navy): #0A1628
• Logo: /favicon.png
• Recommended widget copy: "Earn the most with SuperPay"

Sandbox vs live keys

SuperPay issues two types of API keys:

Sandbox keys are available immediately on request. Live keys require a brief application review (typically < 1 business day) to ensure origin allowlists and integration quality.

Get an API key

Ready to integrate? Apply for a live API key →

Submit your business name, contact email, store origins, and a brief description of your integration. We'll verify your email and review your application — you'll receive your sp_live_… key via email once approved, typically within 1 business day.

Need to rotate a lost key or update your allowed origins? Email hello@superpayrewards.com.