Skip to content
Last updated

Authorizations

Send authorizations if real-time notifications and updates are a requirement, so cardholders can receive feedback before settlement. Use the required fields and request example below to submit the authorization amount, customer identity and merchant details for reward estimates. The authorization reference defines the complete request and responses.

Required fields

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

FieldRequirement
idYour stable internal ID for this authorization.
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-auth' \
  -H 'Authorization: token tok_11111111-1111-4111-8111-111111111111:api_test_secret' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "id": "issuer-auth-001",
  "merchantDescriptor": "Example Merchant",
  "amount": 5000,
  "currency": "usd",
  "mcc": "5814",
  "createdAt": "2026-07-01T18:42:00.000Z",
  "cardLast4": "4242",
  "physical": true,
  "billingZip": "10001",
  "network": "visa",
  "cardholderId": "issuer-cardholder-001",
  "cardId": "issuer-card-001",
  "authMethod": "contactless",
  "state": "approved",
  "merchantId": "processor-merchant-001"
}
JSON

Authorization states are approved, declined and closed. A closed authorization is not a purchase refund. An authorization estimate does not imply settlement.

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.

If this authorization arrives or is processed after its settlement, Percents does not send an authorization webhook. The settlement reward remains the awarded result.