{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/transaction-ingestion/overview","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Transaction ingestion"},"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":["Purchase data lets Percents determine which rewards a cardholder earns and which branded balance a purchase spends. Use the intake, account creation and retry rules below to submit authorizations and settlements consistently for both products. Each operation accepts one event or a batch of up to 32 using your issuer API credential. No SDK is required."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/transaction-ingestion/authorizations"},"children":["Authorizations"]},": send card authorization facts for an earlier provisional result."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/transaction-ingestion/settlements"},"children":["Settlements"]},": send settled purchases with or without a preceding authorization."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"responses-and-acceptance","__idx":1},"children":["Responses and acceptance"]},{"$$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":"HTTP status"},"children":["HTTP status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All submitted events accepted. No accounts were created and there is no body."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All submitted events accepted and accounts were created. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lazilyProvisionedAccounts"]}," contains account mappings for sources that created accounts, in input order."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["207"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Mixed batch: the failure array identifies failed events. The other events were accepted."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All submitted events failed. Inspect the failure array."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example failure array:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"[\n  {\n    \"id\": \"issuer-txn-invalid\",\n    \"failureReason\": \"Invalid request\"\n  },\n  {\n    \"id\": \"issuer-txn-processing-failed\",\n    \"reason\": \"processing error\",\n    \"data\": \"Unable to process this event\"\n  }\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Validation failures use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failureReason"]},". Processing failures use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason: processing error"]}," and can include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," message for people to read. Do not parse that message for retry decisions. After an uncertain result, use source lookup and retry with the same event identity to avoid creating another purchase."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authentication errors and errors affecting the entire request may have the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/standards/errors"},"children":["public error shape"]},". Read the status and body. For batches, inspect individual failures even when the HTTP status is 2xx. Acceptance does not confirm reward qualification. Processing and notifications happen later, and some accepted events have no reward notification."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"account-creation","__idx":2},"children":["Account creation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both intake operations can find existing accounts or create the missing cardholder group, cardholder and card. Every event includes the external cardholder/card IDs and complete card facts, including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardLast4"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["network"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["physical"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["billingZip"]},". The full requirements are on the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/transaction-ingestion/authorizations#required-fields"},"children":["authorization"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/transaction-ingestion/settlements#required-fields"},"children":["settlement"]}," pages."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 assignment, omission and the configured IDs to use after lazy provisioning."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A creation response contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lazilyProvisionedAccounts"]}," only when accounts are created, with mappings for only those new accounts. If the response is lost, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/cardholder-groups#identity-lookup"},"children":["identity lookup"]}," returns current mappings without creating accounts."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"idempotency-and-retries","__idx":3},"children":["Idempotency and retries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Event identity is issuer plus source kind plus external ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},". Authorization and settlement namespaces are separate even when their IDs use the same string."]},{"$$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":"Previous outcome"},"children":["Previous outcome"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Next submission with the same event ID"},"children":["Next submission with the same event ID"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Successfully processed. Identical normalized data"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ignore the retry without creating another purchase or reward."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Successfully processed. Changed data"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keep the original processed purchase. Changed data does not replace it."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Received but processing failed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Permit an unchanged retry. Receipt alone does not count as successful processing."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Still pending"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Continue processing the existing source. Avoid parallel duplicate effects."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is no event correction input. Preserve the original event ID after a lost response or failed attempt. Use lookup to distinguish receipt, processing failure and successful processing."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"captures-ordering-and-history","__idx":4},"children":["Captures, ordering and history"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Give each capture a distinct settlement ID. Captures can share ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalAuthId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Settlement may arrive without or before authorization, and its amount can differ."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An authorization that arrives or is processed after settlement produces no authorization webhook and does not create another reward."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use one authoritative purchase submission path. For segmented offers, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/merchant-segments#purchase-history-for-onboarding"},"children":["coordinate with Percents to backfill purchase history"]},". Do not submit historical purchases as new earning events."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"product-outcomes","__idx":5},"children":["Product outcomes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/reward-lifecycle"},"children":["reward lifecycle"]}," explains authorization estimates and awarded settlement rewards. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["disputed"]}," to report refunds and disputes for either product. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/transaction-ingestion/settlements#report-refunds-and-disputes"},"children":["cashback recovery"]}," for fraud and abuse follow-up coordinated directly with the issuer, without routine clawback webhooks."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/reward-lifecycle"},"children":["Branded rewards"]}," can earn value restricted to a merchant, spend an available balance and apply supported clawbacks. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/reward-lifecycle"},"children":["branded lifecycle"]}," for details."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"product-specific-response-fields","__idx":6},"children":["Product-specific response fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each endpoint's response schema marks fields that apply only to branded rewards."]},{"$$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 or result"},"children":["Field or result"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How to read it"},"children":["How to read it"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rewardProductType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identifies the product of an earned reward."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cashback"]}," in transaction reward detail"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contains the cashback result."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Top-level earnings, spending and clawback amounts in transaction reward detail"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Describe branded balance effects."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["daysToAvailability"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["daysToExpiry"]},", balance amounts, spending restrictions and refund issuer debits"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Apply to branded rewards."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the schema for the requested product. Not every returned amount represents another reward."]}]},"headings":[{"value":"Transaction ingestion","id":"transaction-ingestion","depth":1},{"value":"Responses and acceptance","id":"responses-and-acceptance","depth":2},{"value":"Account creation","id":"account-creation","depth":2},{"value":"Idempotency and retries","id":"idempotency-and-retries","depth":2},{"value":"Captures, ordering and history","id":"captures-ordering-and-history","depth":2},{"value":"Product outcomes","id":"product-outcomes","depth":2},{"value":"Product-specific response fields","id":"product-specific-response-fields","depth":2}],"frontmatter":{"title":"Transaction ingestion","description":"Submit authorizations and settlements with stable identities and safe retries.","seo":{"title":"Transaction ingestion"}},"lastModified":"2026-11-10T20:25:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/transaction-ingestion/overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}