Integration Guide

A complete reference for integrating POST /v1/agent/recommend into your AI agent, chatbot, or automated shopping assistant.

Overview

The SuperPay Agent Commerce API gives AI agents access to the same card-reward ranking engine that powers the SuperPay consumer wallet. One endpoint:

• /v1/agent/recommend — Pass a transaction amount, optional MCC or category, and the user's card portfolio. Returns a ranked list of the best cards to use, with reward rate, estimated reward in cents, and a human-readable reason string your agent can speak aloud.

Quick Start

Copy-paste this cURL to fire your first request using the sandbox key from /for-agents:

curl -X POST https://superpayrewards.com/v1/agent/recommend \
  -H "Authorization: Bearer sp_agent_xxxxxxxx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 87.45,
    "mcc": "5411",
    "merchant_name": "Whole Foods",
    "cards": [
      {
        "id": "amex_blue_cash_preferred",
        "issuer": "American Express",
        "reward_type": "cashback",
        "base_rate": 1,
        "category_bonuses": [{ "category": "groceries", "rate": 6 }]
      },
      {
        "id": "citi_double_cash",
        "issuer": "Citi",
        "reward_type": "cashback",
        "base_rate": 2
      }
    ]
  }'

Expected response: the Amex Blue Cash Preferred ranks #1 at 6% for groceries, with an estimated reward of ~$5.24 on an $87.45 purchase.

Authentication

All Agent API requests require an sp_agent_… key. Send it in one of two ways:

Authorization: Bearer sp_agent_xxxxxxxx_…

X-SuperPay-Key: sp_agent_xxxxxxxx_…

Both headers are accepted; Authorization: Bearer is preferred for server-to-server calls. Keys are sp_agent_ + 8 hex characters + _ + 48 hex characters.

Request Reference

Endpoint: POST https://superpayrewards.com/v1/agent/recommend

Content-Type: application/json

Top-level fields

Card Portfolio Schema

Each object in cards[] represents one card in the user's wallet:

Example card objects

// Cashback card with category bonuses
{
  "id": "amex_blue_cash_preferred",
  "issuer": "American Express",
  "reward_type": "cashback",
  "base_rate": 1,
  "category_bonuses": [
    { "category": "groceries", "rate": 6 },
    { "category": "streaming",  "rate": 6 },
    { "category": "gas",        "rate": 3 }
  ]
}

// Flat-rate cashback card (no category bonuses)
{
  "id": "citi_double_cash",
  "issuer": "Citi",
  "reward_type": "cashback",
  "base_rate": 2
}

// Points card with travel/dining bonuses
{
  "id": "chase_sapphire_preferred",
  "issuer": "Chase",
  "reward_type": "points",
  "base_rate": 1,
  "category_bonuses": [
    { "category": "dining", "rate": 3 },
    { "category": "travel", "rate": 3 }
  ]
}

MCC → Category Reference

When mcc is absent or unmapped, pass one of these values in the category field. Common MCC codes are listed for reference:

Response Reference

{
  "recommendation_id": "9f8b2c1a4d7e…",
  "category": "groceries",
  "amount_cents": 8745,
  "top_cards": [
    {
      "rank": 1,
      "id": "amex_blue_cash_preferred",
      "issuer": "American Express",
      "reward_type": "cashback",
      "reward_rate": 6,
      "reason": "6% on groceries",
      "estimated_reward_cents": 524,
      "estimated_reward_display": "$5.24"
    },
    {
      "rank": 2,
      "id": "citi_double_cash",
      "issuer": "Citi",
      "reward_type": "cashback",
      "reward_rate": 2,
      "reason": "2% on everything",
      "estimated_reward_cents": 174,
      "estimated_reward_display": "$1.74"
    }
  ],
  "top_card": { … }
}

Rate Limits

Rate-limit headers are included on every response:

Implement exponential backoff when you receive a 429 RATE_LIMITED response. The window resets every 60 seconds.

Error Codes

{
  "code": "INVALID_CARD_DATA",
  "message": "One or more cards failed validation.",
  "card_errors": [
    { "index": 0, "id": "my_card_id", "issues": ["reward_type must be cashback, points, or miles"] }
  ]
}

Sandbox vs. Production

SDK Snippets

cURL

curl -X POST https://superpayrewards.com/v1/agent/recommend \
  -H "Authorization: Bearer $SUPERPAY_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 87.45,
    "mcc": "5411",
    "merchant_name": "Whole Foods",
    "cards": [
      {
        "id": "amex_bcp",
        "issuer": "American Express",
        "reward_type": "cashback",
        "base_rate": 1,
        "category_bonuses": [{ "category": "groceries", "rate": 6 }]
      },
      { "id": "citi_dc", "issuer": "Citi", "reward_type": "cashback", "base_rate": 2 }
    ]
  }'

Node.js (fetch)

async function getBestCard({ amount, mcc, merchantName, cards }) {
  const res = await fetch('https://superpayrewards.com/v1/agent/recommend', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SUPERPAY_AGENT_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ amount, mcc, merchant_name: merchantName, cards }),
  });

  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(`SuperPay ${res.status}: ${err.code || 'UNKNOWN'} — ${err.message || ''}`);
  }

  const { top_cards, category, recommendation_id } = await res.json();
  return {
    bestCard: top_cards[0],
    category,
    recommendationId: recommendation_id,
    // top_cards[0].reason → "6% on groceries"   (ready for agent response)
    // top_cards[0].estimated_reward_display → "$5.24"
  };
}

Python (requests)

import os, requests

def get_best_card(amount, cards, mcc=None, merchant_name=None, category=None):
    payload = {"amount": amount, "cards": cards}
    if mcc:           payload["mcc"] = mcc
    if merchant_name: payload["merchant_name"] = merchant_name
    if category:      payload["category"] = category

    resp = requests.post(
        "https://superpayrewards.com/v1/agent/recommend",
        headers={
            "Authorization": f"Bearer {os.environ['SUPERPAY_AGENT_KEY']}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=10,
    )
    resp.raise_for_status()
    data = resp.json()
    best = data["top_cards"][0]
    return best  # best["reason"] → "6% on groceries"

OpenAI function / tool definition

{
  "type": "function",
  "function": {
    "name": "get_best_payment_card",
    "description": "Returns the optimal credit card to use for a purchase based on reward rates. Always call this before the user pays.",
    "parameters": {
      "type": "object",
      "properties": {
        "amount": { "type": "number", "description": "Purchase amount in USD" },
        "merchant_name": { "type": "string", "description": "Merchant or store name" },
        "mcc": { "type": "string", "description": "ISO 18245 MCC code if available" }
      },
      "required": ["amount"]
    }
  }
}

In your tool handler, pass the user's card portfolio from your agent's memory alongside the LLM-extracted fields, then inject top_cards[0].reason back into the assistant message.

Key Rotation

Rotate a lost or compromised production key via the API — no email required:

POST https://superpayrewards.com/api/agent-partner/rotate-key
Authorization: Bearer sp_agent_xxxxxxxx_...
Content-Type: application/json

{}   # empty body

The response contains your new plaintext key — store it immediately. The old key is revoked atomically.

{
  "message": "Key rotated successfully.",
  "new_key": "sp_agent_newprefix_…",
  "new_key_prefix": "sp_agent_newprefix"
}

To view your current partner profile (name, email, tier, key prefix): GET /api/agent-partner/me with the same bearer token.

Questions? Email hello@superpayrewards.com or visit /for-agents. Include your recommendation_id for faster support.