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.
Submit events to POST /api/v2/incoming-auth.
| Field | Requirement |
|---|---|
id | Your stable internal ID for this authorization. |
merchantDescriptor | Actual processor merchant descriptor. |
mcc | Merchant category code. |
amount | Positive integer in minor units. For example, 5000 is $50.00 USD. |
currency | usd or USD. |
createdAt | Event occurrence timestamp. |
cardholderId | Your internal cardholder ID, required on every event. |
cardId | Your internal card ID, required on every event. |
cardLast4 | Four numeric PAN digits. |
network | Card network. |
physical | Whether the card is physical or virtual, required for full card creation. |
billingZip | Billing postal code, required for full card creation. |
authMethod | Authorization method. |
state | Source 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.
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"
}
JSONAuthorization 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.