A complete branded test should show both earning merchant value and using it on a later purchase. Follow the requests below to create a test customer, activate an offer, earn a balance and verify a subsequent spend using your configured sandbox fixture.
Your configured sandbox merchant and offer determine the amounts and timing. Before starting:
- Use an enabled sandbox merchant with a branded rewards offer that qualifies for the sample purchase. This walkthrough uses
ONE_TIMEmerchant activation. Confirm the configured offer returns that policy before continuing. - For a quick spend test, ask Percents to confirm immediate availability and spend eligibility for the fixture. Otherwise, wait until the returned availability time and satisfy the merchant's other spend requirements.
- Configure a reachable HTTPS webhook destination and signing token with Percents, and implement the verified webhook receiver.
Sandbox data can be purged daily. Create fresh test fixtures as needed. Save the IDs for retries within a scenario. Do not regenerate source IDs after an uncertain response.
The shell examples use curl and jq. Set the actual sandbox token and merchant ID on your server. Keep credentials out of source control and browsers.
export PERCENTS_AUTHORIZATION='token <tok_id>:<api_secret>'
export PERCENTS_MERCHANT_ID='mp_55555555-5555-4555-8555-555555555555'
export PERCENTS_SCENARIO_ID='branded-demo-001'
curl --fail-with-body 'https://sandbox.percents.com/api/v2/chg' \
-H "Authorization: $PERCENTS_AUTHORIZATION" \
-H 'Content-Type: application/json' \
--data-binary @- > branded-group-response.json <<JSON
{
"externalId": "${PERCENTS_SCENARIO_ID}-group",
"defaultLanguage": "en",
"active": true,
"cardholders": [{
"externalId": "${PERCENTS_SCENARIO_ID}-holder",
"active": true,
"cards": [{
"externalId": "${PERCENTS_SCENARIO_ID}-card",
"last4": "4242",
"bin": "411111",
"network": "visa",
"physical": true,
"billingZip": "10001",
"active": true
}]
}],
"idempotencyKey": "${PERCENTS_SCENARIO_ID}-setup"
}
JSON
export PERCENTS_CHG_ID="$(jq -er '.id' branded-group-response.json)"curl --fail-with-body \
"https://sandbox.percents.com/api/v2/chg/$PERCENTS_CHG_ID/merchant/$PERCENTS_MERCHANT_ID/offers?page=1&pageSize=100" \
-H "Authorization: $PERCENTS_AUTHORIZATION" > branded-offers-response.json
export PERCENTS_OFFER_ID="$(jq -er '[.data[] | select(.rewardProductType == "branded_balance" and .activationType == "ONE_TIME")][0].id' branded-offers-response.json)"
curl --fail-with-body -X PUT \
"https://sandbox.percents.com/api/v2/chg/$PERCENTS_CHG_ID/merchant/$PERCENTS_MERCHANT_ID/activation" \
-H "Authorization: $PERCENTS_AUTHORIZATION" \
-H 'Content-Type: application/json' \
--data-binary @- <<JSON
{
"presentedOfferId": "$PERCENTS_OFFER_ID",
"idempotencyKey": "${PERCENTS_SCENARIO_ID}-activation"
}
JSONThis example selects a ONE_TIME offer, which uses merchant activation. Check that its dates, minimums, spatial restriction and other conditions fit the test purchase. Paginate if the first page has no suitable fixture. Branded VIEW and CLICK offers use user activity. PASSIVE offers need no activation.
You can send this settlement without an authorization first. To force the test purchase to your configured branded merchant, reuse the network/processor merchantId field for its public mp_ fixture ID and send the matching BRANDED V2 descriptor. The sandbox matching instructions explain why this override must not be used in production.
curl --fail-with-body -i 'https://sandbox.percents.com/api/v2/incoming-txn' \
-H "Authorization: $PERCENTS_AUTHORIZATION" \
-H 'Content-Type: application/json' \
--data-binary @- <<JSON
{
"id": "${PERCENTS_SCENARIO_ID}-earn",
"amount": 2500,
"currency": "usd",
"merchantDescriptor": "BRANDED V2 $PERCENTS_MERCHANT_ID",
"merchantId": "$PERCENTS_MERCHANT_ID",
"mcc": "5814",
"createdAt": "2026-07-01T18:42:00.000Z",
"cardLast4": "4242",
"physical": true,
"billingZip": "10001",
"network": "visa",
"cardholderId": "${PERCENTS_SCENARIO_ID}-holder",
"cardId": "${PERCENTS_SCENARIO_ID}-card",
"authMethod": "contactless",
"state": "settled"
}
JSONWhen testing, use a current occurrence time and an enabled offer covering that time.
- When all items are accepted, the request returns
204with no body. Inspect any failure response. Acceptance does not guarantee a reward. - When the fixture qualifies, verify the
qualified_settlementand read merchant-branded value earned fromdata.reward.amountMinor. - Use purchase lookup if a notification is missing. Keep the same purchase ID.
curl --fail-with-body \
"https://sandbox.percents.com/api/v2/chg/$PERCENTS_CHG_ID/merchant/$PERCENTS_MERCHANT_ID/balance" \
-H "Authorization: $PERCENTS_AUTHORIZATION"
curl --fail-with-body \
"https://sandbox.percents.com/api/v2/chg/$PERCENTS_CHG_ID/merchant/$PERCENTS_MERCHANT_ID/spend-eligibility" \
-H "Authorization: $PERCENTS_AUTHORIZATION"Continue only when available balance meets the merchant's minBalanceRequiredForSpend and spending is allowed.
- The default minimum is 100 ($1 USD). Read the merchant's configured value rather than using net balance.
- Do not use earned-but-unavailable value. The greater of the issuer and merchant minimum delays applies.
- Other merchant restrictions can still prevent spending.
curl --fail-with-body -i 'https://sandbox.percents.com/api/v2/incoming-txn' \
-H "Authorization: $PERCENTS_AUTHORIZATION" \
-H 'Content-Type: application/json' \
--data-binary @- <<JSON
{
"id": "${PERCENTS_SCENARIO_ID}-spend",
"amount": 100,
"currency": "usd",
"merchantDescriptor": "BRANDED V2 $PERCENTS_MERCHANT_ID",
"merchantId": "$PERCENTS_MERCHANT_ID",
"mcc": "5814",
"createdAt": "2026-07-02T18:42:00.000Z",
"cardLast4": "4242",
"physical": true,
"billingZip": "10001",
"network": "visa",
"cardholderId": "${PERCENTS_SCENARIO_ID}-holder",
"cardId": "${PERCENTS_SCENARIO_ID}-card",
"authMethod": "contactless",
"state": "settled"
}
JSONUse the actual time of the subsequent purchase.
- The
qualified_settlementnotification reports consumed balance indata.spend.amountMinor. Verify the signature and deduplicate usingwebhookIdbefore applying it once as the customer statement credit. - This purchase need not earn anything. If it also earns merchant-branded value, the same notification includes
data.reward. - Authorization spending is only tentative. Later supported branded reversals are handled separately.
Read the merchant balance again and compare the remaining grants and expiry dates. Retain public transaction IDs from notifications for transaction reward detail.