Consistent amounts, dates and identifiers help your wallet display rewards correctly and connect them to the right purchase. Use the currency units, reward-rate formats, limits and ID rules below when building requests and formatting results for either product.
Send money as an integer in the currency's smallest unit. For USD, 1250 means $12.50. This applies to purchase amounts, fixed rewards, balances and limits. Do not send decimal strings or fractions.
Percentage rates use basis points: 500 means 5%, and 125 means 1.25%. Send whole numbers, not percentage strings or fractional basis points.
Each reward rate has one of two forms:
| Rate kind | Fields | Example |
|---|---|---|
basis_points | Integer basisPoints | 500 means 5%. |
fixed_amount | Integer amountMinor and currency | 250 with usd means a fixed $2.50 reward. |
A fixed $2.50 USD reward is:
{
"kind": "fixed_amount",
"amountMinor": 250,
"currency": "usd"
}Read kind before displaying a rate. Use the returned calculated reward amount for customer messaging.
Responses use usd. Purchase intake accepts usd or USD. Always send the currency explicitly.
| Field | Meaning |
|---|---|
minSpendAmountMinor | Minimum purchase amount that can qualify, when configured. |
maxTransactionAmountMinor | Largest purchase amount that can qualify. A larger purchase is ineligible. |
maxEarnAmountMinor | Largest reward amount that can be earned. This caps the reward, not the purchase. |
spatialConstraint | Whether the offer applies online, offline or online_and_offline. |
endAt | Offer end time. null means no configured end. |
For a 5% offer with a purchase limit of 10000 and reward cap of 400:
- A $100.00 purchase can qualify and earn $4.00 after the cap.
- A $100.01 purchase cannot qualify. Percents does not reduce it to $100.00 for calculation.
Where a field allows null, it means no value has been configured. Offer start and end times determine when purchases can qualify. An earned branded balance has its own availability and expiry times. The API reference marks fields that apply only to branded rewards.
Send timestamps in ISO 8601 format with a timezone. Activity occurredAt specifically requires UTC ending in Z, as explained below.
Cashback percentage calculations round half up to four, then three, then two decimal places before returning integer minor units. Use the returned reward amount in your wallet instead of recalculating it.
| Prefix | Public resource |
|---|---|
chg_ | Cardholder group. |
ch_ | Cardholder. |
card_ | Card. |
mp_ | Merchant profile. |
mpo_ | Offer. |
auth_ | Accepted authorization record. |
txn_ | Accepted settlement record. |
brevt_ | Reward event where returned. |
rg_ | Branded reward grant. |
evt_ | Webhook event. |
iss_ | Issuer identifier used by SDK session setup. |
tok_ / api_ | Token or resource for managing credentials. |
err_ | Public error instance. |
Treat IDs as opaque strings:
- Report activity with the returned
mpo_offer ID. - Look up purchases with their external authorization or settlement IDs, or their Percents
auth_ortxn_IDs. - Send processor transaction data in purchase intake
merchantId. This differs from the catalogmp_merchant ID in reward results.
The sandbox has a matching convention for tests only.
Your internal cardholder, card, group, authorization and settlement IDs are the API’s external identifiers. Field names such as externalId reflect that they originate outside Percents. V2 intake cardholderId and cardId are external values. The similarly named fields in V2 resource paths are Percents IDs. Activity has distinct Percents-ID and external-ID routes. Your credential determines issuer scope.
When building a URL:
- Percent encode each path component and query value once.
- Do not concatenate an external value containing
/,?,+,&or#directly into the URL. - For query lookups, use your HTTP library's encoder or curl
--get --data-urlencode.
When the external group ID is omitted:
- A new group for one cardholder uses that cardholder's external ID.
- An existing cardholder keeps its assigned group.
- Store the returned external mapping and its separate public
chg_ID.
Activity occurredAt must be an ISO 8601 UTC timestamp ending in Z, such as 2026-07-01T18:39:01.300Z. This activity requirement does not change the timestamp formats accepted by V2 authorization and settlement intake.
Catalog paging starts at page 1 and allows pageSize up to 100. The defaults are 1 and 25, respectively. Continue while hasNextPage is true. The catalog can change between page requests.
Authorization and settlement event identity is issuer plus source kind plus external id. Each capture uses a distinct settlement ID. An identical retry of a successfully processed event is ignored. A changed submission under that ID does not replace the original event. Failed processing remains retryable. See intake idempotency.