Skip to content
Last updated

Cashback Rewards Quickstart

Cashback rewards give cardholders money back on qualifying card purchases. Follow this walkthrough to authenticate, present an offer, record activation, submit a settled purchase and use its reward notification in your wallet.

Authentication

Percents provisions your issuer API credential and provides it securely. Keep it on your server and include it in every API request:

Authorization: token <tok_id>:<api_secret>
EnvironmentHost
Testinghttps://sandbox.percents.com
Productionhttps://prod.percents.com

Replace <env-host> in this guide with the correct host and use the credential for that environment. See API authentication for setup and access requirements.

Register Accounts When You Need Them

You can register cardholder accounts first, or let Percents create missing accounts when it receives a new external cardholder or card ID. This guide uses lazy provisioning. A cardholder group holds rewards for one cardholder or several who share an account.

Save lazilyProvisionedAccounts when returned. It maps your internal IDs to Percents IDs and contains only accounts created by that request. Use the group mapping to connect webhook data.cardholderGroupId to your customer.

For testing, use the offers and purchase data agreed with Percents. See the sandbox guide.

1. Present an Offer

Read general offers:

GET <env-host>/api/v2/offers

Choose a live offer with rewardProductType: cashback and activationType: CLICK. Show its rate and terms to the cardholder. Use its actual offer ID in step 2.

Request pages with page and pageSize. Continue while hasNextPage is true. Stop if no suitable offer is available. The offer guide explains offers for a specific customer after accounts have been registered.

The purchase in step 3 must be at the selected offer's merchant and meet its dates, activation requirement and terms. Selecting an offer alone does not make a purchase qualify.

2. Record the Cardholder's Click

After the cardholder clicks the offer, send the click to the activity endpoint:

POST <env-host>/api/v2/cardholder/external/issuer-cardholder-001/user-activity
{
  "events": [
    {
      "eventId": "issuer-activity-001",
      "offerId": "mpo_66666666-6666-4666-8666-666666666666",
      "occurredAt": "2026-07-01T18:41:00.000Z",
      "type": "CLICK",
      "clickFlavor": "ACTIVATE"
    }
  ]
}
  • Use the time of the real click. Do not send a click just because an offer was displayed.
  • A new cardholder gets 201 Created and lazilyProvisionedAccounts. Save those ID mappings.
  • An existing cardholder gets 204 No Content. This call does not need or create a card.

This example uses CLICK. VIEW offers accept clicks or qualifying visibility events. PASSIVE offers need no activation. Still report observed views and clicks for engagement measurement.

3. Submit the Settled Purchase

When the purchase settles, send the purchase and card details:

POST <env-host>/api/v2/incoming-txn
{
  "id": "issuer-txn-001",
  "amount": 5000,
  "currency": "usd",
  "merchantDescriptor": "Example Coffee",
  "merchantId": "processor-merchant-001",
  "mcc": "5814",
  "createdAt": "2026-07-01T18:42:00.000Z",
  "authTimestamp": "2026-07-01T18:41:30.000Z",
  "cardholderId": "issuer-cardholder-001",
  "cardId": "issuer-card-001",
  "cardLast4": "4242",
  "cardBIN": "411111",
  "physical": true,
  "billingZip": "10001",
  "network": "visa",
  "authMethod": "contactless",
  "authCode": "123456",
  "arn": "12345678901234567890123",
  "state": "settled",
  "merchantAddressStreet": "123 Main Street",
  "merchantAddressCity": "New York",
  "merchantAddressState": "NY",
  "merchantAddressCountry": "US",
  "merchantAddressZip": "10001",
  "merchantLat": "40.7128",
  "merchantLong": "-74.0060"
}

Replace the sample values with actual event times and purchase details:

  • 5000 means $50.00 USD.
  • Use the same external cardholder ID as step 2.
  • Keep the purchase ID when retrying the same event. Use a new ID for a different purchase.
  • merchantId is the network or processor's ID, not a catalog mp_ ID.
  • Include the original authorization ID as externalAuthId when you sent that authorization.

For shared accounts, follow the group identity rules.

Save any new lazilyProvisionedAccounts mappings. See the settlement reference for required fields and additional purchase details, and refund and dispute reporting for later events.

Send authorizations if real-time notifications and updates are a requirement. Use the resulting estimates for early customer feedback and the settlement result for the actual reward. See the reward lifecycle for details.

4. Listen for Webhooks with Earned Rewards for Qualifying Events

A qualified_settlement webhook reports the cashback actually earned. Use its reward amount, rate and cap for customer messaging. Connect data.cardholderGroupId to your customer through the saved group mapping.

The $50 purchase submitted as issuer-txn-001 earns $2.50 at 500 basis points (5%), below the $4 cap. The settlement notification connects the awarded cashback to that purchase:

Webhook excerpt — selected fields from the full cashback settlement example.

{
  "type": "qualified_settlement",
  "data": {
    "source": { "externalId": "issuer-txn-001" },
    "reward": {
      "rewardProductType": "cashback",
      "currency": "usd",
      "amountMinor": 250,
      "cardholderEarnRate": { "kind": "basis_points", "basisPoints": 500 },
      "maxEarnAmountMinor": 400
    }
  }
}

Show the customer “You earned $2.50 cashback” using the awarded amount. Follow your agreed cashback arrangements for customer crediting.

See webhook setup and delivery for receiving these notifications.

Only qualifying outcomes produce a notification. If a result is missing, look up the purchase using your original purchase ID.

Full Quickstart Script

These pseudocode examples show every applicable request field, including optional fields, in seven languages. They are not a Percents SDK and omit imports, HTTP client setup and a web server.

The examples use an internal group ID to keep the cardholder in the same group across activity and purchases. Omit externalCardholderGroupId if you rely on the default lazy assignment. Include externalAuthId when the original authorization ID is available. Supply optional merchant details, authCode and arn from your purchase data when available. Do not invent missing values.

Implement these helpers in your application:

HelperWhat it does
apiUses your host and issuer credential. Parses JSON, handles empty 204 responses and stops on HTTP errors or 207 batch failures.
findOfferStarts with the URL shown and increments page, keeping pageSize, until it finds a live offer for the selected product and CLICK policy. Stops if there is no match.
accounts.saveCreatedSaves mappings from external IDs to Percents IDs when present. Does nothing when the key is absent.
webhook.listenDelivers events to your handler using the shared webhook setup and delivery rules.
walletDisplays offer terms or the reported earned reward in your own wallet.

Optional field access (such as optional(...) in Python) returns no value when a key is absent. Helper names follow each language's style. Replace sample IDs and times with real events and percent encode external IDs in URLs.

Retry a lost or temporary failed request with its original event ID. Use purchase lookup to check its current result.

// Authentication: configure api on your server with the environment host and securely provided issuer credential.
const PRODUCT = "cashback"

// 1. Present a live CLICK offer. Stop if none is available.
const offer = await api.findOffer("/api/v2/offers?page=1&pageSize=25", PRODUCT, "CLICK")
wallet.showOffer(offer)

// 2. Send this only after the cardholder really clicks the offer.
const activity = await api.post(
  "/api/v2/cardholder/external/issuer-cardholder-001/user-activity",
  { externalCardholderGroupId: "issuer-group-001", events: [{ eventId: "issuer-activity-001", offerId: offer.id,
    type: "CLICK", clickFlavor: "ACTIVATE", occurredAt: "2026-07-01T18:41:00.000Z" }] }
)
accounts.saveCreated(activity?.lazilyProvisionedAccounts)

// 4. Use qualified settlement outcomes to update the customer wallet.
webhook.listen("qualified_settlement", event => {
  if (event.data.reward?.rewardProductType === PRODUCT) {
    wallet.showEarnedReward(event.data.cardholderGroupId, event.data.reward)
  }
})

// 3. Send the actual purchase after settlement. Reuse this ID for retries.
// Include optional fields only when available in your purchase data.
const purchase = {
  "id": "issuer-txn-001", "amount": 5000,
  "currency": "usd", "merchantDescriptor": "Example Coffee",
  "merchantId": "processor-merchant-001", "mcc": "5814",
  "createdAt": "2026-07-01T18:42:00.000Z", "authTimestamp": "2026-07-01T18:41:30.000Z",
  "cardholderId": "issuer-cardholder-001", "cardId": "issuer-card-001",
  "cardLast4": "4242", "cardBIN": "411111",
  "physical": true, "billingZip": "10001",
  "network": "visa", "authMethod": "contactless",
  "externalCardholderGroupId": "issuer-group-001",
  "externalAuthId": "issuer-auth-001",
  "authCode": "123456",
  "arn": "12345678901234567890123",
  "merchantAddressStreet": "123 Main Street",
  "merchantAddressCity": "New York",
  "merchantAddressState": "NY",
  "merchantAddressCountry": "US",
  "merchantAddressZip": "10001",
  "merchantLat": "40.7128",
  "merchantLong": "-74.0060",
  "state": "settled"
}
const result = await api.post("/api/v2/incoming-txn", purchase)
accounts.saveCreated(result?.lazilyProvisionedAccounts)