Skip to content
Last updated

Cashback purchase lookup

A missing response or reward notification can leave your wallet unsure whether a purchase earned cashback. Look up the original purchase ID to check processing, read the current reward and decide whether to wait or investigate an error. Lookup does not register accounts or change rewards.

GET <env-host>/api/v2/transaction/resolve?externalId=issuer-txn-001
GET <env-host>/api/v2/authorization/resolve?externalId=issuer-auth-001

Use settlement lookup or authorization lookup. Percent encode the external ID once.

Processing results

StatusMeaning and next action
pendingAccepted but processing is incomplete. Check again later.
processedProcessing finished. reward contains the qualified reward, or is null if none qualified.
failedInspect error. Retry a temporary failure with the same event ID. Correct invalid input before retrying.

A missing or inaccessible purchase returns 404. Processing failure is distinct from a successfully processed purchase with no qualified reward.

Qualified reward

{
  "externalId": "issuer-txn-001",
  "percentsId": "txn_99999999-9999-4999-8999-999999999999",
  "status": "processed",
  "reward": {
    "merchantId": "mp_55555555-5555-4555-8555-555555555555",
    "offerId": "mpo_66666666-6666-4666-8666-666666666666",
    "currency": "usd",
    "amountMinor": 250,
    "maxEarnAmountMinor": 400,
    "rewardProductType": "cashback",
    "cardholderEarnRate": {
      "kind": "basis_points",
      "basisPoints": 500
    }
  },
  "error": null
}

An authorization result estimates the reward from the authorization amount. The settlement result is the amount actually awarded and can differ. The reward lifecycle explains why settlement takes precedence. Do not add the two rewards together.

Identity lookup

GET <env-host>/api/v2/chg/resolve?externalCardholderId=issuer-cardholder-001

This lookup returns the current cardholder and group ID mappings. Use it after a lost creation response or before calling targeted endpoints. It creates no accounts and returns no lazilyProvisionedAccounts key. The account identity rules explain which mappings to retain.

Delivery and retries

Deduplicate webhooks with webhookId. If notifications arrive out of order or a response was lost, read the current result. Do not create another purchase ID to retry the same event. Follow the intake retry rules to preserve the original event identity.

Read current offer terms from offers. Use the reward's embedded earn rate and cap to describe the calculated reward.