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.
The examples follow the settlement-only scenario in the lazy provisioning quickstart:
- Browse before enrollment.
- Record a
CLICK. - Send a $50 purchase.
- 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.
Save the sample CLICK activity as activity.json. Use the returned offer ID and policy.
PASSIVEneeds no activation request. Still report observed views and clicks for engagement measurement.VIEWaccepts a click or paired exposure events. An observed click also satisfiesVIEW, 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_AUTHORIZATIONin the server environment totoken <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
CLICKoffer 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.
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.
| Language | HTTP and JSON dependencies |
|---|---|
| TypeScript | Node.js fetch |
| Python, Go, Ruby and C# | Standard HTTP libraries |
| Java | java.net.http plus Jackson Databind for JSON |
| Rust | reqwest 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 })}`));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.