Skip to content
Last updated

Transaction ingestion

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.

Responses and acceptance

HTTP statusMeaning
204All submitted events accepted. No accounts were created and there is no body.
201All submitted events accepted and accounts were created. lazilyProvisionedAccounts contains account mappings for sources that created accounts, in input order.
207Mixed batch: the failure array identifies failed events. The other events were accepted.
400All 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.

Account creation

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.

Idempotency and retries

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 outcomeNext submission with the same event ID
Successfully processed. Identical normalized dataIgnore the retry without creating another purchase or reward.
Successfully processed. Changed dataKeep the original processed purchase. Changed data does not replace it.
Received but processing failedPermit an unchanged retry. Receipt alone does not count as successful processing.
Still pendingContinue 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.

Captures, ordering and history

  • 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.

Product outcomes

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.

Product-specific response fields

Each endpoint's response schema marks fields that apply only to branded rewards.

Field or resultHow to read it
rewardProductTypeIdentifies the product of an earned reward.
cashback in transaction reward detailContains the cashback result.
Top-level earnings, spending and clawback amounts in transaction reward detailDescribe branded balance effects.
daysToAvailability, daysToExpiry, balance amounts, spending restrictions and refund issuer debitsApply to branded rewards.

Check the schema for the requested product. Not every returned amount represents another reward.