Skip to content
Last updated

HTTP code examples

Use these HTTP examples to connect a cashback purchase flow with the server language you already use. They cover offer discovery, click activity, settled purchase submission and result lookup with one issuer API credential and no Percents SDK.

Example Flow

The examples follow the settlement-only scenario in the lazy provisioning quickstart:

  1. Browse before enrollment.
  2. Record a CLICK.
  3. Send a $50 purchase.
  4. Look up the result by your own ID.

A webhook receiver is a separate HTTPS endpoint: configure it with Percents and use the signature, envelope and update examples. Do not wait for a webhook as the only proof that intake succeeded.

Example payloads

Save the sample CLICK activity as activity.json. Use the returned offer ID and policy.

  • PASSIVE needs no activation request. Still report observed views and clicks for engagement measurement.
  • VIEW accepts a click or paired exposure events. An observed click also satisfies VIEW, even when visibility lasts less than 1.3 seconds.
{
  "events": [
    {
      "eventId": "issuer-activity-001",
      "offerId": "mpo_66666666-6666-4666-8666-666666666666",
      "type": "CLICK",
      "occurredAt": "2026-07-01T18:41:00.000Z",
      "clickFlavor": "ACTIVATE"
    }
  ]
}

Save this as settlement.json:

{
  "id": "issuer-txn-001",
  "amount": 5000,
  "currency": "usd",
  "merchantDescriptor": "Example Merchant",
  "merchantId": "processor-merchant-001",
  "mcc": "5814",
  "createdAt": "2026-07-01T18:42:00.000Z",
  "cardLast4": "4242",
  "physical": true,
  "billingZip": "10001",
  "network": "visa",
  "cardholderId": "issuer-cardholder-001",
  "cardId": "issuer-card-001",
  "authMethod": "contactless",
  "state": "settled"
}

merchantId is processor data, distinct from the public mp_ merchant. Sandbox matching uses a test-only convention. Use actual processor facts and issuer IDs in your enabled environment. Do not invent missing billing/card facts. billingZip and physical are required card facts for complete account creation.

Before running the examples:

  • Set PERCENTS_AUTHORIZATION in the server environment to token <tok_id>:<api_secret>. Never put it in a browser bundle.
  • Keep the two saved JSON files in the current directory. The programs read them from there.
  • Use a real, available CLICK offer before testing. The sample offer and customer IDs are test fixtures. The initial catalog page does not automatically select an offer. Paginate to inspect the complete catalog.

Full HTTP examples

Each helper rejects HTTP errors and intake partial-batch failure arrays. A 204 has no body. The programs print the current purchase result. After a transient failure or lost response, retry with the original ID. Do not generate another purchase ID. Use identity lookup if you need account mappings after a lost creation response.

LanguageHTTP and JSON dependencies
TypeScriptNode.js fetch
Python, Go, Ruby and C#Standard HTTP libraries
Javajava.net.http plus Jackson Databind for JSON
Rustreqwest with blocking/JSON support and serde_json

Install dependencies for your chosen language in your own project.

import { readFile } from 'node:fs/promises';

const authorization = process.env.PERCENTS_AUTHORIZATION;
if (!authorization) throw new Error('Set PERCENTS_AUTHORIZATION');

async function request(method: string, path: string, payload?: unknown): Promise<any> {
  const response = await fetch(`https://sandbox.percents.com${path}`, {
    method,
    headers: { Authorization: authorization!, 'Content-Type': 'application/json' },
    body: payload === undefined ? undefined : JSON.stringify(payload),
  });
  const raw = await response.text();
  if (!response.ok) throw new Error(`${response.status}: ${raw}`);
  const body = raw ? JSON.parse(raw) : undefined;
  if (path.startsWith('/api/v2/incoming-') && response.status === 207) {
    throw new Error(`Inspect intake failures: ${raw}`);
  }
  return body;
}

const activity = JSON.parse(await readFile('activity.json', 'utf8'));
const settlement = JSON.parse(await readFile('settlement.json', 'utf8'));
console.log(await request('GET', '/api/v2/offers?page=1&pageSize=25'));
console.log(await request('POST',
  `/api/v2/cardholder/external/${encodeURIComponent(settlement.cardholderId)}/user-activity`,
  activity));
await request('POST', '/api/v2/incoming-txn', settlement);
console.log(await request('GET',
  `/api/v2/transaction/resolve?${new URLSearchParams({ externalId: settlement.id })}`));

Near-real-time auth and branded rewards

To add an authorization preview, use the complete authorization payload at POST /api/v2/incoming-auth, then associate a later settlement with externalAuthId and authTimestamp. Keep the same event identity rules and inspect the same intake statuses. The estimate uses the submitted authorization amount. The settlement amount can differ.

The branded earn/spend example uses explicit customer setup and branded merchant activation. Its later merchant purchase consumes an available branded balance. Do not add that spending step or its expiry/availability requirements to cashback.