Skip to content
Last updated

Money, dates and limits

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.

Money and rates

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 kindFieldsExample
basis_pointsInteger basisPoints500 means 5%.
fixed_amountInteger amountMinor and currency250 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.

Purchase limits and dates

FieldMeaning
minSpendAmountMinorMinimum purchase amount that can qualify, when configured.
maxTransactionAmountMinorLargest purchase amount that can qualify. A larger purchase is ineligible.
maxEarnAmountMinorLargest reward amount that can be earned. This caps the reward, not the purchase.
spatialConstraintWhether the offer applies online, offline or online_and_offline.
endAtOffer 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.

Percents identifiers

PrefixPublic 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_ or txn_ IDs.
  • Send processor transaction data in purchase intake merchantId. This differs from the catalog mp_ merchant ID in reward results.

The sandbox has a matching convention for tests only.

External IDs, encoding and paging

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.

Retries and ordering

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.