Skip to content
Last updated

Settlements

Settlement data determines the actual reward awarded and branded value spent on a purchase. Use the required fields and request example below to submit purchases, then report refunds and disputes when they occur. The settlement reference defines the complete request and responses.

Required fields

Submit events to POST /api/v2/incoming-txn.

FieldRequirement
idYour stable internal ID for this settlement.
merchantDescriptorActual processor merchant descriptor.
mccMerchant category code.
amountPositive integer in minor units. For example, 5000 is $50.00 USD.
currencyusd or USD.
createdAtEvent occurrence timestamp.
cardholderIdYour internal cardholder ID, required on every event.
cardIdYour internal card ID, required on every event.
cardLast4Four numeric PAN digits.
networkCard network.
physicalWhether the card is physical or virtual, required for full card creation.
billingZipBilling postal code, required for full card creation.
authMethodAuthorization method.
stateSource event state.

Send the required card details even when the card already exists, and include externalCardholderGroupId when applicable. See Cardholders & Cardholder Groups for account assignment, lazy provisioning and the IDs to use.

Complete request

curl --fail-with-body 'https://sandbox.percents.com/api/v2/incoming-txn' \
  -H 'Authorization: token tok_11111111-1111-4111-8111-111111111111:api_test_secret' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "id": "issuer-txn-001",
  "amount": 5000,
  "currency": "usd",
  "merchantDescriptor": "Example Coffee",
  "merchantId": "processor-merchant-001",
  "mcc": "5814",
  "createdAt": "2026-07-01T18:42:00.000Z",
  "authTimestamp": "2026-07-01T18:41:30.000Z",
  "cardholderId": "issuer-cardholder-001",
  "cardId": "issuer-card-001",
  "cardLast4": "4242",
  "cardBIN": "411111",
  "physical": true,
  "billingZip": "10001",
  "network": "visa",
  "authMethod": "contactless",
  "authCode": "123456",
  "arn": "12345678901234567890123",
  "state": "settled",
  "merchantAddressStreet": "123 Main Street",
  "merchantAddressCity": "New York",
  "merchantAddressState": "NY",
  "merchantAddressCountry": "US",
  "merchantAddressZip": "10001",
  "merchantLat": "40.7128",
  "merchantLong": "-74.0060"
}
JSON

Use settled for cashback purchases. Use refunded and disputed to report refunds and disputes for either product. Cashback uses this data for fraud detection.

  • Use a distinct settlement ID for each capture.
  • If you sent the related authorization, supply its ID as externalAuthId.
  • Supply authTimestamp when you know the authorization time, even if you did not send an authorization event.
  • Supply arn when the acquirer reference number is available.

For branded spending, authorization time determines whether the purchase falls within the balance's availability and expiry window. Settlement can arrive after expiry. Percents uses the first available time:

  1. The linked authorization time.
  2. authTimestamp, when no linked time is available.
  3. createdAt, when both authorization times are missing.

See the branded spend window for details.

merchantId is optional processor data, distinct from public catalog mp_ merchant IDs. The reference defines other optional fields for merchant addresses, locations, BINs and authorization codes. The sandbox convention supports forced merchant matching for tests.

The intake guide explains response codes, batching and safe retries. The reward lifecycle explains when a qualified purchase produces a notification.

Report refunds and disputes

Send a refund or dispute to the same endpoint with state: refunded or state: disputed. Give each event its own stable id and send a positive amount in minor units. Keep that ID and the same data when retrying.

When available, set externalAuthId to the original authorization's external ID. This field identifies an authorization. It is not a settlement ID. Include the cardholder, card and merchant details required for purchase events.

For cashback, Percents uses these reports to detect fraud and abuse. They do not trigger routine cashback clawback webhooks, but the absence of those webhooks does not prevent recovery of cashback paid in cases of fraud or abuse. Recovery may include an issuer invoice adjustment and is coordinated directly with the issuer.

For branded rewards, see clawbacks for balance deductions and issuer debits. Reporting a dispute does not automatically reverse a reward.