Skip to content
Last updated

Sandbox Earn and Spend

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.

Before You Start

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_TIME merchant 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.

1. Configure and explicitly set up a customer

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)"

2. Select a branded offer and activate its merchant

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"
}
JSON

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

3. Send the earn settlement

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"
}
JSON

When testing, use a current occurrence time and an enabled offer covering that time.

  • When all items are accepted, the request returns 204 with no body. Inspect any failure response. Acceptance does not guarantee a reward.
  • When the fixture qualifies, verify the qualified_settlement and read merchant-branded value earned from data.reward.amountMinor.
  • Use purchase lookup if a notification is missing. Keep the same purchase ID.

4. Check availability and spend eligibility

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.

5. Send a subsequent merchant purchase

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"
}
JSON

Use the actual time of the subsequent purchase.

  • The qualified_settlement notification reports consumed balance in data.spend.amountMinor. Verify the signature and deduplicate using webhookId before 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.