{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/branded-rewards/transaction-ingestion","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Transaction Ingestion","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"transaction-ingestion","__idx":0},"children":["Transaction Ingestion"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Transaction ingestion submits issuer card authorization events and settled transaction events for reward processing."]},{"$$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":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/incoming-auth"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submit card authorization events."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/incoming-txn"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submit settled transaction events."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These endpoints accept either one object or an array of objects. A fully accepted request returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]},". If some events fail and some are accepted, the response is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," with an array of failures. If every submitted event fails, the response is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," with an array of failures."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"required-fields","__idx":1},"children":["Required Fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card authorization event ingestion requires a stable issuer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantDescriptor"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcc"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdAt"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardLast4"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["network"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardholderId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authMethod"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Settled transaction event ingestion requires the same base fields plus settled-transaction-specific fields in the OpenAPI schema, including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arn"]}," where available and related card authorization event data when provided by the issuer processor."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sandbox-matching","__idx":2},"children":["Sandbox Matching"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The transaction ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantId"]}," field represents the merchant identifier from the ISO 8583 transaction message. In production, treat it as merchant data supplied by the issuer or processor."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sandbox does not perform intelligent brand matching for the MVP. In sandbox only, Percents overloads ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantId"]}," as a forced-match input: set it to the Percents ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mp_"]}," merchant partner id you want the transaction event to match. This field is not related to API authentication."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"issuer-auth-0001\",\n  \"amount\": 12500,\n  \"currency\": \"usd\",\n  \"merchantDescriptor\": \"Sandbox Coffee\",\n  \"mcc\": \"5814\",\n  \"createdAt\": \"2026-07-01T18:42:00.000Z\",\n  \"cardLast4\": \"4242\",\n  \"network\": \"visa\",\n  \"cardholderId\": \"issuer-cardholder-1\",\n  \"cardId\": \"issuer-card-1\",\n  \"authMethod\": \"online\",\n  \"state\": \"approved\",\n  \"merchantId\": \"mp_33333333-3333-4333-8333-333333333333\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"processing-semantics","__idx":3},"children":["Processing Semantics"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card authorization events can create preview reward effects and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["qualified_auth"]}," webhook when the event qualifies. Settlements post final effects and can create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["qualified_settlement"]}," webhook. Work with the Percents account manager to validate refund flows."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the transaction reward detail endpoints to reconcile a specific transaction after processing:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v2/chg/{chgId}/transaction/{txnId}/reward-detail"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/chg/{chgId}/transactions/reward-overviews"]}]}]}]},"headings":[{"value":"Transaction Ingestion","id":"transaction-ingestion","depth":1},{"value":"Required Fields","id":"required-fields","depth":2},{"value":"Sandbox Matching","id":"sandbox-matching","depth":2},{"value":"Processing Semantics","id":"processing-semantics","depth":2}],"frontmatter":{"seo":{"title":"Transaction Ingestion"}},"lastModified":"2026-07-21T18:22:26.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/branded-rewards/transaction-ingestion","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}