# Sandbox

Use `https://sandbox.percents.com` for integration testing.

Sandbox data is subject to daily purging. Do not rely on sandbox cardholder groups, activations, balances, transactions, webhook records, or generated ids persisting across days; integration tests should recreate the setup data they need.

Sandbox uses the same API-token header shape as production:

```http
Authorization: token tok_11111111-1111-4111-8111-111111111111:api_test_secret
```

## Transaction Matching

The `merchantId` field on ingested card authorization event and settled transaction event payloads is normal transaction data. It represents the merchant identifier from the ISO 8583 transaction message.

Sandbox does not perform intelligent brand matching for the MVP. In sandbox only, Percents overloads `merchantId` as a forced-match input: pass the Percents `mp_` merchant partner id for the merchant you want the transaction event to match.

This is separate from API authentication. API authentication uses the `Authorization` token header.

Transaction payload fragment:

```json
{
  "merchantId": "mp_33333333-3333-4333-8333-333333333333"
}
```

Use the same sandbox `merchantId` value on the related settled transaction event payload when you want that event to qualify against the same merchant.

## Refunds

Work with the Percents account manager to validate refund flows. Refund and clawback behavior is documented so integrators can build the production processing model and reconcile reversal effects.

## Recommended Sandbox Flow

1. Create or update a cardholder group with one cardholder and one card.
2. List merchants and pick a merchant id returned by the sandbox.
3. Activate that merchant for the cardholder group. Activation is required for both cashback and branded balance offers.
4. Ingest a card authorization event using the selected `mp_` merchant partner id as the sandbox `merchantId` forced-match value.
5. Ingest the matching settled transaction using the same sandbox `merchantId` value.
6. Receive and verify webhooks.
7. Read reward summary, merchant balance, activity, and transaction reward detail.


## Sandbox Data Expectations

Sandbox ids use the same typed prefixes as production. Amounts are always minor units and currently USD-only where the contract requires currency. Timestamps are ISO 8601 strings.