Purchase data lets Percents determine which rewards a cardholder earns and which branded balance a purchase spends. Use the intake, account creation and retry rules below to submit authorizations and settlements consistently for both products. Each operation accepts one event or a batch of up to 32 using your issuer API credential. No SDK is required.
- Authorizations: send card authorization facts for an earlier provisional result.
- Settlements: send settled purchases with or without a preceding authorization.
| HTTP status | Meaning |
|---|---|
204 | All submitted events accepted. No accounts were created and there is no body. |
201 | All submitted events accepted and accounts were created. lazilyProvisionedAccounts contains account mappings for sources that created accounts, in input order. |
207 | Mixed batch: the failure array identifies failed events. The other events were accepted. |
400 | All submitted events failed. Inspect the failure array. |
Example failure array:
[
{
"id": "issuer-txn-invalid",
"failureReason": "Invalid request"
},
{
"id": "issuer-txn-processing-failed",
"reason": "processing error",
"data": "Unable to process this event"
}
]Validation failures use failureReason. Processing failures use reason: processing error and can include a data message for people to read. Do not parse that message for retry decisions. After an uncertain result, use source lookup and retry with the same event identity to avoid creating another purchase.
Authentication errors and errors affecting the entire request may have the public error shape. Read the status and body. For batches, inspect individual failures even when the HTTP status is 2xx. Acceptance does not confirm reward qualification. Processing and notifications happen later, and some accepted events have no reward notification.
Both intake operations can find existing accounts or create the missing cardholder group, cardholder and card. Every event includes the external cardholder/card IDs and complete card facts, including cardLast4, network, physical and billingZip. The full requirements are on the authorization and settlement pages.
Include externalCardholderGroupId when applicable. See Cardholders & Cardholder Groups for assignment, omission and the configured IDs to use after lazy provisioning.
A creation response contains lazilyProvisionedAccounts only when accounts are created, with mappings for only those new accounts. If the response is lost, identity lookup returns current mappings without creating accounts.
Event identity is issuer plus source kind plus external id. Authorization and settlement namespaces are separate even when their IDs use the same string.
| Previous outcome | Next submission with the same event ID |
|---|---|
| Successfully processed. Identical normalized data | Ignore the retry without creating another purchase or reward. |
| Successfully processed. Changed data | Keep the original processed purchase. Changed data does not replace it. |
| Received but processing failed | Permit an unchanged retry. Receipt alone does not count as successful processing. |
| Still pending | Continue processing the existing source. Avoid parallel duplicate effects. |
There is no event correction input. Preserve the original event ID after a lost response or failed attempt. Use lookup to distinguish receipt, processing failure and successful processing.
- Give each capture a distinct settlement ID. Captures can share
externalAuthId. - Settlement may arrive without or before authorization, and its amount can differ.
- An authorization that arrives or is processed after settlement produces no authorization webhook and does not create another reward.
Use one authoritative purchase submission path. For segmented offers, coordinate with Percents to backfill purchase history. Do not submit historical purchases as new earning events.
The reward lifecycle explains authorization estimates and awarded settlement rewards. Use refunded and disputed to report refunds and disputes for either product. See cashback recovery for fraud and abuse follow-up coordinated directly with the issuer, without routine clawback webhooks.
Branded rewards can earn value restricted to a merchant, spend an available balance and apply supported clawbacks. See the branded lifecycle for details.
Each endpoint's response schema marks fields that apply only to branded rewards.
| Field or result | How to read it |
|---|---|
rewardProductType | Identifies the product of an earned reward. |
cashback in transaction reward detail | Contains the cashback result. |
| Top-level earnings, spending and clawback amounts in transaction reward detail | Describe branded balance effects. |
daysToAvailability, daysToExpiry, balance amounts, spending restrictions and refund issuer debits | Apply to branded rewards. |
Check the schema for the requested product. Not every returned amount represents another reward.