{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/transaction-ingestion/authorizations","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Authorizations"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authorizations","__idx":0},"children":["Authorizations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/recordIncomingAuth"},"children":["authorization reference"]}," defines the complete request and responses."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"required-fields","__idx":1},"children":["Required fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Submit events to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/recordIncomingAuth"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/incoming-auth"]}]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Requirement"},"children":["Requirement"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your stable internal ID for this authorization."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantDescriptor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Actual processor merchant descriptor."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcc"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Merchant category code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Positive integer in minor units. For example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5000"]}," is $50.00 USD."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["usd"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Event occurrence timestamp."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardholderId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your internal cardholder ID, required on every event."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your internal card ID, required on every event."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardLast4"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Four numeric PAN digits."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["network"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Card network."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["physical"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether the card is physical or virtual, required for full card creation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["billingZip"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Billing postal code, required for full card creation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authMethod"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authorization method."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Source event state."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the required card details even when the card already exists, and include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCardholderGroupId"]}," when applicable. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/cardholder-groups#lazy-provisioning"},"children":["Cardholders & Cardholder Groups"]}," for account assignment, lazy provisioning and the IDs to use."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-request","__idx":2},"children":["Complete request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --fail-with-body 'https://sandbox.percents.com/api/v2/incoming-auth' \\\n  -H 'Authorization: token tok_11111111-1111-4111-8111-111111111111:api_test_secret' \\\n  -H 'Content-Type: application/json' \\\n  --data-binary @- <<'JSON'\n{\n  \"id\": \"issuer-auth-001\",\n  \"merchantDescriptor\": \"Example Merchant\",\n  \"amount\": 5000,\n  \"currency\": \"usd\",\n  \"mcc\": \"5814\",\n  \"createdAt\": \"2026-07-01T18:42:00.000Z\",\n  \"cardLast4\": \"4242\",\n  \"physical\": true,\n  \"billingZip\": \"10001\",\n  \"network\": \"visa\",\n  \"cardholderId\": \"issuer-cardholder-001\",\n  \"cardId\": \"issuer-card-001\",\n  \"authMethod\": \"contactless\",\n  \"state\": \"approved\",\n  \"merchantId\": \"processor-merchant-001\"\n}\nJSON\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authorization states are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["approved"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["declined"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["closed"]},". A closed authorization is not a purchase refund. An authorization estimate does not imply settlement."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantId"]}," is optional processor data, distinct from public catalog ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mp_"]}," merchant IDs. The reference defines other optional fields for merchant addresses, locations, BINs and authorization codes. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/overview/sandbox#merchant-ids-on-purchase-events"},"children":["sandbox convention"]}," supports forced merchant matching for tests."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/transaction-ingestion/overview"},"children":["intake guide"]}," explains response codes, batching and safe retries. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/reward-lifecycle"},"children":["reward lifecycle"]}," explains when a qualified purchase produces a notification."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If this authorization arrives or is processed after its settlement, Percents does not send an authorization webhook. The settlement reward remains the awarded result."]}]},"headings":[{"value":"Authorizations","id":"authorizations","depth":1},{"value":"Required fields","id":"required-fields","depth":2},{"value":"Complete request","id":"complete-request","depth":2}],"frontmatter":{"title":"Authorizations","description":"Complete purchase input fields, account creation and endpoint examples.","seo":{"title":"Authorizations"}},"lastModified":"2026-11-10T20:25:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/transaction-ingestion/authorizations","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}