{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/transaction-ingestion/settlements","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Settlements"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"settlements","__idx":0},"children":["Settlements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Settlement data determines the actual reward awarded and branded value spent on a purchase. Use the required fields and request example below to submit purchases, then report refunds and disputes when they occur. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/recordIncomingTxn"},"children":["settlement 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/recordIncomingTxn"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/incoming-txn"]}]},"."]},{"$$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 settlement."]}]},{"$$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-txn' \\\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-txn-001\",\n  \"amount\": 5000,\n  \"currency\": \"usd\",\n  \"merchantDescriptor\": \"Example Coffee\",\n  \"merchantId\": \"processor-merchant-001\",\n  \"mcc\": \"5814\",\n  \"createdAt\": \"2026-07-01T18:42:00.000Z\",\n  \"authTimestamp\": \"2026-07-01T18:41:30.000Z\",\n  \"cardholderId\": \"issuer-cardholder-001\",\n  \"cardId\": \"issuer-card-001\",\n  \"cardLast4\": \"4242\",\n  \"cardBIN\": \"411111\",\n  \"physical\": true,\n  \"billingZip\": \"10001\",\n  \"network\": \"visa\",\n  \"authMethod\": \"contactless\",\n  \"authCode\": \"123456\",\n  \"arn\": \"12345678901234567890123\",\n  \"state\": \"settled\",\n  \"merchantAddressStreet\": \"123 Main Street\",\n  \"merchantAddressCity\": \"New York\",\n  \"merchantAddressState\": \"NY\",\n  \"merchantAddressCountry\": \"US\",\n  \"merchantAddressZip\": \"10001\",\n  \"merchantLat\": \"40.7128\",\n  \"merchantLong\": \"-74.0060\"\n}\nJSON\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settled"]}," for cashback purchases. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["disputed"]}," to report refunds and disputes for either product. Cashback uses this data for fraud detection."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use a distinct settlement ID for each capture."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you sent the related authorization, supply its ID as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalAuthId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Supply ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authTimestamp"]}," when you know the authorization time, even if you did not send an authorization event."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Supply ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arn"]}," when the acquirer reference number is available."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For branded spending, authorization time determines whether the purchase falls within the balance's availability and expiry window. Settlement can arrive after expiry. Percents uses the first available time:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The linked authorization time."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authTimestamp"]},", when no linked time is available."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdAt"]},", when both authorization times are missing."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/reward-lifecycle#authorization-time-and-delayed-settlement"},"children":["branded spend window"]}," for details."]},{"$$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":"Heading","attributes":{"level":2,"id":"report-refunds-and-disputes","__idx":3},"children":["Report refunds and disputes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send a refund or dispute to the same endpoint with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state: refunded"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state: disputed"]},". Give each event its own stable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," and send a positive ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," in minor units. Keep that ID and the same data when retrying."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When available, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalAuthId"]}," to the original authorization's external ID. This field identifies an authorization. It is not a settlement ID. Include the cardholder, card and merchant details required for purchase events."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For cashback, Percents uses these reports to detect fraud and abuse. They do not trigger routine cashback clawback webhooks, but the absence of those webhooks does not prevent recovery of cashback paid in cases of fraud or abuse. Recovery may include an issuer invoice adjustment and is coordinated directly with the issuer."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For branded rewards, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/webhooks"},"children":["clawbacks"]}," for balance deductions and issuer debits. Reporting a dispute does not automatically reverse a reward."]}]},"headings":[{"value":"Settlements","id":"settlements","depth":1},{"value":"Required fields","id":"required-fields","depth":2},{"value":"Complete request","id":"complete-request","depth":2},{"value":"Report refunds and disputes","id":"report-refunds-and-disputes","depth":2}],"frontmatter":{"title":"Settlements","description":"Complete purchase input fields, account creation and endpoint examples.","seo":{"title":"Settlements"}},"lastModified":"2026-11-10T20:25:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/transaction-ingestion/settlements","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}