Skip to content
Last updated

Branded rewards webhooks

Branded reward notifications let your wallet explain earned merchant value, spending and clawbacks. Use the payloads below to distinguish authorization estimates from settled amounts and identify when to update balances or apply a customer statement credit. Every event follows the standard webhook schema.

Qualified Outcomes

Authorization and settlement notifications can contain reward, spend or both. Each field is omitted when it does not apply, and no notification is sent when neither applies. A purchase before required earning activation produces no earn notification. Branded spending can still qualify without new earnings.

Earning After Branded Spending

When a purchase both spends branded balance and earns new rewards, the earning calculation subtracts the branded spending from the purchase amount. Available balance that is not applied to the purchase is not deducted.

WebhookAmount used to calculate new earningsHow to use the result
qualified_authAuthorization amount minus tentative data.spend.amountMinor, when present.Use data.reward.amountMinor as an estimate. No balance is consumed and no spend credit should be applied yet.
qualified_settlementSettlement amount minus data.spend.amountMinor actually consumed, when present.Use data.reward.amountMinor as the awarded reward and the separate spending amount for the customer statement credit.

A $105 purchase with $5 applied at 10% (1000 basis points) earns $10 on the remaining $100, assuming the offer qualifies and no cap reduces the reward. See the calculation example and its matching settlement webhook. Use the settlement result if the purchase amount or branded spending differs from the authorization estimate.

Authorization estimate

A qualified_auth can include an estimated reward and tentative spending. It uses the submitted authorization amount and purchase time. No balance is consumed at authorization, and the issuer must wait for settlement before applying a spend credit. An authorization arriving or processed after settlement produces no auth webhook.

{
  "webhookId": "evt_cccccccc-cccc-4ccc-8ccc-cccccccccccc",
  "type": "qualified_auth",
  "data": {
    "source": {
      "externalId": "issuer-auth-001",
      "percentsId": "auth_77777777-7777-4777-8777-777777777777"
    },
    "cardholderGroupId": "chg_22222222-2222-4222-8222-222222222222",
    "spend": {
      "merchantId": "mp_55555555-5555-4555-8555-555555555555",
      "currency": "usd",
      "amountMinor": 100
    }
  }
}

This purchase has a tentative $1 spend and no new earn. When reward is present, it includes the applied cardholderEarnRate and maxEarnAmountMinor for customer messaging.

Settlement outcome

A qualified_settlement reports the actual earned reward and any branded balance actually consumed. Apply data.spend.amountMinor once as the customer statement credit. If spend is absent, there is no spend credit to apply. A purchase before required earning activation can still spend eligible existing value. Its notification omits reward.

{
  "webhookId": "evt_eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee",
  "type": "qualified_settlement",
  "data": {
    "source": {
      "externalId": "issuer-txn-001",
      "percentsId": "txn_99999999-9999-4999-8999-999999999999"
    },
    "cardholderGroupId": "chg_22222222-2222-4222-8222-222222222222",
    "reward": {
      "merchantId": "mp_55555555-5555-4555-8555-555555555555",
      "offerId": "mpo_66666666-6666-4666-8666-666666666666",
      "currency": "usd",
      "amountMinor": 245,
      "maxEarnAmountMinor": 400,
      "rewardProductType": "branded_balance",
      "cardholderEarnRate": {
        "kind": "basis_points",
        "basisPoints": 500
      }
    },
    "spend": {
      "merchantId": "mp_55555555-5555-4555-8555-555555555555",
      "currency": "usd",
      "amountMinor": 100
    }
  }
}

This $50 purchase spends $1 of existing value and earns $2.45 on the remaining $49 at 5%, below the $4 cap. Settlement can differ from the authorization estimate. Do not add estimates to actual amounts or apply a second credit from an authorization webhook. Omit reward entirely for a settlement that only spends balance. No offer ID, earn rate or cap is needed for spending alone.

Spending consumes eligible branded grants in order of expiry, using the grant that expires soonest first. A valid authorization time within the spend window is honored even when settlement arrives after expiry. See the branded lifecycle for more details.

lazilyProvisionedAccounts appears only when this purchase created accounts and contains only the new mappings to store. Earn details can include segmentSource to distinguish purchase history, a policy-based fallback and an unsegmented offer. See Offer Segments and Purchase History.

Supported branded reversal

earnedAmountReversedMinor is the value clawed back from the cardholder's branded balance. shortfallAmountMinor is the debit against the issuer because previously spent value could not be clawed back. Expiry does not create this shortfall.

{
  "webhookId": "evt_aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "type": "clawback",
  "data": {
    "source": {
      "externalId": "issuer-refund-001",
      "percentsId": "txn_99999999-9999-4999-8999-999999999999"
    },
    "cardholderGroupId": "chg_22222222-2222-4222-8222-222222222222",
    "merchantId": "mp_55555555-5555-4555-8555-555555555555",
    "currency": "usd",
    "earnedAmountReversedMinor": 50,
    "shortfallAmountMinor": 200
  }
}

In this $2.50 clawback:

AmountOutcome
$0.50 remaining balanceRemoved from the branded balance.
$2 already spentReported as an issuer debit.

The debit may be applied against the issuer's next payment or a later reward earned by the cardholder at this merchant.

  • The issuer chooses how to handle its cost: a statement debit, absorbing it or another approach. We recommend a $2 statement debit but do not require it.
  • If the missing $2 had expired instead, it would not create this issuer debit.
  • Use webhookId to prevent duplicate account actions.

Verify signatures and delivery IDs before applying any account action. Use current balances and purchase lookup when a notification is missing or arrives out of order.