{"templateId":"markdown","versions":[{"version":"1.0","label":"v1.0","link":"/omni-api/overview/file-uploads/plaid","default":true,"active":true,"folderId":"6bec560c"}],"sharedDataIds":{"sidebar":"sidebar-omni-api/@1.0/overview/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Plaid transaction format","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":"plaid-transaction-format","__idx":0},"children":["Plaid transaction format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plaid-txn-stream"]}," is the only publicly documented file content contract. Upload UTF-8 JSON with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fileType=json"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type: application/json"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The payload must be an object containing a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactions"]}," array and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accounts"]}," array, joined by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account_id"]},". Every distinct ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account_id"]}," referenced by a transaction must be present in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accounts"]},"; partial account coverage fails validation for the entire file."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"recommended-envelope","__idx":1},"children":["Recommended envelope"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"accounts\": [\n    {\n      \"account_id\": \"acc_EXAMPLE_abc123xyz\",\n      \"mask\": \"4321\",\n      \"name\": \"Freedom Unlimited\",\n      \"official_name\": \"CHASE FREEDOM UNLIMITED VISA SIGNATURE\",\n      \"type\": \"credit\",\n      \"subtype\": \"credit card\",\n      \"balances\": {\n        \"available\": 1234.56,\n        \"current\": 1234.56,\n        \"iso_currency_code\": \"USD\"\n      }\n    }\n  ],\n  \"transactions\": [\n    {\n      \"transaction_id\": \"plaid-transaction-1\",\n      \"percentsMerchantId\": \"9b1f2f48-eaf2-4c22-9a49-76d32f942183\",\n      \"segment\": \"loyal\",\n      \"pending_transaction_id\": null,\n      \"account_id\": \"acc_EXAMPLE_abc123xyz\",\n      \"amount\": 4.75,\n      \"iso_currency_code\": \"USD\",\n      \"date\": \"2026-07-11\",\n      \"datetime\": \"2026-07-11T14:32:07Z\",\n      \"authorized_date\": \"2026-07-10\",\n      \"authorized_datetime\": \"2026-07-10T18:04:12Z\",\n      \"name\": \"BLUE BOTTLE COFFEE #142 OAKLAND CA\",\n      \"merchant_name\": \"Blue Bottle Coffee\",\n      \"merchant_entity_id\": \"mrch_ent_EXAMPLE_bluebottle\",\n      \"payment_channel\": \"in store\",\n      \"pending\": false,\n      \"category\": [\"Food and Drink\", \"Restaurants\", \"Coffee Shop\"],\n      \"personal_finance_category\": {\n        \"primary\": \"FOOD_AND_DRINK\",\n        \"detailed\": \"FOOD_AND_DRINK_COFFEE\",\n        \"confidence_level\": \"VERY_HIGH\"\n      },\n      \"location\": {\n        \"city\": \"Oakland\",\n        \"region\": \"CA\",\n        \"postal_code\": \"94607\",\n        \"country\": \"US\"\n      }\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"fields-used-for-normalization","__idx":2},"children":["Fields used for normalization"]},{"$$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 and behavior"},"children":["Requirement and behavior"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required, non-empty unique transaction identifier"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["percentsMerchantId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required UUID supplied by Percents; identifies the Omni merchant independently of Plaid's merchant text and IDs"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["segment"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required; one of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["new"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loyal"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lapsed"]},", or JSON ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," when the cardholder has no segment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required; 100% of transaction account IDs must match an entry in the top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accounts"]}," array"]}]},{"$$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":["Required finite number in Plaid transaction units; do not convert dollars to cents"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["datetime"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorized_datetime"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["date"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorized_date"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["At least one valid value; Percents uses the first available in this order"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchant_name"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["At least one required; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchant_name"]}," is preferred as canonical merchant name"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Used as the transaction descriptor when present"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchant_entity_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Used as the network merchant ID when present"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iso_currency_code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]}," when absent"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["account ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mask"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required on the matching account"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["account ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["official_name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subtype"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional card/account metadata"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_channel"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["in store"]}," maps to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chip"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["online"]}," maps to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["online"]},"; other values remain in the raw payload without a mapped auth method"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additional Plaid fields are allowed and preserved with the raw transaction for audit and troubleshooting. Do not remove fields from a standard Plaid response merely because Percents does not currently normalize them."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every transaction in a file must contain the custom ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["percentsMerchantId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["segment"]}," fields. Percents rejects the complete file before ingestion when a merchant UUID is unknown, a segment is missing or invalid, or any other row fails the public contract."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On validation failure, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FileUploadSchemaValidation"]}," webhook returns every missing account ID in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorMetadata.missingAccountIds"]}," and every unknown merchant UUID in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorMetadata.unknownPercentsMerchantIds"]},"."]}]},"headings":[{"value":"Plaid transaction format","id":"plaid-transaction-format","depth":1},{"value":"Recommended envelope","id":"recommended-envelope","depth":2},{"value":"Fields used for normalization","id":"fields-used-for-normalization","depth":2}],"frontmatter":{"seo":{"title":"Plaid transaction format"}},"lastModified":"2026-08-11T03:50:30.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/omni-api/overview/file-uploads/plaid","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}