{"total":65,"items":[{"contentType":"guidePage","name":"Address Verification (AVS)","createDate":"2026-09-18T13:01:45.19Z","updateDate":"2026-11-15T16:32:42.673Z","route":{"path":"/103/cardholder-verification/address-verification-avs/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"4350272d-62cc-404f-b0e2-0efb15d7ae19","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"7dfe4405-472c-43ab-a497-d7626aad67d4","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"edd8b630-cedd-44dc-a43f-72ca5e5fab2c","properties":{"title":"Address Verification (AVS)","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"4ecfe215-a77c-4296-b593-0bfec9646b65","properties":{"text":"When a card is used without being present, the merchant can send address details along with the transaction. Address Verification compares what arrives against the addresses TXN holds for that card and returns a standardized result. It is a fraud signal for you to act on, not a decision the platform makes on your behalf."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"4ff18aab-8b6e-40f8-b66f-f6a46b7c025f","properties":{"text":"AVS runs on card-not-present transactions: ECommerce, mail and telephone order, and automated fuel dispensers, including transactions made with a wallet token rather than the card itself. The merchant submits address data as part of the authorization, TXN compares it to the addresses it holds, and a standardized response goes back to the card scheme alongside the authorization result. The comparison is configurable and the behavior varies by region, in line with what each scheme requires there."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"041f57a2-f945-4f6a-8835-5e46bddf05ee","properties":{"sectionText":"What actually gets compared"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"1bdeb3ce-0311-42fc-ae1c-451199bbc808","properties":{"text":"Address matching is not a straight string comparison. The rules are configurable, and the usual pieces are the postcode and the numeric part of the street address, because those are the parts a fraudster is least likely to have and most likely to get wrong. A result tells you which parts matched: both, one, or neither. Two addresses that a human would call the same can return a partial match on formatting alone, which is why a partial result is a prompt to look rather than proof of anything."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ed6eb6dc-9adf-419c-b09c-e34bf592c844","properties":{"sectionText":"Every address on file is checked"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"91254f80-c04a-49c9-b93c-a79e89c5b778","properties":{"text":"A card program can hold an address in several places: on the card itself, on the cardholder, and on the cardholder group they belong to. AVS does not pick one of them. The address arriving with the transaction is compared against every address held across that hierarchy, and a match against any one of them is a match. A cardholder with more than one address on file is therefore not penalised for using whichever of them the merchant happened to ask for."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"b02e80c8-59bd-44e4-bb6c-cea0393e7174","properties":{"alertTitle":"An address you no longer use still verifies.","alertContent":"Because any address on the hierarchy can produce a match, one left on file keeps passing verification indefinitely. If a cardholder moves, adding the new address is only half the job. Remove the old one, or AVS will go on accepting it.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"046a9c59-d469-454d-91c7-3f1b7c7061f5","properties":{"sectionText":"A mismatch is a signal, not a decline"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"39b6ab53-f3cf-4320-8beb-834a9bcafdb2","properties":{"text":"TXN returns the AVS result. It does not decline the transaction because the address did not match. What a mismatch is worth is a risk judgment that belongs to your program, and different programs reasonably reach different answers: a full match required for a high-value first order, a partial match tolerated for a returning cardholder. If your account uses delegated approval, that judgment is one of the things your decisioning service is making."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"0d49a383-779c-4535-8437-9bf868843757","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"16b0d202-b2d3-4101-990e-e4626786bab8","name":"Cv Avs Address Check Dark","mediaType":"Image","url":"/media/rumpnif0/cv-avs-address-check-dark.png","extension":"png","width":2400,"height":1060,"bytes":252650,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"c2eb6903-0a32-4548-83e0-5bc2e5634d68","name":"Cv Avs Address Check Light","mediaType":"Image","url":"/media/rsrl03c1/cv-avs-address-check-light.png","extension":"png","width":2400,"height":1060,"bytes":253410,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"24a9bcee-0d04-46fc-91ed-9bb95b9974cd","properties":{"alertTitle":"AVS does not protect you unless you act on it.","alertContent":"Enabling address verification and doing nothing with the result changes nothing about which transactions are approved. The result has to reach whatever makes your risk decision, and something has to be configured to care about it.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ef374b2c-58cd-4ff1-9a8f-dcce2136d767","properties":{"sectionText":"Overriding a result"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3ac10465-90e7-4b03-b159-34922f3481a6","properties":{"text":"An address can be corrected in the moment rather than after the fact. Updated address data can be submitted in real time during authorization, so a cardholder who has just moved is not stuck waiting for a profile change or a replacement card. Separately, a delegated approval response can override the AVS result outright as part of the decision it returns. Both routes are governed by risk controls you configure, and both are fully logged: every AVS decision and every override is auditable afterwards."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"762489ab-fe5a-4355-aadb-d88b8f7fefa7","properties":{"sectionText":"How address verification relates to other objects"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"61d40ce9-3424-4b31-ba99-e7705b196973","properties":{"text":"The addresses being checked come from the card, the cardholder and the cardholder group, all of them, not one chosen from among them. The result attaches to the transaction. If your account uses delegated approval, the source deciding that authorization can override the result before it is applied. A separate resolution order decides where a physical card is posted, which is a different mechanism and not this one. Account Name Inquiry is the same idea applied to the cardholder\u0027s name rather than their address."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"5559e69e-97d6-42e3-9eb3-f3911931be5a","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"97724166-5f52-4dea-b13d-67be3566a68b","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"359478cc-0d87-4236-9a33-0434a9ca8584","properties":{"cardTitle":"Account Name Inquiry (ANI)","cardText":"The same check applied to the cardholder\u0027s name.","pageLink":{"contentType":"guidePage","name":"Account Name Inquiry (ANI)","createDate":"2026-09-18T13:01:54.237Z","updateDate":"2026-11-15T16:32:43.603Z","route":{"path":"/103/cardholder-verification/account-name-inquiry-ani/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"6bdc1181-e1d0-4e24-ae33-306200e4d9dd","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"f89df2c6-0308-491a-963b-0ac523afa147","properties":{"cardTitle":"Cardholders","cardText":"Where addresses are held, and how they are updated.","pageLink":{"contentType":"guidePage","name":"Cardholders","createDate":"2026-09-16T06:22:18.73Z","updateDate":"2026-11-15T16:32:44.66Z","route":{"path":"/103/foundational-objects/cardholders/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"a615ed27-e2f2-4afe-b764-4fc583ef8f6c","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"4f3f102a-b240-4537-a5a4-0ac151f1998b","properties":{"cardTitle":"Delegated Approvals","cardText":"How a decisioning service can override a verification result.","pageLink":{"contentType":"guidePage","name":"How Delegated Approval Works","createDate":"2026-09-16T06:26:34.807Z","updateDate":"2026-11-15T16:32:47.123Z","route":{"path":"/103/delegated-approvals/how-delegated-approval-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e47adf53-2c39-46bb-bb12-ff0c765b075c","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"6fec159d-249c-477c-bbf7-68ae519b8c15","properties":{"prevPageTitle":"Trusted Merchants","nextPageTitle":"Account Name Inquiry (ANI)"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Strong Customer Authentication","createDate":"2026-09-18T11:31:11.723Z","updateDate":"2026-11-15T16:32:43.757Z","route":{"path":"/103/authentication-sca/strong-customer-authentication/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"6f1882ed-93f8-4f26-9cb9-b6b8a47e85b3","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"1b633abf-7d74-4761-9829-395c9ab70341","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"c3035b22-a1fa-4bc3-b013-f722c8f34b0b","properties":{"title":"Strong Customer Authentication","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"0d18d816-f2e0-446b-ac4d-894fdc37e1e0","properties":{"text":"Strong Customer Authentication is a European and UK requirement for a cardholder to prove who they are before most electronic payments go through. This page explains what it asks for, when it applies and how it works for card payments."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"0fbedd4f-d597-4805-a208-708bee50a2d7","properties":{"text":"Strong Customer Authentication (SCA) was introduced by the second Payment Services Directive (PSD2), and the detail is set out in regulatory technical standards. Its purpose is to make electronic payments harder to use fraudulently by asking for more than a card number. It applies in the European Economic Area and, under rules overseen by the Financial Conduct Authority, in the United Kingdom. The two started from the same text but are now maintained separately, so details such as limits can differ between them."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3371dab5-f922-4ee9-960e-f226f348e409","properties":{"sectionText":"Two factors from different categories"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"d4883a11-8278-47de-af63-a06cd938147a","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"9da1ff45-66d7-4634-9174-0356464faefb","name":"Sca Factors Dark","mediaType":"Image","url":"/media/zi0pok34/sca-factors-dark.png","extension":"png","width":2400,"height":1080,"bytes":216259,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"1e7d1c8d-849c-42db-a47d-ac13c68f0d61","name":"Sca Factors Light","mediaType":"Image","url":"/media/alldxkhv/sca-factors-light.png","extension":"png","width":2400,"height":1080,"bytes":214997,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"7ff0f535-ff09-4e85-8cd7-c05742f12f38","properties":{"text":"A cardholder is strongly authenticated when they provide two factors from different categories:\n\n- **Something they know:** a PIN, password or passcode that only they should know.\n- **Something they have:** something only they hold, such as a phone registered to them or the chip on their card.\n- **Something they are:** a physical characteristic, such as a fingerprint or face, checked by their device.\n\nThe two must be independent, so that losing or exposing one does not compromise the other."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertAlternative","id":"57168e32-3c5c-4c10-86d2-1a54d70ac54d","properties":{"alertTitle":null,"alertContent":"Two different categories, not two checks. A password followed by a security question is two checks of the same kind, so it is not strong authentication. A phone unlocked with a fingerprint is.","severity":"general info "}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"b27d96de-545d-4c7e-9ade-0e8ae984faac","properties":{"sectionText":"When it applies"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"778bb5c4-7df3-4083-9b0f-66b7884f767c","properties":{"text":"SCA is required when a cardholder pays electronically, accesses their payment account online, or does anything remotely that could carry a risk of fraud. For card payments, that usually means one of two situations:\n\n- **In store:** the card is inserted and the PIN entered, or the payment is made with a phone wallet the cardholder has unlocked.\n- **Online:** the card issuer checks who the cardholder is during checkout through 3-D Secure, usually in a banking app or with a one-time passcode."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"92d4cf92-1306-468d-94ba-01bf2fe8cb02","properties":{"sectionText":"Online payments are tied to the amount and the merchant"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"10a6216c-f9fd-427a-bc42-8690c34b48db","properties":{"text":"For a payment made remotely, the authentication must be linked to the exact amount and the merchant the cardholder agreed to. If either changes afterwards, the authentication no longer covers the payment. This is why an online authentication shows the cardholder who they are paying and how much."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"7ae61f33-2466-4c93-b30e-b0553a431f9d","properties":{"sectionText":"Exemptions"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"154333fd-9157-44c6-ab50-9a1aaaf176de","properties":{"text":"Asking for authentication on every payment would slow down payments that carry little risk, so the rules let some go through without it. Exemptions are optional: the card issuer can always decide to ask anyway. The limits for each one are set in regulation and differ between the EEA and the UK."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"b3b4f5e6-9c7f-4a37-a222-ac1f2a6301d0","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"00988998-ca5a-480a-8ed4-0aebf9cf8f7a","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"3e3f5c84-4148-4025-b3c6-b2e5c66fa6c6","properties":{"cellContent":"Exemption"}},"settings":null},{"content":{"contentType":"tableCell","id":"ed39f19b-ae24-4c82-aa3a-2ec48caacc16","properties":{"cellContent":"What it covers"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"529486f5-e98e-4da8-8541-8c34d4a80f9e","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"fbc48527-e9d5-4255-8251-127db480f8c9","properties":{"cellContent":"Low-value contactless"}},"settings":null},{"content":{"contentType":"tableCell","id":"8d126587-a8f5-4a42-a2db-dcd5c8bb2e0d","properties":{"cellContent":"Small in-store contactless payments, until a set number or total value has been spent without authentication"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"54b96477-43b4-4c0a-b945-5f5a492d4e8f","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"f1b10ba0-fdfc-43b4-91de-13ad5d50d3bf","properties":{"cellContent":"Low-value online"}},"settings":null},{"content":{"contentType":"tableCell","id":"1c132a6d-d1fe-47a1-a367-97eb95fc1674","properties":{"cellContent":"Small online payments, under the same kind of running limits"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"d2c6e4d3-50ad-465f-8699-11f40c4e55ec","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"08d10bfc-8b5d-45e7-a23c-fc487515903c","properties":{"cellContent":"Recurring payments"}},"settings":null},{"content":{"contentType":"tableCell","id":"5aaf1bba-24f0-4e37-b851-969df0aed941","properties":{"cellContent":"Later payments in a series of the same amount to the same merchant, once the first was authenticated"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"86228c35-47d6-4926-bedb-53fe4f5c16f6","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"e09468d0-cc3c-4c13-a57b-67d9bc699039","properties":{"cellContent":"Trusted beneficiaries"}},"settings":null},{"content":{"contentType":"tableCell","id":"32d10993-ec90-4268-8191-f54e88cfab81","properties":{"cellContent":"Merchants the cardholder has chosen to trust"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"938b71f3-b03c-4ed8-b83a-750953a642b6","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"eb96177d-ff61-4967-a103-0ac1c90aaaf1","properties":{"cellContent":"Transaction risk analysis"}},"settings":null},{"content":{"contentType":"tableCell","id":"74855758-9a3a-469f-b402-00ce5cd797eb","properties":{"cellContent":"Online payments judged low risk by real-time fraud analysis, within limits tied to fraud rates"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"6c8a0697-c8b4-47c2-900f-2220ef097707","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"f3855988-1ded-43c3-968f-a7b65a2b77e5","properties":{"cellContent":"Unattended transport and parking"}},"settings":null},{"content":{"contentType":"tableCell","id":"43d12494-e204-489e-a221-518fd2059046","properties":{"cellContent":"Fares and parking fees paid at unattended terminals"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"e445606c-08d1-459f-8844-e64317353786","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"f12ab035-4e82-4df9-a872-3c6065f18c9d","properties":{"cellContent":"Secure corporate payments"}},"settings":null},{"content":{"contentType":"tableCell","id":"2e3096cd-0ed0-42e0-85f0-8e4fd33c22e4","properties":{"cellContent":"Payments made through dedicated, secure corporate processes"}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"017f66c2-cb9c-49bd-98e1-f06aca485b41","properties":{"sectionText":"Payments outside the rules"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"132e5272-9bee-480d-bca1-0870ba09584d","properties":{"text":"Some payments are not exempt but out of scope, meaning the rules never applied. These include payments a merchant starts under an agreement the cardholder authenticated at the outset, such as a subscription; mail and telephone orders; and payments where the card issuer or the merchant\u2019s payment provider is outside the EEA and the UK, where authentication is applied where possible."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"7d434b61-3ab5-4cc7-9baf-08a1192b8996","properties":{"sectionText":"Who is responsible"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"f80fcdcc-e54c-4ff9-aed1-1486f7c146cd","properties":{"text":"The duty to apply SCA sits with the payment service provider, which for card payments is the card issuer. Merchants and their payment providers decide how to request authentication and whether to ask for an exemption. Where a merchant\u2019s provider applies an exemption, it generally takes on liability for fraud on that payment. Where the payment was fully authenticated, liability for fraud generally moves away from the merchant."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"d95d29b1-e630-4297-a62b-e27e88bedc05","properties":{"sectionText":"What the cardholder sees"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ea752b2f-b255-4ad4-9d86-93436801f6a6","properties":{"text":"When a payment needs authentication, it is paused rather than refused. In store, the terminal asks for the card to be inserted and the PIN entered. Online, the cardholder is asked to confirm in their banking app, enter a one-time passcode, or answer a further check. Explaining this in cardholder communications helps avoid an interrupted payment being read as a failed one."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"8af73fe9-97a8-4222-9671-ceb085c5d1f5","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"011da560-acc4-4bec-9f82-566d8db6fe7c","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"48e966c3-c1d6-49ba-8d98-845f9f172f0d","properties":{"cardTitle":"SCA Counters and Contactless Limits","cardText":"The counters behind the rule, what moves them, and what resets them.","pageLink":{"contentType":"guidePage","name":"SCA Counters and Contactless Limits","createDate":"2026-09-18T11:31:20.097Z","updateDate":"2026-11-15T16:32:42.133Z","route":{"path":"/103/authentication-sca/sca-counters-and-contactless-limits/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2f69ffc6-6124-4eba-8a7d-9d7c316195c7","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"6fe6ab0c-f6c4-4061-9a88-8835dbd5d7ab","properties":{"cardTitle":"3-D Secure","cardText":"How online authentication works for card payments.","pageLink":{"contentType":"guidePage","name":"3-D Secure","createDate":"2026-09-16T06:24:47.867Z","updateDate":"2026-11-15T16:32:41.32Z","route":{"path":"/103/authentication-sca/3-d-secure/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2c14bfed-9803-44c3-a57c-6105c8c6131d","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"753fe2af-9636-4611-9af5-450e193afebc","properties":{"cardTitle":"Trusted Merchants","cardText":"Letting a cardholder skip the challenge at a merchant they have already authenticated with.","pageLink":{"contentType":"guidePage","name":"Trusted Merchants","createDate":"2026-09-16T06:24:40.2Z","updateDate":"2026-11-15T16:32:39.053Z","route":{"path":"/103/authentication-sca/trusted-merchants/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"09bbc81a-17c3-429c-b340-e9ec7579ee78","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"9ec517c5-0638-498f-9ecf-43d6775d2184","properties":{"prevPageTitle":"Merchant Controls","nextPageTitle":"SCA Counters and Contactless Limits"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Versions and Changes","createDate":"2026-09-16T11:13:56.453Z","updateDate":"2026-11-15T16:32:44.057Z","route":{"path":"/103/going-live/versions-and-changes/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"8f1cb6b9-3dda-4ea5-9498-87379b576efb","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"ec8ac6ff-5612-43cb-84a3-c2af7b73886d","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"05b0ae3e-4ae5-48e4-ab8e-a7463ac0b579","properties":{"title":"Versions and Changes","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"b6f917cd-35cf-49b5-b6e3-16313d062d56","properties":{"text":"An API that is still changing needs a way for you to know what you are integrating against, and a way to find out before something changes underneath you. Both come down to a header you send and a habit someone on your side has to own."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"5c134e30-4497-40fd-94e7-f85f199aae0b","properties":{"text":"The API carries a single version covering the whole surface rather than a version per path. There is one answer to \u0022which version am I on\u0022 instead of a different one for every endpoint you call, which makes the question worth asking and the answer worth recording."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"d8ae43fc-b0dd-4634-aaff-3b807124f420","properties":{"sectionText":"Two versions are live at any time"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"2b169730-adf9-46b3-9713-583ebf816523","properties":{"text":"There are always two versions you can call, and which two depends on where the platform is in its deployment cycle. One of them is always what is deployed now. The other is either the version before it, so you can compare against what you were building on, or the version coming next, so you can move your integration onto it before it becomes current. You choose which one you are calling with the x-api-version header.\n\nThat second slot is the useful one. Outside a rollout it gives you somewhere to diff against when behavior changes unexpectedly. During a rollout it gives you a window to test against what is about to land rather than discovering it on the day. Knowing which of the two you are looking at is the point of checking the version identifier rather than assuming.\n\nIt is a window, not a permanent home. Older versions are retired over time, so plan your move rather than staying on the earlier one indefinitely."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"9ef3684d-1bc6-45c6-9278-bb201135150c","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"db1282ad-eedc-4669-8356-100428993ea3","name":"Gl Versions And Changes Declare Version Dark","mediaType":"Image","url":"/media/ejefi1nv/gl-versions-and-changes-declare-version-dark.png","extension":"png","width":2400,"height":1300,"bytes":493991,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"acac1cb9-d2bf-4a6c-a115-8e14abfb846b","name":"Gl Versions And Changes Declare Version Light","mediaType":"Image","url":"/media/g1lougww/gl-versions-and-changes-declare-version-light.png","extension":"png","width":2400,"height":1300,"bytes":493432,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3d54d748-d672-43d5-8e3f-9fbf0344f8bd","properties":{"sectionText":"You declare the version on every call"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"1aba65ac-601e-4058-8b43-18a03df3be1f","properties":{"text":"The version is a required request header, x-api-version, carried on every request you make. It is not a default you can rely on and not something the platform infers from your credentials. You state which contract you are calling against, and the response you get back conforms to that contract."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"9ca9a68f-77dd-4e59-b3be-4969d6acf732","properties":{"alertTitle":"A call without the version header is rejected, not defaulted.","alertContent":"This is easy to miss, and it fails in a way that looks like something else. The request does not quietly fall back to the current version. It is refused with a 400, and so is a malformed or unsupported value. If your first call against a new environment comes back with an error that seems unrelated to what you sent, check the header before you check anything else.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"fc535d06-d91e-4dde-9d13-945ef7d4c76e","properties":{"sectionText":"Record the version you send"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"0b788b22-2e11-4c90-86d0-36a2061ae730","properties":{"text":"Log the x-api-version you send next to your requestId on every call. When a deployment, a proxy or a piece of shared client code turns out not to be sending what you thought, that record shows which contract you asked for. To see which version an environment is actually running, call the health endpoint."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"2ff13969-1ff2-46cf-8536-8d7ebc80884b","properties":{"sectionText":"Environments are deployed independently"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"f5bedc91-8381-4e56-acae-594872763620","properties":{"text":"The version answering in sandbox is not necessarily the version running in production. They are released separately, so confirming which is which in the environment you are about to release against is a real step rather than a formality. The health endpoint answers this directly: it returns the deployed version along with the environment label, which is why it is the right first call when something behaves differently in two places that should be identical."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"4b1a4473-3917-44de-999c-544bc65ff823","properties":{"alertTitle":"\u0022It works in sandbox\u0022 is a version claim as much as a behavior one.","alertContent":"When the same call behaves differently across two environments, the version each is running is the first thing to establish rather than the last. Read the deployed version in both before concluding the platform is inconsistent. The difference is often a deployment that has reached one and not yet the other, which is a timing question rather than a defect.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"abc1a698-b81f-4c1f-920c-e493ab094a47","properties":{"sectionText":"Breaking changes are announced. Additive ones are not."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ffa50371-bf1c-44c0-9511-71e64b4c915c","properties":{"text":"Changes to the shape of the contract are communicated ahead of being deployed, so that a breaking change arrives as something you have already planned for. Additive change is different: a new field appearing in a response, or a new value in an existing field, is not announced individually, because it is not expected to break a client that was built to tolerate it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"a9adbc36-bec1-4dbb-aa13-fafb5783fea8","properties":{"sectionText":"Build to absorb additive change rather than reject it"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"1feda914-5306-4c2b-b9ee-ea82dd270cf8","properties":{"text":"Ignore fields you do not recognize rather than failing on them. Do not treat an unexpected value in an existing field as fatal where a sensible default will do. Read error descriptions as human-readable text for a person rather than as something to match on, and key your logic on the codes instead. These are small decisions at build time and they are the difference between a routine platform addition passing unnoticed and the same addition becoming an incident."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"7f9dda9a-9aac-4813-a3fe-7c80c98e9006","properties":{"alertTitle":"A strict parser turns every routine addition into an outage.","alertContent":"An integration that rejects any payload containing something it has not seen before will work perfectly until the first time TXN adds a field, at which point it fails everywhere at once for a change that broke nothing. This is worth testing deliberately rather than assuming: send your own handler a response with an extra field and an unfamiliar enum value, and confirm it carries on.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"46c8fe57-4432-4755-8418-8bef6ac71b22","properties":{"sectionText":"Where changes are published"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"cad87081-ccef-4a19-b52a-6f843b220e4c","properties":{"text":"Changes to the platform are published on the Hub\u0027s changelog. Reading it is not something to do when something breaks; it is something to do on a schedule. Make one person on your side responsible for it and for turning what it says into work in your own release plan. A breaking change you knew about is a scheduled task, and the same change discovered in production is an incident."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"213984f5-da0c-4978-b450-b494c91a6c8c","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"6c130b78-1340-43f0-9295-1fa8954838cb","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"2af13b33-2cc5-41a4-b70f-ed7d8cc81f69","properties":{"cardTitle":"Health Checks","cardText":"Reading the deployed version and the environment answering.","pageLink":{"contentType":"guidePage","name":"Health Checks","createDate":"2026-11-14T13:47:02.173Z","updateDate":"2026-11-15T16:32:46.023Z","route":{"path":"/103/staying-in-sync/health-checks/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"d2724a96-2414-4d80-a111-986fcd0b18e5","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"848c804b-8cbb-4d51-b986-b7826416ca98","properties":{"cardTitle":"Requests and Responses","cardText":"The headers every call carries, including the version.","pageLink":{"contentType":"guidePage","name":"Requests and Responses","createDate":"2026-11-14T09:22:41.207Z","updateDate":"2026-11-15T16:32:46.957Z","route":{"path":"/103/api-essentials/requests-and-responses/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dd68c2a5-1262-438b-adfb-f6bf84e3e336","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"f098080f-d569-4722-99eb-5352f775016f","properties":{"cardTitle":"Changelog","cardText":"Where changes to the platform are published.","pageLink":{"contentType":"changelog","name":"Changelog","createDate":"2026-05-25T12:38:22Z","updateDate":"2026-11-14T06:23:07.26Z","route":{"path":"/","queryString":null,"startItem":{"id":"057f5aad-b705-4e19-ac80-136708268fd2","path":"changelog"}},"id":"057f5aad-b705-4e19-ac80-136708268fd2","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"3e8ce7c2-df79-43b3-b37c-f06d59fe3ae8","properties":{"prevPageTitle":"Health Checks","nextPageTitle":"Go-Live Checklist"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Requests and Responses","createDate":"2026-11-14T09:22:41.207Z","updateDate":"2026-11-15T16:32:46.957Z","route":{"path":"/103/api-essentials/requests-and-responses/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dd68c2a5-1262-438b-adfb-f6bf84e3e336","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"1722cc73-424e-4b4e-a019-57bd08271469","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"1f4fbf67-0ee0-4291-bb80-987b5e14e98a","properties":{"title":"Requests and Responses","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"d4ecc815-caf9-41ad-9bc0-2f7015453946","properties":{"text":"Some patterns hold across the whole Core API rather than belonging to any one object: what every request carries, the shape every response comes back in, and how a list of records is paged, sorted and trimmed. Reading this once means every other guide can assume these rules rather than restating them."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3017aeed-a5b6-45a0-aa6a-c997af2a3556","properties":{"text":"None of this is specific to cardholders, accounts or cards. It holds for every call you make, which is why it is worth twenty minutes now rather than discovering it one endpoint at a time.\n\nFor what a particular operation accepts, see the API Reference."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"20ea5841-f144-44ff-b397-8cb474739393","properties":{"sectionText":"Every response shares one envelope"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"42c42dc7-7dec-4a95-85d7-9b4ce1e74443","properties":{"text":"Whatever you call, the response comes back in the same shape. The identifiers you sent are echoed back, so you can confirm they arrived as intended. Alongside them TXN adds an identifier for the response itself and a timestamp of its own. Then either your result or a structured error.\n\nNever both. A response carries one or the other, so your code can branch on which is populated rather than inspecting the status code and the body separately."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ab9a9336-b98a-46e8-b2f7-0b787168d0a5","properties":{"text":"Learning this shape once means every endpoint looks the same to your code. A handler written against the envelope works for a cardholder, an account, a card or anything added later."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"c8504c9c-fe18-4983-a817-1f4792c91b14","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"8c016e3a-8473-4063-9372-23d51c2953fa","name":"Ae Requests And Responses Envelope Dark","mediaType":"Image","url":"/media/wwseooq0/ae-requests-and-responses-envelope-dark.png","extension":"png","width":2400,"height":1080,"bytes":240993,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"6972bd44-0ff8-4402-b547-6503cac3859b","name":"Ae Requests And Responses Envelope Light","mediaType":"Image","url":"/media/zn1djx2r/ae-requests-and-responses-envelope-light.png","extension":"png","width":2400,"height":1080,"bytes":236720,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ed5b9cb6-a49c-4396-bbc8-3e4e5431520c","properties":{"sectionText":"What every request must carry"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"03aa866b-f269-42b7-abe9-760f3e8750e4","properties":{"text":"Every call carries the headers below. A request with a required header missing or invalid is rejected."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"edd75644-f0ed-4409-8f15-69192c423b1b","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"e5d6fcd2-0900-44af-ae3e-44026e82de11","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"6d2e7c84-0373-4e96-b291-2b1e6af4160c","properties":{"cellContent":"Header"}},"settings":null},{"content":{"contentType":"tableCell","id":"22cd7559-519e-4a72-8266-e866314a350a","properties":{"cellContent":"Required"}},"settings":null},{"content":{"contentType":"tableCell","id":"72feb32c-3472-407c-b08e-b63dce4ab7ba","properties":{"cellContent":"What it carries"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"239b56a5-e9e9-4387-a3a1-310248a061a3","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"4e364ae8-2b51-48e5-9ac0-cc611ff864cc","properties":{"cellContent":"Authorization"}},"settings":null},{"content":{"contentType":"tableCell","id":"5b70f41a-7864-4a34-8d0c-444a1f8984fb","properties":{"cellContent":"Yes"}},"settings":null},{"content":{"contentType":"tableCell","id":"552308f2-52eb-4b14-a9fb-3e453438926d","properties":{"cellContent":"Your access token, sent as a bearer token. Authentication covers how to obtain and renew it."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"147dceed-28f1-4986-9421-d9439b0a54f0","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"33ba292a-7fb8-4b07-b050-3b1813ef6824","properties":{"cellContent":"requestId"}},"settings":null},{"content":{"contentType":"tableCell","id":"12f2a34d-aa6b-4e27-8833-eeeae55776f7","properties":{"cellContent":"Yes"}},"settings":null},{"content":{"contentType":"tableCell","id":"d7bb3742-f774-4de2-ab50-da2dcba783aa","properties":{"cellContent":"A UUID you generate to identify the call. TXN also uses it to recognize a repeated write. Retries and Idempotency covers it."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"946db91a-7180-453c-b951-8f15a79f12ec","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"921bb0c2-8b97-4972-8efd-fa70bfaac112","properties":{"cellContent":"correlationId"}},"settings":null},{"content":{"contentType":"tableCell","id":"da17a47e-e5d0-4814-b5aa-b4c83a2d518b","properties":{"cellContent":"No"}},"settings":null},{"content":{"contentType":"tableCell","id":"b7f4882a-40a9-4879-abc7-2217b9f08035","properties":{"cellContent":"A UUID of your own choosing that ties related calls together. It is echoed back in x-correlation-id."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"b2970710-4615-4f8c-9a21-ee2f084d2dd3","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"5973b187-8916-476d-8d1a-c6c8dbe95426","properties":{"cellContent":"x-api-version"}},"settings":null},{"content":{"contentType":"tableCell","id":"7eec3afc-844f-4e12-838c-0a3831b87126","properties":{"cellContent":"Yes"}},"settings":null},{"content":{"contentType":"tableCell","id":"8e708654-7ea8-4ce6-9b80-8e5e3e6c3a03","properties":{"cellContent":"The version of the API you are calling. A missing, malformed or unsupported value returns 400."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"bb9fa4aa-0798-4793-ad61-0606125fb95a","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"2cc63d6d-803c-4890-b9af-ab52a66bfb7d","properties":{"cellContent":"Content-Type"}},"settings":null},{"content":{"contentType":"tableCell","id":"dd152836-782c-435d-9573-e8cbf2427a3b","properties":{"cellContent":"When the call has a body"}},"settings":null},{"content":{"contentType":"tableCell","id":"79fca0fd-3e3c-453d-b3c3-1a9b86abb009","properties":{"cellContent":"The format of the request body. A wrong or missing value returns 415."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3ab06833-ccd3-426e-94ed-5658dc7d66b5","properties":{"text":"Two of these are about tracing rather than identity, and conflating them is common. The request identifier names one specific call. Use a new one for each new request, and reuse it only when you retry that same request. TXN uses it to find the call if you raise a query, and to recognize a repeated write. The correlation identifier groups several calls into one flow, so an entire onboarding sequence can be traced as a unit rather than reassembled afterwards. Set a fresh one per flow: one that spans your whole integration\u0027s history traces nothing more precisely than not using one at all."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"630075d6-994e-44a9-8f8a-c24ca02e9c79","properties":{"sectionText":"What comes back in the headers"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"44358715-81f3-4869-a3af-4f8c1c338ed0","properties":{"text":"The envelope is not the whole response. Every call also comes back with a set of headers worth wiring into your logging from the start, because they are what makes a problem diagnosable after the fact rather than during it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"14fad929-4e59-4d0a-8d0d-728c9d1d32be","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"3b2c0c65-a012-438f-8a47-05a8fca5b9dc","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"bf8af507-2827-424f-b883-2a526a3886b2","properties":{"cellContent":"Header"}},"settings":null},{"content":{"contentType":"tableCell","id":"647ad9ec-1de0-4213-81f7-2257f0547a79","properties":{"cellContent":"What it tells you"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"3c9a63a5-f018-40a9-9984-2f82efb53328","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"e7b43d9b-1075-4202-ae5f-1a47cd4f8ec3","properties":{"cellContent":"x-request-id"}},"settings":null},{"content":{"contentType":"tableCell","id":"f3e980b7-b8e5-4e0f-9386-7de2e52f4f49","properties":{"cellContent":"Echoes the requestId you sent with the call. Quote it when raising a query with TXN."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"5ddb7077-4046-4446-9b48-0a956c21d368","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"98714387-9724-46bc-9b67-9f2e35402a3a","properties":{"cellContent":"x-correlation-id"}},"settings":null},{"content":{"contentType":"tableCell","id":"1dacfbfb-1603-4bd2-b0d4-b3798e938d3f","properties":{"cellContent":"Echoes the correlationId you sent. Use it to tie related calls together."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"f3e9d7c3-ce80-4442-ba78-9424e8f4fae8","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ee815610-22a0-4272-a3e8-acad70cc7c93","properties":{"cellContent":"x-response-time"}},"settings":null},{"content":{"contentType":"tableCell","id":"883fb529-d1ea-4146-b69e-ec0bc6d2b8ae","properties":{"cellContent":"How long the platform took to process the request, in milliseconds."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"6bc0b7a8-81cb-4e6e-8699-9cc13e1fce5b","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"0a902a8c-321b-45e0-9d09-436e0b7bab6c","properties":{"cellContent":"x-rate-limit-*"}},"settings":null},{"content":{"contentType":"tableCell","id":"7750757d-7edf-4ce0-b72c-b671a0e14fdb","properties":{"cellContent":"Two headers stating your rate limit and the window it applies over. Rate Limits covers them."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"40827074-086f-47df-86f0-5b0efd35e408","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"fc2e5add-f682-4566-a2a1-8701f4bc577a","properties":{"cellContent":"x-idempotent-replayed"}},"settings":null},{"content":{"contentType":"tableCell","id":"78f80f99-5097-4465-bc4f-1ecb09d74de7","properties":{"cellContent":"true when the response is a stored replay of an earlier write, false on the first attempt. Not set on reads. Retries and Idempotency covers it."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"bd40d25c-b187-4c3f-a42c-da4b239e5130","properties":{"sectionText":"Working with lists"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"648adf39-953e-44cf-b689-a211a0ecbfa0","properties":{"text":"A call returning a list is paged by page number and page size. The response tells you where you are: how many records match in total, which page you are on, how many records it holds, how many pages exist, and whether a next or previous page is available. Page size is capped, so a large result set always means several calls rather than one large one.\n\nTwo other things shape what you get back. You can sort a list by naming a field and a direction. You can also ask for a subset of fields rather than the whole record, which is worth doing on large lists where you only need a few values per row."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"24485ec2-c0bd-47ca-922d-2a1490cce7ce","properties":{"alertTitle":"List behavior varies between operations","alertContent":"Some list operations accept a sort expression and some do not, and the parameter carrying it is not named consistently across the API. Some treat paging parameters as optional, while at least one requires them. A shared helper written against one list can fail against another, so check the API Reference per operation rather than assuming.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"a88883cd-53b7-4229-86c1-c3c83bfaa57f","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"891742e6-fa8b-4498-b38c-370895befaaf","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"8b565a8a-bb32-4068-a68c-b48b2aa58708","properties":{"cardTitle":"Errors","cardText":"What comes back when a call fails, and what each status means.","pageLink":{"contentType":"guidePage","name":"Errors","createDate":"2026-11-14T09:22:41.277Z","updateDate":"2026-11-15T16:32:46.777Z","route":{"path":"/103/api-essentials/errors/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dba005b5-8d0e-48ba-84b2-85c6855f7c5e","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"4b2bc5c3-eb58-4a5e-914c-1bc2416d59ad","properties":{"cardTitle":"Core Objects","cardText":"The objects these requests act on, and how they relate to each other.","pageLink":{"contentType":"guidePage","name":"Core Objects","createDate":"2026-09-16T06:20:31.817Z","updateDate":"2026-11-15T16:32:39.203Z","route":{"path":"/103/getting-started/core-objects/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"0b97009e-ae9c-4b9b-a63d-ec7d5bd5c0c4","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"10414a09-161b-44b8-8911-d68b75d2ebe9","properties":{"cardTitle":"Retries and Idempotency","cardText":"The idempotency header, and what happens when a write is repeated.","pageLink":{"contentType":"guidePage","name":"Retries and Idempotency","createDate":"2026-11-14T09:22:41.407Z","updateDate":"2026-11-15T16:32:39.84Z","route":{"path":"/103/api-essentials/retries-and-idempotency/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"182084cf-2e4d-406f-a1e4-9a1dcba5f19d","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"45426c2f-8937-40fb-9ef0-69de769ba960","properties":{"prevPageTitle":"Payment Terms","nextPageTitle":"Errors"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"How Delegated Approval Works","createDate":"2026-09-16T06:26:34.807Z","updateDate":"2026-11-15T16:32:47.123Z","route":{"path":"/103/delegated-approvals/how-delegated-approval-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e47adf53-2c39-46bb-bb12-ff0c765b075c","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"64e91521-b8f6-4ed1-a411-71416a460dfc","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"92f4343e-b10a-48db-89e3-4b49f068d247","properties":{"title":"How Delegated Approval Works","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"a07c83ae-096d-47ff-bdff-3947b4e32ad4","properties":{"text":"By default the issuer\u0027s own system makes every authorization decision: a request arrives, it is checked against balance and controls, and a response goes straight back to the network. Delegated approval puts a different decision-maker in that path. Instead of TXN deciding alone, TXN asks a system you run, and that system\u0027s answer becomes the authorization outcome."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"4b9e66ce-e3a5-442c-83ad-4518817f448b","properties":{"text":"Before the parts, the direction. Delegated approval is TXN calling you. You stand up endpoints, TXN calls them and reads your response. You do not post decisions to TXN, and there is no TXN endpoint for you to submit an outcome to. Everything below follows from that, and an integration built the other way round will not work."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"579cd092-a2fb-42d9-aa3f-00ecdb5e5be2","properties":{"sectionText":"The pieces and how they fit together"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3737833f-6455-43e2-8707-6e8ae921b9ec","properties":{"text":"Your side is two endpoints. One answers decision requests during a live transaction. The other answers health checks, so TXN can tell your system is reachable when no transaction happens to be in flight. TXN\u0027s side is two records you configure. A delegated approval source tells TXN how to reach you: the address it calls, the credentials it presents, and how long it waits for an answer. A stand-in is the ruleset that decides in your place when your endpoint cannot be reached. A stand-in is not a safety net that exists by default: an unconfigured one provides no cover at all, and what it reacts to is something you set deliberately."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"40e28ad2-0e79-4cd9-9a53-1c5b7f5e14d6","properties":{"sectionText":"How a transaction moves through the flow"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"f0634d7c-2aa1-4d03-93ca-0c662198e41c","properties":{"text":"A transaction arrives and TXN needs an authorization decision. Where a delegated approval source is configured for that traffic, TXN calls your registered address and waits, up to the timeout on that source\u0027s record, for your reply. Two things can happen next. If you answer inside the timeout, your decision is the authorization outcome. If you do not answer in time, or answer with an error the stand-in is configured to react to, the stand-in decides instead. Either way TXN records the outcome and remains the system of record for it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"e45f5c67-f5d4-4421-bc7a-87344d532daa","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"f9142c88-ed3a-4608-b875-a6f5e7bb022a","name":"Da How Delegated Approval Works Flow Dark","mediaType":"Image","url":"/media/a5tfet0t/da-how-delegated-approval-works-flow-dark.png","extension":"png","width":2400,"height":1100,"bytes":318512,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"cd9a7dc3-7e02-4c3c-810c-a285fa6455a8","name":"Da How Delegated Approval Works Flow Light","mediaType":"Image","url":"/media/js1ny41l/da-how-delegated-approval-works-flow-light.png","extension":"png","width":2400,"height":1100,"bytes":314244,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"046ca7e2-42cc-47b6-8d7e-2608952512bd","properties":{"sectionText":"Handling a decision request"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"7499c386-e53a-467b-88b1-8d2b227f0657","properties":{"text":"The decision request is the delegated approval. TXN sends your endpoint the transaction awaiting authorization and the reply your endpoint returns is the decision. There is nothing else to submit afterwards. What arrives is TXN\u0027s own transaction record, so you can expect a known shape rather than something you define, and it can carry additional context alongside it: an order reference, a custom reason code, or other metadata TXN attaches to help your decisioning and your later reconciliation. What you send back is an approve or a decline. Your response also carries a second meaning beyond this one transaction: a client-error response tells TXN your endpoint is unavailable, a server-error response tells it your endpoint hit a temporary fault. Those are exactly the signals a stand-in watches for, so how your endpoint fails determines whether the fallback engages."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"7a87f844-07a4-44be-840b-8316f3ae0c9d","properties":{"alertTitle":"Failing silently is the worst option available.","alertContent":"An endpoint that accepts the connection and then hangs leaves TXN waiting out the full timeout on every transaction, where a prompt error response would have handed over to the stand-in immediately. Return an error quickly rather than stalling.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"bb98f804-08aa-4f8f-81a4-5f59ec9b7817","properties":{"sectionText":"What else your response can carry"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"9a5cc3fb-062b-4b0f-afd5-2076ee02be83","properties":{"text":"The decision is the point of the response, but it is not the only thing the response can do. It can return an updated available balance, which is often the most valuable part: your system is the authority on what the cardholder can actually spend, and sending the current figure back keeps TXN\u0027s view aligned rather than drifting. It can carry the results of an address or name verification you performed, so those attach to the transaction rather than being lost inside your own systems. And it can carry tags and a memo of your own, which stay with the transaction for reporting and reconciliation afterwards. All of it is optional. A response that only approves or declines is a valid response."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"c16aaa9e-6612-4b01-a599-3fb83e70f5f0","properties":{"alertTitle":"A balance you return replaces the one TXN holds.","alertContent":"Balance enrichment is an override, not a suggestion. Send a stale or wrongly calculated figure and TXN will authorize against it, including any transaction a stand-in decides afterwards using that same figure. Return the balance you would be willing to have decisions made on when your system is unreachable.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"13d6d1e9-e4da-44d6-bf63-35feb7447d8c","properties":{"sectionText":"What happens after you answer"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"e4573dea-e460-47fb-be45-9ad465c277d2","properties":{"text":"TXN updates the transaction state from your decision, applies whatever enrichment your response carried, and records the whole exchange for audit. It then fires the webhook notifications for that transaction, carrying the metadata through, so your wider systems learn the outcome the same way they learn about any other transaction rather than through a second channel specific to this one. Because TXN is the caller, there is no submission to look up afterwards and no receipt to store. Your own logs, correlated with the transaction, are your record of what you decided and when."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"a0d65ef3-b929-425a-930c-a21887bd3663","properties":{"sectionText":"Answering a health check"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"badfbaec-cbf5-40f5-a252-7348219e357b","properties":{"text":"A decision request only happens when there is a transaction to decide. A health check happens regardless, on TXN\u0027s own schedule, which is what makes it useful: it distinguishes a system that is quiet because there is no traffic from one that has gone down. A source with genuinely low volume can go a long time without a decision request under completely normal conditions."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"88401407-79f1-4e35-a24e-189fd9b72112","properties":{"alertTitle":"This is not a heartbeat you send.","alertContent":"Both the decision request and the health check are TXN calling you. There is nothing for you to post and nothing for you to schedule. Your obligation is to keep a second endpoint reachable and answer it.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"902c4b08-64f1-49b4-8a4d-1fe1baa832de","properties":{"text":"Answer promptly and successfully while your system is healthy, and fail fast when it is not. Monitor your own health endpoint alongside your stand-in configuration rather than instead of it: an endpoint that starts failing health checks is worth alerting on in its own right, ahead of a real transaction ever reaching the stand-in\u0027s triggers. This health check is specific to delegated approval. For the platform\u0027s own availability, which you poll rather than answer, see Health Checks."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"8d9f2b4e-94a6-43d9-8e38-6d6a94770c33","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"a9305856-8410-470e-a7b0-15fc654a424e","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"b11a7883-3598-4ddd-8385-8d34dbbe571b","properties":{"cardTitle":"Delegated Approval Sources","cardText":"How TXN reaches your endpoint, and how long it waits.","pageLink":{"contentType":"guidePage","name":"Delegated Approval Sources","createDate":"2026-09-16T06:26:56.91Z","updateDate":"2026-11-15T16:32:46.167Z","route":{"path":"/103/delegated-approvals/delegated-approval-sources/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"d321a15f-1299-48cb-a8cb-11440abd0a74","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"a4cefe0e-2571-46d6-a1f6-478114f8e5ab","properties":{"cardTitle":"Delegated Approval Stand-Ins","cardText":"What decides when your endpoint cannot be reached.","pageLink":{"contentType":"guidePage","name":"Delegated Approval Stand-Ins","createDate":"2026-09-16T06:26:45.147Z","updateDate":"2026-11-15T16:32:47.573Z","route":{"path":"/103/delegated-approvals/delegated-approval-stand-ins/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"ec2e9c3f-38f6-4b67-99be-540bae84c71b","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"28d53b2a-a26a-4068-acea-ad2736f1c40d","properties":{"cardTitle":"Webhooks","cardText":"How your systems hear the outcome once a decision is processed.","pageLink":{"contentType":"guidePage","name":"Webhooks","createDate":"2026-11-14T13:47:02.143Z","updateDate":"2026-11-15T16:32:40.257Z","route":{"path":"/103/staying-in-sync/webhooks/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1c117316-3d0f-42ce-9780-e5051e263d76","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"d78844c2-4591-4d36-9b49-36ba6ac22e90","properties":{"prevPageTitle":"Account Name Inquiry (ANI)","nextPageTitle":"Delegated Approval Sources"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Transactions","createDate":"2026-09-16T06:23:22.427Z","updateDate":"2026-11-15T16:32:47.27Z","route":{"path":"/103/money-movement/transactions/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e79295d5-99a5-4e5f-859c-c15d73178622","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"1df8f2da-4d75-47e8-9788-9655687479e6","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"d7646999-53a4-4899-96f8-28bbf722218b","properties":{"title":"Transactions","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"fcef4d39-80f4-4cb0-a710-4a29bb51f5f0","properties":{"text":"A card gets used and the network sends TXN a series of messages about it, sometimes over days. All of them belong to one transaction. Understanding that the record is a single thing being enriched, rather than a row per message, is what makes everything else on this page make sense."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"27fd8404-a7b8-4f87-99d7-b3584a86fcf6","properties":{"text":"Your application does not create transactions. They are produced by real activity on a card and your integration reads them back. What arrives from the network is a sequence: an authorization, perhaps an advice, a clearing, possibly a reversal. TXN treats all of them as lifecycle events of one logical transaction rather than as separate records, and correlates them back to the original authorization. So the thing you read is the current, complete state of an event that may still be in progress."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4712c0d3-57a6-408e-a3cc-772bcca8ed99","properties":{"sectionText":"Every message is either actionable or informational"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"f65d5af2-a618-4635-bdd9-1a684ab55f00","properties":{"text":"The first thing TXN does with an incoming message is classify it. An actionable message needs an approve or decline answer returned to the network in real time: this is an authorization, and it is the only kind of message where a decision is being asked for. An informational message needs no response: it reports something that has already happened, such as a clearing, a reversal, an advice or a settlement. Informational does not mean inconsequential. These messages still move the transaction\u0027s state, update the ledger and release or adjust holds. They simply do not require an answer."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ed84860b-2695-4072-98b6-ed29e029a3fb","properties":{"sectionText":"The record is immutable, and changes arrive as new events"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"77f4ab93-13f0-4543-b48a-aa81af93666d","properties":{"text":"The initial transaction record does not get edited. When a financial value changes (an amount is adjusted, a hold is reduced, a settlement figure arrives), it is recorded as a delta event alongside the original rather than overwriting it. Historical values, audit events and financial events are all retained. That is why the transaction\u0027s history is readable after the fact rather than reconstructed: nothing that was ever true about the transaction has been written over."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"ec8eec30-c668-4478-b3aa-7bcc21f56454","properties":{"alertTitle":"Do not wait for a field to change in place.","alertContent":"Because values are never overwritten, the thing that moves as a transaction progresses is its state, not the figures you first read. If you are tracking a transaction through to settlement, follow the lifecycle state and the events attached to it rather than polling for an amount to be different. The amount you read at authorization will still be the authorization amount long after the transaction has settled for something else.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"715922da-6acb-472b-85ed-33b5ea3c8d6e","properties":{"sectionText":"The lifecycle is a state model, not a status field"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"c5b608f6-ebdc-4609-87c9-0cbc2007fdf4","properties":{"text":"Transaction states are centrally managed and only approved transitions can be made. An authorization that is reversed moves to reversed; one that settles moves to settled; one that is never completed moves to expired. An attempt to move a transaction somewhere the model does not allow is refused and logged rather than quietly applied. Every transition is timestamped and recorded, which is what makes the audit trail trustworthy rather than merely present."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"b1fecaa9-4bfa-4784-b6cd-99357917a6cc","properties":{"sectionText":"What happens during an authorization"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"c4f468ba-7fb8-4a15-8631-313cac38ff98","properties":{"text":"An authorization arrives and TXN evaluates it against everything configured for that card: the spend controls, the merchant controls, the country controls on the product, and the card\u0027s own transaction controls. Country controls run in one of three modes: permitting only listed countries, blocking listed countries, or not applying at all. Where the account uses delegated approval, the decision goes to your endpoint instead. If the transaction passes, TXN approves it to the network and places a hold against the account, which is why the available balance drops before anything has settled."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"72009793-0f75-4d06-a449-030abfe8ff01","properties":{"sectionText":"Three amounts, and only one of them is the ledger"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"972b39e1-d09f-4b5d-a343-7266b8c67c2e","properties":{"text":"A transaction carries the original amount in the merchant\u0027s currency, the amount billed to the cardholder in the account\u0027s currency, and the amount that eventually settles through clearing. These are three different figures and they serve different purposes. The cardholder billing amount and currency are what TXN\u0027s ledger is calculated from. The original merchant amount is recorded for reporting and display and has no effect on the ledger. The settlement amount is recorded, along with any conversion rate the network supplies, but is not what the ledger is built on either."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"b20dd0ba-b505-4836-b92d-0c02bd49bc39","properties":{"alertTitle":"Reconcile against the billing amount, not the one the cardholder saw at the till.","alertContent":"On any transaction involving more than one currency, the merchant amount and the billing amount will differ, and only the second one moves money on the account. Building reconciliation on the original transaction amount produces figures that look right on a single-currency program and quietly break the first time a cardholder buys something abroad.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"75bdea5d-3833-41bc-a129-62ab1f0292bd","properties":{"sectionText":"Authorization and clearing arrive separately"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"2a548400-9a04-44f3-8db3-9268a322c4c5","properties":{"text":"For most card activity the approval and the money are two different messages arriving at two different times. The authorization decides whether the transaction is allowed and reserves the amount; the clearing arrives later and is what actually settles. Between those two points the transaction is real, visible and incomplete, and the final settled figure can differ from the amount authorized. Advices sit in between: an advice updates the transaction\u0027s state and adjusts the hold to the advised amount without re-running the original authorization decision."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4528447c-62d5-4c09-96b3-cd3eae246044","properties":{"sectionText":"How a clearing finds its authorization"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"2d432336-06d3-4ae3-bb24-6b74d40ebcff","properties":{"text":"Every clearing record is evaluated for linkage to a prior authorization. Matching runs through progressively looser strategies until one succeeds: first an exact match on approval code, amount, date and acting cardholder; then the same match across a wider time window when the exact date does not line up; then the network\u0027s own reference for the transaction. One authorization can link to several clearings, which is what a split settlement or a partial capture looks like. A clearing links to at most one authorization."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"a56a73f8-1930-4fbc-8c00-b609058c5f7d","properties":{"alertTitle":"An unmatched clearing is still money that moved.","alertContent":"Some clearings never find their authorization: an offline or fallback transaction that was approved without one, a merchant submitting very late, or data that simply does not line up. These are kept, flagged as informational, posted to the ledger so they are visible, and included in reconciliation. What they are not is attached to an authorization. If your reconciliation walks authorizations and reads their clearings, it will miss them entirely.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"8e19d1aa-84f3-4c08-9cab-2eed5fe1209d","properties":{"sectionText":"Reversals, increments and partial approvals"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"946818b9-71f4-45fa-beda-eeba04c64a1c","properties":{"text":"A reversal, full or partial, releases or reduces the hold and updates the ledger, and is processed as soon as it arrives rather than waiting on anything downstream. An incremental authorization increases an existing hold, and the controls are evaluated against the incremental amount alone rather than the new total. A partial approval happens where the full amount cannot be authorized but the terminal is willing to take less, which depends both on the terminal and on whether the product permits it. In every case the original authorization record remains available afterwards."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"17ab2d15-1749-418f-8f44-96033278395b","properties":{"sectionText":"When an authorization is never completed"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b2da8dff-f074-42b4-a1bd-e3c767d90c12","properties":{"text":"An authorization that is never cleared does not sit there indefinitely. It expires according to the card scheme\u0027s rules and the expiry window configured on the merchant control group that applies, at which point the transaction moves to expired and the hold against the account is released automatically. The same outcome can be reached deliberately: a pending authorization can be released on request, which expires it and clears its hold. A release is refused if the transaction has already settled, reversed or expired, because there is nothing left to release."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"cb876c21-93bd-45de-aaec-8ef1e17316c8","properties":{"sectionText":"How your systems find out"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"1e5e7c61-ff54-4414-b56f-c295c4ccaeb1","properties":{"text":"Lifecycle events emit webhooks carrying the identifiers needed to correlate the event back to the transaction, the card, the account and the cardholder on your side. That covers advices, clearings, reversals, settlements, expiries and manual releases. Webhooks are the intended way to follow a transaction\u0027s progress: there is no polling loop you are expected to run, and reading a transaction back is for answering a question about one, not for discovering that something changed."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"615b3861-be0a-48c3-aed1-187ddbfd3b4a","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"dd541ac0-2a50-4bff-81bd-65cfb702491d","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"06c78579-5f78-4176-b9ad-8ba3862d2910","properties":{"cardTitle":"Balances","cardText":"The two figures a hold moves, and which one to reconcile against.","pageLink":{"contentType":"guidePage","name":"Balances","createDate":"2026-09-16T06:23:36.843Z","updateDate":"2026-11-15T16:32:40.1Z","route":{"path":"/103/money-movement/balances/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1acbd4db-1c7f-4f4b-a390-e6cb6c889e2d","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"6d055ad8-28e3-4f1f-b618-4d53977f0e7e","properties":{"cardTitle":"Spend Controls","cardText":"What an authorization is evaluated against, and why one declines.","pageLink":{"contentType":"guidePage","name":"Spend Controls","createDate":"2026-09-16T10:47:00.377Z","updateDate":"2026-11-15T16:32:45.233Z","route":{"path":"/103/card-controls/spend-controls/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b3eace44-6780-4c51-831b-164ca1d52e67","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"f707d1ff-2335-4ebb-ac34-146f45f8f763","properties":{"cardTitle":"Webhooks","cardText":"How lifecycle events reach your systems.","pageLink":{"contentType":"guidePage","name":"Webhooks","createDate":"2026-11-14T13:47:02.143Z","updateDate":"2026-11-15T16:32:40.257Z","route":{"path":"/103/staying-in-sync/webhooks/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1c117316-3d0f-42ce-9780-e5051e263d76","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"93d2aaaf-93e1-463c-9693-9f5f0cbc8dc8","properties":{"prevPageTitle":"PINs","nextPageTitle":"Balances"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Products","createDate":"2026-09-16T06:22:36.26Z","updateDate":"2026-11-15T16:32:42.283Z","route":{"path":"/103/foundational-objects/products/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"38067e3a-67a3-4525-b8e7-987c4c4c8b58","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"ebc3d899-d859-47bb-bd9b-e8fc5e84cd66","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"9c8d0c36-210f-4087-828f-9572b3eb0955","properties":{"title":"Products","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"3182cbd2-a3bc-430c-a3e9-98027ed39b0d","properties":{"text":"An issuing platform separates the card someone carries from the configuration that decides how it behaves. Grouping cards under shared defaults is what lets you launch a distinct offering, a travel card, an expense card, a rewards card, without hand-tuning every card issued under it. On TXN that configuration layer is the product. It is the largest configuration surface in the API, and every card references one when it is issued."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"b8a59475-5534-4f09-8597-4435c64f3197","properties":{"sectionText":"What a product controls"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"d8f9701d-0ab9-46b4-bb4c-bf8a2d463d12","properties":{"text":"Three groups of settings hang off a product, and only the first is about issuance.\n\nThe card-creation settings decide how cards come into existence: the range they are issued from, how long they last, whether they auto-activate and auto-generate a PIN, and a ceiling on how many active or suspended cards one cardholder may hold under the product.\n\nThe physical card settings decide what happens to anything that ships: the fulfillment provider and shipping method, card art, offline PIN handling, address verification, and which digital wallet providers cards may be provisioned into, each with its own switches for in-app, manual, card-on-file and web provisioning.\n\nThe transaction controls decide how cards under the product behave when they are used: which transaction types are permitted, the default posture towards merchants, country allow and block lists, the PIN retry limit, whether partial approval is allowed, and the Strong Customer Authentication thresholds for contactless and remote transactions."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"cfe17243-36b6-4d9a-b78a-277dee72575d","properties":{"sectionText":"How a product relates to cards"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"19671248-aff2-4df0-abbc-95fb11c2dad6","properties":{"text":"A card references its product when it is issued, not the card program. There is no per-card override for anything held at product level, so two cards behave differently only if they belong to different products.\n\nA product also carries the delegated approval source, if you are making authorization decisions in your own systems. See Delegated Approvals for how that works."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"d2389baf-75cb-4c5d-9105-d12c1e9cc0ef","properties":{"alertTitle":"A product change reaches cards that already exist.","alertContent":"Editing a product is not a change to future cards only. Every card already issued against it picks up the new configuration. Before you change a live product, know how many cards point at it and what the change does to them.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"107a1ee5-a1b2-4796-a376-5feb9a2facf3","properties":{"sectionText":"Three switches, not one"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"5c605816-9d1d-4653-9869-aafbef7c283b","properties":{"text":"A product is not active or inactive as a single switch. Whether it is active, whether it allows transactions, and whether it allows new cards to be created under it are three separate settings, each permitted by default."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ade9c6fe-6f78-422f-b712-59c80505f10d","properties":{"sectionText":"Products have no lifecycle"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"1672fad3-4680-4c5a-a071-58257d66873c","properties":{"text":"Unlike accounts, cardholders, cardholder groups and cards, a product has no transitions and no lifecycle to track. You create it, you update it, and the three switches above are how you take it out of service. There is no state machine and nothing to query."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"f5893267-c3ed-4877-a649-7933d7fd6686","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"b11e70d9-5603-471b-baae-40d6babb74c1","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"b2f11580-97c0-471e-92ac-880c4aaef1da","properties":{"cardTitle":"Cards","cardText":"What a card inherits from its product, and what it needs before it can exist.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"e2360e3f-3597-4729-9f14-76ea18037fe0","properties":{"cardTitle":"Delegated Approvals","cardText":"Making the authorization decision in your own systems.","pageLink":{"contentType":"guidePage","name":"How Delegated Approval Works","createDate":"2026-09-16T06:26:34.807Z","updateDate":"2026-11-15T16:32:47.123Z","route":{"path":"/103/delegated-approvals/how-delegated-approval-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e47adf53-2c39-46bb-bb12-ff0c765b075c","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"ee2d37c1-50ff-423d-a50d-85e9fd130515","properties":{"cardTitle":"Controls \u0026 Security","cardText":"The transaction controls a product sets, in detail.","pageLink":{"contentType":"guidePage","name":"Spend Controls","createDate":"2026-09-16T10:47:00.377Z","updateDate":"2026-11-15T16:32:45.233Z","route":{"path":"/103/card-controls/spend-controls/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b3eace44-6780-4c51-831b-164ca1d52e67","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"e2e8e639-fc61-410b-a261-8d473f8035bc","properties":{"prevPageTitle":"The API Specification","nextPageTitle":"Cardholders"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Digital Wallet Tokens","createDate":"2026-11-14T13:46:40.313Z","updateDate":"2026-11-15T16:32:42.527Z","route":{"path":"/103/digital-wallet-tokens/digital-wallet-tokens/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"40b1a666-ed74-4f45-8745-d54c19dc8a2c","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"cb4daa24-6d85-4972-9a0e-07f2c34ba26b","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"25d23e97-fac4-4938-8258-bdf064920a41","properties":{"title":"Digital Wallet Tokens","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"72955ff7-5e99-4869-aad5-36113a15c4e3","properties":{"text":"When a cardholder adds a card to Apple Pay or Google Pay, what lands on the device is not the card. It is a token that stands in for it, with its own number, its own expiry and its own lifecycle. Most of the surprises on this page come from that separation."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"5eb27223-fbb4-4267-a62b-1a8244c0e43e","properties":{"text":"A token belongs to one card, and one card can have several tokens: a phone, a watch, a second device, the same card in two different wallets. Each is a separate record with its own identifier, its own network token number and its own expiry date, which is not the card\u0027s expiry date. The card number itself never reaches the device or the merchant, which is the entire point of the mechanism."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"746e3b49-77c0-4f18-b5b5-7e11d9da99a5","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"4cb624d6-124b-4b22-b0f1-f22740722a73","name":"Dwt Provisioning Flow Dark","mediaType":"Image","url":"/media/lhxpb4rc/dwt-provisioning-flow-dark.png","extension":"png","width":2400,"height":830,"bytes":232772,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"e04ec2ac-5519-443a-9c50-adee870ee6d2","name":"Dwt Provisioning Flow Light","mediaType":"Image","url":"/media/emeaqvtq/dwt-provisioning-flow-light.png","extension":"png","width":2400,"height":830,"bytes":226009,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"75d9e0ad-8ea6-4482-bd11-f81e4231bca7","properties":{"sectionText":"Whether provisioning is possible at all"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"1f863fd0-a8f1-4a5e-bc56-d45742016319","properties":{"text":"Three things have to be enabled before a card can be provisioned anywhere: digital wallet provisioning on the product, the specific wallet provider on that product, and the route being used to provision. Turning the product-level switch off disables every wallet provider under it regardless of their individual settings. A request that fails any of these is refused with a reason recorded against it, rather than being evaluated and declined on its merits."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"71c7ca67-a6e0-4712-9fba-8c2a5a049a66","properties":{"sectionText":"Four ways a card reaches a wallet"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3ba22a61-8047-4102-8714-4ef27cf2112b","properties":{"text":"A card reaches a wallet by one of four routes, and they differ in who starts the request and what you build. Push provisioning starts in your app. Web push provisioning starts from your website. With manual provisioning, the cardholder keys or scans their card details into the wallet. With card on file, the cardholder chooses a card the wallet already holds. Whichever route is used, the request meets the same two assessments and ends in the same kind of token.\n\nPush provisioning is the route that involves your app: a request for the payload and the handoff to the wallet provider\u0027s SDK, which Push Provisioning covers. Each route is enabled separately, so turning one on does not turn on the others."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"5ca8dc00-4e26-481a-81d5-b99a46fc8c3e","properties":{"sectionText":"Two assessments, kept deliberately apart"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"906bb80f-cc6f-415d-ad84-aac98f764a77","properties":{"text":"A provisioning request is assessed twice. The payment network makes its own decision and returns it with a score and reason codes. TXN then makes its own assessment (approved, review or declined) taking the network\u0027s view as an input alongside card validation, risk evaluation and whatever rules the program carries. Both are recorded separately on the token, and neither is overwritten by the other. Separately again, the token carries a provisioning status saying what actually happened: provisioned, verification required, or declined."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"f45be971-b234-4dd1-b410-9398633d776f","properties":{"alertTitle":"The network\u0027s recommendation is an input, not the answer.","alertContent":"It is tempting to read the network\u0027s decision as the outcome and stop there. It is not. A cautious recommendation from the network does not automatically decline the request, and equally does not get approved on the strength of the network\u0027s view alone: it typically routes to verification instead. Where you need to know what happened to a provisioning attempt, read the provisioning status. Where you need to know why, read both assessments, because they can differ and the difference is usually the explanation.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"a1faaa4a-4eef-42e2-a06e-3f50b402369a","properties":{"sectionText":"When the cardholder has to prove who they are"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"1f84fd36-40f8-4f50-92c4-726f66801ee1","properties":{"text":"Where the assessment calls for it, the cardholder is asked to verify themselves before the token is activated. Several methods are supported (verification inside your app, a one-time passcode by text or email, a verification link, or a call to customer service) and the product configuration decides which are available and in what order they are offered. At least two are available wherever additional verification is required, so there is always a fallback if the first is not usable."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"0f9bf4cb-aa02-49c8-acd1-a3c66552b359","properties":{"sectionText":"What else is checked"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b1e441c9-28e4-4712-aba2-c44b7aaf5fe1","properties":{"text":"Alongside the risk assessment, provisioning validates the card\u0027s expiry date and its security code. Where the product is configured for it, the cardholder\u0027s address is verified as part of the evaluation too. On-device verification, the cardholder\u0027s biometric or passcode on the device itself, is recognized and recorded as part of the picture rather than being invisible to the platform."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3d74efc9-078f-4e93-9b17-8e90aa8c1b4c","properties":{"sectionText":"A token\u0027s lifecycle is its own"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"6f6ff648-98a1-4b86-8cae-77b2f9f1d1d2","properties":{"text":"Tokens and cards are managed independently by default. Changing a card\u0027s status does not change the status of the tokens provisioned from it, and tokens carry on working against a card whose state has moved unless you say otherwise. A card transition carries an optional instruction to propagate, and when it is set the corresponding transition is applied to every token on that card, each processed individually with its own transition record and its own recorded outcome."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"914e87f3-7139-4692-9a9f-7b1b587bda5e","properties":{"alertTitle":"Closing a card leaves its tokens live unless you propagate.","alertContent":"This is the single most consequential thing on the page. A card put on hold or closed for fraud, with tokens still provisioned from it, leaves those tokens spendable. Independence is the right default for ordinary lifecycle changes and the wrong one for a card reported lost or stolen, so set the propagation instruction whenever the reason is one that should stop all use of the card. Propagation is queued rather than instant, so allow a short delay before the token actually stops.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e4dca70b-dc0c-448d-be4b-44d4ebf67f24","properties":{"sectionText":"Finding the tokens on a card"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ebc1a45b-2b61-4aa9-89a4-71bf0f803ea1","properties":{"text":"Tokens can be listed in their own right, retrieved individually, or read through the card or the cardholder they belong to, which is usually the more useful question, since \u0022what is provisioned from this card\u0022 is what you need before deciding whether to propagate anything. Each token\u0027s transitions can be read too, so the history of a token is available rather than only its current state."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"50087ab8-0478-417c-9ca3-16ace80b3590","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"4724832e-76d4-4fea-a424-6067be947b87","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"a9758471-6c74-420d-aaee-719b2d424694","properties":{"cardTitle":"Push Provisioning","cardText":"Getting a card into a wallet from your own app.","pageLink":{"contentType":"guidePage","name":"Push Provisioning","createDate":"2026-11-14T13:46:40.343Z","updateDate":"2026-11-15T16:32:43.463Z","route":{"path":"/103/digital-wallet-tokens/push-provisioning/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"623782dd-77b3-47e5-bf5f-a52fe8a68337","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"a05b38bc-3d55-4478-aafa-30746b389f46","properties":{"cardTitle":"Cards","cardText":"The card a token stands in for, and its own lifecycle.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"c97f4100-58ac-4490-88d5-fc0704929b1d","properties":{"cardTitle":"Replacing a Card","cardText":"What happens to tokens when the card underneath them is replaced.","pageLink":{"contentType":"guidePage","name":"Replacing a Card","createDate":"2026-11-14T13:45:44.953Z","updateDate":"2026-11-15T16:32:41.983Z","route":{"path":"/103/managing-cards/replacing-a-card/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2db9d6c2-7f22-452f-b105-e3f518240751","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"6b894dc7-ffa0-4d35-b750-e719db5c83ec","properties":{"prevPageTitle":"Delegated Approval Stand-Ins","nextPageTitle":"Push Provisioning"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Introduction","createDate":"2026-09-16T06:20:11.61Z","updateDate":"2026-11-15T16:32:44.873Z","route":{"path":"/103/getting-started/introduction/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"a89f4a70-6b1c-43a4-8198-441f004cafff","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"82c3c3d3-9f1f-4129-ad1e-61872001503d","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"ebd2816a-daaf-4c81-84e9-1b0724b37de7","properties":{"title":"Introduction","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"3f3314eb-5f09-420d-855e-2107b1e0b737","properties":{"text":"Running a Card Program means two distinct jobs: issuing, which creates and manages the cards, the people behind them and the money they draw against, and processing, which decides in real time whether each payment goes through and records what happened. TXN does both on one platform, so you build against one API rather than joining two together."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"54c836b2-cdfa-4682-a264-c54fe0d64cc1","properties":{"text":"You integrate against the Core API to create cardholders, open the accounts their cards draw against, issue physical and virtual cards, set the rules that govern how those cards can be used, and read back what happened when they were used. Underneath, TXN provides the scheme connectivity that makes a card you issue work at a merchant.\n\nThese guides explain what each part of the platform is and how to think about it. For the exact fields, request shapes and operations, see the API Reference."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"dc98a8be-b094-4bad-8c11-ff385c64f56d","properties":{"sectionText":"What you can build"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"555b83be-740e-4016-807d-acaf911dc85c","properties":{"text":"Setting up happens in a fixed order, because each piece depends on the one before it. You create cardholders for the people or entities cards belong to, and cardholder groups where a set of cardholders share the same reference data. You open accounts to hold the balance a card draws against. You then issue cards against them, physical or virtual, and manage PINs.\n\nWhat a card is allowed to do comes from configuration rather than from the card itself. Products hold the settings shared by a whole population of cards. On top of that you set spend limits, restrict or allow categories of merchant, and mark individual merchants as trusted.\n\nOnce a card can be used, the platform authorizes every attempt against the controls you configured and records the outcome. You read transactions and balances back, and TXN posts events to an endpoint you register so your systems learn what happened without polling. Cards reach Apple Pay and Google Pay through digital wallet tokens and push provisioning. If you would rather make the authorization decision yourself than leave it to the platform, Delegated Approvals let you do that.\n\nNone of this has to touch real money first. You can simulate transactions in a test environment and exercise the whole flow end to end before going live."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"b0c1a862-662c-4ef1-940c-86d9810f2ba1","properties":{"sectionText":"What TXN runs, and what stays yours"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b20f8da8-99ce-40c4-b105-57eb9d6f136c","properties":{"text":"TXN is the issuer-processor. It runs the technical layer: issuing cards, cardholders and accounts, authorizing each transaction against the controls you have set, and carrying the messages that pass to and from the card scheme.\n\nSome things sit above anything you create through the API. Scheme membership and the BIN your cards are issued under belong to a BIN Sponsor. The Card Program your cards belong to, and the arrangement with that BIN Sponsor behind it, are put in place during onboarding. Your integration references them rather than creating them.\n\nFrom products downwards, everything is yours to set and change day to day: what a population of cards can do, the controls that govern them, and the cardholders and accounts behind them. The application your customers use and the experience built around the card are yours to build. TXN governs the platform and the standards a program runs to, and does not take over build decisions that belong to your team."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"55ec215c-f6e7-4277-96ef-09f067596d08","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"4827c74d-4cd6-421f-955a-3cc06c703d38","name":"Gs Introduction Who Owns What Dark","mediaType":"Image","url":"/media/yighd5v5/gs-introduction-who-owns-what-dark.png","extension":"png","width":2400,"height":1080,"bytes":294803,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"c3912b10-f367-47d1-8a1d-9c4208d1d4ee","name":"Gs Introduction Who Owns What Light","mediaType":"Image","url":"/media/t5qno3io/gs-introduction-who-owns-what-light.png","extension":"png","width":2400,"height":1080,"bytes":292743,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"d184a06a-0683-4f06-aca3-46bffa295108","properties":{"alertTitle":"Card Programs are provisioned, not created","alertContent":"There is no way to set up a Card Program, a BIN or a BIN Sponsor arrangement through this API. They exist in your environment before your first call. If you are looking for where to create one, it is an onboarding conversation rather than an API call.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"026f8ec3-6c41-4342-a556-bcff5e054d14","properties":{"sectionText":"The rest of the platform"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3151c389-db7c-40f9-9ab2-4546f4781db8","properties":{"text":"The platform has four surfaces. The Core API is the one this documentation covers."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"1145f5ed-3836-4f8c-b4fc-ca3402878293","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"26ff8d7d-91cc-4fda-9b24-e4cbf958b83b","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"57a13f77-3331-4c0d-9586-325195c9d78a","properties":{"cellContent":"Surface"}},"settings":null},{"content":{"contentType":"tableCell","id":"c5df1797-96bb-4647-89e4-090da49990fd","properties":{"cellContent":"What it is"}},"settings":null},{"content":{"contentType":"tableCell","id":"34803ee2-0d04-4670-b17a-e156d47feea7","properties":{"cellContent":"Used by"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"2b1ac02d-b498-4029-91ca-54234291c34b","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ec27f360-912c-46aa-9092-ca726ad28186","properties":{"cellContent":"Core API"}},"settings":null},{"content":{"contentType":"tableCell","id":"76bbd582-221b-442f-820b-34a02de77e91","properties":{"cellContent":"Program configuration, the card lifecycle, transactions and reporting. Everything your integration does goes through it."}},"settings":null},{"content":{"contentType":"tableCell","id":"1d09f95d-44fa-484b-98af-0ab6fd0ae75c","properties":{"cellContent":"Your code"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"e060dcc5-4220-4ead-bdf5-6e4ad11fb5fe","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"6b346aad-0296-4bdc-b56d-e2123ef2e195","properties":{"cellContent":"Control Center"}},"settings":null},{"content":{"contentType":"tableCell","id":"f47ca1ae-29d0-4da8-a8bb-d294185df404","properties":{"cellContent":"The operational interface. Environment addresses and credentials are issued here, webhooks are configured here, and your operations staff use it for configuration, monitoring and investigation."}},"settings":null},{"content":{"contentType":"tableCell","id":"15259c73-9397-4c17-9454-8a373fd72e50","properties":{"cellContent":"Your people"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"0be3a6dd-6f97-4afd-b038-930a681cd519","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"3a716055-254d-489e-b47d-c71640c0a111","properties":{"cellContent":"Knowledge Hub"}},"settings":null},{"content":{"contentType":"tableCell","id":"31d4cb94-2767-4734-a72c-19dec10d7ff9","properties":{"cellContent":"This site: the guides, the API Reference and the interactive Playground."}},"settings":null},{"content":{"contentType":"tableCell","id":"2cbfca01-8951-48f1-bbb7-6ed3eb5dcbd5","properties":{"cellContent":"Developers"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"3c3e2500-0865-4ca1-9dec-65a14391b1e5","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ff8d2ddd-c333-4b65-95a9-c21079292f14","properties":{"cellContent":"Intelligent Assistant"}},"settings":null},{"content":{"contentType":"tableCell","id":"61c23ae5-4f8f-4c3c-a39c-3bdfcb50e4f3","properties":{"cellContent":"The platform\u0027s reasoning layer. It answers questions in plain language across TXN, assists your operations team in Control Center, and lets your own AI systems act on the platform through a governed interface."}},"settings":null},{"content":{"contentType":"tableCell","id":"2d08545d-e820-430d-bbc6-5ba1eb2f5155","properties":{"cellContent":"Developers, operations staff and your own AI systems"}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"03a70cc9-e5c4-472c-bcef-86223aa41e66","properties":{"sectionText":"Before you begin"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"b47ca5a3-3d82-422c-a354-06eee17b9f41","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"6815c5a9-8b15-4a79-9545-8703298ed742","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"25766449-7862-467f-8a7c-13768e16056e","properties":{"cellContent":"What you need"}},"settings":null},{"content":{"contentType":"tableCell","id":"3f157fe9-bf1d-4b05-8669-b87b6590f1c6","properties":{"cellContent":"Where it comes from"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"54ed398b-4552-4ae8-8537-2a06e468b613","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"f48e89a1-c459-4eb4-ac6e-2cdc3ca06401","properties":{"cellContent":"A Card Program in your environment"}},"settings":null},{"content":{"contentType":"tableCell","id":"fa472558-d8c3-4414-bc5e-93c996d96723","properties":{"cellContent":"Provisioned during onboarding, before you start building"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"de7d822f-10c6-4b3e-93c5-2b2d7e592fec","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"a07c5d78-793f-4afd-bf2a-94032492b3b0","properties":{"cellContent":"Credentials for the environment you are building against"}},"settings":null},{"content":{"contentType":"tableCell","id":"ff6db12f-fc15-4348-b2ca-0f6466e16348","properties":{"cellContent":"Issued in Control Center, per environment. Credentials from one environment do not work in another"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"0e13152a-ae4a-4871-b356-e8bb961f8a9d","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"fcc4f282-7749-41f6-8f10-d4f14edaf962","properties":{"cellContent":"An endpoint you control, if you want events rather than polling"}},"settings":null},{"content":{"contentType":"tableCell","id":"130d1d78-1e88-465b-a743-f8ec0eed9cad","properties":{"cellContent":"Yours to host and register"}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"fa5b2e1b-0121-404f-b96a-cec12ef05ef4","properties":{"sectionText":"After Getting Started"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3d9a8d9a-254d-4b4f-b5ce-11691118a353","properties":{"text":"Read Getting Started in order. It takes you from nothing to a first successful call, and every other section assumes you have done so. Payment Concepts is the glossary: come back to it whenever a term is unfamiliar."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"3ede6e66-f450-4c86-94dc-5dc0b83fef9d","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"143cfa15-504b-46f8-92f7-ee795ec24f5a","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"1d8ae065-a3cb-4fb1-ae74-fc141b167237","properties":{"cellContent":"What you are doing"}},"settings":null},{"content":{"contentType":"tableCell","id":"1f3b699c-d3e2-4d0e-9efd-cf2c4b470847","properties":{"cellContent":"Read"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"2cd07ba6-3eb5-429d-b1ed-df0a6be2b363","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"c6569a97-2552-4d0d-9d3f-fe87dc46bcc6","properties":{"cellContent":"Setting up the objects a program is built from"}},"settings":null},{"content":{"contentType":"tableCell","id":"2db10a5b-ce97-40a9-bf62-e90e83588cf3","properties":{"cellContent":"Foundational Objects. The right next stop for most integrations."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"0e25d5f0-f6d1-44b9-a147-f5ed54858211","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"2baa7963-6a3d-4c4a-a24c-c493f32c9e1f","properties":{"cellContent":"Deciding what a card can and cannot be used for"}},"settings":null},{"content":{"contentType":"tableCell","id":"7f3e0942-c485-4895-9ffd-c52ed58ac28b","properties":{"cellContent":"Card Controls"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"c3d5342f-dc15-4eab-bc2b-a60af44a10c4","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"aee04350-23d5-4749-9dfd-eba65d891884","properties":{"cellContent":"Checking cardholder names and addresses"}},"settings":null},{"content":{"contentType":"tableCell","id":"e9dbeba6-5df7-475d-9925-422c20495da5","properties":{"cellContent":"Cardholder Verification"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"19dc52f5-b1f6-4206-9b05-a6732523239e","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"468e3369-ed22-43f5-b756-91325e8d1471","properties":{"cellContent":"Authenticating cardholders, including 3-D Secure"}},"settings":null},{"content":{"contentType":"tableCell","id":"85d18bf1-bde5-463f-a5d4-b7c99cd3f6ca","properties":{"cellContent":"Authentication \u0026 SCA"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"2727816f-237d-42bb-b696-3c6f3d42470f","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"910b5510-723b-4d3d-85bf-550bd58e4508","properties":{"cellContent":"Getting cards into Apple Pay and Google Pay"}},"settings":null},{"content":{"contentType":"tableCell","id":"5bbbb0e2-28f5-43ec-bcd8-2450d24f37e1","properties":{"cellContent":"Digital Wallet Tokens"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"c1c428a8-fd3c-41e2-987e-e44377b7efd5","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"d48d13f0-7457-420b-a8bb-da4ff726fd6d","properties":{"cellContent":"Making the authorization decision in your own systems"}},"settings":null},{"content":{"contentType":"tableCell","id":"61b3391a-7d71-4be5-8e12-f06d429bae67","properties":{"cellContent":"Delegated Approvals"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"2e3ca90d-7f21-47cf-8a1a-feafb7e2132a","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"95d3932a-d1e7-4f6a-ab83-e86b288d4fb7","properties":{"cellContent":"Every integration"}},"settings":null},{"content":{"contentType":"tableCell","id":"d8a11ffc-b250-4958-a600-8f275bc8c472","properties":{"cellContent":"Money Movement, Staying In Sync and Going Live. Read Going Live before you launch, not after."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e1e12b7e-d09a-447c-ad6e-7cf6e9e808e9","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"b852c334-a156-4566-b972-dd06c7dcbfab","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"c6a56e84-0d84-43eb-9b30-a122b4924ce4","properties":{"cardTitle":"How TXN Works","cardText":"What an issuer-processor is, and the roles behind a Card Program.","pageLink":{"contentType":"guidePage","name":"How TXN Works","createDate":"2026-09-16T10:34:03.717Z","updateDate":"2026-11-15T16:32:40.527Z","route":{"path":"/103/working-with-txn/how-txn-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1e283b0f-5937-4e57-87cb-9402b1cf9f3b","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"c5a86f68-198d-4cd2-b057-dd57c44719c4","properties":{"cardTitle":"Responsibilities","cardText":"Where the line falls between what TXN runs and what your team builds.","pageLink":{"contentType":"guidePage","name":"Responsibilities","createDate":"2026-09-17T15:55:58.67Z","updateDate":"2026-11-15T16:32:42.99Z","route":{"path":"/103/working-with-txn/responsibilities/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"56c5fab4-4ca7-4e79-98c6-543faaa61044","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"88e23923-f487-479e-bfc1-6ae46a6dc33d","properties":{"cardTitle":"Payment Concepts","cardText":"The vocabulary used across these guides, defined in one place.","pageLink":{"contentType":"guidePage","name":"Payment Terms","createDate":"2026-09-18T14:44:39.46Z","updateDate":"2026-11-16T06:59:32.047Z","route":{"path":"/103/payment-concepts/payment-terms/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b72be41a-a634-425c-ae8b-4ca31e6dffa0","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"3b199a7a-c36f-4c91-a332-9aacb921c71a","properties":{"prevPageTitle":null,"nextPageTitle":"Core Objects"}},"settings":null}},"cultures":{}},{"contentType":"baseGuidePage","name":"Getting Started","createDate":"2026-09-16T06:19:49.757Z","updateDate":"2026-11-15T16:32:38.58Z","route":{"path":"/103/getting-started/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"0e3f3e99-9954-4941-99b5-813baa9a2e4a","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"4fe536f8-60a1-4442-ae41-7612bb9a9de6","name":"Getting Started C Book","mediaType":"umbracoMediaVectorGraphics","url":"/media/bkffpln0/getting-started-c-book.svg","extension":"svg","width":null,"height":null,"bytes":8152,"properties":{}}]},"cultures":{}},{"contentType":"guidePage","name":"Webhooks","createDate":"2026-11-14T13:47:02.143Z","updateDate":"2026-11-15T16:32:40.257Z","route":{"path":"/103/staying-in-sync/webhooks/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1c117316-3d0f-42ce-9780-e5051e263d76","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"ded44885-8e6d-4422-ada5-c68009f0aa75","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"1a0dfcfd-3284-487c-977c-1b589e325aa3","properties":{"title":"Webhooks","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"f911a21d-094a-4a34-8e54-f128e28a2b0e","properties":{"text":"A transaction clears, a card expires, a stand-in engages, and none of it waits for you to ask. Webhooks are how your systems find out, and the framework around them (signing, retries, persistence and replay) is what makes them something you can depend on."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"63d2a2c2-354f-43de-a8b3-eba94ad69118","properties":{"text":"A webhook configuration is a record you create: a name, the destination TXN should call, the events you want sent there, and a signing secret. You can supply your own identifier for it or let TXN generate one, and a duplicate identifier is rejected rather than silently reused. Credentials for TXN to present when calling you are optional. An active flag lets you stop delivery without deleting the configuration. You can register more than one, which is how most programs separate their concerns: one destination for transactions, another for card lifecycle, another for a test harness."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"5af28ace-2cca-48ea-bf8c-f9519390f8b4","properties":{"sectionText":"Event names have a shape, and the shape is the point"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"efcb8167-52ea-4c4f-ba84-090e8901d6ce","properties":{"text":"Events are named as an entity and what happened to it, sometimes with a subresource in between: a card being created, a card becoming active, a physical card being created, an account being closed, an authentication succeeding, a token being provisioned, a transaction being authorized. That structure is not decoration. It is what subscriptions filter on, so the naming convention and the subscription model are the same mechanism viewed from two ends."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3a1c8249-b830-4acb-a326-a112cb90262c","properties":{"sectionText":"Subscribing: exact, by category, or everything"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"4bc9543b-5e6b-43dc-8acb-de1b89ee109e","properties":{"text":"Your event filters can name an exact event type, a category with a wildcard so you receive everything in it, a nested prefix for a narrower slice, or a single wildcard for everything the platform publishes. Most integrations start with the broadest subscription that makes sense and narrow it once they know which events they actually act on, because the cost of receiving an event you ignore is much lower than the cost of discovering you never subscribed to one you needed."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"d8709c06-1ee0-4656-a607-b7f43a5360b8","properties":{"alertTitle":"A category subscription picks up events that did not exist when you wrote it.","alertContent":"New event types are added to existing categories over time, and anything subscribed to a category by wildcard starts receiving them automatically with no change at your end. That is usually what you want, and it does mean your handler will one day be passed an event type it has never seen. Ignore unknown event types rather than failing on them.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"deef5af9-2137-409e-962c-7f343f5e1b58","properties":{"sectionText":"What generates events"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"e62330be-5867-4dc9-920d-9234ecc55c78","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"ffa3c832-972c-4464-886c-f68a41bb574b","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"0c14eb3d-0310-4de2-98d8-8e782ef3d4ee","properties":{"cellContent":"Area"}},"settings":null},{"content":{"contentType":"tableCell","id":"de4c78c4-b152-49ae-a7e0-734a51fba963","properties":{"cellContent":"What it reports"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"34c392d9-b08d-453d-abf3-b9b948ce0095","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"8bf1c6d6-9381-4bfc-b72b-c01392bd76a4","properties":{"cellContent":"Cardholders and cardholder groups"}},"settings":null},{"content":{"contentType":"tableCell","id":"92454359-9635-41ac-bca0-5f7b586afcec","properties":{"cellContent":"Transitions through their lifecycle states"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"67fcf9e0-ebdc-436a-85ca-cd2e74288f32","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"f1a9015f-6b4f-4440-95d2-ad8f6b176c96","properties":{"cellContent":"Accounts"}},"settings":null},{"content":{"contentType":"tableCell","id":"065fceec-a65c-4982-8637-9ebfa0916a8a","properties":{"cellContent":"Transitions, including closure"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"097014a8-2ac2-4e28-848c-862eb433e9d6","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"3a6879a6-c820-4169-a13f-2ae3f2c4977d","properties":{"cellContent":"Cards"}},"settings":null},{"content":{"contentType":"tableCell","id":"168a8b6f-5e5c-4b77-bf19-b7f61d3124fb","properties":{"cellContent":"Transitions through inactive, active, on hold and closed"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"1f6bf757-414e-48a9-9cfc-f998638dc576","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"d90c992c-a7d5-45e5-b318-074c1e14801f","properties":{"cellContent":"Products"}},"settings":null},{"content":{"contentType":"tableCell","id":"71249901-f642-41cb-8128-848115ed7117","properties":{"cellContent":"Product-level changes"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"0ab94a59-589d-4105-915d-8a01ffb930cc","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"9302e698-c984-4b39-ace9-a046aa104feb","properties":{"cellContent":"PINs"}},"settings":null},{"content":{"contentType":"tableCell","id":"33f68e7f-2b52-4557-8215-0ffca9e0a75f","properties":{"cellContent":"PIN events"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"188944b8-8cac-40fe-879f-6dd17617d04f","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"e1bd699a-3641-4eeb-8dc9-06734d15da59","properties":{"cellContent":"Digital wallet tokens"}},"settings":null},{"content":{"contentType":"tableCell","id":"81f1727b-3668-4d6d-8c22-628afe9d88c2","properties":{"cellContent":"Provisioning and token lifecycle"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"40d005f1-fe51-49c3-a742-3fd43560cc5d","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"28c79c72-965a-43be-8255-172030688126","properties":{"cellContent":"Transactions"}},"settings":null},{"content":{"contentType":"tableCell","id":"8e8b6c0c-6b79-4457-84d7-89612244a664","properties":{"cellContent":"Authorization, clearing, reversal, settlement and expiry"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"26021906-33f0-4433-a435-a775a10d1852","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ed7ffab5-0c5c-47b6-ac44-1a0e3573aebd","properties":{"cellContent":"3-D Secure"}},"settings":null},{"content":{"contentType":"tableCell","id":"7996d38b-c21f-4e0f-a17e-678ea1ddaef5","properties":{"cellContent":"Authentication outcomes"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"46693546-a163-4a05-918b-dd1f11b7cdde","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"be912018-ccf0-4c19-8e73-706d73c18145","properties":{"cellContent":"Delegated approval stand-ins"}},"settings":null},{"content":{"contentType":"tableCell","id":"0917fac4-12c4-4f74-9719-6f6a7bd4956b","properties":{"cellContent":"Stand-in becoming active, and returning to normal"}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"e43ef628-5dcf-4f4e-8f01-118940c7bab1","properties":{"text":"That list grows. The framework is built so a new event type, or a whole new category, can be published through the existing registration, filtering, delivery, persistence, replay and retry machinery without anything changing on your side beyond deciding whether you care about it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"5ebbcc26-16a4-4e7a-a352-c81ddc009031","properties":{"sectionText":"Every delivery is signed"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"5c4645cf-0d4b-4411-9fd5-a8c1aa576569","properties":{"text":"TXN signs every webhook delivery using HMAC-SHA256 with the signing secret from your configuration. The delivery carries the signature, a timestamp and the webhook identifier as headers, and the timestamp forms part of what is signed. So verifying a delivery means checking the signature against the body and the timestamp together rather than the body alone."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"9261ed1b-bb19-4734-987f-be29afb322a8","properties":{"alertTitle":"Verify the signature before you act on the payload.","alertContent":"Your webhook endpoint is a URL on the public internet that accepts posted data claiming to be from TXN. The signature is the only thing that distinguishes a real delivery from anything else that finds the address. Verify it on every request, including the ones that look routine, and reject anything that fails rather than processing it and logging a warning. Because the timestamp is part of the signed material, a replayed old delivery is detectable too.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"924e9f89-da0d-4612-9257-25a824b64b0e","properties":{"sectionText":"What a payload will never contain"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"f3f2f06a-d22b-4f47-8c2d-99310b056659","properties":{"text":"Webhook payloads never carry the full card number, the security code, a PIN or PIN block, or track data. That is a hard restriction rather than a default. If your processing needs one of those values it has to come from the PCI-scoped read on the card itself, under the access controls that apply there, and not from an event."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"36550437-8dcf-4665-8232-ff1fd3b0d4f4","properties":{"sectionText":"When a delivery fails"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"1a41fb3b-6050-4398-9512-24a809a76455","properties":{"text":"A failed delivery is retried automatically, with the interval increasing between attempts so a destination that is already struggling is not made worse. Both the intervals and the maximum number of attempts are configurable. Every attempt is recorded separately, and each one carries the original payload, the original headers and the original event identifier rather than a regenerated version. A successful retry stops the process immediately."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"537a2a35-afc6-45ca-b978-d6728abd7c35","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"2341576d-4b3c-4bf2-b6c5-2e6a141f9131","name":"Ss Webhooks Delivery Flow Dark","mediaType":"Image","url":"/media/2kobpfkv/ss-webhooks-delivery-flow-dark.png","extension":"png","width":2400,"height":850,"bytes":295889,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"1e740a1d-67c4-4f71-b4b7-8d65fdf3123e","name":"Ss Webhooks Delivery Flow Light","mediaType":"Image","url":"/media/sladfkfn/ss-webhooks-delivery-flow-light.png","extension":"png","width":2400,"height":850,"bytes":288373,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e37c7677-3f98-4e54-bf03-78b4617deb7d","properties":{"sectionText":"When retries run out"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"e1285d1c-ad10-4a91-9a35-d6eeec9a4e35","properties":{"text":"An event that exhausts its retries is marked failed and kept. It is not discarded and it does not silently vanish from your event stream. Failed events remain available for inspection and for replay, which is the recovery path when the cause was something at your end that has since been fixed."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4fb2990f-c00e-4e33-af7c-ab9342ab4602","properties":{"sectionText":"A struggling endpoint is paused rather than hammered"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"06dad1f2-4974-471c-a38f-7de1892a28f4","properties":{"text":"Endpoint health is monitored, and delivery to an endpoint that is failing can be paused rather than continuing to push events at it. Events generated while delivery is paused are retained, and delivery resumes automatically once the endpoint recovers. From your side the visible effect of an outage is a gap followed by a catch-up, not a hole.\n\nWorth knowing too that events are created whether or not a subscription exists for them and whether or not your endpoint is healthy. Subscribing to a category later, or bringing an endpoint back up, does not mean the events from the quiet period never existed: they were generated, persisted and remain addressable."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e9885ad0-e0a2-49ca-a294-0c48171c35eb","properties":{"sectionText":"Everything is persisted, not just the successes"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"0b76020a-baf5-4099-8dbb-d3277b5155af","properties":{"text":"For every event TXN records the payload, the headers, the delivery metadata, each delivery attempt, the status, the timestamps and the response received. Those records survive a service restart or a failover. That is what makes the next section possible, and it is also what lets you answer \u0022did you send it and what did we say\u0022 without having to have logged it yourself."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"9f208fbe-df81-4335-a0e5-8cb78d917ed8","properties":{"sectionText":"Replaying an event"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"019cfb54-a06a-49c9-8fca-7d0d96454268","properties":{"text":"A persisted event can be replayed to a webhook configuration. The replay resends the original stored payload rather than regenerating it, keeps the original event identifier, and creates a new delivery attempt record so the history shows what happened. TXN validates that the configuration exists, that it is active, that the event exists and that the event belongs to that configuration. Replay is refused for a configuration that has been disabled or revoked, and the endpoint is rate limited."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"70f93272-1ab3-4584-b386-ecb5f04fc6a8","properties":{"alertTitle":"A replay is indistinguishable from the original, so your handler has to be idempotent.","alertContent":"The replayed payload is byte-identical to the one originally sent and carries the same event identifier. Nothing in it says \u0022this is a replay\u0022. A handler that creates a record on every event it receives will create a second one. Key your processing on the event identifier and treat a repeat as already handled: this is also what protects you against a retry that succeeded at TXN\u0027s end but appeared to fail at yours.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"07231314-e784-4c9e-8c3f-c176e69a114f","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"371235ab-c02c-4862-9c57-f684e2ef69af","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"bc4bf9ca-f08e-4634-ae18-8b9187d4f85d","properties":{"cardTitle":"Health Checks","cardText":"Confirming a destination is reachable before you depend on it.","pageLink":{"contentType":"guidePage","name":"Health Checks","createDate":"2026-11-14T13:47:02.173Z","updateDate":"2026-11-15T16:32:46.023Z","route":{"path":"/103/staying-in-sync/health-checks/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"d2724a96-2414-4d80-a111-986fcd0b18e5","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"38ee7812-7b30-472d-a406-62381224761c","properties":{"cardTitle":"Transactions","cardText":"The lifecycle events your webhooks report.","pageLink":{"contentType":"guidePage","name":"Transactions","createDate":"2026-09-16T06:23:22.427Z","updateDate":"2026-11-15T16:32:47.27Z","route":{"path":"/103/money-movement/transactions/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e79295d5-99a5-4e5f-859c-c15d73178622","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"64f2add1-db5e-4092-baec-2f3ee5abeb1a","properties":{"cardTitle":"Retries and Idempotency","cardText":"Repeating a call safely when you do not know whether it landed.","pageLink":{"contentType":"guidePage","name":"Retries and Idempotency","createDate":"2026-11-14T09:22:41.407Z","updateDate":"2026-11-15T16:32:39.84Z","route":{"path":"/103/api-essentials/retries-and-idempotency/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"182084cf-2e4d-406f-a1e4-9a1dcba5f19d","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"e3f1fb85-1f28-42e5-aa92-a169c897178c","properties":{"prevPageTitle":"Push Provisioning","nextPageTitle":"Health Checks"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"How TXN Works","createDate":"2026-09-16T10:34:03.717Z","updateDate":"2026-11-15T16:32:40.527Z","route":{"path":"/103/working-with-txn/how-txn-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1e283b0f-5937-4e57-87cb-9402b1cf9f3b","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"ebc1075f-9014-4513-9723-6b7f678673a5","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"65dab594-ddd1-4aa3-9ef4-63aacecb3983","properties":{"title":"How TXN Works","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"faf8192b-5a10-4c80-b99e-59a945f75fd0","properties":{"text":"Running a Card Program means sitting between a card scheme, a BIN Sponsor and every merchant a cardholder ever pays. Someone has to authorize each transaction in real time, hold the scheme membership and banking relationship that make a card legitimately spendable, and run the technology deciding, at the moment a card is tapped, whether a payment goes through. Most fintechs, digital banks and embedded finance businesses that want to offer cards do not want to build or become any of that."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"87d143ac-6404-4016-b15a-d5d2f21291dd","properties":{"text":"TXN is an issuer-processor: one platform providing both the issuing side, creating and managing the cards, cardholders and accounts a Card Program needs, and the processing side underneath it, authorizing and recording what happens each time one of those cards is used. You integrate against the Core API to build your Card Program on top of it, and TXN provides the scheme connectivity your cards need to work."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"185b9d08-9a56-47ab-a6aa-08a8a475e054","properties":{"sectionText":"What TXN provides"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"7143ef80-de11-44ca-8f5b-98f995de0953","properties":{"text":"TXN is one programmable model exposed through four surfaces.\n\n- The Core API is what your engineering team integrates against.\n- Control Center is where your operations team works once a Card Program is live.\n- The Knowledge Hub holds the guides and reference you are reading now.\n- The Intelligent Assistant is the AI layer across the platform, where AI systems assist and a named person approves any high-impact change.\n\nUnderneath those, TXN provides the scheme and network connectivity a Card Program needs, so a card issued through TXN can actually be used at a merchant. Around them sits the support to run a Card Program: guided onboarding, due diligence, a structured go-live and ongoing service.\n\nIssuing and processing are the two halves of what happens underneath, and it helps to keep them distinct. Issuing covers the lifecycle of a card and the people behind it: creating cardholders, opening the accounts their cards draw against, and issuing physical or virtual cards against both. Processing is what happens once a card exists and is used: authorizing each transaction, applying the controls you have configured, and recording the result. A new integration starts on the issuing side, since nothing can be processed until a cardholder, an account and a card exist."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"b69dc93f-7678-4c35-9fc9-8be0438e4295","properties":{"sectionText":"The arrangement underneath the platform"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"009dc15e-2372-4c10-978f-9021f80b5959","properties":{"text":"A card only works because a card scheme and a regulated bank stand behind it. TXN\u0027s role is to sit between your Card Program and the scheme, so your business does not have to become a scheme member itself.\n\nScheme membership and the BIN your Card Program issues on sit with a BIN Sponsor. The Program Owner secures that relationship, not TXN. What TXN provides is the connectivity that makes a card issued under your BIN usable at a merchant, and the platform that issues and authorizes against it.\n\nOn the platform, the configuration a set of cards shares is held on a product: limits, behavior and defaults that every card issued against it inherits. Change a product and every card under it is affected, which is why product changes carry more weight than most."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"0a28fc29-c951-4fa1-b9d1-6f09e9e7b4fa","properties":{"sectionText":"The roles in a Card Program"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"5ec4a3d2-a988-4f66-a657-e96426406d7d","properties":{"text":"These are roles rather than necessarily separate businesses. You may hold more than one."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"2223fd45-a838-44ae-adb8-4c0417add82a","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"75dbbe3c-edc2-4931-81e4-b54fd333c3e8","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"c78f6720-93fd-4590-9495-75407386a80c","properties":{"cellContent":"Role"}},"settings":null},{"content":{"contentType":"tableCell","id":"7b7c0c36-3346-42c5-9df6-cf070c2b15fb","properties":{"cellContent":"What it does"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"a61c7b01-9552-498a-a5f4-411bbc6d9b0e","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"51721da3-53c0-4e03-bbb7-5bdc650d4fda","properties":{"cellContent":"Card scheme"}},"settings":null},{"content":{"contentType":"tableCell","id":"389d30d8-9431-46c9-a5f0-e2d0d659f124","properties":{"cellContent":"Visa or Mastercard. Sets the rules and allocates BIN Ranges to its members."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"8bbe14b8-1775-4aeb-b387-9548c48affb7","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"1dc3ffef-ef78-43e4-870d-a63896f6440e","properties":{"cellContent":"BIN Sponsor"}},"settings":null},{"content":{"contentType":"tableCell","id":"0f84df02-ca15-4765-ab71-1538dcf62b77","properties":{"cellContent":"Holds scheme membership and sponsors the BIN your Card Program issues on. Carries the regulatory license and the settlement obligation to the scheme. The Program Owner secures this relationship, not TXN. Also called a Sponsoring Bank."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"f8648d34-c350-4cff-81fb-dcd4f0a86dde","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"6d03fdf7-d953-408a-a847-a2daeba289ac","properties":{"cellContent":"Program Owner"}},"settings":null},{"content":{"contentType":"tableCell","id":"97c990ab-a0d6-4a62-ab3e-4d58319a4415","properties":{"cellContent":"Runs the Card Program day to day: cardholder onboarding, the application your customers use and the product experience built around the card."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"20605f8d-745c-4e45-847d-fb779f84b148","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"8c703cc8-d78b-4845-9537-0d1380204c07","properties":{"cellContent":"Program Manager"}},"settings":null},{"content":{"contentType":"tableCell","id":"857add51-305f-4942-b51e-2e4de8466a4b","properties":{"cellContent":"A role taken on to manage one or more Card Programs, including the relationship with the BIN Sponsor. The BIN Sponsor can itself be the Program Manager. Not the same as the Program Owner."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"173dc516-f1c0-4c18-b3ec-810ceecde709","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"592fd4c9-b0c2-4bf6-a875-9ff76ebd2677","properties":{"cellContent":"TXN"}},"settings":null},{"content":{"contentType":"tableCell","id":"457eee4e-a80a-470c-b76b-ca697bf234d2","properties":{"cellContent":"The issuer-processor. Runs the technical layer: issuing cards, cardholders and accounts, authorizing transactions, and carrying those messages to and from the scheme."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"3e17e25b-4b88-4d47-a305-006869ba09c1","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"c1480349-0d8e-4211-a4b8-4b5980e2c812","name":"Wwt How Txn Works Roles Dark","mediaType":"Image","url":"/media/y1eb235h/wwt-how-txn-works-roles-dark.png","extension":"png","width":2400,"height":1120,"bytes":283955,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"726ead6e-d26f-4d78-95db-381bc09c3da5","name":"Wwt How Txn Works Roles Light","mediaType":"Image","url":"/media/2ftdrrag/wwt-how-txn-works-roles-light.png","extension":"png","width":2400,"height":1120,"bytes":280547,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"f14914f5-b896-497d-9b80-87af7620e741","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"2c11d50e-1518-4987-82d6-1d2c072f03fd","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"b831e6a2-776b-48a9-8987-1915ceac2e63","properties":{"cardTitle":"Core Objects","cardText":"The objects a Card Program is built from, and the order you create them in.","pageLink":{"contentType":"guidePage","name":"Core Objects","createDate":"2026-09-16T06:20:31.817Z","updateDate":"2026-11-15T16:32:39.203Z","route":{"path":"/103/getting-started/core-objects/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"0b97009e-ae9c-4b9b-a63d-ec7d5bd5c0c4","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"d8d90a30-5165-4731-9392-c1b0cf6f3d47","properties":{"cardTitle":"Control Center","cardText":"The operational interface your team works in once a Card Program is live.","pageLink":{"contentType":"guidePage","name":"Control Center","createDate":"2026-09-17T10:20:00.54Z","updateDate":"2026-11-15T16:32:46.61Z","route":{"path":"/103/getting-started/control-center/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dad6c052-ee94-4769-96a3-4ecef68cef59","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"4dfd985b-d621-41cb-a13c-7383f7d26423","properties":{"cardTitle":"Intelligent Assistant","cardText":"The AI layer across the platform, and how your own agents connect to it.","pageLink":{"contentType":"guidePage","name":"Intelligent Assistant","createDate":"2026-09-17T10:41:28.027Z","updateDate":"2026-11-15T16:32:38.773Z","route":{"path":"/103/getting-started/intelligent-assistant/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"062f45f3-7255-4872-b13b-514b87f1744e","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"9aa95362-f5c2-4810-9228-eeaf152219f8","properties":{"prevPageTitle":"Intelligent Assistant","nextPageTitle":"Responsibilities"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Transaction Lifecycle","createDate":"2026-11-14T14:52:32.293Z","updateDate":"2026-11-16T06:59:29.687Z","route":{"path":"/103/payment-concepts/transaction-lifecycle/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"209c1bc0-bf02-4c6c-a7b1-75403bb43d66","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"baab0a52-59b6-4b5f-bfe0-8047dfcb8342","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"694f99b2-ed2d-400e-a0d4-882548928dbb","properties":{"title":"Transaction Lifecycle","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"24dfaf91-6dcb-40b7-a882-802483b3d124","properties":{"text":"A card payment is a sequence of separate steps rather than a single event. This page follows a payment from authorization through clearing to settlement, and then through what can happen to it afterwards. It explains what each step does to the balance a cardholder sees.Card payments carry a vocabulary of their own, and most of it is assumed rather than explained. This page defines the terms you will meet in these guides, in scheme documentation and in conversation with your BIN Sponsor. Terms that name something TXN builds are defined briefly here and in full on the page that owns them."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"91b03fc9-1a17-4fe5-b89d-18372b1151bf","properties":{"text":"Each step of a card payment does a different job, and each changes what the cardholder can spend in a different way. This page takes them in order and shows where a payment can stop, reverse or be disputed along the way.\n\nTerms used here are defined on Payment Terms A to Z. How TXN records each step is covered on Transactions."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"6de4878e-6c50-496d-8e03-cf02e43b5365","properties":{"sectionText":"How a card payment moves"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"26654186-6dcc-4f5e-be1b-1cd92e4392d6","properties":{"text":"A card payment involves five parties and three steps. A cardholder pays a merchant. The merchant\u0027s bank, the acquirer, passes the payment to the card network, which carries it to the issuer-processor behind the card. TXN is the issuer-processor, and a BIN Sponsor stands behind its cards.\n\nIn the common dual-message structure the three steps arrive in this order: Authorization asks whether the payment can go ahead, Clearing sends the final amount, and Settlement moves the money. Single-message programs combine the first two."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"0281cf6b-069e-4c4d-8cf5-f558ea5741aa","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"eadc69ee-c0a8-40e2-91a0-7df127bf22fe","name":"Gs Payment Concepts Card Payment Dark","mediaType":"Image","url":"/media/mgrjuxgb/gs-payment-concepts-card-payment-dark.png","extension":"png","width":2400,"height":1040,"bytes":226884,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"1cfe899f-950b-4169-be8b-fde7968980e2","name":"Gs Payment Concepts Card Payment Light","mediaType":"Image","url":"/media/cbblrktc/gs-payment-concepts-card-payment-light.png","extension":"png","width":2400,"height":1040,"bytes":225061,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"5ce0c8cc-4088-4b62-8d1e-a484ad1de54a","properties":{"sectionText":"Authorization"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ecef1551-b5af-4942-b2ac-5e317405540c","properties":{"text":"Authorization is the real-time question of whether a payment may go ahead. The merchant\u0027s request travels from the acquirer through the card network to the issuer-processor, which decides against the card\u0027s controls and available balance and returns an answer. TXN makes that decision unless your Card Program uses Delegated Approval, in which case your own systems decide.\n\nAn approval reserves the amount against the available balance and returns an authorization code. It does not move money. The cardholder\u0027s available balance falls, while the ledger balance is unchanged until the payment settles."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"92e0abcb-d770-4316-ac38-d26d78014948","properties":{"sectionText":"Clearing and settlement"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"d2a86971-4f56-4355-861c-bff27d37a694","properties":{"text":"Clearing is the exchange of transaction detail between the acquirer and the issuer after a payment has been authorized. The acquirer submits a presentment, the clearing record for the transaction, and the issuer matches it to the earlier authorization. Clearing determines the final amount and what will be settled. No money moves at this stage.\n\nBefore clearing, the merchant captures the authorization, which finalizes it so that the money can move.\n\nSettlement is the movement of money between the institutions involved, after clearing has determined what is owed. When the payment settles, the ledger balance catches up with what the available balance already showed. How a clearing finds its authorization is covered on Transactions."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e2d1202f-c5b5-4e1a-b0ef-2dab58a4ab9b","properties":{"sectionText":"After the payment"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"a5d4f747-26ac-4c57-bbfc-5d7450f03718","properties":{"text":"A payment can change after it has been authorized.\n\nA reversal cancels an authorization before it clears and releases the amount that was held. A hotel releasing a pre-authorization is the usual example. A refund returns money to the cardholder after a transaction has cleared, and the merchant initiates it. A chargeback is the forced return of funds from the merchant to the cardholder after a dispute is upheld, and it follows scheme rules and timelines.\n\nA payment that is authorized but never captured by the merchant eventually falls away, and the held amount is released."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"62d8d0c6-6e49-42c7-9c8d-79c4192d2c41","properties":{"sectionText":"What the balance shows"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"142230d4-72f8-409e-85a0-04276a95605c","properties":{"text":"Two balances describe the same account at different moments. The available balance is what can be spent now: the ledger balance less pending transactions and holds. The ledger balance is cleared, settled funds only.\n\nDuring a payment the available balance moves first, at authorization, and the ledger balance moves later, when the payment settles. A balance that shows a hold long before anything settles is the dual-message structure at work. How TXN records each step is covered on Transactions."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"321e142b-5f10-4e51-bb1e-2799974ffea0","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"2634b4fc-8272-43b9-9852-a90a1b9300a5","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"6122eb49-a5a9-4d48-9f67-ae24843ac016","properties":{"cardTitle":"Payment Terms A to Z","cardText":"Definitions for the terms used on this page and across the guides.","pageLink":{"contentType":"guidePage","name":"Payment Terms","createDate":"2026-09-18T14:44:39.46Z","updateDate":"2026-11-16T06:59:32.047Z","route":{"path":"/103/payment-concepts/payment-terms/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b72be41a-a634-425c-ae8b-4ca31e6dffa0","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"82e9aeb8-7121-42a0-a9b8-cc21f7c11f0e","properties":{"cardTitle":"How TXN Works","cardText":"What an issuer-processor is, and the roles behind a Card Program.","pageLink":{"contentType":"guidePage","name":"How TXN Works","createDate":"2026-09-16T10:34:03.717Z","updateDate":"2026-11-15T16:32:40.527Z","route":{"path":"/103/working-with-txn/how-txn-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1e283b0f-5937-4e57-87cb-9402b1cf9f3b","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"10db214f-9fa5-4712-8962-3a086a45dae9","properties":{"cardTitle":"Transactions","cardText":"How TXN records each step of a payment.","pageLink":{"contentType":"guidePage","name":"Transactions","createDate":"2026-09-16T06:23:22.427Z","updateDate":"2026-11-15T16:32:47.27Z","route":{"path":"/103/money-movement/transactions/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e79295d5-99a5-4e5f-859c-c15d73178622","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"8481b19b-00d0-4b0a-a30d-dd53d46c6092","properties":{"prevPageTitle":"From First Call to Go-Live","nextPageTitle":"Payment Terms"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Responsibilities","createDate":"2026-09-17T15:55:58.67Z","updateDate":"2026-11-15T16:32:42.99Z","route":{"path":"/103/working-with-txn/responsibilities/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"56c5fab4-4ca7-4e79-98c6-543faaa61044","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"fb080762-ba10-4eb1-9cc5-f58e765771d1","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"505b5f5b-3e24-42dc-a843-24fc6f07e88a","properties":{"title":"Responsibilities","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"42b723ac-e3ad-48ad-a222-43fc7207bd9b","properties":{"text":"Building a Card Program on TXN means TXN runs the platform and your team builds and operates everything that sits on top of it. This page sets out where that line falls on the technical side, so you can scope the work before you start rather than discover a gap during integration."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"e71b0848-0a69-4ccc-950c-33608e99bfba","properties":{"text":"The short version: TXN is responsible for the platform being there, being correct and being connected to the card schemes. You are responsible for your integration, your data, your credentials and anything your cardholders see."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3eaf54e4-768f-4920-8fb8-fdc4e092666e","properties":{"sectionText":"What TXN runs"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"a61c4149-61bc-4361-9919-2c54db233703","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"243d9738-45b8-4ac0-a542-cad350971d76","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"94e3fb7d-6ce5-4c3f-a9b8-eca3cdcf11ee","properties":{"cellContent":"Area"}},"settings":null},{"content":{"contentType":"tableCell","id":"c67696b1-479c-409f-a09d-11061759595f","properties":{"cellContent":"What TXN is responsible for"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"d7098ac2-12eb-4c6e-a3ae-7eb10a5cdffc","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"9893faf2-7222-4cb7-a319-c8d681d94bbf","properties":{"cellContent":"The platform"}},"settings":null},{"content":{"contentType":"tableCell","id":"d7195603-e90c-4642-8b3f-e3b4405fba84","properties":{"cellContent":"Running the Core API, Control Center and the Knowledge Hub, and keeping them available."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"7e37c34d-5fc5-43e3-8d45-eac1282a9a4f","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"fb402d65-37e4-448c-b68f-e8939eeaaf29","properties":{"cellContent":"Authorization"}},"settings":null},{"content":{"contentType":"tableCell","id":"eea8caef-04a5-4f88-ad5e-bdae496fb8ad","properties":{"cellContent":"Deciding each transaction in real time against the controls and balance, unless your Card Program uses Delegated Approval."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"02ca225e-bc84-4765-99e7-28ef05ab9c6d","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"43637c51-337c-44b3-9e2e-0d9aebfa91fa","properties":{"cellContent":"Clearing and settlement"}},"settings":null},{"content":{"contentType":"tableCell","id":"d954e65f-53ac-4c8a-9fa5-27c84995cfa4","properties":{"cellContent":"Processing the movement of funds behind each transaction."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"dfe878f4-408a-4d9f-8039-b9219bdc9e13","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"4c76609d-b959-4e2e-a0cb-2a0bbdfbb1a6","properties":{"cellContent":"Scheme connectivity"}},"settings":null},{"content":{"contentType":"tableCell","id":"3e9d1a6d-4d2c-41a3-b73e-e27d44abe5a0","properties":{"cellContent":"The connection to the card scheme that makes a card issued under your BIN usable at a merchant."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"732ee6ca-f1a2-4427-a490-30ba543c4a9e","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"7400cc02-37d5-452a-b5c9-b7c41dd31122","properties":{"cellContent":"Card production"}},"settings":null},{"content":{"contentType":"tableCell","id":"baabd385-8443-414c-9c91-0ec6e26ba4f7","properties":{"cellContent":"Sending physical card orders to the fulfillment provider and tracking them through to dispatch."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"83138ecd-895a-43d1-9b26-b507eb71184c","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"40f2e2f6-871e-4be2-9838-d5da06992bf7","properties":{"cellContent":"3-D Secure"}},"settings":null},{"content":{"contentType":"tableCell","id":"842910b1-2e98-430b-9736-7d54dec14011","properties":{"cellContent":"Running 3-D Secure authentication and recording authentication events."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"3762a8e9-d04c-4c35-a496-7ca39fd291d8","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"50249ab1-a807-403a-a1aa-6ebe5acf23d5","properties":{"cellContent":"Environments and credentials"}},"settings":null},{"content":{"contentType":"tableCell","id":"acd2ac1b-9c0d-4ebd-ae75-b37d2ae08b4e","properties":{"cellContent":"Provisioning your UAT and Production environments and issuing the credentials for each. The Public Sandbox is open to everyone."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"2d35aa4f-558e-4a21-ae11-405f7f09e4b0","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"9de056af-967a-4fd0-96ef-fd30ccf7e543","properties":{"cellContent":"Change management"}},"settings":null},{"content":{"contentType":"tableCell","id":"fdcc71ff-ff17-49e2-a5e9-24eb05d74946","properties":{"cellContent":"Giving advance notice of breaking changes and keeping a prior API version available through the transition."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4bff57ed-91a5-4180-8a8e-80b24bc742ab","properties":{"sectionText":"What your team builds and runs"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"c2c1b9dd-5a41-49a8-a928-66beff4109df","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"14f9e67b-fdab-47c6-8412-ad49881f883e","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"b68ff238-3bff-468c-b90a-ed7b0e01bc03","properties":{"cellContent":"Area"}},"settings":null},{"content":{"contentType":"tableCell","id":"c0e6e643-5a83-4e79-bd47-bbfd47eb5bfb","properties":{"cellContent":"What you are responsible for"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"aca4d51d-0be5-4a96-a590-0e29c9fd5f06","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"e2db5e9b-67f9-48f3-bc58-fba81fc43caf","properties":{"cellContent":"The integration"}},"settings":null},{"content":{"contentType":"tableCell","id":"e3d58695-ad66-4662-bb5e-2522865ba38f","properties":{"cellContent":"Building and maintaining your integration against the API, at your own cost, and keeping it current as the API versions forward."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"f73019a0-470a-456d-9e58-b12b7d16fa49","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"b6355ba2-12f1-4381-aa45-a6d5ebc4e557","properties":{"cellContent":"Your infrastructure"}},"settings":null},{"content":{"contentType":"tableCell","id":"8df47600-0878-412f-a772-a86fee16697e","properties":{"cellContent":"Your systems, your network and your connectivity to TXN."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"1824d4d6-3f4e-4b83-b989-9fd10ca02059","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"7e32d8f4-804a-4325-a7ad-7a2af877ee50","properties":{"cellContent":"The BIN Sponsor relationship"}},"settings":null},{"content":{"contentType":"tableCell","id":"9e20dfe0-990a-46c3-9637-fcc57100bdd0","properties":{"cellContent":"Securing the BIN Sponsor that holds scheme membership and the BIN your Card Program issues on. TXN does not provide it."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"e874b451-bafe-4b85-bbd8-04c0390ad58b","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"af41446f-f083-4cfd-b71c-bf614827ed98","properties":{"cellContent":"Creating the objects"}},"settings":null},{"content":{"contentType":"tableCell","id":"7b7ccc4e-6e03-48f6-a986-99ca10d96b26","properties":{"cellContent":"Enrolling cardholders, opening accounts and issuing cards through the API."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"95003dae-a133-423d-9e1a-98f05eac0a60","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"737a186a-6b1d-41de-85f4-e64ee74746ff","properties":{"cellContent":"Data accuracy"}},"settings":null},{"content":{"contentType":"tableCell","id":"64b3900b-4476-46f2-893b-afc2362b2565","properties":{"cellContent":"The completeness and accuracy of everything you send. TXN stores what you provide; it does not correct it."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"b97061a8-23e3-4d86-b07e-a87e6e4330db","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"c1c313bc-7e1f-4603-9ab9-77fef0aae87b","properties":{"cellContent":"The cardholder experience"}},"settings":null},{"content":{"contentType":"tableCell","id":"c5dc5e7c-7f97-47d1-8894-4c72bdc83e2e","properties":{"cellContent":"Your application, your cardholder-facing screens and anything a cardholder reads or touches."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"87e1cc30-adf2-45f1-a919-b4a312591331","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"c84716f2-b8b8-40c9-9ced-7adc3ca8039c","properties":{"cellContent":"Error handling"}},"settings":null},{"content":{"contentType":"tableCell","id":"1d3b367b-9d1a-4d0f-9a03-a00ea7ba269e","properties":{"cellContent":"Retrying safely, honouring rate limits, and reconciling when a response does not arrive."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"67ae735c-8847-4883-99ba-12ccb1b732d5","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"b648d64b-2d82-40a6-b27a-37a14fb2dc11","properties":{"cellContent":"Event delivery"}},"settings":null},{"content":{"contentType":"tableCell","id":"55d09292-9124-4f46-89c3-2e9f18b5d798","properties":{"cellContent":"Hosting and operating the endpoint TXN sends events to, if you consume them rather than polling."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"2acd4dd6-206d-46be-96e2-c923334dd7fd","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"be9789b6-44c5-4fec-80d3-7b6d18e7e82f","properties":{"cellContent":"Credentials"}},"settings":null},{"content":{"contentType":"tableCell","id":"d621a83c-21de-4572-8348-9a9463f2e036","properties":{"cellContent":"Storing, rotating and protecting your API credentials, and never sharing them between systems or people."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"ba20a802-77d0-4a20-8ef1-10e8624ebaca","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"4c684c8d-c67a-45bb-93ef-7ceb5ad0ca21","properties":{"cellContent":"Control Center access"}},"settings":null},{"content":{"contentType":"tableCell","id":"b876fbc3-5990-424e-bbe7-cabc8fe4630a","properties":{"cellContent":"Multi-factor authentication for every user, role-based access, and removing access when someone leaves."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"a6927a4b-962e-438e-b9d3-cc0e3dc5e414","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"4311ee30-90a9-455d-9653-48709a65aff0","properties":{"cellContent":"Testing"}},"settings":null},{"content":{"contentType":"tableCell","id":"866cca74-b663-4023-8293-58af885e76e1","properties":{"cellContent":"Completing your integration testing in UAT before go-live, and keeping a working test card available afterwards."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"d67eed2d-4f58-4575-8918-2dc5e625f249","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"33ce0c88-001c-4fde-a71d-b74411628455","properties":{"cellContent":"Monitoring"}},"settings":null},{"content":{"contentType":"tableCell","id":"7cb8d3bc-3531-4c2f-a047-07d323f2ffa5","properties":{"cellContent":"Watching your own side of the integration. TXN monitors the platform, not your systems."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"2ae210a2-72d9-4a87-a91d-0162dbb81ccd","properties":{"alertTitle":"Tell TXN quickly if credentials are exposed.","alertContent":"If you become aware that an API credential has been compromised, or that Control Center access has been used by someone who should not have it, notify TXN within 24 hours. Rotating a credential is straightforward; discovering the exposure late is what causes the damage.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"eace26b8-4349-42c9-b70e-b5bb6c09a893","properties":{"sectionText":"Where the line moves"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"7f233a86-4556-4a20-8615-3d982b32632d","properties":{"text":"Two choices shift responsibility from TXN to you, and both are made early.\n\nDelegated Approval. If your account uses Delegated Approval rather than platform managed funding, you make the authorization decision. That means running a service that answers TXN in real time, every time, inside the scheme\u0027s timeout. The availability of that service becomes yours, not TXN\u0027s, and the Stand-In you configure decides what happens when it does not answer. See Delegated Approvals.\n\nHandling PIN and card data directly. If your Card Program is PCI-certified you can call the operations that return a PIN or full card details. Doing so brings that data, and its compliance scope, inside your systems. If you are not certified, TXN\u0027s hosted screens keep it out. See PINs."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"915c9267-2b79-4f0e-a5cd-f4d947d98f9d","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"42e51311-efb0-44ff-b333-ea4a5cb69f16","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"c1f199ef-e4ed-44b7-9fe7-1c4f6e8db321","properties":{"cardTitle":"From First Call to Go-Live","cardText":"The journey from first conversation to production, and what access opens when.","pageLink":{"contentType":"guidePage","name":"From First Call to Go-Live","createDate":"2026-09-16T10:37:09.553Z","updateDate":"2026-11-15T16:32:46.457Z","route":{"path":"/103/working-with-txn/from-first-call-to-go-live/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"d6f8f50b-69d9-4bbf-8fe3-83fdbbe71cf6","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"b3a308bd-33d6-4230-b7e2-9dea33528fba","properties":{"cardTitle":"Environments","cardText":"The three environments and what each is for.","pageLink":{"contentType":"guidePage","name":"Environments","createDate":"2026-09-16T06:21:03.5Z","updateDate":"2026-11-15T16:32:45.067Z","route":{"path":"/103/getting-started/environments/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b230a635-a702-4570-a189-ce295a6165dc","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"011b5695-fca1-45c8-a762-37ff77218195","properties":{"cardTitle":"Go-Live Checklist","cardText":"What has to be true before you can move to production.","pageLink":{"contentType":"guidePage","name":"Go-Live Checklist","createDate":"2026-09-16T11:15:47.56Z","updateDate":"2026-11-15T16:32:39.463Z","route":{"path":"/103/going-live/go-live-checklist/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"12248e91-a4b4-4166-aa39-5c888cb4f7dc","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"dd14702e-632a-472b-be31-4f11b08eef09","properties":{"prevPageTitle":"How TXN Works","nextPageTitle":"From First Call to Go-Live"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Push Provisioning","createDate":"2026-11-14T13:46:40.343Z","updateDate":"2026-11-15T16:32:43.463Z","route":{"path":"/103/digital-wallet-tokens/push-provisioning/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"623782dd-77b3-47e5-bf5f-a52fe8a68337","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"e81a7b2c-ad5f-4afb-a58e-b03d1896d288","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"dbd63f2a-5b4c-49b9-92b7-5b7fac7aec5a","properties":{"title":"Push Provisioning","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"eb5eb9e1-6cb3-4285-9280-10dc73ee42e9","properties":{"text":"Push provisioning lets a cardholder add their card to a wallet from inside your app, without reading digits off a piece of plastic. Your part is one call and a handoff. Understanding where TXN\u0027s responsibility stops is most of what makes it work."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"8fc4c87a-5338-4737-8923-934274301481","properties":{"text":"The division of labour is clean. You ask TXN for a provisioning payload, naming the card, the wallet provider and the type of device. TXN validates that the card is eligible and builds a payload in the shape that provider requires, with the right certificates and encryption applied. Your app takes that payload and hands it to the wallet provider\u0027s own SDK. The provider completes the provisioning from there."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"5ae6bfbd-86c7-42f3-88c6-b5380a3b784e","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"ad26ce54-477e-49b7-ba03-650092af3435","name":"Dwt Push Provisioning Handoff Dark","mediaType":"Image","url":"/media/1mcgagyx/dwt-push-provisioning-handoff-dark.png","extension":"png","width":2400,"height":840,"bytes":237907,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"d1703d27-aba8-4398-8a74-f1e479b366e9","name":"Dwt Push Provisioning Handoff Light","mediaType":"Image","url":"/media/vd1dmz4b/dwt-push-provisioning-handoff-light.png","extension":"png","width":2400,"height":840,"bytes":234147,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"f8af0b00-7f31-45b5-9ba5-f2075b43f7e2","properties":{"sectionText":"What TXN does not do"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"37413891-8fb4-44f1-9b82-9c572b6a474b","properties":{"text":"TXN does not talk to the wallet on your behalf and does not complete the provisioning. It produces the payload and records what happened. Everything from the handoff onwards is between your app and the wallet provider, governed by that provider\u0027s current specifications rather than by anything here, which is also why the provider-specific fields differ between Apple and Google and are theirs to define rather than ours."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"b807206f-1bc4-4c2e-9a0a-7ad3db4f0433","properties":{"alertTitle":"A payload in hand is not a provisioned token.","alertContent":"The call returning successfully means TXN has built you a valid payload. It does not mean the card is in the wallet. Provisioning completes only once the wallet provider and the network have done their part, and confirmation comes back after the network token is activated. If your app treats the payload response as the success signal, it will tell cardholders their card is added at the moment it has merely become addable.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"0aba3b2a-6c6b-4d3f-9921-cd5ca8403486","properties":{"sectionText":"The payload expires, and it expires quickly"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"99cc1082-d8fd-421f-b56a-d1bc9409f297","properties":{"text":"The payload is short-lived and intended for a single use. It is returned with its creation and expiry times so your app can tell when it has gone stale. An expired payload is not retried: a new one is requested. Build for that rather than caching the payload and reusing it, because the failure mode of a stale payload is a provisioning attempt that fails for no reason the cardholder can understand."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"9977ba87-786b-4287-a908-249b00f37f97","properties":{"sectionText":"Before any of that, the configuration has to allow it"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"4ce9efe5-76ca-4442-8874-1dfbf2bd789c","properties":{"text":"Push provisioning is refused unless three things are enabled: digital wallet provisioning on the product, the specific wallet provider, and push provisioning as a route for that provider. Each is a separate switch and all three have to be on. A refusal records the reason, so a configuration problem is distinguishable from an eligibility one when you come to investigate."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4ba523f9-2ce2-46ef-8526-7362d7fe123d","properties":{"sectionText":"Presenting the cards a cardholder can add"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"e0147656-f2c1-4d0a-b8e0-b8ce6ddaad10","properties":{"text":"The other half of the experience is in your app. Show only the cards that are actually eligible and not already provisioned, so the cardholder is never offered something that will fail. Show each with its name and its card artwork, following the wallet provider\u0027s presentation requirements. Authenticate the cardholder before provisioning, by password or biometric. Eligibility is checked before the list is drawn, so the list can be built without the cardholder waiting on it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"d398868b-8a65-4db9-9676-c8d4bb650dca","properties":{"alertTitle":"Do not offer a card that is already in the wallet.","alertContent":"A card already provisioned to the wallet on that device should not appear in the list. Offering it produces a confusing failure the cardholder will read as a broken app rather than a duplicate request, and it is entirely avoidable: the tokens already provisioned from a card can be read before the list is drawn.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"8741a512-3a1c-420d-b738-eeb669462296","properties":{"sectionText":"Every attempt is recorded"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"9b55daab-4ab3-48da-a8de-e6c81109bccb","properties":{"text":"Each push provisioning request is recorded with the wallet provider chosen, whether payload generation succeeded, the payload\u0027s creation and expiry times, and the eventual outcome once the provider and network have finished. So an attempt that failed somewhere in the handoff is traceable to the step that failed rather than being a gap between your logs and the wallet provider\u0027s."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"619581eb-0a86-444c-9c70-d8a51cefbe86","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"67d2ede4-2a28-4004-b8a0-d3cfdc7babc9","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"6f51bead-7f7b-4332-a5cd-1bb2653ab982","properties":{"cardTitle":"Digital Wallet Tokens","cardText":"The token this produces, and how it is assessed.","pageLink":{"contentType":"guidePage","name":"Digital Wallet Tokens","createDate":"2026-11-14T13:46:40.313Z","updateDate":"2026-11-15T16:32:42.527Z","route":{"path":"/103/digital-wallet-tokens/digital-wallet-tokens/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"40b1a666-ed74-4f45-8745-d54c19dc8a2c","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"808a060c-6d1d-49a2-a1fe-8e11ea6c6c3d","properties":{"cardTitle":"Replacing a Card","cardText":"What happens to tokens when the card underneath them is replaced.","pageLink":{"contentType":"guidePage","name":"Replacing a Card","createDate":"2026-11-14T13:45:44.953Z","updateDate":"2026-11-15T16:32:41.983Z","route":{"path":"/103/managing-cards/replacing-a-card/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2db9d6c2-7f22-452f-b105-e3f518240751","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"ac004f74-662b-4e39-ab81-a7a15cd13c72","properties":{"cardTitle":"Cards","cardText":"Card eligibility, and the states that affect it.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"0cf22047-07ac-410b-8064-f522ca1dec76","properties":{"prevPageTitle":"Digital Wallet Tokens","nextPageTitle":"Webhooks"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Account Name Inquiry (ANI)","createDate":"2026-09-18T13:01:54.237Z","updateDate":"2026-11-15T16:32:43.603Z","route":{"path":"/103/cardholder-verification/account-name-inquiry-ani/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"6bdc1181-e1d0-4e24-ae33-306200e4d9dd","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"b7ea93e3-520c-4a49-a966-b9cfa504ac97","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"3e0fcc49-943e-411e-9499-00a94c16511d","properties":{"title":"Account Name Inquiry (ANI)","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"7a49fe0c-6379-46af-afb7-27c3c905f623","properties":{"text":"Account Name Inquiry checks whether the name someone has supplied matches the name TXN holds for the cardholder. It runs as a zero-amount authorization, so nothing is charged and no funds are held. Like address verification, it returns a result for you to act on rather than a decision the platform makes for you."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"18a3d442-d047-4b9c-bcaa-14a7e1c024f7","properties":{"text":"A name check answers a narrow question: does the person named on this payment match the person the card belongs to. It is the same kind of check as address verification, applied to the cardholder\u0027s name instead of their address, and it exists for the same reason: to give you something to weigh before money moves. The two are independent. A transaction can pass one and fail the other."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"f0c8d381-5a96-4c3e-8908-3dfce0652bac","properties":{"sectionText":"A zero-amount authorization is not a payment"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"4b3518a0-c56e-4f69-9d60-06ef5bdbb3fe","properties":{"text":"The check is carried out by sending an authorization for no amount. Nothing is charged, nothing is held against the available balance, and nothing later settles. The message exists only to carry the question and return the answer. That is what makes a name check safe to run before a relationship exists rather than as part of a payment the cardholder has already committed to."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"a8f34801-6b41-49e3-ab34-21bd8bfc4deb","properties":{"sectionText":"What gets compared"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ebef26eb-cc19-4842-801c-92147cd7b92c","properties":{"text":"The name supplied with the request is compared against the name TXN holds for the cardholder, and the result comes back with the authorization response. Names are messier to match than postcodes: initials, middle names, married names, transliterations and the order of given and family names all vary legitimately between one system and another. A result that is not a clean match is a prompt to look rather than evidence of anything."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"3c028029-6fed-4137-87de-35dfa12acf1e","properties":{"alertTitle":"The check is only as good as the name you sent TXN.","alertContent":"The comparison is against the cardholder record your integration created. If onboarding captured a shortened name, dropped a middle name, or reversed the name order, a legitimate cardholder will fail the check every time and nothing about the platform will explain why. Name quality at enrollment decides what this check is worth.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"070d9d9b-8a54-41b1-bcbc-570cef8e7c28","properties":{"sectionText":"A result is a signal, not a decline"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"9f0098b1-872d-4e84-88f8-2fd45158d920","properties":{"text":"TXN returns the result. It does not decline on the strength of a name mismatch alone. What a mismatch is worth is a judgment for your program, and reasonable programs land in different places depending on what the check is guarding. If your account uses delegated approval, that judgment sits with the service deciding the authorization."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"03361dc0-5895-40c2-aafa-593368247597","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"efabee5e-ab3b-4c41-8be1-352e4255f90f","name":"Cv Ani Name Check Dark","mediaType":"Image","url":"/media/0eso0wks/cv-ani-name-check-dark.png","extension":"png","width":2400,"height":1060,"bytes":256602,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"9fb19057-c421-4cd4-9403-8438733f3f48","name":"Cv Ani Name Check Light","mediaType":"Image","url":"/media/1bnpokki/cv-ani-name-check-light.png","extension":"png","width":2400,"height":1060,"bytes":257745,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"f1bdc301-c33c-4b70-a4ef-e81974a7dbe2","properties":{"sectionText":"Overriding a result"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"71b0947a-45b8-4283-a25d-32ee75f41647","properties":{"text":"A delegated approval response can override the ANI result outright as part of the decision it returns. That route is governed by the risk and compliance policies you configure, it is fully logged, and it operates within whatever the relevant region mandates. Every result and every override is auditable afterwards."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3703ee7e-bc69-4fbe-96c6-2b2130902215","properties":{"sectionText":"How account name inquiry relates to other objects"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"e4dd1367-5566-4438-9da5-a093119e5269","properties":{"text":"The name being checked is the one held on the cardholder. The check runs as a zero-amount authorization against the card. If your account uses delegated approval, the source deciding that authorization can override the result before it is applied. Address Verification is the same idea applied to the cardholder\u0027s address rather than their name."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3b90c919-81ad-4fdd-90b7-c30d582f453b","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"f99aac2f-41b5-4e0e-b686-0442dbe21bc1","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"becddf3f-029a-4c03-9f8b-be9aa98788ab","properties":{"cardTitle":"Address Verification (AVS)","cardText":"The same check applied to the cardholder\u0027s address.","pageLink":{"contentType":"guidePage","name":"Address Verification (AVS)","createDate":"2026-09-18T13:01:45.19Z","updateDate":"2026-11-15T16:32:42.673Z","route":{"path":"/103/cardholder-verification/address-verification-avs/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"4350272d-62cc-404f-b0e2-0efb15d7ae19","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"8fd7fee2-e1cd-4f73-b8c4-1651d13d3b59","properties":{"cardTitle":"Cardholders","cardText":"Where the name is held, and why capturing it accurately matters.","pageLink":{"contentType":"guidePage","name":"Cardholders","createDate":"2026-09-16T06:22:18.73Z","updateDate":"2026-11-15T16:32:44.66Z","route":{"path":"/103/foundational-objects/cardholders/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"a615ed27-e2f2-4afe-b764-4fc583ef8f6c","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"57026287-df51-40df-9309-9dce0c531df8","properties":{"cardTitle":"Delegated Approvals","cardText":"How a decisioning service can override a verification result.","pageLink":{"contentType":"guidePage","name":"How Delegated Approval Works","createDate":"2026-09-16T06:26:34.807Z","updateDate":"2026-11-15T16:32:47.123Z","route":{"path":"/103/delegated-approvals/how-delegated-approval-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e47adf53-2c39-46bb-bb12-ff0c765b075c","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"9c80548c-19b4-43b0-9834-6f3cbee13b16","properties":{"prevPageTitle":"Address Verification (AVS)","nextPageTitle":"How Delegated Approval Works"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Delegated Approval Sources","createDate":"2026-09-16T06:26:56.91Z","updateDate":"2026-11-15T16:32:46.167Z","route":{"path":"/103/delegated-approvals/delegated-approval-sources/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"d321a15f-1299-48cb-a8cb-11440abd0a74","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"b85512b2-444f-4572-9483-7841b796d801","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"5cd7cc3f-93d0-47c9-9151-da79d789dde7","properties":{"title":"Delegated Approval Sources","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"e78c24d6-52b1-437d-9ad5-16eb2a668b16","properties":{"text":"A delegated approval source is the record telling TXN how to reach the system that makes your authorization decisions: the address it calls, the credentials it presents, and how long it waits for an answer. The decision logic itself never leaves your side. This is only the connection."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"21c95abe-0eb2-4ffc-bb7f-f9885b6ac520","properties":{"text":"Registering a source captures how TXN reaches you and nothing about what you decide. A name and description for your own reference, the address TXN calls, the credentials it presents when it gets there, a timeout governing how long it waits, and a switch controlling whether the source is in service. That is the whole record. Nothing in it configures decision logic, because that lives entirely in the system at the other end."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"0b6c26e6-d62e-4bf4-a1a0-89b120539e2c","properties":{"alertTitle":"These credentials are TXN\u0027s, not yours.","alertContent":"The credentials on a source record are what TXN presents when calling you. They are not something a caller of the TXN API supplies, and they are unrelated to your own TXN credentials. Your endpoint is responsible for checking them.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"dcb97cda-db65-4aa0-82d9-08a61590eca3","properties":{"sectionText":"TXN checks it can reach you before accepting the record"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"d1c12d75-a0a8-4f31-b4a5-cee453f71252","properties":{"text":"Creating a source is not simply storing what you typed. The address has to be HTTPS, and the platform validates that it can actually reach the endpoint and that the credentials are accepted before the record is created. The same check runs when you change the address or the credentials on an existing source. That is deliberate: a delegated approval source that cannot be reached is worse than no source at all, because it is discovered during a live transaction rather than at configuration time."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"70588d66-f445-4d71-bbf1-7953b37c1ded","properties":{"sectionText":"Choosing a timeout"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"f4b0696d-628b-46a4-9475-2786135197f0","properties":{"text":"Each source carries its own timeout, and a default applies where you do not set one. Choosing it is not a matter of taking the largest value the platform accepts. Your timeout sits inside the card scheme\u0027s own network timeout for the region you operate in, and TXN needs part of that window for its own work before and after calling you. What is left over is what you can safely wait for. Europe is the tightest constraint; other regions allow longer, so the right value is not the same everywhere, and in all of them it has to stay meaningfully below the network timeout above it. Set it too short and a system that would have answered correctly is treated as unreachable. Set it too long and the scheme gives up before your answer reaches it. This value is exactly what a stand-in\u0027s timeout trigger measures against. The API Reference carries the permitted range and the current default."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"3b8e0cf5-f708-4095-a4aa-db01add8cc1a","properties":{"alertTitle":"The maximum allowed is not the maximum you should use.","alertContent":"The platform accepts a longer timeout than most programs should ever set. The real ceiling is the scheme\u0027s network timeout in your region, less the time TXN needs on either side of your call. Set yours at the platform\u0027s limit and the scheme can abandon the transaction before your answer arrives: worse than a decline, because by then the stand-in has no transaction left to decide either.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"38768d31-bdbd-4b9f-9ab4-a1cf1a36de4c","properties":{"sectionText":"How a source starts receiving traffic"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"6feb93f3-76c8-4f25-9311-04cd75ad0c51","properties":{"text":"Registering a source does not route anything to it. A source is attached to a product, and cards issued under that product then have their authorizations routed to it. That is the whole routing mechanism: there is no separate rule engine deciding which traffic goes where, and no per-card override. Attaching or changing a source on a product takes effect from the next transaction, so a change is live almost immediately but does not disturb anything already in flight."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"643fb9e2-53b2-45e6-b592-987cf935e8f1","properties":{"sectionText":"Taking a source out of service"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"278829be-d65a-4009-99a2-7489d77fb6c4","properties":{"text":"A source can be made inactive without deleting it, which is what planned maintenance on your side calls for. The change takes effect immediately and is recorded in the audit trail. Bring it back later and its address, credentials and timeout are intact rather than needing to be registered again. A source can also be updated in place, supplying only the fields you are changing, so adjusting a timeout does not mean restating the address and credentials alongside it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"ff971122-b580-44c0-85fc-5e7349e46d96","properties":{"alertTitle":"You cannot read a credential back.","alertContent":"Credentials are stored securely and are never returned in plain text when you read or list a source. That is the right behavior, but it means TXN is not a place to look one up later. Keep your own record of what you configured, or plan to rotate rather than recover.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"a09cc37f-f034-4899-89d7-a19fdc511b00","properties":{"sectionText":"How a source relates to stand-ins"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3b278ea1-42bf-4752-928b-9387fe941a3c","properties":{"text":"A source exists to be called during a live transaction; a stand-in exists to cover for it when that call does not go the way it should. A stand-in names the sources it applies to, so the relationship runs one way: a source has no idea a stand-in is watching it, but a stand-in is meaningless without at least one source to protect."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"7a3d8fdf-a25a-416e-bbeb-31d264a7f66d","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"b636898d-36b6-47cc-b266-8ff6f5d6bded","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"c2b8ab64-7a57-4633-9105-f82f51405d89","properties":{"cardTitle":"How Delegated Approval Works","cardText":"The flow a source sits inside, and what your endpoint has to answer.","pageLink":{"contentType":"guidePage","name":"How Delegated Approval Works","createDate":"2026-09-16T06:26:34.807Z","updateDate":"2026-11-15T16:32:47.123Z","route":{"path":"/103/delegated-approvals/how-delegated-approval-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e47adf53-2c39-46bb-bb12-ff0c765b075c","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"97472646-c518-4b1f-8180-1b69f0a4b31b","properties":{"cardTitle":"Delegated Approval Stand-Ins","cardText":"What decides when a source cannot be reached.","pageLink":{"contentType":"guidePage","name":"Delegated Approval Stand-Ins","createDate":"2026-09-16T06:26:45.147Z","updateDate":"2026-11-15T16:32:47.573Z","route":{"path":"/103/delegated-approvals/delegated-approval-stand-ins/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"ec2e9c3f-38f6-4b67-99be-540bae84c71b","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"6f2c919e-43bd-4dff-84a1-80bd61141815","properties":{"cardTitle":"Products","cardText":"Where a source is attached, and how routing actually happens.","pageLink":{"contentType":"guidePage","name":"Products","createDate":"2026-09-16T06:22:36.26Z","updateDate":"2026-11-15T16:32:42.283Z","route":{"path":"/103/foundational-objects/products/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"38067e3a-67a3-4525-b8e7-987c4c4c8b58","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"0546fbd6-ba6f-4d14-a4b6-f61dc657ed52","properties":{"prevPageTitle":"How Delegated Approval Works","nextPageTitle":"Delegated Approval Stand-Ins"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Errors","createDate":"2026-11-14T09:22:41.277Z","updateDate":"2026-11-15T16:32:46.777Z","route":{"path":"/103/api-essentials/errors/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dba005b5-8d0e-48ba-84b2-85c6855f7c5e","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"9c382aaa-3b0a-42d7-8f52-9e8e09dcbe9c","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"13ed5f41-74b7-4b77-b696-f8f444de450e","properties":{"title":"Errors","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"b1518549-5507-4d7a-b340-a0d170cea7cb","properties":{"text":"Something will fail, and what you do about it depends on being able to tell what kind of failure it was. Every error from the Core API comes back in the same envelope as a success, carrying a code your logic can match on and a description meant for a person. This page covers how to read one, and what each class of error is telling you."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"70043eb1-d942-43fe-9408-1978f64df6f6","properties":{"text":"Errors are not a separate API. They arrive in the same envelope as a successful response, in the same shape every time, whichever endpoint you called. A handler written once works everywhere.\n\nFor the responses a particular operation can return, see the API Reference."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"960ec51b-c36c-4f4c-890d-d4a298e84142","properties":{"sectionText":"How an error is reported"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"c940aff0-3d2d-4752-902c-2437875fafa4","properties":{"text":"A response carries either a result or an error, never both, so your code branches on which one is populated rather than parsing the status code and the body separately.\n\nOn a failure the result is empty and the error is populated. The rest of the envelope is the same as it is for a success."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"a0e52413-744f-4b9b-92b8-cbe8a026e899","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"ffba2165-664f-47b8-8a2f-6041ed1b832c","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"6b996f0e-c669-4552-9080-050b0d78da0f","properties":{"cellContent":"Field"}},"settings":null},{"content":{"contentType":"tableCell","id":"f7246879-a50e-473a-8bb8-e501d9bef6dd","properties":{"cellContent":"What it is"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"ea875471-b331-4bf0-84c0-d6f517d39aed","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"11336aa4-9e2a-47d9-bc44-d87577816023","properties":{"cellContent":"error.code"}},"settings":null},{"content":{"contentType":"tableCell","id":"4a81e649-c771-4ab9-880e-8e8dc060d142","properties":{"cellContent":"A short, stable identifier for the kind of failure. This is what your logic matches on."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"fdecec79-ff17-418d-ab75-24edfeee376f","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"92ca912d-893a-480e-b6e0-37564fd9ddf3","properties":{"cellContent":"error.description"}},"settings":null},{"content":{"contentType":"tableCell","id":"c544013a-cb26-44f7-bec7-da9e5f030648","properties":{"cellContent":"A human-readable description of what went wrong. Meant for a person reading a log, not for your code."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"89e53913-4646-4a0d-beef-068c6513d68e","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"44af4120-8937-42f7-bd06-ad33eafe7352","properties":{"cellContent":"requestId"}},"settings":null},{"content":{"contentType":"tableCell","id":"e8c57188-e214-441c-861a-31209bb1d03f","properties":{"cellContent":"The identifier for the call that failed, echoed from the one you sent. Quote it when raising a query with TXN."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"9752a87d-9ce1-411c-993a-403c4844948c","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"7a20a158-0aca-4b5c-8d6e-52d03ab24777","properties":{"cellContent":"correlationId"}},"settings":null},{"content":{"contentType":"tableCell","id":"a083d037-e4ff-4f8d-912a-ab91150a0375","properties":{"cellContent":"The correlation identifier you sent, echoed back."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"bbe52fb6-21cf-43f2-9da5-b0b94af29265","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"b4b3c2ef-1d18-4091-928d-afe6753b6153","properties":{"cellContent":"responseId"}},"settings":null},{"content":{"contentType":"tableCell","id":"460b26ea-70ea-44d9-8b1e-0231870e63c2","properties":{"cellContent":"An identifier TXN assigns to this response."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"9b7b92cc-caa5-4141-a42d-75a06fd09ae0","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"b946de9e-4543-47bd-8c5f-a27c91279878","properties":{"cellContent":"dateTime"}},"settings":null},{"content":{"contentType":"tableCell","id":"c55f14c7-b327-4796-b420-cf4e42f53e3d","properties":{"cellContent":"TXN\u0027s timestamp for the response."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"567f092d-4451-4b9a-96f5-bca285da298e","properties":{"sectionText":"What each error means"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"6938e0a9-731e-4160-8ac0-5f7ddfc05b9a","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"04064ce7-17cd-480d-91d2-5971e785c4d8","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"4f4e5e9c-df5c-4adc-991f-4e25c9c5f714","properties":{"cellContent":"Status"}},"settings":null},{"content":{"contentType":"tableCell","id":"3664bd79-2c86-4aba-a0da-295cbb8823e3","properties":{"cellContent":"What it means"}},"settings":null},{"content":{"contentType":"tableCell","id":"9c60196f-1492-493f-8051-21bbfdc37ee7","properties":{"cellContent":"What to do"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"044311dc-019b-4029-a3ed-b0d0f639cdba","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"959583d7-7427-4328-aebe-2dc145d2e528","properties":{"cellContent":"400"}},"settings":null},{"content":{"contentType":"tableCell","id":"5ce82533-81be-41e5-9876-ef1196cde5bf","properties":{"cellContent":"The request could not be understood: malformed JSON, a missing required field, a field or query parameter the API does not recognize, a value in the wrong format, or a missing, malformed or unsupported x-api-version."}},"settings":null},{"content":{"contentType":"tableCell","id":"5baeaf5a-8392-4d85-b968-ab80ea39ff22","properties":{"cellContent":"Fix the request. Retrying it unchanged will fail again."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"6c758de1-8589-4b43-8f93-b20880f66990","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"a7fab68a-97f0-432c-af33-72bd895d028f","properties":{"cellContent":"401"}},"settings":null},{"content":{"contentType":"tableCell","id":"566018c8-4b9d-400c-8c41-eecd03615dce","properties":{"cellContent":"Missing or invalid credentials."}},"settings":null},{"content":{"contentType":"tableCell","id":"e3e02673-b9e1-4213-86ef-dd52a0307e55","properties":{"cellContent":"Check your token has not expired and that you are calling the environment it was issued for."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"0d2a4b1b-9e3d-4413-bc8e-d3b52b53c7f0","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"bf09b590-ba0f-4896-a13d-180784013e80","properties":{"cellContent":"403"}},"settings":null},{"content":{"contentType":"tableCell","id":"1b21ada1-4d0d-4ed7-b917-da7f6f14d016","properties":{"cellContent":"Your credentials are valid but lack the permission or Card Program scope for this call."}},"settings":null},{"content":{"contentType":"tableCell","id":"217cb65b-0027-4811-9711-2caf0c1e72f0","properties":{"cellContent":"Check the scope the credential was created with."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"e7b5b941-145a-4c22-8e13-c214ae805980","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"9ef92093-69c3-4ca6-8b6e-15a2c2d2612f","properties":{"cellContent":"404"}},"settings":null},{"content":{"contentType":"tableCell","id":"ff532bc5-5c32-413e-84b6-7e2c04d73687","properties":{"cellContent":"The resource does not exist, or you cannot see it."}},"settings":null},{"content":{"contentType":"tableCell","id":"ea17b9ef-f9b3-4d92-9df5-3d65fd596c88","properties":{"cellContent":"See the note below."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"997dfba6-1588-461d-8c4e-4933c3a9cd42","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"a5ec60e1-5924-4e4c-9b5b-766869dad8fe","properties":{"cellContent":"409"}},"settings":null},{"content":{"contentType":"tableCell","id":"e2e3583a-f836-43dc-a266-e70c219dbb8f","properties":{"cellContent":"The request conflicts with the current state of the object, for example creating something that already exists, or a state transition the current state does not allow."}},"settings":null},{"content":{"contentType":"tableCell","id":"5df9182d-ad46-40aa-97d8-8f5a8cd5263d","properties":{"cellContent":"Do not simply repeat the call. Read the object back, then decide what to do."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"406cb589-861a-4d84-9332-5a926b8e27a3","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"317bb4b5-750f-4a89-80a1-3316c15d6ef6","properties":{"cellContent":"415"}},"settings":null},{"content":{"contentType":"tableCell","id":"cbf57e53-1fed-48e2-92ec-0782e57b35d3","properties":{"cellContent":"The content-type is wrong or missing."}},"settings":null},{"content":{"contentType":"tableCell","id":"da3f9505-7034-49c6-8b58-8a5a43f232a7","properties":{"cellContent":"Set content-type to match the JSON body you are sending."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"26693746-8202-4698-abed-a804b16ffb3c","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"7018af31-333f-428f-b338-a369d8578911","properties":{"cellContent":"422"}},"settings":null},{"content":{"contentType":"tableCell","id":"65c6d9e1-f909-44bc-ae5b-3cf7ff65b5bf","properties":{"cellContent":"The request is well formed but breaks a business rule."}},"settings":null},{"content":{"contentType":"tableCell","id":"1e80df77-496d-43c0-ba90-fc27e6b4cd78","properties":{"cellContent":"The response identifies which field failed. Fix the request rather than retrying it."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"7bb33b89-9a0d-4af4-934b-7c06fca2e1aa","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"23dda6fa-a555-4c92-afe3-d22df9aaac52","properties":{"cellContent":"429"}},"settings":null},{"content":{"contentType":"tableCell","id":"e2f290d8-af57-4980-b453-aad3441a2c5c","properties":{"cellContent":"You have exceeded your rate limit."}},"settings":null},{"content":{"contentType":"tableCell","id":"9206f500-224e-49c7-ab4b-d6b62f48961d","properties":{"cellContent":"Back off and retry. See Rate Limits."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"93496355-25f8-4be6-92c3-e83293221c41","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"135f18e6-c686-4d02-8404-bddac6af66a3","properties":{"cellContent":"500"}},"settings":null},{"content":{"contentType":"tableCell","id":"7c64ee9e-c7c4-4168-9c4c-a492868462ac","properties":{"cellContent":"Something failed unexpectedly on the platform."}},"settings":null},{"content":{"contentType":"tableCell","id":"99c6d882-b091-44c1-958f-a308f65555eb","properties":{"cellContent":"Safe to retry after a delay, reusing the same requestId on a write. Quote the requestId if it persists."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"d2e574a7-6ef1-4526-a573-deb5f4a3df29","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"0bdcffe3-c57b-4907-a8ba-7891138f0a46","properties":{"cellContent":"503"}},"settings":null},{"content":{"contentType":"tableCell","id":"74756a2f-f4ef-4e9b-8745-08d8465e8502","properties":{"cellContent":"The platform or something it depends on is temporarily unavailable."}},"settings":null},{"content":{"contentType":"tableCell","id":"fd511ec4-9814-439d-a065-390764aa80fa","properties":{"cellContent":"Retry after a delay, reusing the same requestId on a write."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"faef693c-6318-4cd1-ba75-889b10f14809","properties":{"alertTitle":"A 404 does not mean the object is missing","alertContent":"TXN returns 404 both when a resource does not exist and when your credentials cannot see it. The two are deliberately indistinguishable, so that the API never reveals what exists outside your scope. If you are certain an object exists and you are getting 404, check the scope of the credential before you go looking for the object.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"087445b7-6ad5-4be3-b5b6-de5bb72ac5cb","properties":{"sectionText":"Building error handling that lasts"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"555ac049-fe4c-45da-a155-63ddfd4152f5","properties":{"text":"Match your logic against error.code, not error.description. The code is a stable contract. The description is explanatory text and TXN may reword it without that counting as a breaking change, so anything branching on its wording will break quietly.\n\nKeep the requestId from any call that fails. It is what lets TXN find the exact call rather than you reconstructing it afterwards, and it is the first thing you will be asked for. It also comes back in the x-request-id header.\n\nNot every failure deserves the same response. A 400, 401, 403, 404, 415 or 422 is telling you the request was wrong, and repeating it unchanged will fail again. A 429, 500 or 503 is telling you to come back later, and those are worth retrying with a delay. A 409 is neither: something about the state conflicts, and the right move is usually to read the object back before deciding what to do."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"6e8945b4-8e28-41e2-b19d-871f68f8a14c","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"cdc601b3-ece5-468c-89f3-0cb59f6c28b8","name":"Ae Errors What To Do Dark","mediaType":"Image","url":"/media/htfja42m/ae-errors-what-to-do-dark.png","extension":"png","width":2400,"height":1000,"bytes":243816,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"e504d922-8a90-45e6-81a3-766efe51d1e4","name":"Ae Errors What To Do Light","mediaType":"Image","url":"/media/vujfeu5z/ae-errors-what-to-do-light.png","extension":"png","width":2400,"height":1000,"bytes":239935,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"76b37bff-268d-4eea-9bc3-64f784756bf3","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"676f9d04-598e-40f5-a956-c556a9bfe705","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"d2fb92f9-c9b6-4add-85f0-2f05482f4cc6","properties":{"cardTitle":"Rate Limits","cardText":"Why a 429 happens, and how to pace your integration so it does not.","pageLink":{"contentType":"guidePage","name":"Rate Limits","createDate":"2026-11-14T09:22:41.343Z","updateDate":"2026-11-15T16:32:47.413Z","route":{"path":"/103/api-essentials/rate-limits/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"eaf38fec-bda3-49d6-be92-41e32f25e364","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"eae34675-7895-46fc-9f1e-63d18102676a","properties":{"cardTitle":"Retries and Idempotency","cardText":"Which failures are safe to retry, and how to retry a write safely.","pageLink":{"contentType":"guidePage","name":"Retries and Idempotency","createDate":"2026-11-14T09:22:41.407Z","updateDate":"2026-11-15T16:32:39.84Z","route":{"path":"/103/api-essentials/retries-and-idempotency/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"182084cf-2e4d-406f-a1e4-9a1dcba5f19d","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"9bc38f4f-e596-450e-8654-cce7d7b3978e","properties":{"cardTitle":"Authentication","cardText":"What a 401 or 403 usually means, and how tokens are issued and renewed.","pageLink":{"contentType":"guidePage","name":"Authentication","createDate":"2026-09-16T06:20:42.913Z","updateDate":"2026-11-15T16:32:43.17Z","route":{"path":"/103/getting-started/authentication/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"56e49f8f-4cd4-44d1-acca-d5cda1431fc6","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"fd2b4d92-9e61-4c39-a91f-0170b9731c46","properties":{"prevPageTitle":"Requests and Responses","nextPageTitle":"Error Code Reference"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Activating a Card","createDate":"2026-11-14T13:45:44.983Z","updateDate":"2026-11-15T16:32:47.71Z","route":{"path":"/103/managing-cards/activating-a-card/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"fbf32662-f391-441b-bdc3-9f3bbc072bc1","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"1078fe65-24e7-4b69-931d-cddc01cbb872","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"c4146496-b955-4141-9011-57b0322b3625","properties":{"title":"Activating a Card","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"1714061c-fd04-4596-923e-5cccf91b29c3","properties":{"text":"A card is created inactive and cannot transact until something activates it. There are three ways that happens, and the one you choose is mostly a question of where the card physically is at the time."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"7d817b2a-cbe8-4039-9030-82c294d2a9a8","properties":{"text":"Inactive is the starting state for a reason. A card that works the moment it exists spends its whole journey through the post in a usable condition, and a card that never arrives is indistinguishable from one that did. Starting inactive means the window where a card is both real and spendable is one you control rather than one the postal system decides."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"f41cfd90-8144-4f65-a43a-561adfcecd3c","properties":{"sectionText":"Three ways a card becomes active"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"0efb641f-4a56-4253-9988-2e71a2fe5109","properties":{"text":"A product can auto-activate its cards at issuance, so the card is live the moment you create it. That suits a virtual card the cardholder is expected to use straight away. Left to activate manually, the card waits until you transition it, which is the right model for a physical card that should not work until it is in someone\u0027s hands. Or activation can be scheduled, so the card becomes active at a date and time you set rather than at the moment you call."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"1bb19a66-376a-43bf-a3ff-67909f149bff","properties":{"sectionText":"Scheduling activation for later"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"dd6992d0-6936-4e05-bfc3-10d933553575","properties":{"text":"A scheduled activation is set on the individual card rather than on the product, so cards issued under the same product can come to life at different times. Until that moment arrives the card sits inactive and is blocked from transacting. When the timestamp passes TXN activates the card itself, with no further call from you and nothing to poll."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"06914839-3d37-435a-8569-c614995e6bdc","properties":{"alertTitle":"Inactive does not mean restricted, it means nothing works.","alertContent":"A card waiting on a scheduled activation is not a card with tight limits. It cannot transact at all, and nothing you might expect to slip through will. This matters most in testing, where a scheduled card looks completely configured (product attached, controls in place, number issued) and declines everything anyway. Check the activation timestamp before looking anywhere else.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"2eda367b-0bc2-4b64-82d2-015d260e237e","properties":{"sectionText":"What scheduling is actually for"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"31193515-5fb3-42a7-80f3-a369e92eac76","properties":{"text":"Three situations account for most of it. Onboarding, where cards are produced in advance of the people who will hold them being ready. Campaign launches, where a batch of cards should become spendable at a moment that has been decided by someone other than you. And delayed fulfillment, where the card exists long before it arrives. In each case the alternative is remembering to make a call at the right moment, which is the thing scheduling removes."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"67c46122-7ed1-430d-bc4e-dab802068975","properties":{"sectionText":"Activation is a transition, and it shows in the record"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"aa14e21b-86e8-4188-b535-bf6a21b3ea1f","properties":{"text":"However a card becomes active (automatically at issuance, because you asked, or because a scheduled time arrived), it is recorded as a transition with its own reason and timestamp. A first activation is recorded differently from a later one, so a card\u0027s history tells you whether it has ever been live before rather than only what state it is in now."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"742fa7d2-636b-4307-baed-befd46a08457","properties":{"sectionText":"What activation sets in motion"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"31775959-9eba-4b92-a119-82625d77a86b","properties":{"text":"For a first issuance, activation changes the card\u0027s status and nothing else, because there is nothing preceding it. For a replacement it does considerably more: activation is the moment digital wallet tokens move across from the card being replaced, and the moment merchants holding the old number are given the new one. Neither happens when you create the replacement, only when it goes live."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"865133d9-55e6-4a29-ac3a-3ea66ef04441","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"7abc6d9d-6a5a-4ab9-ae69-899a3e918eac","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"14dbe351-d129-4275-a4be-d4c03f6d5300","properties":{"cardTitle":"Cards","cardText":"The card record, its states and what a transition can carry.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"a64cf424-70d1-4ab7-8ef5-5b6c1a4ff6d9","properties":{"cardTitle":"Replacing a Card","cardText":"Why activation matters more on a replacement than on a first issuance.","pageLink":{"contentType":"guidePage","name":"Replacing a Card","createDate":"2026-11-14T13:45:44.953Z","updateDate":"2026-11-15T16:32:41.983Z","route":{"path":"/103/managing-cards/replacing-a-card/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2db9d6c2-7f22-452f-b105-e3f518240751","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"f7e6885d-504d-4d18-b420-d5314b705770","properties":{"cardTitle":"Products","cardText":"Where auto-activation at issuance is set.","pageLink":{"contentType":"guidePage","name":"Products","createDate":"2026-09-16T06:22:36.26Z","updateDate":"2026-11-15T16:32:42.283Z","route":{"path":"/103/foundational-objects/products/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"38067e3a-67a3-4525-b8e7-987c4c4c8b58","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"4a465135-a544-4538-89ca-05a8a14f5467","properties":{"prevPageTitle":"Balances","nextPageTitle":"Replacing a Card"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"SCA Counters and Contactless Limits","createDate":"2026-09-18T11:31:20.097Z","updateDate":"2026-11-15T16:32:42.133Z","route":{"path":"/103/authentication-sca/sca-counters-and-contactless-limits/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2f69ffc6-6124-4eba-8a7d-9d7c316195c7","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"cd92df88-a713-47d9-972f-9481a28fc645","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"4b525298-525b-4f22-b371-a74af7e761d6","properties":{"title":"SCA Counters and Contactless Limits","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"0deb2686-c3bb-4205-be40-a79d050ea863","properties":{"text":"Behind the rule sit counters on each card, tracking how much has been spent without authentication and how many payments have gone through untouched. When either passes the threshold you have set, the next payment asks the cardholder to confirm who they are. This page covers what moves those counters, what resets them, and what you configure."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3ef690cb-a83a-4e07-be71-0423f8cfaecc","properties":{"text":"Each card carries counters for contactless and for e-commerce, tracked separately. Two things are counted: a cumulative value, being the total spent since the last authentication, and a consecutive count, being how many payments have gone through since then. Either reaching its threshold is enough to require authentication on the next payment. The counters are maintained by the platform and are readable on the card, but they are not writable: nothing you send can set or clear them directly."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"806f0d86-e135-4e3a-aaf9-7e990ce3b982","properties":{"sectionText":"What moves a counter, and what does not"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"a2dbcb8d-7217-45bb-847f-ebe0e3bf6cbc","properties":{"text":"An ordinary contactless payment that goes through without authentication increases both the cumulative value and the consecutive count. A payment that was exempt does not. That is deliberate and it is the part most often got wrong: an exemption is not a free payment that quietly fills the counter up, it sits outside the count entirely. E-commerce payments move the e-commerce counters on the same basis, independently of the contactless ones."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"499f5948-6cff-4f87-867b-63f3030dfe06","properties":{"alertTitle":"An exempt transaction does not count towards the limit.","alertContent":"Exempt contactless transactions must not be declined and do not increment the contactless counters. If you are reconciling a cardholder\u0027s position against your own view of their spending, counting every contactless payment will give you a number higher than the one TXN is enforcing against.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"31cf139a-78c3-4bb5-aab4-54b035fcbe76","properties":{"sectionText":"What resets them"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"c820271b-3ee8-4175-8499-9d4b96dfca31","properties":{"text":"A successful authentication resets the counters. In practice that is the cardholder entering a PIN at a terminal, or completing a 3-D Secure challenge online. The reset is the point of the mechanism: the rule is not \u0022so many taps ever\u0022, it is \u0022so much, or so many, since you last proved it was you\u0022. A cardholder who authenticates regularly will rarely meet a threshold at all."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"9368cd51-9443-4455-9fa4-14b176a7d5f2","properties":{"sectionText":"The limits you set"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"de9ebb73-1709-4724-8b19-62ab58a3049e","properties":{"text":"You define both a single-transaction limit and a cumulative limit, and the platform enforces them per card. The rules that apply them are configurable per program and per region, so a program operating across several markets can hold different thresholds in each rather than flattening to the strictest. Regulatory and scheme ceilings sit above whatever you configure, so your values narrow the window rather than widening it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"9a647ca9-daaf-4895-9252-604346a941ea","properties":{"sectionText":"Limits held in another currency"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b27b5d3c-d517-4159-b24a-97275429fc7c","properties":{"text":"A limit is expressed in a currency you choose, and transactions do not arrive only in that currency. Where they differ, the transaction amount is converted using a real-time rate at the point the limit is evaluated. A cardholder spending abroad is therefore assessed against the same threshold as one spending at home, rather than against a figure that happens to be larger or smaller because of the currency it arrived in."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"c84eda35-d0a3-40d5-b814-508ade83ff33","properties":{"sectionText":"Changing the configuration does not reset the counters"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"64ee9c2f-b849-4cad-8319-f842f7a4706f","properties":{"text":"Product-level authentication settings can be changed at any time and apply from the next transaction. What they do not do is clear anything. A card partway through its count stays partway through it; the change alters the criteria those existing counters are measured against, not the counters themselves."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"1518b979-ecd0-483d-847f-7cb6e577765a","properties":{"alertTitle":"Raising a threshold does not give a cardholder a clean slate.","alertContent":"If a cardholder is one payment away from a challenge and you raise the limit, they are still one payment away from wherever the new threshold falls. Only a successful authentication resets a counter. Support teams expecting a configuration change to clear a cardholder\u0027s position will be surprised, and so will the cardholder.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"2dc4904a-d19f-46e0-a05f-65ae7f313162","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"f857a4f4-a574-455c-ac3c-228c26e29dec","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"7465ee46-f3f7-4538-aaf4-3635127dca53","properties":{"cardTitle":"Strong Customer Authentication","cardText":"What the rule is, and when a payment is exempt or out of scope.","pageLink":{"contentType":"guidePage","name":"Strong Customer Authentication","createDate":"2026-09-18T11:31:11.723Z","updateDate":"2026-11-15T16:32:43.757Z","route":{"path":"/103/authentication-sca/strong-customer-authentication/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"6f1882ed-93f8-4f26-9cb9-b6b8a47e85b3","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"b342a67d-cb44-4108-a78a-3f9a7d714849","properties":{"cardTitle":"3-D Secure","cardText":"The online challenge that resets the e-commerce counters.","pageLink":{"contentType":"guidePage","name":"3-D Secure","createDate":"2026-09-16T06:24:47.867Z","updateDate":"2026-11-15T16:32:41.32Z","route":{"path":"/103/authentication-sca/3-d-secure/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2c14bfed-9803-44c3-a57c-6105c8c6131d","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"cda4d9c8-3e05-4974-ae78-1a1f025663e5","properties":{"cardTitle":"Products","cardText":"Where authentication settings are configured and inherited from.","pageLink":{"contentType":"guidePage","name":"Products","createDate":"2026-09-16T06:22:36.26Z","updateDate":"2026-11-15T16:32:42.283Z","route":{"path":"/103/foundational-objects/products/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"38067e3a-67a3-4525-b8e7-987c4c4c8b58","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"1ca2f9b3-e2a3-4bee-aee1-808588a91715","properties":{"prevPageTitle":"Strong Customer Authentication","nextPageTitle":"3-D Secure"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Cardholders","createDate":"2026-09-16T06:22:18.73Z","updateDate":"2026-11-15T16:32:44.66Z","route":{"path":"/103/foundational-objects/cardholders/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"a615ed27-e2f2-4afe-b764-4fc583ef8f6c","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"eeafec42-4dae-42a5-905c-5bb84782c572","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"be96ff41-eb6b-4b46-bc14-07e14db16202","properties":{"title":"Cardholders","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"5d509840-cfd1-4178-8cc8-03a2c9c8d5d3","properties":{"text":"Every card issuing platform needs a record of the person, or entity, a card belongs to: someone to identify, contact and hold accountable for how a card is used. That record is the anchor everything else in an issuing relationship points back to."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"6d00a0ae-1fed-4952-b576-9e11508159bf","properties":{"text":"On TXN, that anchor is the cardholder. Your application creates one to register who a set of accounts and cards belongs to, and from then on accounts, cards and, optionally, groups and hierarchies all reference it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"1e063b9b-1589-4350-8a45-7be4ff0b4008","properties":{"sectionText":"What creating a cardholder sets up"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"443a15f3-8121-407c-90d7-5dedc2d4746a","properties":{"text":"A cardholder record gathers three things in one place: a profile, holding name, date of birth and correspondence language; contact details; and addresses, with billing and shipping held separately. All of it is established in a single call, so there is no multi-step assembly to orchestrate.\n\nWhat may surprise you is how little of it the platform insists on. The create call enforces almost nothing: a cardholder can exist with a profile and no contact details, or with neither. That latitude is useful for progressive onboarding, but it means the completeness of your cardholder records is your integration\u0027s responsibility rather than something the API will enforce for you. Decide what your own flow requires and validate it before you call.\n\nA cardholder also carries a free key-value attributes collection. That is where your own customer reference belongs, so you can match a TXN cardholder back to the record in your system without keeping a separate mapping table.\n\nA cardholder can be retrieved and updated afterwards, and its accounts and cards can each be listed separately, which is useful for building a single-view profile screen."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"d6a1c1bf-ee80-494f-ab80-1aba55ae45ec","properties":{"alertTitle":"Send only what you are changing.","alertContent":"Updating a cardholder is a partial update. Fields you leave out are untouched, so there is no need to read the record first and send it back whole. Send only what has actually changed. It keeps your audit trail meaningful, because an update carrying every field makes it impossible to tell later what the change was actually about.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"818d1e4c-4b5f-420f-95b5-45ee7ce301cf","properties":{"sectionText":"How a cardholder relates to other objects"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"6367db55-0878-4d8f-97c3-3aeb0b440ff5","properties":{"text":"Accounts. A cardholder can hold more than one account (see Accounts). An account\u0027s own ownership is recorded on the account, but the association is also carried on the cardholder, so keep the two consistent when you update either.\n\nCards. A cardholder can have more than one card, and a card cannot exist without one (see Cards). Card issuance fails without a valid cardholder reference.\n\nParent cardholders and cardholder groups. A cardholder can optionally link to a parent cardholder, for a dependant or a managed employee, or to a cardholder group for shared identity data. Neither is required; they exist for integrations modeling those relationships."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"c4811b03-10e8-422a-8e43-936876b1e76e","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"35c7cfa4-d055-4d61-a608-963e1d8fb501","name":"Fo Cardholders Groups Parents And State Dark","mediaType":"Image","url":"/media/fmcjdaz2/fo-cardholders-groups-parents-and-state-dark.png","extension":"png","width":2400,"height":1340,"bytes":344526,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"10296525-0d46-4582-a4c5-9107aeb73d07","name":"Fo Cardholders Groups Parents And State Light","mediaType":"Image","url":"/media/vkxh5jrp/fo-cardholders-groups-parents-and-state-light.png","extension":"png","width":2400,"height":1340,"bytes":341262,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"fb3c48cd-d893-46e0-8e4e-020e2860a67a","properties":{"sectionText":"The cardholder lifecycle"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"8fe3e908-533f-49f8-9bf7-453d9aca2ee5","properties":{"text":"A cardholder moves through three states: active, on hold and closed. For a cardholder this answers whether the person or entity behind a set of cards and accounts is in good standing, independent of whether any individual card is usable. That independence is deliberate: it lets you hold a cardholder for review without interrupting every card they use.\n\nEvery transition records a target status, a reason, and what initiated it, as its own auditable record with the previous status, the new status and an effective time. You can list a cardholder\u0027s transitions or fetch one by id.\n\nTransitions are not only yours to make. The initiator is recorded as your API call, a TXN processor system, or an operator acting in Control Center, so a cardholder\u0027s history may contain changes your integration did not make. Read the transitions rather than assuming the status only changes when you change it.\n\nActive and on hold are reversible. A cardholder held for review can be returned to active once the review clears. Closed is not."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"8270fc0b-330f-447c-b19a-955167539585","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"7169a1e1-33ee-44c4-b090-a9d698265aa9","name":"Fo Cardholders Lifecycle Dark","mediaType":"Image","url":"/media/nzvd5r2h/fo-cardholders-lifecycle-dark.png","extension":"png","width":2400,"height":1400,"bytes":286745,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"21041be6-abc5-47e9-94aa-13d72ca47833","name":"Fo Cardholders Lifecycle Light","mediaType":"Image","url":"/media/nhifff3m/fo-cardholders-lifecycle-light.png","extension":"png","width":2400,"height":1400,"bytes":283391,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"e103f763-73ab-4afd-b647-c1e2d63a0548","properties":{"alertTitle":"Closing a cardholder is permanent.","alertContent":"Closed is a terminal state and there is no route back. A closed cardholder cannot be reopened, no new cards can be issued against them, and no transaction on any of their cards will be authorized again. If you need to stop activity temporarily, use on hold. Close only when you are certain the relationship has ended.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ab601660-0e09-42f4-aa30-f04b7521074d","properties":{"sectionText":"Choosing a transition reason"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b14407be-95d7-4bed-9862-0a937904b03f","properties":{"text":"The reason is not a free-text note for your own records. It determines the response code TXN signals to the card scheme, so the reason you choose changes what a merchant sees when a card is declined. Choosing confirmed fraud where you meant account under review produces a different outcome at the terminal."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"569d8438-bc30-4205-8719-d913e47b3b3a","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"283fe335-5f0f-4e56-820a-a21341baa6aa","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"dbfa8a6f-df6f-46dc-b187-d7e810f6f712","properties":{"cellContent":"Transition reason"}},"settings":null},{"content":{"contentType":"tableCell","id":"6b7bb8c4-c65a-4766-9841-dde83d9fd2ad","properties":{"cellContent":"When it applies"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"c8917e79-d9a1-46d5-baf0-4c6d6a793cd6","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"15ce07ba-c630-40ba-8615-4bc2fa3ebb89","properties":{"cellContent":"INACTIVITY_OVER_TIME"}},"settings":null},{"content":{"contentType":"tableCell","id":"7ee064b4-1467-4b5f-943b-de7bb126e596","properties":{"cellContent":"The cardholder has been dormant long enough to warrant a status change."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"1bf80acb-69a6-4613-b4bf-18aaf102aae5","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ce5e2c28-aeb2-437a-9ff9-5f5dfbdaa4d0","properties":{"cellContent":"ACCOUNT_UNDER_REVIEW"}},"settings":null},{"content":{"contentType":"tableCell","id":"775cc230-15bc-43e5-9b07-16a29953d4b9","properties":{"cellContent":"A review is in progress and activity should pause until it concludes."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"a784d9b8-5e12-4a09-b939-0d8d52ab6d15","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"31289605-8d26-4774-888e-37db4c4a29a5","properties":{"cellContent":"SUSPICIOUS_ACTIVITY"}},"settings":null},{"content":{"contentType":"tableCell","id":"baa6fe2e-a8b0-46fa-b016-1ce171d20d95","properties":{"cellContent":"Behavior has been flagged but not confirmed as fraud."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"84608028-a2e2-4ac6-a223-f15ce2a3dc31","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"cd2a68e3-bd8e-427a-b6f7-ec090c595c3c","properties":{"cellContent":"CONFIRMED_FRAUD"}},"settings":null},{"content":{"contentType":"tableCell","id":"0e271d8f-6c45-4f8b-8e42-23d8ecf8b809","properties":{"cellContent":"Fraud has been established."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"379c27e8-572d-439a-b43a-32b42721c6d1","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"f48538d3-e94e-4ad7-94dd-6763fcdde2fe","properties":{"cellContent":"ACCOUNT_OR_CARD_COMPROMISED"}},"settings":null},{"content":{"contentType":"tableCell","id":"7737fc0e-1d10-4b01-9d6c-fdc80475c1d5","properties":{"cellContent":"Credentials or card details are known to be exposed."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"0b603ac6-6b13-4c46-b164-ef8926fb2e2a","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"23c6411b-5421-434f-a5d0-0837b68c2481","properties":{"cellContent":"INITIATED_BY_PROCESSOR"}},"settings":null},{"content":{"contentType":"tableCell","id":"614dc87b-f83b-445c-b5a7-32707cb074ba","properties":{"cellContent":"TXN initiated the change."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"ccbed686-0594-4b82-bdf4-56c3f87c9361","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"e0d965a6-0f0e-46a4-8cac-1b0a7df6f42a","properties":{"cellContent":"INITIATED_BY_ISSUER"}},"settings":null},{"content":{"contentType":"tableCell","id":"3fec2ee7-d4f9-4d8a-aad1-cc823721fee7","properties":{"cellContent":"The issuer initiated the change."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"780cf57e-fc69-4b16-9d4a-33afebf27f9d","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"9487c82e-8655-4a37-88e7-66fc1874a6f5","properties":{"cellContent":"NOTIFICATION_OF_DEATH"}},"settings":null},{"content":{"contentType":"tableCell","id":"6db6c61c-c2f7-44b3-b342-f7d05d936e2d","properties":{"cellContent":"The platform has been notified the cardholder has died."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"b25671b8-3eb2-4021-8374-37cae6b90cd4","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"53beac9a-553f-4e08-8b74-5ff7863add1f","properties":{"cellContent":"OTHER_REASON"}},"settings":null},{"content":{"contentType":"tableCell","id":"16631fa6-0d04-4cd7-9972-e394c1014cce","properties":{"cellContent":"Anything not covered above. Use the memo field to say what."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b110d274-9c52-4748-8a39-4ea4ed2adbbe","properties":{"text":"The same set of reasons applies to cardholder groups and accounts."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"de281673-26d8-462d-8cb2-812f0ff028d3","properties":{"alertTitle":"Deciding whether a hold reaches the cards.","alertContent":"A cardholder transition carries an applyToLinkedCards flag, and it defaults to false. Left alone, holding or closing a cardholder changes the cardholder only, and their cards keep working. Set it to true when the cardholder\u0027s status should reach everything they hold. Choose deliberately rather than relying on the default.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"0649de49-fd8f-456c-992e-305b9ba7fee3","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"f33e23a0-fbbc-48b1-9139-4ce0fd3f9f3b","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"4d2f17b6-61f5-4e31-9c88-3eebcc7e3bb5","properties":{"cardTitle":"Accounts","cardText":"The balances a cardholder\u0027s cards draw against, and how ownership is recorded.","pageLink":{"contentType":"guidePage","name":"Accounts","createDate":"2026-09-16T06:22:09.903Z","updateDate":"2026-11-15T16:32:43.31Z","route":{"path":"/103/foundational-objects/accounts/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"5c10167b-6790-43b8-8d90-d56c1a423a5c","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"16b62fc7-b237-4fb8-a877-ab0d78a44cc8","properties":{"cardTitle":"Cards","cardText":"What a card needs before it can exist, and its own separate lifecycle.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"91ecd9c9-376f-4e41-ab79-b85426e6eaa0","properties":{"cardTitle":"Cardholder Groups","cardText":"Sharing identity data across a set of cardholders.","pageLink":{"contentType":"guidePage","name":"Cardholder Groups","createDate":"2026-09-16T06:22:27.497Z","updateDate":"2026-11-15T16:32:46.307Z","route":{"path":"/103/foundational-objects/cardholder-groups/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"d66b448a-3627-49ab-92fb-be2ce8243427","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"6e7c263d-7adf-464a-8ece-f5d244f801a8","properties":{"prevPageTitle":"Products","nextPageTitle":"Cardholder Groups"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Spend Controls","createDate":"2026-09-16T10:47:00.377Z","updateDate":"2026-11-15T16:32:45.233Z","route":{"path":"/103/card-controls/spend-controls/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b3eace44-6780-4c51-831b-164ca1d52e67","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"7e446809-e73d-4972-ad4a-db02317c0dc5","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"e0786672-954b-4abd-ae52-9267e5a0d797","properties":{"title":"Spend Controls","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"de15c04e-33a4-45fb-9b75-67ef2c02f0ad","properties":{"text":"Issuing a card means deciding what it may be used for. Two separate mechanisms answer that. Restrictions decide which kinds of transaction a card accepts at all. Spend controls decide how much may be spent, over what period, and under what conditions."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3a90d111-02a7-42b9-b847-4b35ee04c1d2","properties":{"text":"The difference matters when you come to build. Restrictions are fields carried on the product and the card, switched on or off, with no resource of their own. A spend control is a resource in its own right, created through its own endpoint, with an identifier, a period and limits you can read back and change. Reach for a restriction when the answer is \u0022this card never does that\u0022. Reach for a spend control when the answer is \u0022up to this much, over this long\u0022."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ba7e9551-de64-43aa-8bf0-a1bb0f73d283","properties":{"sectionText":"Restrictions: which transaction types a card accepts"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b89915e8-83b9-4c30-95ff-3278b921cd67","properties":{"text":"Every card carries a set of switches deciding which kinds of transaction it accepts: online payments, chip, contactless, ATM withdrawals, mail and telephone order, quasi-cash, account funding, original credit and cashback. Each is permitted unless you turn it off, so a card issued without any of them specified accepts all of them. The same set exists on the product, which is where a program-wide posture belongs, and a card that does not set its own inherits the product\u0027s values at the moment it is created. Set them on the product for the population, and on the card only where one card should differ. Changing them on a card takes effect immediately; changing them on the product applies from the next transaction, and does not rewrite cards that already carry their own."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"d7a65ac0-ef20-44e1-889b-30d72560d685","properties":{"sectionText":"Spend controls: how much, over what period"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"44d12d87-5c85-41f1-a395-0023bab87da5","properties":{"text":"A spend control caps two independent things: a value ceiling and a count ceiling. Either may be set, or both. You choose the period it measures over: a single transaction, a day, a week, a month, a year, the lifetime of the card, or a rolling window you define. Amounts are always evaluated in the cardholder\u0027s billing currency, whatever currency the transaction arrives in, so a limit means the same thing wherever the card is used. You can supply your own identifier when you create one, or let the platform allocate it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"0ba1db24-02c4-41b4-8ad2-baaa985c3652","properties":{"sectionText":"Narrowing a control"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"aa4f33f1-76d6-405a-b459-9259f8428229","properties":{"text":"A control does not have to apply to everything. It can be scoped to particular transaction types, to particular merchant category codes, merchant identifiers or merchant groups, to particular countries or regions, and to a time of day or day of the week. A limit that only bites abroad, or only at weekends, is the same control with its scope narrowed rather than a different kind of thing. It can also apply collectively or individually: a collective limit measures spend across every card in its scope combined, while an individual limit evaluates each one separately. A team budget and a per-person budget differ only in that one setting."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"2927398d-cd16-4090-83af-80b9af5bb8e7","properties":{"sectionText":"Every layer has to pass"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b1ff9a89-4e74-464c-bf07-f1ba35db045e","properties":{"text":"Spend controls apply across a hierarchy rather than at one place. A transaction is checked against limits held at the BIN sponsor, the program manager, the card program, the product, the cardholder group, a parent cardholder, the cardholder, the account and the card. It has to pass every applicable layer to be authorized, and failing any one of them declines it. The outermost layers, at the top of the hierarchy, are hard ceilings that nothing below can raise."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"7b40721e-1f86-410d-9198-042221237109","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"c5290ea3-97d8-4cdb-9a8b-edbb6287734a","name":"Cc Spend Controls Layers Dark","mediaType":"Image","url":"/media/ftcg423r/cc-spend-controls-layers-dark.png","extension":"png","width":2400,"height":1190,"bytes":272899,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"0abf71fe-30bf-4872-bc0c-ebf59c825804","name":"Cc Spend Controls Layers Light","mediaType":"Image","url":"/media/og3ptpgw/cc-spend-controls-layers-light.png","extension":"png","width":2400,"height":1190,"bytes":266657,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"2ec35730-2b09-4a65-a455-cb093b6821d8","properties":{"alertTitle":"A decline can come from a layer you did not set.","alertContent":"If a transaction is declined and the card\u0027s own limits look fine, check the layers above it. A cardholder group or account limit will decline a transaction the card would have allowed, and the card\u0027s remaining allowance will not explain why.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"02748d38-f27e-4333-a6f8-144cb09d3ab7","properties":{"sectionText":"Behavior during stand-in"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"489b7dbb-4d1e-4fb7-b5d9-7fe66602521d","properties":{"text":"Every control states how it behaves when a stand-in is deciding in place of your own system. It can apply always, only during stand-in, or never during stand-in. You also choose what prior spending counts while stand-in is active: all spending in the period, only the transactions decided during stand-in, or a fresh count starting when stand-in begins. Both are decisions at creation rather than defaults worth accepting without thinking about."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"a878f128-3f30-4538-b76c-047abb85e5ff","properties":{"sectionText":"Spend controls versus spend overrides"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"252bc6cf-7697-40c8-a798-bc9f6854fe8b","properties":{"text":"A spend control is policy: it describes how a population of cards should behave. A spend override is an exception for one card, for a defined stretch of time, that does not disturb the policy. Reach for an override when a single cardholder needs different treatment temporarily, and change the control when the policy itself is wrong."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"d6ce0c58-e209-4eed-843d-ced33ef9851c","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"96fe1aae-547f-4cc3-b020-22ab5aaca76a","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"9e9f1116-41b9-434a-aaa8-8c6d02f24baf","properties":{"cardTitle":"Spend Overrides","cardText":"Raising a limit for one card, temporarily, without changing policy.","pageLink":{"contentType":"guidePage","name":"Spend Overrides","createDate":"2026-09-16T06:24:22.233Z","updateDate":"2026-11-15T16:32:44.193Z","route":{"path":"/103/card-controls/spend-overrides/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"90242594-37ea-4d33-afe6-db47662679eb","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"cae2fa2c-8699-401d-ba37-1bf2c9aeccfb","properties":{"cardTitle":"Merchant Controls","cardText":"Restricting where a card works rather than how much it spends.","pageLink":{"contentType":"guidePage","name":"Merchant Controls","createDate":"2026-09-16T06:24:31.46Z","updateDate":"2026-11-15T16:32:42.82Z","route":{"path":"/103/card-controls/merchant-controls/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"51fd9837-c394-466d-8bcf-b1b71c811da2","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"3287f72a-d5f4-498b-8b95-8abe8196757e","properties":{"cardTitle":"Products","cardText":"Where a program-wide control posture is set and inherited from.","pageLink":{"contentType":"guidePage","name":"Products","createDate":"2026-09-16T06:22:36.26Z","updateDate":"2026-11-15T16:32:42.283Z","route":{"path":"/103/foundational-objects/products/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"38067e3a-67a3-4525-b8e7-987c4c4c8b58","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"4035ab89-8ee0-402a-b3db-5a960a691bbc","properties":{"prevPageTitle":"Card Expiry","nextPageTitle":"Spend Overrides"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Health Checks","createDate":"2026-11-14T13:47:02.173Z","updateDate":"2026-11-15T16:32:46.023Z","route":{"path":"/103/staying-in-sync/health-checks/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"d2724a96-2414-4d80-a111-986fcd0b18e5","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"6764bb6a-1df9-4049-8040-60707e721415","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"b6c4f997-a6ad-4e9d-9da8-9a4c45beac5f","properties":{"title":"Health Checks","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"b23b9137-8807-4203-a505-3fdf4f59c5e5","properties":{"text":"\u0022Health check\u0022 means three different things on TXN, and two of them are TXN calling you rather than the other way round. Knowing which one someone is talking about saves a surprising amount of confusion."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"a1e8710a-4c5a-4711-b89a-7fd5c96b94cc","properties":{"text":"The three checks answer different questions, run in different directions, and have different consequences when they fail. Mixing them up is the usual reason someone concludes the platform is down when what has actually happened is that TXN could not reach them."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"85fe6f0d-5a6e-4d7b-b3bc-3f6eeec6361d","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"fedee49a-3ec2-4adf-9c35-d5c3d17953de","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"6a15346d-2559-4c63-b698-b949a09fffb5","properties":{"cellContent":"Check"}},"settings":null},{"content":{"contentType":"tableCell","id":"31d3f7d2-f067-4785-a1e2-ec19c0bb44f9","properties":{"cellContent":"Direction"}},"settings":null},{"content":{"contentType":"tableCell","id":"83885f63-37b7-48da-a3df-66a610559020","properties":{"cellContent":"What it tells you"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"9f89fd42-887a-41e9-9869-20ba07cabb3f","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"470b6c41-a538-4388-9a16-f0a3e8cc6c91","properties":{"cellContent":"Platform status"}},"settings":null},{"content":{"contentType":"tableCell","id":"bc3767ff-2449-4add-9ce9-5232e65a75e3","properties":{"cellContent":"You call TXN"}},"settings":null},{"content":{"contentType":"tableCell","id":"dee01b1d-1743-498a-85d3-0c09dbd57517","properties":{"cellContent":"Whether the API is up, and which environment answered"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"78a2a405-61f5-4071-b041-15604bbbc33c","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"f07f838f-e717-40e0-b25b-f852238d693b","properties":{"cellContent":"Webhook destination"}},"settings":null},{"content":{"contentType":"tableCell","id":"c5c1bd14-6465-4d8f-aa85-d857954d9e33","properties":{"cellContent":"TXN calls you"}},"settings":null},{"content":{"contentType":"tableCell","id":"b9cf74cd-150e-4aec-a9d6-00ecfc2e5d5f","properties":{"cellContent":"Whether TXN should keep sending you events"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"57aee33d-d39f-40e3-a544-621fdbba9a7d","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"e69fb842-4e7a-47d6-882e-8748e5c6745d","properties":{"cellContent":"Delegated approval endpoint"}},"settings":null},{"content":{"contentType":"tableCell","id":"8ff20d34-9115-4a8e-afe5-7765840d8fac","properties":{"cellContent":"TXN calls you"}},"settings":null},{"content":{"contentType":"tableCell","id":"1645a9e3-b52e-47af-aef2-56de21424226","properties":{"cellContent":"Whether your decision system is able to authorize transactions"}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"d42257ec-08b0-45ce-91aa-8fd062e632a6","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"aa6f022b-27fd-4fb8-88da-4ace9207bacf","name":"Ss Health Checks Three Checks Dark","mediaType":"Image","url":"/media/utecsheu/ss-health-checks-three-checks-dark.png","extension":"png","width":2400,"height":930,"bytes":347596,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"7fdfc713-0517-4a2a-a703-39791d0f7cec","name":"Ss Health Checks Three Checks Light","mediaType":"Image","url":"/media/tqgjtsl4/ss-health-checks-three-checks-light.png","extension":"png","width":2400,"height":930,"bytes":338698,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"9193bdb8-9599-4be9-86cc-49734d08784c","properties":{"sectionText":"The platform\u0027s own status, which you poll"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"0c5623cd-816b-46b6-b557-5af7b82289ea","properties":{"text":"TXN exposes a health endpoint you can call to ask whether the API is available. It takes no request body, changes nothing and has no side effects, so it is safe to call as often as your monitoring needs within the ordinary rate limits. The response carries a status, the deployed version, the current server time, how long the service has been running, and the environment label."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"5d14233f-9ead-4ad6-8f90-8e306e507d73","properties":{"text":"That environment label earns its place. The most common real use of this endpoint is not monitoring at all: it is confirming that the credentials and base address you have configured are pointing where you think they are, before you spend an afternoon debugging why your sandbox card cannot be found in production."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"657b0f93-58ec-4481-b602-2ce53af5b29d","properties":{"alertTitle":"The status is in the body, not the response code.","alertContent":"This endpoint answers successfully even when it is telling you the platform is degraded or unhealthy. A monitoring check that treats any successful response as \u0022up\u0022 will report a healthy platform throughout an outage. Read the status value out of the body and alert on that.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b51c8bdd-8808-40fa-8d55-97695f8421ca","properties":{"text":"Treat what comes back as the instance that answered reporting on itself. It confirms the API is reachable and what it says about its own condition. It is not a guarantee about every subsystem behind it, so a healthy response does not by itself mean a particular transaction will process."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"7b17806a-ac3b-4207-baaa-d440fe951047","properties":{"sectionText":"Your webhook destination, which TXN checks"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"fd58872e-307c-4935-90d4-a94deddfccb4","properties":{"text":"TXN calls a health endpoint on your webhook destination on a configured schedule, separately from event traffic. The point is to find out whether you can receive events before pushing a batch at an endpoint that cannot take them. Your endpoint is expected to answer with its status inside a defined timeout, and the checks themselves are rate limited so that the monitoring does not become a load problem of its own."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"98dd5a57-65d1-4591-b0f0-210dc0783800","properties":{"alertTitle":"A failed health check suspends your event delivery, not just the check.","alertContent":"When this check fails, webhook delivery to that destination is suspended for the next cycle rather than continuing. That is deliberate and it protects you, but it means an endpoint that fails health checks while otherwise working will stop receiving events. Nothing is lost, events generated during the suspension are retained and delivered when the endpoint recovers, but if your events have gone quiet and the platform is fine, this is the first thing to check.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"86bbbdf8-4519-4d6c-970b-f18276e2b648","properties":{"sectionText":"Your delegated approval endpoint, which TXN checks"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"53b0109f-8e02-44e0-9fad-4fb1a3d110f4","properties":{"text":"A program using delegated approval runs a second endpoint alongside the one that makes decisions, and TXN calls it on its own schedule. This is not a heartbeat you send; it is a question TXN asks. A decision request only arrives when there is a transaction to decide, so on a quiet program TXN could otherwise go a long time without discovering that your decision system has stopped working. The health check closes that gap."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"b2c34e74-6619-41b8-b9a9-4342ff600432","properties":{"alertTitle":"Answer honestly, and fail fast when you cannot decide.","alertContent":"The worst thing your health endpoint can do is answer successfully while your decision system is unable to authorize. TXN takes a healthy answer at face value and keeps routing live transactions at you, and those transactions are what pays the price. Answer promptly and successfully while you are genuinely able to decide, and fail quickly when you are not, so the fallback engages before cardholders notice.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"377464dc-d644-4889-85af-301171ed30c5","properties":{"sectionText":"Every response is traceable"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"dfce0625-f400-4ff8-801d-d7e4f235ea32","properties":{"text":"Like every call on the platform, a health response carries the correlation identifiers that let a specific request be traced through the platform and quoted to support. Requests and Responses covers what those are and how to use them."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e90b0ef7-79ee-4b26-9e00-f44c84e7f04b","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"1f06175f-0544-449c-9393-778a072a6493","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"75b6d106-af4d-4a7c-a79f-e2326f029e1b","properties":{"cardTitle":"Webhooks","cardText":"What gets suspended when a destination fails its check.","pageLink":{"contentType":"guidePage","name":"Webhooks","createDate":"2026-11-14T13:47:02.143Z","updateDate":"2026-11-15T16:32:40.257Z","route":{"path":"/103/staying-in-sync/webhooks/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1c117316-3d0f-42ce-9780-e5051e263d76","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"f13871d9-c35d-4ab8-b0f0-0b8e9b3c5c36","properties":{"cardTitle":"How Delegated Approval Works","cardText":"The decision endpoint the second check sits alongside.","pageLink":{"contentType":"guidePage","name":"How Delegated Approval Works","createDate":"2026-09-16T06:26:34.807Z","updateDate":"2026-11-15T16:32:47.123Z","route":{"path":"/103/delegated-approvals/how-delegated-approval-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e47adf53-2c39-46bb-bb12-ff0c765b075c","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"5c57cc5f-dd59-408f-8ef9-6b2930596769","properties":{"cardTitle":"Environments","cardText":"Which environment you are actually pointed at.","pageLink":{"contentType":"guidePage","name":"Environments","createDate":"2026-09-16T06:21:03.5Z","updateDate":"2026-11-15T16:32:45.067Z","route":{"path":"/103/getting-started/environments/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b230a635-a702-4570-a189-ce295a6165dc","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"2ce39501-aa69-44f0-aef6-72d92e9e7179","properties":{"prevPageTitle":"Webhooks","nextPageTitle":"Versions and Changes"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Core Objects","createDate":"2026-09-16T06:20:31.817Z","updateDate":"2026-11-15T16:32:39.203Z","route":{"path":"/103/getting-started/core-objects/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"0b97009e-ae9c-4b9b-a63d-ec7d5bd5c0c4","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"259cf5a3-2485-4dc0-9244-eb0a18c171da","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"fe5ffb58-5668-4595-bfa0-a76032914198","properties":{"title":"Core Objects","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"9d771a47-9026-4bb2-8918-e8eb1bb75eae","properties":{"text":"Every card issuing platform is built from a small set of objects that reference each other in a fixed order: someone the cards belong to, something that holds the money, the card itself, and the configuration behind it. Learning that shape once makes every other guide shorter, because each one can then assume you know where a given piece of behavior lives."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"a11c65df-c8cb-4fb5-a514-6af5ec46ee89","properties":{"text":"This page is the map. It covers what each object is for and how they reference each other, in enough detail to place something new when you meet it. The pages under Foundational Objects carry the full detail, lifecycle and edge cases for each object individually.\n\nFor the exact fields and operations on any of them, see the API Reference."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"8666ad25-41ca-4697-818d-5d7380b932ed","properties":{"sectionText":"Everything lives under a Card Program"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"76a7d6c7-96cc-42c0-97d6-493247325689","properties":{"text":"Everything you create through the API belongs to one Card Program. Cardholders, the groups they can belong to, accounts, products and cards are all held within it. The Card Program itself is arranged before you start building rather than created through the API, so from your first call onwards it is the context you work in rather than something you manage. What sits above it is covered at the end of this page."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"170645f7-3f8d-4948-a6a5-594b940c3729","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"7575b0e5-8b3e-49a0-a3c6-4dd82c2fe461","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"70e6b575-84e7-43c5-9c80-815e0a802326","properties":{"cellContent":"Object"}},"settings":null},{"content":{"contentType":"tableCell","id":"64b00681-74f2-4672-8f04-ce865d5ea1f5","properties":{"cellContent":"Description"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"5e7670b3-1fd6-4469-8ef7-0f1217786dc4","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"5dfe7c3c-e6eb-4561-8040-99acc77d300e","properties":{"cellContent":"Cardholder"}},"settings":null},{"content":{"contentType":"tableCell","id":"19dc9864-fea5-4419-9f2f-db607b64a6e1","properties":{"cellContent":"- A cardholder is the person or entity a card belongs to. Creating one captures who they are and how to reach them, including the addresses a physical card would be sent to.\n- A cardholder may have a parent cardholder, which is how hierarchical programs are represented, and may belong to a cardholder group. Both are optional, and a cardholder can have both, one or neither. Neither affects what a card issued to that cardholder is allowed to do."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"c816590c-e03e-4365-912f-5fc0fa99c71a","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"a5f4552e-9383-4360-b26c-4310dff9fc06","properties":{"cellContent":"Cardholder group"}},"settings":null},{"content":{"contentType":"tableCell","id":"ab58a9c6-4e1a-4257-b870-27255cb82212","properties":{"cellContent":"- A cardholder group is shared reference data. It holds a name, addresses and attributes that a number of cardholders can point at in common, rather than each one repeating the same details.\n- It is not a rules engine. A group carries no spend limits, no merchant restrictions and no configuration that reaches a card. Membership is set from the cardholder rather than from the group\u0027s own record."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"475627bc-78b2-4e83-ac13-d816d124c6a4","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"1316c7f8-c1a6-4b9b-9d50-8fbe4cc5e203","properties":{"cellContent":"Account"}},"settings":null},{"content":{"contentType":"tableCell","id":"77e01c3e-683e-41c8-ab20-7eba63e6956d","properties":{"cellContent":"- An account is where a balance sits. It is a TXN construct rather than a bank account, and it lives inside the Card Program alongside everything else you create.\n- Cards draw against an account rather than against a cardholder directly. An account has an owner, and can optionally be shared with other members, which is how one balance is made spendable by more than one person.\n- An account also carries one decision worth making deliberately: how spending against it is funded and approved. Either TXN holds the balance and you top it up, or you take the approval decision yourself through Delegated Approval, where your own systems approve or decline each transaction in real time. That choice shapes a good deal of your integration, and it is covered in full on the Accounts page."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"f30e4049-9170-43f8-b601-5ec30c490b24","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"17267f61-1ad1-46bd-8050-46e0fe380f6c","properties":{"cellContent":"Product"}},"settings":null},{"content":{"contentType":"tableCell","id":"da410d0e-0e46-4061-a26d-f8c3eec428d6","properties":{"cellContent":"- A product is the configuration a whole population of cards shares. It is created under a named Card Program, and it holds the BIN Range assigned to that program. A card issued against a product takes its behavior from the product rather than carrying settings of its own.\n- That inheritance is the point of the object. It lets you define how a set of cards behaves once, rather than configuring each card individually as you issue it.\n- Because that inheritance works both ways, a change to a product reaches the cards already issued under it, not only cards issued afterwards."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3d6033ab-9568-47cd-86d4-2e24865339ad","properties":{"sectionText":"How a card comes together"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"38b029c6-bb0c-4145-9213-90fb5822f8b5","properties":{"text":"A card is the only object that references three others. It is issued against a cardholder, an account and a product together, and it cannot exist until all three do.\n\nEach reference does a different job. The cardholder says who the card belongs to. The account says where the money comes from. The product says what the card is allowed to do. None of the three is optional.\n\nThis is what sets the order you build in. A cardholder and an account can be created independently of one another, and a product is created once for a whole population of cards rather than per card. The card comes last, because it is the only object that depends on all the rest.\n\nCards come in three forms: physical, virtual, and single-use virtual. The form is chosen when the card is issued."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"70d55d8c-80c9-4504-97f1-3fa54c0c3c56","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"e49bd430-e43c-45dd-9d11-4484b5c6914e","name":"Core Objects Arrangements Dark","mediaType":"Image","url":"/media/x2pn0usv/core-objects-arrangements-dark.png","extension":"png","width":2400,"height":1200,"bytes":238141,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"79a9c257-2c0e-425b-af94-98cc11424260","name":"Core Objects Arrangements Light","mediaType":"Image","url":"/media/1aeo5t1h/core-objects-arrangements-light.png","extension":"png","width":2400,"height":1200,"bytes":236053,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"10214848-2904-4dd3-8c24-70babd838ac7","properties":{"text":"A card is issued against a cardholder, an account and a product, and cannot exist until all three do. A cardholder may have a parent cardholder and may join a cardholder group. Using a card produces transactions, recorded against its account. Everything sits inside one Card Program."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"6d3dd5e1-200a-4f3e-b7be-0a28f90bff16","properties":{"alertTitle":"A card can be moved to a different cardholder","alertContent":"Transferring a card moves it to a different cardholder. Nothing in the card\u0027s existing account, transaction or lifecycle history is removed, altered or overwritten by the transfer. A card that needs either of those to be different is a new card, which for a physical card means reissuing and reposting it. Decide both before you issue.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"1bdedc82-0a87-48f2-8d2b-2b12dc03d838","properties":{"sectionText":"What changes over time"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"a64cf229-0097-47a0-9e13-6f13b573b96f","properties":{"text":"Four of these objects have a lifecycle: cardholders, cardholder groups, accounts and cards. Each can be moved between states, and each change is recorded as a transition rather than simply overwriting a status, so there is a history of what changed and why.\n\nProducts have no lifecycle. A product is changed in place rather than moved through states, which is the reason a change to one reaches the cards already issued under it.\n\nChanging the state of something above a card does two different things, and telling them apart matters. The first is effect. Putting an account on hold stops transactions on every card drawing against it, while those cards stay active in their own right. Read a card back and it still reports as active, because its own state has not changed. What has changed is whether anything will authorize against it.\n\nThe second is a state change you ask for. A transition can optionally be pushed down the hierarchy: from a cardholder group to its cardholders and on to their cards, or from a cardholder or an account to the cards beneath. That genuinely moves the lower object\u0027s own state, and it exists so you can reflect a change across a whole hierarchy in one action rather than walking it yourself. It is opt-in, so nothing moves down unless you choose it.\n\nWhich you want depends on whether the change is temporary. A hold that will be lifted is better left as an effect. A change meant to stick is better pushed down, so the hierarchy tells a consistent story afterwards."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"64b47d57-3820-4985-a59b-e29d62d95b90","properties":{"alertTitle":"An active card can still decline","alertContent":"A card\u0027s own state does not tell you whether it can be used. If the account it draws against is on hold, the card reports as active and nothing will authorize against it. When you are diagnosing a decline, check the account and the cardholder as well as the card.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"0930ac50-63d3-41f4-a9aa-9f3fa24562df","properties":{"text":"Using a live card produces transactions, recorded against the account the card draws on. Money Movement covers what a transaction is and how to read one back."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"bb7ff1f3-b55e-4550-9efb-e3b9261579d0","properties":{"sectionText":"What sits above a Card Program"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b5fcd269-4307-431b-abab-d97aedf5f37e","properties":{"text":"Above the Card Program sit the arrangements that make a card legitimately spendable. A BIN Sponsor owns a BIN and divides it into BIN Ranges. A Program Manager manages the Card Program and assigns a range to it, and that range is held by the product rather than by any other object.\n\nThese are separate relationships rather than a chain of command. A BIN Sponsor does not sit above a Program Manager, and a Program Manager may work with more than one BIN Sponsor. In some programs the BIN Sponsor also acts as the Program Manager. What connects them is the BIN Range, not ownership.\n\nOnly one of these reaches into the work you do day to day. Because the product holds the BIN Range, the product is where the arrangement becomes visible in what you build. Nothing you create references a BIN or a BIN Sponsor directly."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"dbd38d66-02fe-4243-8d0a-e39df9c862bd","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"51eec37d-d062-4fe3-8c40-b0993a265f87","name":"Core Objects Card Model Dark Final","mediaType":"Image","url":"/media/4ielrzyl/core-objects-card-model-dark-final.png","extension":"png","width":2400,"height":1300,"bytes":245383,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"324796e7-2ed3-4954-a376-e4a19dd3e2d1","name":"Core Objects Card Model Light Final","mediaType":"Image","url":"/media/nboadbf0/core-objects-card-model-light-final.png","extension":"png","width":2400,"height":1300,"bytes":242367,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"db4d5270-5322-40a4-b302-363500ce0d08","properties":{"text":"A BIN Sponsor owns a BIN, which is divided into BIN Ranges. A Program Manager manages the Card Program and assigns a range to it. The range is held by the product, which is the only place the arrangement is visible in what you build."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"94888d95-7229-4408-89f4-2fd6d28ec810","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"c0c48f05-c294-4c4a-b3ed-b5382aabeb0b","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"b2a0cfe0-9c9c-418b-817d-9ca39b680f39","properties":{"cardTitle":"Accounts","cardText":"Ownership, shared members, and choosing how spending is funded and approved.","pageLink":{"contentType":"guidePage","name":"Accounts","createDate":"2026-09-16T06:22:09.903Z","updateDate":"2026-11-15T16:32:43.31Z","route":{"path":"/103/foundational-objects/accounts/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"5c10167b-6790-43b8-8d90-d56c1a423a5c","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"face521c-a777-4c89-9080-d3b27ca8044a","properties":{"cardTitle":"Cards","cardText":"Issuing a card, the three forms, and the card lifecycle.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"40029f13-4e3c-45ba-992f-0b6dd9f7140e","properties":{"cardTitle":"Products","cardText":"The configuration a whole population of cards shares, and where the BIN Range is held.","pageLink":{"contentType":"guidePage","name":"Products","createDate":"2026-09-16T06:22:36.26Z","updateDate":"2026-11-15T16:32:42.283Z","route":{"path":"/103/foundational-objects/products/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"38067e3a-67a3-4525-b8e7-987c4c4c8b58","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"349a7981-537f-459d-80e1-edca1ca2c43b","properties":{"prevPageTitle":"Introduction","nextPageTitle":"Environments"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Go-Live Checklist","createDate":"2026-09-16T11:15:47.56Z","updateDate":"2026-11-15T16:32:39.463Z","route":{"path":"/103/going-live/go-live-checklist/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"12248e91-a4b4-4166-aa39-5c888cb4f7dc","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"1bbf665e-78ac-4eef-8778-e5d858e7f9d4","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"a4097ba1-8898-462f-8953-090e8af9f27a","properties":{"title":"Go-Live Checklist","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"c32c5faa-35a7-4e4b-bf02-5719f0e0d410","properties":{"text":"Going live is the point at which mistakes start costing real money. This checklist covers what to confirm before that happens, including the things that are easy to leave until they fail."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3b7b5b6f-94ba-4964-8e04-b4c304fef279","properties":{"text":"Two kinds of thing go wrong at go-live. The first is the gap between a sandbox integration and a production one, where something you never had to think about turns out to work differently. The second is behavior that only shows up under real traffic, which no amount of sandbox testing will surface because the conditions never arise.\n\nThis page covers both. Work down it before the date rather than on it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"132a4eaa-9619-4b9f-b0a5-422dfa5f50b5","properties":{"sectionText":"Production is a separate environment, not a promoted one"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"21b121fb-4178-4dca-bc71-367513c6d058","properties":{"text":"Nothing you created in a sandbox exists in production. Credentials, products, cards, cardholders, accounts, controls and webhook configuration are all established in production in their own right, and a configured object is only there because somebody put it there.\n\nConfirm which API version your production target answers with. Versions are deployed per environment, so the version your sandbox reports is not evidence of what production is running. See Versions and Changes."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"cd3d030a-d4fc-43c8-be02-1288a4473423","properties":{"sectionText":"How production knows which program a request belongs to"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"a3ebd567-7332-4694-9519-3d15c3523752","properties":{"text":"Production runs a single entry point. Your Card Program is not identified by having an address of its own, and it does not get one. The program context is fixed when you obtain your access token, and every call made with that token goes to that Card Program.\n\nThis matters most for integrations that manage more than one program. What separates them is the token you hold, not where the request was sent."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"e1025f3c-f1b1-4bbc-b7ef-74eefa3589ab","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"2d035683-bacc-489e-ab0e-107ec72f8064","name":"Gl Go Live Checklist Program Context Flow Dark","mediaType":"Image","url":"/media/bsoelg3f/gl-go-live-checklist-program-context-flow-dark.png","extension":"png","width":2400,"height":690,"bytes":225533,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"bf80bf2c-a7ff-4787-984b-42b93e91726b","name":"Gl Go Live Checklist Program Context Flow Light","mediaType":"Image","url":"/media/un0nmcmw/gl-go-live-checklist-program-context-flow-light.png","extension":"png","width":2400,"height":690,"bytes":221626,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"cd2e7c58-875d-419c-a942-497d8af66a67","properties":{"alertTitle":"Do not key anything off the base address.","alertContent":"If your code decides which program it is acting on by looking at where it is pointed, that logic has nothing to work with in production. Routing, configuration lookups, environment switches and test fixtures all need to resolve the program from the credentials and token you hold instead. This is the kind of assumption that survives every sandbox test and then fails on the first day with two programs live.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"37cfea4f-0fdf-44ab-ac0b-6c250d59b36c","properties":{"sectionText":"Authentication in production"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"f36356f3-6a24-4c0a-a8d4-973b89514586","properties":{"text":"Production API requests authenticate with JWT. The token is validated before anything is processed. The claims, scopes and policies it carries decide whether the call is allowed at all, and the Card Program it was issued for decides where the call goes.\n\nConfirm three things in your client. That it obtains a token rather than assuming one is already present. That it caches and renews rather than requesting one per call. And that an expired token is treated as a condition to renew and retry, not as a failed request handed back to whatever called it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4c1b9f97-0dc8-4f44-ac9b-a7c87c444f32","properties":{"sectionText":"Errors and declines need a real path through your code"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b176002f-d9c3-43c3-b777-0c2b47b43c58","properties":{"text":"An error is a normal outcome, not an exception to deal with later. Confirm that your application reads the error code rather than matching on the description, which can be reworded without that counting as a breaking change, and that a 404 is treated as \u0022does not exist, or you cannot see it\u0022, because the two are deliberately indistinguishable.\n\nDeclines deserve the same treatment. A declined authorization is the platform working correctly, and your integration should be able to tell a cardholder why without a developer reading logs."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"5d30034b-992f-48d1-b78d-4b11c0710d34","properties":{"sectionText":"Retrying a write: the hazard is a stale reply, not a duplicate"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"99a97797-a2ad-498e-9530-a535e4cab81b","properties":{"text":"The platform recognizes a repeated request and replays the original response rather than processing it twice, and it tells you with an x-idempotent-replayed header when a reply came from that replay. So retrying a timed-out write is not the duplicate-creation risk it would be on an API without that behavior.\n\nThe risk sits on the other side: reusing a requestId by mistake."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"d71acd86-be58-4ae0-8592-d783b2e87d00","properties":{"alertTitle":"A reused requestId can return the old answer.","alertContent":"If two genuinely separate requests carry the same requestId and the same body, the second is treated as a replay and you get the first response back without the second being processed. Nothing looks like an error. With a different body the request is rejected with a 422. Use a fresh requestId for every new request, and reuse one only to retry the same request.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"94e6427d-26bc-4337-8486-85c074682f3b","properties":{"text":"A replayed response is held for 24 hours by default, so a retry inside that window is safe to send with the same requestId. Only completed successful requests are stored, so a request that failed is processed afresh when you retry it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"da77bb68-0e29-4b4c-9b66-a6ffaa6f970c","properties":{"sectionText":"Your webhook receiver is half the integration"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"f5b91457-bf30-47b9-9675-0bd3c44eae7d","properties":{"text":"Confirm the endpoint is reachable from the platform rather than only from your own network, that signature verification is switched on rather than planned, and that the receiver acknowledges quickly and does its real work afterwards. A slow receiver looks like a failed one, and failed deliveries are retried.\n\nRetries use exponential backoff, so a receiver that was briefly down recovers on its own. That is also what makes repeat delivery normal rather than exceptional. Events are persisted and can be replayed, which is how you fill a gap after an outage rather than reconstructing state by polling."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"86926f90-8e17-4846-9782-af30efe19a79","properties":{"alertTitle":"A repeat delivery is not a fault.","alertContent":"Your receiver will see the same event more than once, because a retry cannot know whether the first attempt was never received or merely never acknowledged. Handle events idempotently by their identifier and make sure a duplicate cannot double-apply anything on your side. Test a repeat delivery before go-live, not after the first retry storm.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4eaf2e79-47bd-4c11-bdb2-460415b1e1f9","properties":{"sectionText":"Rate limits only become real under real traffic"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"acd5c071-9648-43f8-b8c5-6cf439cdfcff","properties":{"text":"Sandbox testing rarely comes near a limit, so this is easy to leave untested until it starts to matter. Every response carries your limit and the length of its window in x-rate-limit-limit and x-rate-limit-window. These are fixed values, not a running count, so they give you the ceiling but not how much of it you have used. Track your own request rate against them.\n\nConfirm that a rate-limited response is handled as a signal to back off and retry rather than as an error to surface, and that whatever you built to retry does not itself make the problem worse. A 429 does not say how long to wait, so build your own backoff."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ceabde26-1706-438b-bfc6-eba9c4d07396","properties":{"sectionText":"Monitoring has to exist before the first incident"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"e33fb470-c701-45cb-b976-3d562070ae18","properties":{"text":"Build monitoring before you need it. Poll the platform health check and alert on the status it reports rather than only on whether the call failed, since an unhealthy platform still answers successfully. See Health Checks.\n\nAlert on your own error rates broken down by error code, so a change in what the platform is telling you appears as a trend rather than as a handful of support tickets a week later."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"9fce2808-e555-4193-a10f-0fa716188707","properties":{"sectionText":"Someone other than your engineers has to be able to run the program"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"246f7241-8667-49c6-9934-0d24c0a1d50d","properties":{"text":"Go-live moves the day-to-day work from your engineering team to whoever supports your cardholders. Confirm that those people have access to Control Center before the first call comes in, and that they can find a card, see a transaction, put a card on hold and check why something declined without needing a developer to run an API call for them.\n\nAn operations team that has to raise a ticket with engineering to answer a cardholder question is a go-live problem, not an onboarding detail."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"55fd34be-b0e6-4894-a8d4-8b78d1c54a58","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"6b209538-95f1-42d2-a990-9de43ed3c296","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"4cb58f6c-31ad-490c-ac8e-b0e8b58e5958","properties":{"cardTitle":"Versions and Changes","cardText":"Which version production is running, and how changes are announced.","pageLink":{"contentType":"guidePage","name":"Versions and Changes","createDate":"2026-09-16T11:13:56.453Z","updateDate":"2026-11-15T16:32:44.057Z","route":{"path":"/103/going-live/versions-and-changes/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"8f1cb6b9-3dda-4ea5-9498-87379b576efb","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"08bf3b10-ea3f-4224-b0f0-d51e33df86ce","properties":{"cardTitle":"Webhooks","cardText":"Configuring, verifying and replaying the events your integration depends on.","pageLink":{"contentType":"guidePage","name":"Webhooks","createDate":"2026-11-14T13:47:02.143Z","updateDate":"2026-11-15T16:32:40.257Z","route":{"path":"/103/staying-in-sync/webhooks/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1c117316-3d0f-42ce-9780-e5051e263d76","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"3dfbe31d-cf8b-41e0-9fc7-be95f9ee15e0","properties":{"cardTitle":"Control Center","cardText":"The operational interface your support team works in once the program is live.","pageLink":{"contentType":"guidePage","name":"Control Center","createDate":"2026-09-17T10:20:00.54Z","updateDate":"2026-11-15T16:32:46.61Z","route":{"path":"/103/getting-started/control-center/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dad6c052-ee94-4769-96a3-4ecef68cef59","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"dea6a695-5a04-4d0d-9ad0-6b21695244a8","properties":{"prevPageTitle":"Versions and Changes","nextPageTitle":null}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Balances","createDate":"2026-09-16T06:23:36.843Z","updateDate":"2026-11-15T16:32:40.1Z","route":{"path":"/103/money-movement/balances/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1acbd4db-1c7f-4f4b-a390-e6cb6c889e2d","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"73b1f34a-56f0-4268-9db6-8549c3aa4fd3","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"728b48b7-fe4d-4e93-87f5-2784b3a32a59","properties":{"title":"Balances","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"290e5473-e60a-45a3-95ab-b64d8d4b1d89","properties":{"text":"A balance on TXN is two figures, not one, and it is authoritative for one thing rather than everything. Getting both of those straight is most of what this page is for."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"d52cde19-c087-40f1-b9e1-07b41d9ebc56","properties":{"text":"Start with the division of truth, because everything else follows from it. TXN authorizes transactions against the balance it holds, so that figure is the source of truth for whether a transaction is approved. It is not necessarily the cardholder\u0027s actual balance. TXN sees card transactions and nothing else: the transfers, top-ups, payroll runs and other money movements happening in your program are invisible here. You hold that picture; TXN holds the one that decides authorizations. Keeping the second in step with the first is ordinary operating work, not error correction."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e090afbb-8deb-4d65-ad75-d53c1e32c569","properties":{"sectionText":"The two figures, and when they disagree"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"593ec272-9a96-4fea-a8f0-dc459e83b3e3","properties":{"text":"A balance read returns a ledger balance and an available balance, and using the wrong one is the most common mistake available here. The ledger balance is cleared funds only: money that has completed its journey and settled. The available balance is what can actually be spent right now: the ledger balance less any pending transactions and holds sitting against the account. They agree when nothing is in flight and diverge the moment something is. A cardholder who has just paid at a terminal sees the available balance drop immediately while the ledger balance stays where it was until that transaction settles."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"161093e7-1743-4e6c-836e-103de9e80f39","properties":{"sectionText":"Which one to show, and which one to reconcile against"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"9a11d770-89a6-44f7-ba35-92d177d9536b","properties":{"text":"A cardholder-facing display wants the available balance, because the question a cardholder is asking is \u0022what can I spend\u0022. Reconciliation wants the ledger balance, because the question there is \u0022what has actually moved\u0022. Showing a cardholder the ledger balance produces the specific complaint that their app disagrees with the shop, and reconciling against the available balance produces figures that do not tie out because they include money that has not gone anywhere yet."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"1b0ffa82-a935-44ea-bea8-801df25e3c39","properties":{"sectionText":"How card activity moves each figure"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"6f2537f4-f416-4c4f-8aee-b7c883163662","properties":{"text":"Balance moves as a consequence of activity on the account\u0027s cards rather than through anything you do. An authorization places a hold, taking the available balance down while the ledger balance stays put. Clearing settles it, and the ledger balance moves. A reversal or a refund puts it back. A failed or reversed transaction rolls back rather than leaving a residue. The gap between the two figures is therefore the answer to \u0022what is in flight\u0022, which is why the pending-versus-settled question is answered by reading the balance rather than by reconstructing it from transaction history."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"1e235376-fa7d-4929-88a7-05daccda3ec1","properties":{"sectionText":"Keeping TXN\u0027s balance in step with yours"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b5adda19-8689-4f91-a97e-ca201bed5e61","properties":{"text":"Since TXN cannot see the money movements on your side, you tell it what changed. A balance adjustment takes an amount, a currency and an operation: set the balance to a figure, increase it by an amount, or decrease it by an amount. The change takes effect immediately and is available to the very next authorization, which is the point: a funding event on your side that has not reached TXN is a funding event the cardholder cannot spend against."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"49380d47-a05a-454e-b32f-4dd516de95fe","properties":{"alertTitle":"Always state the operation.","alertContent":"An adjustment sent without an explicit operation overwrites the balance rather than moving it. That is almost never what you want when you are applying a movement that has already happened on your side, and the failure is quiet: the call succeeds, the balance is now a number you did not intend, and nothing about the response says so. Send the operation on every adjustment, including the ones where the outcome would look the same either way.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"6421e164-b592-402c-8c0a-266ba3398b16","properties":{"sectionText":"The adjustment is recorded, not just applied"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ac6cf386-8446-4858-bdcd-28f2d04d05ac","properties":{"text":"Every adjustment is written to the account\u0027s ledger as a credit or a debit in its own right, alongside the authorizations, clearings and reversals that arrived from card activity. The record captures who made it, when, and the reference you supplied. So the ledger is not only a running total: it is a complete account of how the balance reached its current figure, with your adjustments and TXN\u0027s own movements in one sequence rather than two."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"8b52ed12-5a55-4736-85f9-fcafb40b2391","properties":{"sectionText":"Currency is checked, not converted"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"d299d57e-817d-4576-9f9e-a416ebdf7db6","properties":{"text":"An account is created with a single currency and that never changes. An adjustment carries a currency of its own, and it has to match the account\u0027s. TXN does not convert on your behalf and does not take a best guess at intent."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"28c02ebd-e5b5-4d5a-ac36-4efa87d5fab0","properties":{"alertTitle":"A rejected adjustment changes nothing at all.","alertContent":"Every validation runs before the balance is touched, so a rejected adjustment leaves the balance exactly where it was rather than partially applying. The response carries a deterministic error code and reason, and the failure is logged. Treat that as the contract it is: on a rejection there is nothing to unwind and nothing to reconcile, and the right response is to fix the request rather than to check what state the account was left in.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"eae26918-b203-40e8-b300-aabd54962aad","properties":{"sectionText":"Retrying an adjustment safely"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"8ecbc00a-7426-4a67-af92-511ea41cd79a","properties":{"text":"A balance adjustment is one of the calls where a retry after an uncertain outcome is genuinely dangerous: a network failure after TXN has applied a credit but before you saw the response should not become a second credit. Adjustments are idempotent for exactly this reason, so a retry that repeats the same request identifier is recognized as the same operation rather than performed again. Retries and Idempotency covers how that identity is established across the API."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"b4ab09fb-d1bd-4d31-b454-83b39d9b541c","properties":{"sectionText":"Where the balance stops being the decider"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b4d1883d-52e5-4498-a622-0426b4d5b681","properties":{"text":"All of the above describes a platform managed account, where TXN holds the balance and authorizes against it. On a delegated approval account the decision leaves TXN entirely: the authorization is passed to your systems in real time and you approve or decline it against whatever you hold. TXN still keeps a balance on the account and you can still read and adjust it, but it is not what decides the transaction. Your delegated approval response can also carry a balance, which replaces the figure TXN is holding."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"861ff9f6-91f8-4a4d-923f-8724e435b07a","properties":{"alertTitle":"On a delegated approval account, adjusting the balance will not change what gets approved.","alertContent":"This catches people mid-migration. If an account\u0027s funding type is delegated approval, the decision is made by your endpoint and the balance TXN holds is a record rather than a control. Adjusting it up will not make a declined transaction approve, and adjusting it down will not stop one. Check the account\u0027s funding type before spending time on the balance.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"1940cd93-0947-4348-bef0-da9508e4b96a","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"69e5a932-1fa1-4081-b729-47f4ceb0869f","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"e72941bf-61a8-42e6-b597-f34118e5b97f","properties":{"cardTitle":"Accounts","cardText":"The account the balance belongs to, its currency and its funding type.","pageLink":{"contentType":"guidePage","name":"Accounts","createDate":"2026-09-16T06:22:09.903Z","updateDate":"2026-11-15T16:32:43.31Z","route":{"path":"/103/foundational-objects/accounts/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"5c10167b-6790-43b8-8d90-d56c1a423a5c","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"e25c7423-e3c0-488c-9548-bf8ba037009d","properties":{"cardTitle":"Transactions","cardText":"The card activity that moves the balance without you touching it.","pageLink":{"contentType":"guidePage","name":"Transactions","createDate":"2026-09-16T06:23:22.427Z","updateDate":"2026-11-15T16:32:47.27Z","route":{"path":"/103/money-movement/transactions/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e79295d5-99a5-4e5f-859c-c15d73178622","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"d567e385-3a29-4574-b247-9fd02afe020b","properties":{"cardTitle":"How Delegated Approval Works","cardText":"What decides an authorization when the balance does not.","pageLink":{"contentType":"guidePage","name":"How Delegated Approval Works","createDate":"2026-09-16T06:26:34.807Z","updateDate":"2026-11-15T16:32:47.123Z","route":{"path":"/103/delegated-approvals/how-delegated-approval-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e47adf53-2c39-46bb-bb12-ff0c765b075c","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"10b4d624-e081-49ff-9d6c-d606acabac3d","properties":{"prevPageTitle":"Transactions","nextPageTitle":"Activating a Card"}},"settings":null}},"cultures":{}},{"contentType":"baseGuidePage","name":"Working With TXN","createDate":"2026-09-16T10:30:29.247Z","updateDate":"2026-11-15T16:32:40.413Z","route":{"path":"/103/working-with-txn/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e3388c81-32a2-4b4f-88c1-fe6687c61ef6","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"f3314531-8479-4197-a958-0662dff52743","name":"Working With Txn","mediaType":"umbracoMediaVectorGraphics","url":"/media/yp2jgelc/working-with-txn.svg","extension":"svg","width":null,"height":null,"bytes":8167,"properties":{}}]},"cultures":{}},{"contentType":"guidePage","name":"Payment Terms","createDate":"2026-09-18T14:44:39.46Z","updateDate":"2026-11-16T06:59:32.047Z","route":{"path":"/103/payment-concepts/payment-terms/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b72be41a-a634-425c-ae8b-4ca31e6dffa0","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"baab0a52-59b6-4b5f-bfe0-8047dfcb8342","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"01a4c1f1-f1c8-49fc-9c07-66f377ee636f","properties":{"title":"Payment Terms","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"44dc414b-65ff-4cb1-a23e-2aca5b4f00f5","properties":{"text":"Card payments carry a vocabulary of their own, and much of it is assumed rather than explained. This page defines the terms you will meet in these guides, in scheme documentation and in conversation with your BIN Sponsor. Terms that name something TXN builds are defined briefly here and in full on the page that owns them."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"bb69259b-869e-4b87-9765-443f24a0f327","properties":{"text":"Two kinds of term appear below. Industry terms mean the same thing wherever you meet them. A smaller group names something specific to TXN, and those carry a pointer to the guide that defines them properly rather than a second definition that can drift out of step. Terms are listed alphabetically.\n\nFor how a payment moves from authorization through clearing to settlement, see Transaction Lifecycle."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"15ae4636-a1f5-464d-b174-2c12412f0d00","properties":{"sectionText":"A"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"4790d59e-1584-4955-8e1a-b32e59d4ccfb","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"6943781f-5548-470e-91df-7ab2ecc0de93","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"cc4ce265-bb6e-445c-ade3-69c5bde525df","properties":{"cellContent":"Term"}},"settings":null},{"content":{"contentType":"tableCell","id":"835df7b3-6c15-4aca-8fff-ebf66c7908b6","properties":{"cellContent":"Meaning"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"65ca2a55-343e-4b28-b461-bb95cb61c901","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"10937926-a0b3-4778-8727-62636b3aad8a","properties":{"cellContent":"3-D Secure"}},"settings":null},{"content":{"contentType":"tableCell","id":"65ec5882-adf8-404a-82a7-7b215c903c92","properties":{"cellContent":"The scheme mechanism that lets an issuer authenticate a cardholder during an ECommerce payment. Satisfies Strong Customer Authentication and can shift fraud liability away from the merchant."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"4675daa4-1236-4f82-8cc1-a611b1882e78","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"9fda16b3-fe4d-401c-976f-390b32e75d70","properties":{"cellContent":"Account"}},"settings":null},{"content":{"contentType":"tableCell","id":"ced6325e-2165-4e0e-91a5-280c5fde330f","properties":{"cellContent":"Where a balance sits on TXN, and what a card draws against. A TXN construct rather than a bank account. See Accounts."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"2ce97d3a-056d-4b27-a8b2-2f8236997b89","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"3760d211-5d0f-4589-b581-d2b3a9b5413f","properties":{"cellContent":"Account Name Inquiry"}},"settings":null},{"content":{"contentType":"tableCell","id":"e989134f-444f-4cb2-a504-f2cbe6f4e4a6","properties":{"cellContent":"A check that the name supplied for a payment matches the name the issuer holds for the cardholder. Carried out as a zero-amount authorization."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"d1b6b672-c5e0-4413-830a-81cb7b92baf4","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"9e74bcc4-194b-4143-8dbf-2c2fbbd87301","properties":{"cellContent":"Account updater"}},"settings":null},{"content":{"contentType":"tableCell","id":"fdffef14-ab18-4767-a027-090f72761664","properties":{"cellContent":"A scheme service that pushes changed card details to merchants holding the card on file, so recurring payments survive a reissue."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"5de027e5-4c07-4c68-9b66-9cbe4da1a8b6","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"b54fb868-2d00-4499-a6af-e920f8b74233","properties":{"cellContent":"Account verification"}},"settings":null},{"content":{"contentType":"tableCell","id":"6099b186-7547-451e-a283-46692a649521","properties":{"cellContent":"An authorization for no amount, used to confirm a card exists and is usable without charging anything or holding funds."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"46748690-c60a-4ac6-a8bd-20585e2b5525","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"f9ede6b1-1069-4a64-be48-e57f2e2ad110","properties":{"cellContent":"Acquirer"}},"settings":null},{"content":{"contentType":"tableCell","id":"32d00473-3c10-4064-b07c-a31eaba9c1a2","properties":{"cellContent":"The bank that holds the merchant\u0027s account and receives the money from card payments on their behalf. The merchant\u0027s side of the transaction."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"31937468-eceb-431e-b162-618155b0f1e0","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"c62fdfc6-dd44-4c46-9d5e-dcaf27f2a24e","properties":{"cellContent":"Acquirer processor"}},"settings":null},{"content":{"contentType":"tableCell","id":"4b3ffc52-b23e-4af4-bed9-347bfb781999","properties":{"cellContent":"The processor acting for the acquirer, moving transactions between the merchant and the card network."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"75a5ff40-5802-4ebf-aceb-22fe279c73ff","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"dc64e102-8bd1-44ad-b81a-7e9dc09fcc9d","properties":{"cellContent":"Address Verification Service"}},"settings":null},{"content":{"contentType":"tableCell","id":"99b1499f-ed45-49ac-9de6-2213ea11ce3b","properties":{"cellContent":"A check comparing address details supplied with a card-not-present payment against the addresses the issuer holds. Returns a result rather than a decision."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"27edd062-28f2-40c6-aae5-31830a29d99f","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"365aefed-5a8d-41d5-9758-8dbf84d02978","properties":{"cellContent":"Advice"}},"settings":null},{"content":{"contentType":"tableCell","id":"0f666fd0-8dc1-477a-b1b2-9e15705c45ae","properties":{"cellContent":"A message that tells the other side something has already happened, rather than asking for approval. Contrasted with a request, which awaits an answer."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"75310dd3-1b2f-47ca-bb5b-c36e2257e737","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"135a77d3-a21a-43b1-a0d2-6bd86b7271f2","properties":{"cellContent":"Authorization"}},"settings":null},{"content":{"contentType":"tableCell","id":"50d952b1-8756-45dd-adb6-7c6bb5475ca5","properties":{"cellContent":"The real-time decision on whether a payment may proceed. Reserves the amount against the available balance; it does not move money."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"569ba37b-89c9-4ee1-b06b-5229aa600683","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"3f82a52d-0567-4b9d-9b64-de9fea85f963","properties":{"cellContent":"Authorization code"}},"settings":null},{"content":{"contentType":"tableCell","id":"834cddf3-0c20-414f-a380-0eff05f27580","properties":{"cellContent":"The reference returned when a payment is approved. The merchant keeps it as the record that the issuer said yes."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"6f6858e5-a153-4801-a722-20ac05f37a09","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"d78b0c9b-768e-4a22-b9e0-e355618be96d","properties":{"cellContent":"Available balance"}},"settings":null},{"content":{"contentType":"tableCell","id":"1f9ad882-351e-4d0f-a324-e88e4239ec47","properties":{"cellContent":"What can actually be spent right now: the ledger balance less any pending transactions and holds. Usually the figure a cardholder should see."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"8c217747-4aac-4101-8068-95c320423746","properties":{"sectionText":"B to C"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"07ee615e-7e4a-4e36-aa0a-f23a0baf9e13","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"efb87082-1868-4a64-9b54-064c8e63a33b","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"54daa72c-e5cf-4816-a3ac-013ff993ec6f","properties":{"cellContent":"Term"}},"settings":null},{"content":{"contentType":"tableCell","id":"d03b32f9-6031-4b5a-b460-be4243a8e77e","properties":{"cellContent":"Meaning"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"f569d8c7-6b2a-4e6f-85b1-f06a404aec99","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"f5144139-1c27-486f-ad23-48c7d63a6376","properties":{"cellContent":"Balance adjustment"}},"settings":null},{"content":{"contentType":"tableCell","id":"c29eae2b-aa73-4009-b495-778961814c18","properties":{"cellContent":"How a Program Owner keeps the balance TXN holds in step with their own as money moves on their side. See Balances."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"68b5b074-1506-40a8-ac1e-aa7dac4994ee","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"d978b1be-5899-4189-b4f1-b78a83261d6e","properties":{"cellContent":"BIN"}},"settings":null},{"content":{"contentType":"tableCell","id":"cf765fff-5106-4a14-811a-c6ebfa6bc602","properties":{"cellContent":"Bank Identification Number. The leading digits of a card number, identifying the institution the card was issued under."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"c0501c15-97e5-4a52-baf0-175fbfac1f4e","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"2a976154-3eb4-4619-bcc2-f43df77dfd49","properties":{"cellContent":"BIN Range"}},"settings":null},{"content":{"contentType":"tableCell","id":"7b59f218-0dc9-4a2f-9e25-fe4849904860","properties":{"cellContent":"A block of numbers within a BIN, allocated to a particular Card Program so its cards can be told apart from others on the same BIN."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"0b5b1865-b4a9-4ee0-9e50-ed3698148919","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"8c6fc8fc-1e46-411f-b30a-c50c62ed3f0b","properties":{"cellContent":"BIN Sponsor"}},"settings":null},{"content":{"contentType":"tableCell","id":"90b20b44-dc46-476d-8f04-f6a601daa638","properties":{"cellContent":"The regulated bank that holds scheme membership and owns the BINs a Card Program issues on, approving how they are used. Secured by the Program Owner, not TXN. Also called a Sponsoring Bank."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"d9bc62e5-ac4c-4dce-a0f4-10679aeda5b3","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"92d78944-070f-4e53-a744-e1bbb8676823","properties":{"cellContent":"Capture"}},"settings":null},{"content":{"contentType":"tableCell","id":"03a3cd41-f1c3-4747-8eae-1417656f1135","properties":{"cellContent":"The merchant finalizing an authorization so that the money can actually move. A payment authorized but never captured eventually falls away."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"65eeaa4f-f574-4c23-bc02-c27a83124cfb","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"28ec7bd5-de43-47b1-88a2-d9b0e0a76619","properties":{"cellContent":"Card"}},"settings":null},{"content":{"contentType":"tableCell","id":"4ef73361-38d6-45a7-bd84-24246471f98a","properties":{"cellContent":"The payment instrument itself, issued against a cardholder, an account and a product. See Cards."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"da822fe1-ab8d-4214-801c-a3975ef6322e","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"06ceb0b7-7022-45e6-83a7-152bf11876b1","properties":{"cellContent":"Card network"}},"settings":null},{"content":{"contentType":"tableCell","id":"3dd80ef9-41c8-487d-9021-2c6fde250e1c","properties":{"cellContent":"Visa or Mastercard. Sets the rules, carries messages between issuers and acquirers, and allocates BIN ranges to its members. Also called the card scheme."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"4ee68ce5-1d20-4f65-9f8e-f45a6f8f9df6","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"3a88df8b-21e7-4785-b819-c70991cbf29a","properties":{"cellContent":"Card not present"}},"settings":null},{"content":{"contentType":"tableCell","id":"c7e3cae4-f1bf-4a2a-a200-7119c2b25faa","properties":{"cellContent":"A payment where the card is not physically at the point of sale: ECommerce, mail order, telephone order. Higher fraud risk, and where AVS and 3-D Secure apply."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"2a763b3d-a143-4754-811a-640b0ae70cb0","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ffdca700-229b-4c8d-8263-7063347c11a5","properties":{"cellContent":"Card present"}},"settings":null},{"content":{"contentType":"tableCell","id":"066d21cb-2079-43b2-b423-75a8657efe35","properties":{"cellContent":"A payment where the card is at the point of sale, read by chip, contactless or magnetic stripe."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"fa3e6096-d073-4331-bfe5-095e7e6b3469","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"e448ed8e-b2c2-4300-9e33-e4a741031064","properties":{"cellContent":"Card Program"}},"settings":null},{"content":{"contentType":"tableCell","id":"cbef5529-7533-4d13-b362-62985b4f7d2b","properties":{"cellContent":"The container everything in an integration belongs to: cardholders, accounts, products and cards. Provisioned before your first call. See Core Objects."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"f6cd3adf-041e-4469-ba27-95190c29f058","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"c928e877-de43-495b-978b-aca1c2e0a42e","properties":{"cellContent":"Cardholder"}},"settings":null},{"content":{"contentType":"tableCell","id":"6c4a5232-8c5f-4962-94bc-83fa3f1dd3f1","properties":{"cellContent":"The person or entity a card belongs to. See Cardholders."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"1f878631-012f-4ad7-883c-9d15d5271b00","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"604336de-2221-4c24-98b3-b8155e53340f","properties":{"cellContent":"Cardholder Group"}},"settings":null},{"content":{"contentType":"tableCell","id":"3addd34e-1549-4de0-93ce-5cbc884f579e","properties":{"cellContent":"Shared reference data that a number of cardholders can point at rather than each carrying their own copy. See Cardholder Groups."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"3d5dca5d-00f5-432b-b91f-c6a8313e81f5","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"8732faeb-da00-4499-bcb1-0ef84ad9e979","properties":{"cellContent":"Chargeback"}},"settings":null},{"content":{"contentType":"tableCell","id":"3cbf1ab7-889f-40fe-b693-141507023966","properties":{"cellContent":"The forced return of funds from the merchant to the cardholder after a dispute is upheld. Governed by scheme rules and timelines."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"a1d566bd-4259-495a-a3a3-3ad6ea4c978b","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"86e25c74-55fb-432a-a980-92c9a2b09e35","properties":{"cellContent":"Clearing"}},"settings":null},{"content":{"contentType":"tableCell","id":"3c76ebab-46c8-488e-b6e0-ae9b3e17bf04","properties":{"cellContent":"The exchange of transaction detail between the acquirer and the issuer after a payment has been authorized. Determines what will be settled; no money moves at this stage."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"0a8e9bfd-5a63-4741-a340-4b1ec044abeb","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"1798e3c2-f00f-48fd-84f2-5dd99f5e1adc","properties":{"cellContent":"Credit card"}},"settings":null},{"content":{"contentType":"tableCell","id":"a47083dc-a46c-4751-bd40-2288a78dc231","properties":{"cellContent":"A card that draws on a line of credit extended to the cardholder rather than on funds they already hold."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"0c62dfc0-51b1-49ff-a5da-13db159fb22f","properties":{"sectionText":"D to I"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"f26cef9d-20e6-4f6d-a611-6f6a651d874d","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"89f62332-401d-4ac4-8fcd-64ed436b3411","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"fae14e38-5e82-4876-83df-9dfcb1f96d34","properties":{"cellContent":"Term"}},"settings":null},{"content":{"contentType":"tableCell","id":"3aec92aa-f403-4cc9-9aa9-64e815db56b3","properties":{"cellContent":"Meaning"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"50867f9c-bc57-4707-8ea8-c2599808a47b","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"140cf1b7-6181-4fa7-a9f2-f2a90fd8f57f","properties":{"cellContent":"Debit card"}},"settings":null},{"content":{"contentType":"tableCell","id":"2a8ee7aa-10ac-4c08-81e9-55540b9f4a66","properties":{"cellContent":"A card that draws on funds already held in an account."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"4fd8afa8-db55-4cb0-b545-c9a465ff80b2","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"82fe42be-fc9c-402c-87d4-c9e94d35bfba","properties":{"cellContent":"Delegated Approval"}},"settings":null},{"content":{"contentType":"tableCell","id":"416ff768-e803-47ed-8d42-9b2d2699518c","properties":{"cellContent":"A funding model where the Program Owner\u0027s own systems make the authorization decision rather than TXN. See Delegated Approvals."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"85642be3-ce6c-4841-95ca-752113adae4f","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"8fdaafd9-4494-437e-9d5c-535597c0e2ef","properties":{"cellContent":"Digital wallet"}},"settings":null},{"content":{"contentType":"tableCell","id":"38185aea-769d-4121-937c-53396c06a13a","properties":{"cellContent":"An application holding a card\u0027s credentials on a device, such as Apple Pay or Google Pay. Stores a token rather than the card number."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"14d01dfa-6949-454a-a4ff-6f2e24437e25","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"90ee59e1-4afc-4450-a104-4f9fe51d198a","properties":{"cellContent":"Dispute"}},"settings":null},{"content":{"contentType":"tableCell","id":"b486279f-eb74-49be-a4fc-a918e617252b","properties":{"cellContent":"A cardholder challenging a transaction, on grounds such as fraud, goods never arriving, or an amount they did not agree. May lead to a chargeback."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"e0692e4b-c3d5-4a9f-a300-726b2416ce26","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"b79c077e-82a1-472e-acb6-89ad0a78d7a8","properties":{"cellContent":"ECommerce"}},"settings":null},{"content":{"contentType":"tableCell","id":"ae83f5c9-b4ec-4ee2-9a36-e527eb46c940","properties":{"cellContent":"A payment made online, without the card present. Authentication is performed through 3-D Secure rather than a PIN."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"3469f372-624b-4d63-a4aa-c930dc9187d3","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"2dfb6449-ce98-415d-bff6-278c12601af5","properties":{"cellContent":"Exemption"}},"settings":null},{"content":{"contentType":"tableCell","id":"acaca40a-bebe-4343-b030-bfabcb9c7c47","properties":{"cellContent":"A case where Strong Customer Authentication applies but is waived, because the payment is low risk, low value or recurring. Distinct from a payment that was never in scope."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"ff00d90c-7cf4-4bac-9b6a-1e31cb448703","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"4b4f6838-879b-4698-8125-73f2d9c39dda","properties":{"cellContent":"Expiry date"}},"settings":null},{"content":{"contentType":"tableCell","id":"58c40b4d-d6df-4dc8-9081-1d2479755215","properties":{"cellContent":"The month and year beyond which a card stops working. Changes when a card is reissued, even where the number stays the same."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"fea44e60-e3be-4f95-9bae-ed9d3cdd7490","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"1dc0f848-308c-46e8-856f-f5acbd8372a5","properties":{"cellContent":"Foreign exchange"}},"settings":null},{"content":{"contentType":"tableCell","id":"cbf40be6-e455-40f4-87b1-e7aaf151e7e6","properties":{"cellContent":"Conversion between the currency a transaction arrives in and the currency a limit or balance is held in."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"78135827-f405-43b3-9448-8c2849681b48","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"aee58aae-b138-4b07-9215-4e8e4ceaecc2","properties":{"cellContent":"Idempotency"}},"settings":null},{"content":{"contentType":"tableCell","id":"d43f1bc6-9c3b-4fbb-b818-d65b7d1ee9b2","properties":{"cellContent":"Sending the same request twice having the same effect as sending it once. On TXN, keyed on the request identifier. See Retries and Idempotency."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"b811162e-1aa0-4227-a115-58c16bc72fc7","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ad5a3c7a-c909-4934-b03a-94528e704f3d","properties":{"cellContent":"Interchange fee"}},"settings":null},{"content":{"contentType":"tableCell","id":"d04d27fe-e4ee-421a-86e5-fa44ebfde910","properties":{"cellContent":"The fee the acquirer pays the issuer on each transaction, set by the card network. One of the main economics of an issuing program."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"3c693d4a-b685-4dcb-838c-ba20baeab53d","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ccc60f0f-ca6f-4a70-aa17-4ed4710f026d","properties":{"cellContent":"Issuer"}},"settings":null},{"content":{"contentType":"tableCell","id":"d97be121-e17b-41ec-910c-b1cd94558c2d","properties":{"cellContent":"The party in whose name a card is issued and who carries the obligation behind it."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"d441c840-beb9-44e7-a5d8-7a1bcea8a679","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"d8d13992-b93f-4e05-a3cb-1a0c0163dd45","properties":{"cellContent":"Issuer-processor"}},"settings":null},{"content":{"contentType":"tableCell","id":"dbea2457-1f4c-4a11-bc95-3fab0beac456","properties":{"cellContent":"The platform that issues cards and processes transactions on the issuer\u0027s behalf. TXN\u0027s role."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3d934058-b54d-477a-84b2-9ead311feae0","properties":{"sectionText":"L to P"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"f564fb43-3b05-4edb-9208-cb5dec053e3c","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"ff5538ae-60d1-4307-b292-30f5d221e0cd","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"fde57a5f-3103-404f-9a73-6e17dfefa2f9","properties":{"cellContent":"Term"}},"settings":null},{"content":{"contentType":"tableCell","id":"ee67a4cc-91ed-4dc9-a870-b2b00f3b9ef3","properties":{"cellContent":"Meaning"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"3d7a23bf-5b61-4dfa-8cf0-943acb869313","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"41eb9307-bf94-4a88-bde8-ca6b85a13364","properties":{"cellContent":"Ledger balance"}},"settings":null},{"content":{"contentType":"tableCell","id":"08f5aea5-4da1-4f7b-bdc2-f638af93e301","properties":{"cellContent":"Cleared, settled funds only. What has genuinely moved, as opposed to what is currently spendable. Usually the figure reconciliation wants."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"30deed7f-2223-44ce-a21f-59a8bdb1ceff","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"5413b06b-bd6e-4cd1-9bf8-b52cd5cb7292","properties":{"cellContent":"Liability shift"}},"settings":null},{"content":{"contentType":"tableCell","id":"736a52ca-8a20-4127-a92c-0371d8a6d39d","properties":{"cellContent":"The transfer of responsibility for a fraudulent transaction from the merchant to the issuer, where the cardholder was authenticated through 3-D Secure."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"28d550d7-b37d-48d5-b606-02baacc079e2","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"cd8f668c-c04b-4a21-820f-054fb16fb743","properties":{"cellContent":"Merchant"}},"settings":null},{"content":{"contentType":"tableCell","id":"333d9aa1-15ed-41bf-973b-c403d5326704","properties":{"cellContent":"Any business accepting card payments."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"24176ef7-91a8-47a0-a5bc-d0cb2d89ed39","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"3105e26d-eec5-4660-86c1-fddee9cd344c","properties":{"cellContent":"Merchant category code"}},"settings":null},{"content":{"contentType":"tableCell","id":"a8c2b295-b81e-4b0b-a3e2-c6b78697d09e","properties":{"cellContent":"A four-digit code classifying what kind of business a merchant is. Used to allow or block categories of spending."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"31ec2475-4214-4601-a896-ea327c5e2800","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"f68437bb-bc15-4c1f-9191-0c75dac2e4db","properties":{"cellContent":"Merchant control"}},"settings":null},{"content":{"contentType":"tableCell","id":"18b98c65-1047-4b4e-a7e8-d113e62d9d5d","properties":{"cellContent":"A named, reusable restriction on where a card may be used. See Merchant Controls."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"40aa8948-4c02-4100-8a22-da4500bd574e","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"57a05762-ffcc-4d0e-87e8-43a8855e8392","properties":{"cellContent":"Merchant identifier"}},"settings":null},{"content":{"contentType":"tableCell","id":"f768f2b4-299d-438d-911f-a2d8f2731d48","properties":{"cellContent":"The code identifying an individual merchant to the acquirer. Narrower than a category code, which covers a whole class of business."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"a5b85477-ea85-403d-85ec-2c2ad83bb7b3","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ddc169bc-2cc2-48ee-9caa-26fdc9220f5a","properties":{"cellContent":"MOTO"}},"settings":null},{"content":{"contentType":"tableCell","id":"15a3d858-09dd-43eb-bad8-840d9718467c","properties":{"cellContent":"Mail order and telephone order. A card-not-present payment taken by post or over the phone."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"a1fc2ff4-1836-4d64-bc8d-28ad4333f1cc","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"fa8069c4-9cc3-49fd-8aa3-d99e8e423920","properties":{"cellContent":"PAN"}},"settings":null},{"content":{"contentType":"tableCell","id":"e02ab498-d69b-43cd-afe4-0c86255aaede","properties":{"cellContent":"Primary Account Number. The card number itself. Masked in ordinary API responses and retrievable in full only through PCI-scoped operations."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"223db502-421e-4adc-9bd3-1e5efac0aec7","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"db80cb4b-198f-44fc-8557-bab4f90f2522","properties":{"cellContent":"Physical card"}},"settings":null},{"content":{"contentType":"tableCell","id":"d4fdff89-36bb-42e5-bd83-ea1d29a072f9","properties":{"cellContent":"A manufactured card, produced and posted to the cardholder."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"90b8e258-2559-4aa7-960a-48d4bdd73146","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"6702adf1-71ea-48c3-a0be-bd37e0444e80","properties":{"cellContent":"PIN"}},"settings":null},{"content":{"contentType":"tableCell","id":"0faa6d8d-1ba6-4bdd-8447-e3879898ca35","properties":{"cellContent":"The number a cardholder enters to prove they are the cardholder at a terminal. Satisfies Strong Customer Authentication in person."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"77b442d6-8224-4380-ae03-389b18ac3701","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"a5abf27a-0761-4dd8-944b-00969ea4854a","properties":{"cellContent":"Platform managed funding"}},"settings":null},{"content":{"contentType":"tableCell","id":"027cebe1-593c-43e4-a19f-b7390db48316","properties":{"cellContent":"A funding model where TXN holds the balance and makes the authorization decision against it. See Accounts."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"99692713-f6b3-4863-8d09-78b7b561ef1f","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"5de3a449-91ac-44de-a2fa-9efafbdde78c","properties":{"cellContent":"Prepaid card"}},"settings":null},{"content":{"contentType":"tableCell","id":"4d02f6e4-05cf-431f-9d7a-a94432c7db44","properties":{"cellContent":"A card holding a finite balance, independent of any bank account."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"368586ab-63d4-4e0c-8abf-ede75dac49bb","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"5f4b07c7-dde1-486e-bff0-63603906df03","properties":{"cellContent":"Presentment"}},"settings":null},{"content":{"contentType":"tableCell","id":"ee0db2cc-5398-42ea-8606-9f650c6b06f6","properties":{"cellContent":"The clearing record the acquirer submits for a transaction, which is what the issuer settles against."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"8a14d115-9712-493f-972f-f81a693a06ac","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"82b6180a-1c53-4863-b08c-4fc736d6313f","properties":{"cellContent":"Product"}},"settings":null},{"content":{"contentType":"tableCell","id":"b4c8a1b5-aa84-43c9-890c-c2517fcdddc7","properties":{"cellContent":"The configuration a whole population of cards shares: limits, controls, capabilities and defaults. See Products."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"55f5406a-62a2-47b5-811f-43f8ef288616","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"543d8383-0efa-4328-aa76-6e630b1bdc25","properties":{"cellContent":"Program Manager"}},"settings":null},{"content":{"contentType":"tableCell","id":"0769302e-8e43-4ec5-99dc-c9ceb2935459","properties":{"cellContent":"A role taken on to manage one or more Card Programs, including the relationship with the BIN Sponsor. The BIN Sponsor can itself be the Program Manager. Not the same as the Program Owner."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"ca8460fd-17aa-4c35-8e8b-18890abbcb27","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"9236d8ec-500b-474a-8a00-469852afbb71","properties":{"cellContent":"Program Owner"}},"settings":null},{"content":{"contentType":"tableCell","id":"8ff4f3ac-02e8-4353-a8e7-f77081a52d5c","properties":{"cellContent":"TXN\u0027s client, and the name these guides use for it. The Program Owner runs the Card Program day to day."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"0b9be20d-32f7-45f5-91d8-8a78d0899761","properties":{"sectionText":"R to S"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"53e0ea30-66fe-4f44-a205-7364a28ae79e","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"e3062cfa-5d8d-4dd5-a7dc-d65523a86dd5","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"be32a9aa-fad0-4e8b-973e-a67a55708bf9","properties":{"cellContent":"Term"}},"settings":null},{"content":{"contentType":"tableCell","id":"d1d99324-cc31-40e6-a145-82cb3413eb8c","properties":{"cellContent":"Meaning"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"b6e4e7b2-f589-4672-a0c8-b520a29debeb","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"e2505777-9f55-4cc2-bb04-c6cc226ed4d3","properties":{"cellContent":"Reconciliation"}},"settings":null},{"content":{"contentType":"tableCell","id":"16222561-fa70-4d62-8a3d-b84d2e15bb59","properties":{"cellContent":"Comparing two records of the same activity to confirm they agree. Usually your ledger against the platform\u0027s."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"c1972fb3-59e6-4c25-b4a4-62c84cae2095","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"aaeaedaf-265d-4a42-9dd7-da1ced7a80d9","properties":{"cellContent":"Refund"}},"settings":null},{"content":{"contentType":"tableCell","id":"a8d43b74-0e31-45df-ac2b-d1c689c861ec","properties":{"cellContent":"Money returned to a cardholder after a transaction has cleared, initiated by the merchant."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"edd790e5-07ce-4efb-9159-05e8a6a410b6","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"c553ed62-5ce8-43ba-8b41-91b2f03d433c","properties":{"cellContent":"Reversal"}},"settings":null},{"content":{"contentType":"tableCell","id":"2c3c474e-7055-44cf-ae0b-84fb1ee9a122","properties":{"cellContent":"The cancellation of an authorization before it clears, releasing the amount that was held. A hotel releasing a pre-authorization is the common example."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"68b7334a-469e-489d-92bd-0c3d4356f339","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"43874bcb-b7c1-44ae-98a4-8b7277777dbb","properties":{"cellContent":"Scheme fees"}},"settings":null},{"content":{"contentType":"tableCell","id":"2f4f7418-d18b-4c85-b7b9-9bd63250cf4e","properties":{"cellContent":"Charges levied by the card network on the parties using it, separate from interchange."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"df8306e3-74fc-492b-8f41-cdf8e415fc8d","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ae50e834-7901-455a-a92a-eea98f05de7f","properties":{"cellContent":"Settlement"}},"settings":null},{"content":{"contentType":"tableCell","id":"f0b31c76-d9c7-463c-8fab-733652863f79","properties":{"cellContent":"The actual movement of money between the institutions involved, after clearing has determined what is owed."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"58edc225-43d2-4bc2-81f9-37393c9949f0","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"d039e2c5-3096-4956-bbcc-0ab852ff3c62","properties":{"cellContent":"Single-message and dual-message"}},"settings":null},{"content":{"contentType":"tableCell","id":"69ce1cd8-17f6-4c4d-adb0-c70eff6332f3","properties":{"cellContent":"Two transaction structures. In single-message, authorization and clearing arrive together as one message and the money is committed at once. In dual-message, the authorization comes first and clearing follows later, which is why a balance can show a hold long before anything settles."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"4f42ad34-10f6-424e-944e-de8dc01b3e44","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"51137e5a-95fa-4cb5-b78c-3437617859a4","properties":{"cellContent":"Single-use card"}},"settings":null},{"content":{"contentType":"tableCell","id":"1e60e397-3ed0-410a-ae41-1c08246f916e","properties":{"cellContent":"A virtual card intended for one transaction, after which it is no longer usable. Limits the damage if the number is captured."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"89e4a056-3ac6-4cf7-9f6b-74983f360abc","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"4658f766-575b-46c5-8820-5bce849ab883","properties":{"cellContent":"Spend control"}},"settings":null},{"content":{"contentType":"tableCell","id":"95eb22a5-1c58-4106-85f1-6eac7e45c94b","properties":{"cellContent":"A limit on how much may be spent over a defined period, with its own resource and configurable scopes. See Spend Controls."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"d56cbb86-3619-4357-be18-324c3b0afee6","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"1fb65c0f-720b-4af0-80d3-3b7e0f6458ea","properties":{"cellContent":"Spend override"}},"settings":null},{"content":{"contentType":"tableCell","id":"5836029f-a1ac-4826-bacb-6fa6fede6a87","properties":{"cellContent":"A temporary, card-level exception to a spend control that leaves the underlying policy untouched. See Spend Overrides."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"95758ad4-a5bd-42d8-b946-e43c4032acde","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"56e93376-9c97-4400-8ff1-2b66db5eefd1","properties":{"cellContent":"Stand-In"}},"settings":null},{"content":{"contentType":"tableCell","id":"809a2938-0c68-49c8-aa6d-8566832cef20","properties":{"cellContent":"A ruleset that decides authorizations when the system that would normally decide cannot be reached. See Delegated Approval Stand-Ins."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"b30222de-4092-479c-a4a9-5dda0e6d1dc8","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"2c198097-bab3-4908-9ac5-754fe49408d0","properties":{"cellContent":"Strong Customer Authentication"}},"settings":null},{"content":{"contentType":"tableCell","id":"de12ea31-5fd2-478b-b849-fbefb130f6bb","properties":{"cellContent":"The requirement that a cardholder proves who they are using two independent factors. Applies to most electronic payments in Europe."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e390d9f0-adc0-443a-96dd-52f80c36660f","properties":{"sectionText":"T to V"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"62208e9b-dbea-454f-94b7-495c643a4078","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"d6ecbdd7-e398-4e45-8e98-1739648bc1b1","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ec44f9f0-981e-46ef-b4d3-bde622fad698","properties":{"cellContent":"Term"}},"settings":null},{"content":{"contentType":"tableCell","id":"c65e2340-27cb-4925-ad83-98b0d4315d69","properties":{"cellContent":"Meaning"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"9ebf9cfd-7e50-404d-b959-b1e22580240e","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"5503f390-e377-4baa-96ff-289acd8cc436","properties":{"cellContent":"Terminal ID"}},"settings":null},{"content":{"contentType":"tableCell","id":"7ea97bd4-cf17-4de2-8169-4403c7247c03","properties":{"cellContent":"The code identifying the specific terminal a transaction came from, within a merchant."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"9d81b2b1-e89c-4989-acd2-5a5a930ff385","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"7a640939-457c-4860-8662-c7506d52d032","properties":{"cellContent":"Token"}},"settings":null},{"content":{"contentType":"tableCell","id":"f84e32a6-1fa5-4c73-bdf9-ebb90bfecec6","properties":{"cellContent":"A surrogate value standing in for a card number, tied to a device, wallet or merchant, and cancellable without touching the card."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"b5bd2863-88cc-4181-b72e-18537551c0be","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"97691050-8a4f-4284-a673-9ec8c5242e8e","properties":{"cellContent":"Tokenization"}},"settings":null},{"content":{"contentType":"tableCell","id":"3104b0ac-4ea1-4299-a986-8f340c215ece","properties":{"cellContent":"The process of replacing a card number with a token, so the real number is not held where it does not need to be."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"4c40a8b2-a723-465a-85b3-b87bef3b3093","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"df3b7108-f1c2-4c5f-96d3-5d68055425d5","properties":{"cellContent":"Transition"}},"settings":null},{"content":{"contentType":"tableCell","id":"10b12a1a-34ce-4060-ad03-aaab8474f8a7","properties":{"cellContent":"How an object on TXN moves between lifecycle states, carrying a reason and writing its own audit record. See Cardholders."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"5c58e9b6-75ab-4509-90e8-13c532850a27","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"95e59cd7-1a3a-479c-9ab4-1f8446e75867","properties":{"cellContent":"Trusted merchant"}},"settings":null},{"content":{"contentType":"tableCell","id":"c54bfa19-021d-48d5-9443-93773b55cc26","properties":{"cellContent":"A merchant a cardholder has already authenticated with, recorded against their card so they are not challenged there again. See Trusted Merchants."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"0f553841-34a4-424a-8331-b11cef383b5b","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"55f7b262-d895-4776-9cc0-81c9a1b3da6e","properties":{"cellContent":"Virtual card"}},"settings":null},{"content":{"contentType":"tableCell","id":"1c46f7f7-2b86-49aa-a92b-d7a0c241e760","properties":{"cellContent":"A card with no physical form, usable online and in wallets from the moment it is issued."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"c4aed807-3c66-4ed0-9425-17c55642ee19","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"2f8b6adf-b178-41fa-beaa-bd8b023b9a37","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"2e1f3d49-364d-4619-8355-016a4471d751","properties":{"cardTitle":"Core Objects","cardText":"The objects TXN is built from, and how they reference each other.","pageLink":{"contentType":"guidePage","name":"Core Objects","createDate":"2026-09-16T06:20:31.817Z","updateDate":"2026-11-15T16:32:39.203Z","route":{"path":"/103/getting-started/core-objects/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"0b97009e-ae9c-4b9b-a63d-ec7d5bd5c0c4","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"a1af27ae-a26e-4fde-8c12-890d047f1561","properties":{"cardTitle":"How TXN Works","cardText":"What an issuer-processor is, and the roles behind a Card Program.","pageLink":{"contentType":"guidePage","name":"How TXN Works","createDate":"2026-09-16T10:34:03.717Z","updateDate":"2026-11-15T16:32:40.527Z","route":{"path":"/103/working-with-txn/how-txn-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1e283b0f-5937-4e57-87cb-9402b1cf9f3b","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"de86f5ee-8ed1-4d9f-bcf3-6bcd73598bb7","properties":{"cardTitle":"Transaction Lifecycle","cardText":"How a payment moves from authorization through clearing to settlement.","pageLink":{"contentType":"guidePage","name":"Transaction Lifecycle","createDate":"2026-11-14T14:52:32.293Z","updateDate":"2026-11-16T06:59:29.687Z","route":{"path":"/103/payment-concepts/transaction-lifecycle/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"209c1bc0-bf02-4c6c-a7b1-75403bb43d66","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"8481b19b-00d0-4b0a-a30d-dd53d46c6092","properties":{"prevPageTitle":"Transaction Lifecycle","nextPageTitle":"Requests and Responses"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Spend Overrides","createDate":"2026-09-16T06:24:22.233Z","updateDate":"2026-11-15T16:32:44.193Z","route":{"path":"/103/card-controls/spend-overrides/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"90242594-37ea-4d33-afe6-db47662679eb","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"4750ee56-1443-4ce2-9290-d3873bc7a75a","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"575e4393-0fc0-4dfc-82e8-03c856164a88","properties":{"title":"Spend Overrides","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"322be74d-4073-464a-8a2f-33a5a978c9d1","properties":{"text":"A spend control describes how a population of cards should behave. Sometimes one cardholder needs to do something that policy does not allow. An override is how you grant that without editing the policy, and how you make sure the exception ends on its own."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"d2148461-6824-42b7-a633-c709d5c666fa","properties":{"text":"The narrowness is the feature. An override applies to one card, for a stated period, for a stated reason. It does not touch the spend control governing everything else, so the exception cannot quietly become the rule, and it does not apply to any other card issued under the same product. Someone traveling next month gets what they need without the policy being loosened for the whole program and never tightened back."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"273ab548-ddc2-49df-a83b-53fce6b782d4","properties":{"sectionText":"What an override carries"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"8719f3b0-2a1a-471d-8935-75cd0ebb47d5","properties":{"text":"Creating one takes the card it applies to, the raised limits, the window it is valid for, and why. The limits mirror what a spend control caps: a value ceiling and a count ceiling, in a currency. The window is a start and an end. The reason is recorded twice over: a coded reason drawn from a fixed set such as travel or business expense, and free text alongside it for the detail the code cannot carry."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"ff257da9-ccb1-46aa-9dda-ab2d80f84ae9","properties":{"alertTitle":"The reason code is not free text, and that is deliberate.","alertContent":"Coded reasons are what make overrides reviewable in aggregate. Free text alone gives you a list you have to read one by one; a bounded set lets you answer \u0022how many exceptions did we grant for travel last quarter, and to whom\u0022 without anyone reading anything. Put the specifics in the free-text reason and pick the code that genuinely fits rather than the one nearest to hand.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"bbecb163-5a91-4efa-b56c-02001438afd0","properties":{"sectionText":"It expires whether or not anyone remembers it"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"63d20441-33d6-4c83-963f-9d7f1894a329","properties":{"text":"Every override is time-boxed at creation and the expiry is not optional. That is the design\u0027s central safety property: an exception granted and then forgotten stops on its own rather than becoming permanent by neglect. It is also why an override is the right tool for a temporary need and the wrong one for a permanent change: if what you want is for a card to behave differently from now on, the spend control governing it is what should change."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"9d19162a-0b32-4937-adf4-60e462f491bb","properties":{"sectionText":"The lifecycle, and why it does not start active"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"28ba5955-77b9-4dac-a64b-2ce8b3de3694","properties":{"text":"An override is created pending rather than active. Activating it is a separate step, which gives you room to create it ahead of time and switch it on when it is actually needed. From active it reaches one of three ends: expired when its window closes, cancelled if you end it early, or consumed when it has been fully used. All three are terminal: an override that has ended does not come back, and a further exception means a further override."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"ea66fe00-65e0-4290-8df8-632aff12b4b2","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"07fc6ce3-321d-413f-b57c-d1e5baa1e106","name":"Cc Spend Override Lifecycle Dark","mediaType":"Image","url":"/media/nstlvmlu/cc-spend-override-lifecycle-dark.png","extension":"png","width":2400,"height":920,"bytes":171345,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"d7a71926-d8d1-4163-99a2-4fe8b2e3129f","name":"Cc Spend Override Lifecycle Light","mediaType":"Image","url":"/media/vhjpcyny/cc-spend-override-lifecycle-light.png","extension":"png","width":2400,"height":920,"bytes":169071,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"da387c64-873a-4661-ac2d-a45ff508b2b2","properties":{"sectionText":"It reports its own usage"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"746f0271-187b-4a3e-baf3-89b814543326","properties":{"text":"An override tracks what has actually been spent against it: how many transactions have run, for how much in total, and when it was last used. That turns a governance question into a readable one. An override that expires unused tells you the exception was not needed. One that is consumed early tells you the limit was set too low, or that the underlying control is wrong for this cardholder."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"0edd70ce-2178-44af-871c-b96346e83e57","properties":{"sectionText":"You do not get to say who created it"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"81e710aa-ea1d-4019-94ae-1c4c6c74c298","properties":{"text":"Every override records how it was initiated (through the API, through Control Center, or through another supported channel) and that value is derived by the platform from the access route used. It is not a field you supply and it cannot be set to something else. For a record whose whole purpose is to document a deliberate exception to policy, the provenance has to be something the requester cannot author."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"9777e851-8e92-4e7a-a10f-c982a4e8aab7","properties":{"alertTitle":"An override is a policy exception, so treat creating one as a privileged action.","alertContent":"Only authorized roles can create or update an override, and every operation is logged with identifiers that tie the request and its response together. Worth mirroring that on your side: an endpoint in your own systems that creates overrides is an endpoint that raises spending limits, and it deserves the same access control as anything else that does.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4dbc9ba4-3dae-434c-beb1-1943b86c394c","properties":{"sectionText":"Changing one that already exists"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"36d0390f-7443-4745-8d99-690ed6b3422d","properties":{"text":"An override supports a partial update, so you send only what is changing rather than restating the record. That is also how state moves: activating a pending override, or cancelling an active one, is an update rather than a separate operation. Overrides can be retrieved individually or listed within the scope you have access to, which is how you answer what exceptions are currently live."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"81e3280b-941a-4365-93fc-b2414d52fdb4","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"d3849e62-839d-4159-b5ad-472d9b00ffa3","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"d2346e1c-e48f-44dc-b7ca-e2762516d30b","properties":{"cardTitle":"Spend Controls","cardText":"The policy an override is an exception to.","pageLink":{"contentType":"guidePage","name":"Spend Controls","createDate":"2026-09-16T10:47:00.377Z","updateDate":"2026-11-15T16:32:45.233Z","route":{"path":"/103/card-controls/spend-controls/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b3eace44-6780-4c51-831b-164ca1d52e67","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"f31d38ec-1ccf-4fea-a35b-46d28ddf632b","properties":{"cardTitle":"Cards","cardText":"The card an override is scoped to.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"40a4ff69-35c2-411c-b769-10416c9cf7ec","properties":{"cardTitle":"Merchant Controls","cardText":"Restricting where a card can spend, rather than how much.","pageLink":{"contentType":"guidePage","name":"Merchant Controls","createDate":"2026-09-16T06:24:31.46Z","updateDate":"2026-11-15T16:32:42.82Z","route":{"path":"/103/card-controls/merchant-controls/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"51fd9837-c394-466d-8bcf-b1b71c811da2","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"76519356-d956-43a0-92ec-84fadd311bf5","properties":{"prevPageTitle":"Spend Controls","nextPageTitle":"Merchant Controls"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Cardholder Groups","createDate":"2026-09-16T06:22:27.497Z","updateDate":"2026-11-15T16:32:46.307Z","route":{"path":"/103/foundational-objects/cardholder-groups/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"d66b448a-3627-49ab-92fb-be2ce8243427","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"2f8683df-dbe1-44d8-b67f-10090cfbc085","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"7a15cdb9-e5fe-429f-bdfb-1f65db780904","properties":{"title":"Cardholder Groups","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"cf9284c2-5539-43b8-9983-c76bea7adaf2","properties":{"text":"Issuing programs regularly need to model cardholders who share something in common, an employer, a household, a branch office, without repeating the same name, address and reference data on each one. A shared identity record they can point back to is the usual answer."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"9296a185-ac46-463c-a77b-c5c121b72478","properties":{"text":"On TXN, that record is the cardholder group: a name, an address set and any attributes you attach, referenced in common by a number of cardholders. It is a reusable identity record, not a rules engine; it holds no spend or merchant configuration of its own."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"14eedf31-8d28-4ef7-9ab7-c6d503fa19f3","properties":{"sectionText":"What a group stores, and what it does not"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"40f4eff2-b3d8-45e5-9f35-50d3abd18930","properties":{"text":"Creating a group captures a name plus shared address and attribute data: billing, shipping and return addresses, a location, and any free-form attributes. That is the entire scope of the record. A group holds the details a set of cardholders have in common, not somewhere spend or merchant rules live; those sit on the product and the card.\n\nThe name is a label for your own use. It does not need to be a registered company name, and nothing about the record assumes the group is a business."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3a875220-af03-4a35-b3fa-d8d8ceca57a9","properties":{"sectionText":"Membership is set from the cardholder, not the group"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"cef24f11-1b37-4011-923e-d8a60b64fe4a","properties":{"text":"There is no way to add or remove a member from a group\u0027s own record. A cardholder is linked by setting its own optional group reference when you create or update it (see Cardholders). A group with no cardholder pointing at it is simply unused; it does not track its own membership list. This puts the join logic on the cardholder side: onboarding a cardholder into a group is one field on the cardholder request, not a separate group-membership call."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"64a39a3a-30cb-47a3-8fe1-7905fc0e474a","properties":{"alertTitle":"Send only what you are changing.","alertContent":"Updating a group is a partial update, the same as a cardholder. Fields you leave out are untouched, so send only what has actually changed rather than reading the record and posting it back whole.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e5333abe-94f5-4887-9ea6-e84ef8f05e83","properties":{"sectionText":"The cardholder group lifecycle"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"9309d61c-3ee4-4eb0-8829-a8b4f33852e7","properties":{"text":"A group moves through the same three states as cardholders and accounts: active, on hold and closed. Active and on hold are reversible. Closed is not.\n\nIt draws on the same set of transition reasons, with nothing group-specific about them, which is worth knowing if you are building one piece of handling for transitions across all three object types. The reasons and what each one signals are listed on Cardholders."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"80df60f9-148d-48ce-9309-620ebbf11a0d","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"35c7cfa4-d055-4d61-a608-963e1d8fb501","name":"Fo Cardholders Groups Parents And State Dark","mediaType":"Image","url":"/media/fmcjdaz2/fo-cardholders-groups-parents-and-state-dark.png","extension":"png","width":2400,"height":1340,"bytes":344526,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"10296525-0d46-4582-a4c5-9107aeb73d07","name":"Fo Cardholders Groups Parents And State Light","mediaType":"Image","url":"/media/vkxh5jrp/fo-cardholders-groups-parents-and-state-light.png","extension":"png","width":2400,"height":1340,"bytes":341262,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"bcf0a528-2e70-41d5-9dc7-7e3f1c4e2807","properties":{"alertTitle":"Closing a group is permanent.","alertContent":"Closed is a terminal state and there is no route back. A closed group cannot be reopened. Use on hold when you need to stop activity temporarily.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"17d1bd96-fde1-4ffd-a933-5c41a3d6c6a0","properties":{"alertTitle":"A group transition can optionally reach its linked cards.","alertContent":"Applying a transition to linked cards is optional and does not apply by default, so a group transition on its own changes the group and leaves the cards as they were. Turn it on when the reason for the change should reach the linked cards as well, such as confirmed fraud. A cascade sets the cards\u0027 state at that moment. It does not bind them together afterwards.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e6a6a436-78b5-4f35-a5d7-2d62a71f10e2","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"c8a83475-fe5a-4f84-879d-8e998e6c0fd8","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"08fb6c39-cdca-4c77-b6c2-7c1b5cf0f002","properties":{"cardTitle":"Cardholders","cardText":"How a cardholder joins a group, and the full set of transition reasons.","pageLink":{"contentType":"guidePage","name":"Cardholders","createDate":"2026-09-16T06:22:18.73Z","updateDate":"2026-11-15T16:32:44.66Z","route":{"path":"/103/foundational-objects/cardholders/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"a615ed27-e2f2-4afe-b764-4fc583ef8f6c","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"66b49ebb-e585-463d-a878-190c5147dff9","properties":{"cardTitle":"Accounts","cardText":"The balances behind a group\u0027s cardholders, and their own lifecycle.","pageLink":{"contentType":"guidePage","name":"Accounts","createDate":"2026-09-16T06:22:09.903Z","updateDate":"2026-11-15T16:32:43.31Z","route":{"path":"/103/foundational-objects/accounts/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"5c10167b-6790-43b8-8d90-d56c1a423a5c","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"10007335-16c4-45b8-b7a1-7bff2019b83e","properties":{"cardTitle":"Cards","cardText":"What the cascade actually reaches when you apply a group transition.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"e73f3678-8aef-40ac-92dc-c6a8e792c51d","properties":{"prevPageTitle":"Cardholders","nextPageTitle":"Accounts"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"From First Call to Go-Live","createDate":"2026-09-16T10:37:09.553Z","updateDate":"2026-11-15T16:32:46.457Z","route":{"path":"/103/working-with-txn/from-first-call-to-go-live/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"d6f8f50b-69d9-4bbf-8fe3-83fdbbe71cf6","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"36c813ce-b578-424e-9297-6609570ba183","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"83d05378-6882-45ae-a6bb-2df45874805f","properties":{"title":"From First Call to Go-Live","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"a6f38b1a-a538-4cf4-b8b7-6776ce02d380","properties":{"text":"Getting started with TXN runs along two tracks: a commercial one, taking you from a first conversation to a signed agreement, and a technical one, where your engineers get their hands on the API. They overlap deliberately, and the technical track starts earlier than most people expect."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"483b3bda-0b72-4689-af68-6a4a100ce543","properties":{"text":"If you are the person who has to plan the build, the useful questions are not about when contracts are signed. They are which environment opens when, what is already running in the background, and which item on the plan cannot be compressed no matter how fast everything else moves."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"044cf76c-d7a8-435a-a422-8af99480bd1d","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"c612d657-e640-4527-8df6-95016a52005e","name":"Wwt First Call To Go Live Two Tracks Dark","mediaType":"Image","url":"/media/1aofi2bj/wwt-first-call-to-go-live-two-tracks-dark.png","extension":"png","width":2400,"height":1040,"bytes":253644,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"87bab7be-4ae8-464a-9cd1-7d941f742c75","name":"Wwt First Call To Go Live Two Tracks Light","mediaType":"Image","url":"/media/gf4pymmb/wwt-first-call-to-go-live-two-tracks-light.png","extension":"png","width":2400,"height":1040,"bytes":256678,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"9c998d99-3826-4b3e-84b3-36e6ea1fe7f9","properties":{"sectionText":"Scoping, while your engineers are already building"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"c2deddeb-f2c6-4a9c-a4b7-c49659ce00f2","properties":{"text":"The first conversations establish what you are trying to build: the markets you are going into, the type of card product, how the money moves, and whether TXN is the right fit. Nothing is committed at this stage.\n\nYour engineers do not have to wait for any of it. The Public Sandbox is open from the start, with no commercial step in front of it, so they can read the guides, work through the API Reference and make calls with Try It Now while the commercial conversation is still happening."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"927cf421-b329-4626-bd49-75588111cf80","properties":{"sectionText":"What you are building gets written down"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"fc037a87-1f2b-49c6-a7cf-5cae9e0c73fd","properties":{"text":"As the conversation becomes concrete, TXN captures what you intend to build as a scope snapshot: the product type, the region, what the cards are actually for. That snapshot does two jobs. It anchors the project plan against real dates rather than hopeful ones, and it becomes the thing any later change is measured against.\n\nFor an engineering lead this is worth taking seriously rather than treating as a commercial formality. It is the moment to surface what you actually intend to ship, because a capability nobody wrote down is a capability nobody has planned around."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"f6750de8-8de4-48f0-be46-340eb59ff810","properties":{"sectionText":"The scheme work takes longest"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"254c38e1-de16-4ffb-a9c8-d14f8f5f1ba8","properties":{"text":"Getting a BIN and the scheme setup behind it is raised as its own project, and it is almost always the longest item on the plan. Its lead time is set by the scheme rather than by TXN, and it does not compress because everything else went well.\n\nScheme membership sits with your BIN Sponsor, which adds a participant to the setup conversation and is worth identifying early rather than discovering halfway through."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"86c3ea00-88f8-4a9b-a80b-e7b947e42e85","properties":{"alertTitle":"Build against the scheme date, not the contract date.","alertContent":"Most integration plans anchor on when the paperwork completes, which is the wrong end of the process. The scheme lead time starts when the scheme project is raised and runs regardless of how quickly you build. Plan backwards from it, use that time to get the integration genuinely finished rather than merely working, and go into go-live with your webhook receiver, error handling and monitoring already proven.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"d88cb1fd-5376-4791-ab97-171b93a54ce9","properties":{"sectionText":"The CIQ, and who fills in what"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"1e12d87e-6cd6-4672-962c-108c49f87299","properties":{"text":"Visa requires a configuration questionnaire, the CIQ, covering how the Card Program is set up. It is a common place for onboarding to stall with everyone waiting on somebody else, so agree early who completes each part: TXN for the processor-side settings, and you and your BIN Sponsor for the rest."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e67c7e8c-67a5-4bee-9e44-44d51c6a6380","properties":{"sectionText":"UAT opens before contracts are signed"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"a82f9640-1888-43a6-8766-fecfd8006170","properties":{"text":"Once you confirm in writing that you intend to proceed, and TXN has completed its onboarding checks, UAT is unlocked. This happens before contracting completes, and deliberately so. It lets your engineering team build against an environment configured to look like your Card Program while the paperwork is finished, rather than sitting idle waiting on it.\n\nContracting then completes, after which onboarding begins in earnest and the project plan, the scheme work and the CIQ all run together."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"c17d3aab-b728-4dda-897d-2fd54974f7b0","properties":{"sectionText":"What your engineers can reach, and when"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"42cd185d-cfe9-4808-b756-88e28a45f20f","properties":{"text":"There are three environments, and they open in this order. See Environments for what each one is for."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"3e2ad1cf-426e-4870-9572-f9b8053eef65","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"9ec1d2bc-933a-446e-89eb-0b06910d5c29","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"c0d5402a-7e01-4f35-9de5-473daeb5be59","properties":{"cellContent":"Environment"}},"settings":null},{"content":{"contentType":"tableCell","id":"9c12ee62-9197-4116-b445-65b6236df972","properties":{"cellContent":"When it opens"}},"settings":null},{"content":{"contentType":"tableCell","id":"c2241c43-8652-4b5e-b0a1-200783e02e9a","properties":{"cellContent":"What it gives you"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"e8807afa-6a09-48ce-8d05-0d282252c971","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"0d871dcf-e18a-427a-8a35-72108ea08ddd","properties":{"cellContent":"Public Sandbox"}},"settings":null},{"content":{"contentType":"tableCell","id":"c22d2717-b3e6-4196-ae4b-0d74e67b2f0c","properties":{"cellContent":"Immediately, with nothing in front of it"}},"settings":null},{"content":{"contentType":"tableCell","id":"8acceb0d-b165-4542-a3d5-7517ee9b5506","properties":{"cellContent":"A shared, generic environment with simulated data. It shows how the API behaves, not how your Card Program will behave."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"f98cf29f-41cc-4a1f-a1b0-802a5e703452","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"27bee5a0-0055-4bba-9a76-1ee6c70995b4","properties":{"cellContent":"User Acceptance Testing (UAT)"}},"settings":null},{"content":{"contentType":"tableCell","id":"a000befb-a5fc-48d4-85a9-2dff460d7f65","properties":{"cellContent":"When you confirm in writing that you intend to proceed and TXN\u0027s onboarding checks are complete"}},"settings":null},{"content":{"contentType":"tableCell","id":"ea244208-ffe2-46fd-a3b3-f07f14ad1b54","properties":{"cellContent":"An environment configured to look like your own Card Program, with your products and controls, to build against and validate in."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"a020f0b9-219f-4326-907c-99db9344ce4c","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"1a1e0471-7492-4c07-858c-656fef852f94","properties":{"cellContent":"Production"}},"settings":null},{"content":{"contentType":"tableCell","id":"b90e6f2b-d625-4da3-8c79-a51d54cd66c5","properties":{"cellContent":"At go-live, once onboarding is complete"}},"settings":null},{"content":{"contentType":"tableCell","id":"5d0fd37e-e25d-4d3d-89c9-be6ae80228fd","properties":{"cellContent":"Real cards and real money."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"cb62c683-30c5-42ce-8e28-52868a8c4ee9","properties":{"alertTitle":"The Public Sandbox is not your Card Program.","alertContent":"It is a shared environment with generic configuration, so it will tell you how the API behaves but not how your Card Program will behave. Anything that depends on your own products, spend controls, funding model or webhook configuration is only meaningfully testable in UAT. Use the Public Sandbox to learn the shape of the API, and plan the real integration testing for UAT.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"5111c42a-59dc-401b-bfeb-ef7c12f57428","properties":{"sectionText":"What changes at go-live"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"9ee33723-207d-4159-9b16-d8dce96a8a2c","properties":{"text":"Go-live moves the day-to-day work from your engineering team to whoever supports your cardholders, working in Control Center rather than through the API. The technical work of getting ready for that, and the things most often left until they fail, are covered in the Go-Live Checklist."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"d228d5c1-3d2a-413a-92cf-97a98a924bb6","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"eaef9fc4-63e9-4694-84d7-10f7408be94e","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"946eaafb-06c7-4335-b27a-5beb166ea9f1","properties":{"cardTitle":"Responsibilities","cardText":"What TXN owns, what you own, and where the line sits.","pageLink":{"contentType":"guidePage","name":"Responsibilities","createDate":"2026-09-17T15:55:58.67Z","updateDate":"2026-11-15T16:32:42.99Z","route":{"path":"/103/working-with-txn/responsibilities/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"56c5fab4-4ca7-4e79-98c6-543faaa61044","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"c21d5a22-a390-4d9d-8f0a-efc8e172c918","properties":{"cardTitle":"Environments","cardText":"The three environments and what each one serves.","pageLink":{"contentType":"guidePage","name":"Environments","createDate":"2026-09-16T06:21:03.5Z","updateDate":"2026-11-15T16:32:45.067Z","route":{"path":"/103/getting-started/environments/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b230a635-a702-4570-a189-ce295a6165dc","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"f65e015a-41af-49f1-a4d3-422159230f9c","properties":{"cardTitle":"Go-Live Checklist","cardText":"What to confirm before the first real transaction.","pageLink":{"contentType":"guidePage","name":"Go-Live Checklist","createDate":"2026-09-16T11:15:47.56Z","updateDate":"2026-11-15T16:32:39.463Z","route":{"path":"/103/going-live/go-live-checklist/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"12248e91-a4b4-4166-aa39-5c888cb4f7dc","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"a2a04703-fdab-4c9a-9a08-32c04eacdfa1","properties":{"prevPageTitle":"Responsibilities","nextPageTitle":"Transaction Lifecycle"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Delegated Approval Stand-Ins","createDate":"2026-09-16T06:26:45.147Z","updateDate":"2026-11-15T16:32:47.573Z","route":{"path":"/103/delegated-approvals/delegated-approval-stand-ins/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"ec2e9c3f-38f6-4b67-99be-540bae84c71b","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"0e0120bd-88dd-4dae-8c31-75e12c6620fc","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"530754f7-4097-4fb3-8ff9-40e1c4a4b6e1","properties":{"title":"Delegated Approval Stand-Ins","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"2f1d0ad7-6850-4210-bd30-c82636ea4f73","properties":{"text":"A stand-in decides authorizations when the system TXN would otherwise ask cannot be reached. It is a configuration scoped to one or more delegated approval sources, holding the rules TXN applies on your behalf while your own endpoint is unavailable, and it can engage automatically or be switched on by hand."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"8299fc0b-0033-416c-8676-7ff1aa0b8adf","properties":{"text":"A stand-in exists so that an outage on your side does not become a run of declined transactions for your cardholders. It binds to the sources it covers, carries the triggers that bring it into play, and describes how TXN should decide while it is standing in. Everything in it is a judgment about what you would rather happen when nobody can ask your system: approve conservatively on stale information, or decline and protect yourself."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"7f7d5daf-19fa-4355-8758-918cecd5c1d5","properties":{"sectionText":"What a stand-in binds to"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"05140347-2861-48db-8f3e-4839195315ca","properties":{"text":"One binding is required: the delegated approval sources it covers. A stand-in without a source protects nothing. Alongside those it can bind merchant controls and spend controls of its own, which is how you run a tighter policy during an outage than you would normally: narrower merchant categories, lower limits, or both. Every identifier you bind has to resolve to a record that already exists, so build the controls first and the stand-in around them."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"2df3a130-263a-404d-b2cb-32209734e06d","properties":{"sectionText":"What makes it engage"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"6e0d1695-6af8-41bb-a5b3-ec5da93c9a63","properties":{"text":"Three failure types can each independently be set to trigger a stand-in. An application error is your endpoint answering with a fault. A network error is the connection failing, which specifically excludes the timeout case. A timeout is your endpoint not answering inside the window configured on the source record. They are separate switches because they usually mean different things: a fast application error may be a bug worth failing over for immediately, where an occasional network blip may not be."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"cbf7fc89-41c5-4ed2-963b-1f8799b7dee1","properties":{"alertTitle":"A stand-in with no triggers enabled sits inert.","alertContent":"Scoping a stand-in to a source does not arm it. If none of the three triggers is enabled, your endpoint can fail every request and nothing will engage automatically. Someone would have to notice and switch it on by hand, which during an authorization outage is minutes of declines you did not need to take.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"dfd88f3f-aed3-4414-840c-617507b6bf80","properties":{"sectionText":"Switching one on by hand"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"9c25a0f8-c8e7-4dc3-a470-77680204576f","properties":{"text":"A stand-in can also be activated deliberately rather than waiting for a trigger, and deactivated the same way once your system is healthy again. That is the right tool for planned maintenance, or for a partial degradation your triggers would not catch: your endpoint answering correctly but far too slowly to be useful, say. Each activation and deactivation records who or what initiated it and a reason, so the history explains itself later rather than showing an unexplained state change."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"32b8130f-2141-4c94-b95d-a4eb148fa4ae","properties":{"sectionText":"What changes while a stand-in is active"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"bd14924e-29e5-429c-9157-fd4605be6835","properties":{"text":"While a stand-in is deciding, it is working from what TXN holds rather than from your system\u0027s own view, and three things are configurable. Whether the decision is judged against the balance TXN already holds, which may be behind your own if your system is the authority. Which merchant and spend controls apply, letting the outage policy differ from the normal one. And whether spend already made within a control\u0027s window counts towards its limit, or whether the stand-in starts from a clean sheet."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"534859e4-8fa2-456b-9ca1-6a03c773f060","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"5bcd4702-ce90-483a-a593-fc04a37fba5f","name":"Da Stand In Engages Dark","mediaType":"Image","url":"/media/rwgjx1pz/da-stand-in-engages-dark.png","extension":"png","width":2400,"height":1070,"bytes":303236,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"736e8d9a-37ac-498f-acda-6ba79925feaa","name":"Da Stand In Engages Light","mediaType":"Image","url":"/media/cvddrrof/da-stand-in-engages-light.png","extension":"png","width":2400,"height":1070,"bytes":295740,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"600477b7-4605-4fc9-90a2-0d9443e70381","properties":{"alertTitle":"Starting from a clean sheet can authorize a second full allowance.","alertContent":"If existing spend is not counted, a cardholder who has already spent their monthly limit starts the outage with that limit available again. For a short outage on a low-value program that may be an acceptable trade for continuity. On anything else it is how a stand-in turns a bad hour into a bad month, so choose it deliberately rather than leaving it unset.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"eaf40e00-5a24-40fc-b57c-c0007dfb3e7f","properties":{"sectionText":"State and history are recorded as transitions"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"df320f50-4cdf-4960-909d-f99d065bf5fd","properties":{"text":"A stand-in\u0027s current state records whether it is enabled, what initiated that, and why. The initiator is the same set used for transitions elsewhere on the platform: an API call, the platform itself, or a person acting in Control Center. Every change is kept as its own entry, and the full history is readable the way other transition histories are, which is what lets you reconstruct afterwards exactly when cover engaged and on whose instruction."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ac16cfcc-1698-4274-afdc-5d7d57621a33","properties":{"sectionText":"Changing a stand-in"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"cb80d0b5-88ae-4f79-85f7-6827d31db06a","properties":{"text":"A stand-in is not fixed once created. The sources it covers, the merchant and spend controls it binds, the triggers that engage it and how it behaves while active can all be changed as your program\u0027s needs change. Worth timing those changes carefully, though: editing a stand-in that is currently active changes the basis on which live decisions are being made, so make configuration changes while it is out of play rather than in the middle of the outage it was built for."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3c1a5772-6ecb-4e0b-91e3-5284eb52674f","properties":{"sectionText":"\u0022Stand-in\u0022 means something else elsewhere"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3f855195-b998-461f-862d-081752cc78c5","properties":{"text":"The term is used differently in card payments generally, where a stand-in is the card scheme approving a transaction on the issuer\u0027s behalf when the issuer itself is unreachable. That is a separate mechanism operating above TXN and is not what this page describes. Here, a stand-in is TXN deciding on your behalf when you are unreachable."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"bb7bcc87-6ab3-4a29-bc30-2b0e6e1040f9","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"1d3ab60d-6541-4807-b22f-c31a3bf0a619","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"ef50d443-d044-43d2-9225-2da02d553eb6","properties":{"cardTitle":"How Delegated Approval Works","cardText":"The flow a stand-in covers for, and what your endpoint has to answer.","pageLink":{"contentType":"guidePage","name":"How Delegated Approval Works","createDate":"2026-09-16T06:26:34.807Z","updateDate":"2026-11-15T16:32:47.123Z","route":{"path":"/103/delegated-approvals/how-delegated-approval-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e47adf53-2c39-46bb-bb12-ff0c765b075c","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"213649ff-9fa9-4aa3-8b09-64b70867cafc","properties":{"cardTitle":"Delegated Approval Sources","cardText":"The record a stand-in protects, and the timeout its trigger measures against.","pageLink":{"contentType":"guidePage","name":"Delegated Approval Sources","createDate":"2026-09-16T06:26:56.91Z","updateDate":"2026-11-15T16:32:46.167Z","route":{"path":"/103/delegated-approvals/delegated-approval-sources/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"d321a15f-1299-48cb-a8cb-11440abd0a74","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"58ee817c-4962-425d-92a0-45432e130000","properties":{"cardTitle":"Spend Controls","cardText":"The limits a stand-in can bind, and how existing spend is counted.","pageLink":{"contentType":"guidePage","name":"Spend Controls","createDate":"2026-09-16T10:47:00.377Z","updateDate":"2026-11-15T16:32:45.233Z","route":{"path":"/103/card-controls/spend-controls/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b3eace44-6780-4c51-831b-164ca1d52e67","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"9d516399-c974-4a4a-8206-f4a61cbbd76d","properties":{"prevPageTitle":"Delegated Approval Sources","nextPageTitle":"Digital Wallet Tokens"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"3-D Secure","createDate":"2026-09-16T06:24:47.867Z","updateDate":"2026-11-15T16:32:41.32Z","route":{"path":"/103/authentication-sca/3-d-secure/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2c14bfed-9803-44c3-a57c-6105c8c6131d","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"ec62bc39-715f-4d85-b1c2-9d23e8acf54d","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"aee7873e-4e70-4e73-9dd3-a4476a646811","properties":{"title":"3-D Secure","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"ebd86d2b-0d49-415d-a953-cd39b13b5c89","properties":{"text":"3-D Secure is the scheme mechanism that lets an issuer authenticate a cardholder during an online payment, and it is what a merchant relies on to shift liability for a fraudulent transaction. This page explains how the flow works in general terms."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"2de8588a-1494-4ef0-8405-6ded965d1280","properties":{"text":"3-D Secure works automatically on TXN. There is nothing to set up on a product and nothing to switch on for a card, so a payment that calls for authentication simply goes through the flow described here. For the full field list and schema, see the API Reference."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"a0efeddd-fc98-4b05-8ee1-5e42a184f7bb","properties":{"sectionText":"How a payment is authenticated"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"62cbae99-b32a-4819-bfaf-7779594104a8","properties":{"text":"When a cardholder pays online, the merchant\u0027s checkout sends the payment details, together with data about the device and the transaction, to the card scheme\u0027s directory. The directory routes the request to the issuer\u0027s authentication service, which assesses the risk of the payment and decides how to respond. The response is either to authenticate the payment silently or to challenge the cardholder, and the result is passed back to the merchant."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"cc936ce3-2432-476b-9cde-92174e568a0e","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"bb70f28a-86d8-41a1-b071-087233e27d65","name":"Aut 3Ds Flow Dark","mediaType":"Image","url":"/media/au2dmdnr/aut-3ds-flow-dark.png","extension":"png","width":2400,"height":1010,"bytes":271029,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"af038059-484a-4bcc-90aa-55ea25100660","name":"Aut 3Ds Flow Light","mediaType":"Image","url":"/media/0zfekgjd/aut-3ds-flow-light.png","extension":"png","width":2400,"height":1010,"bytes":268292,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3632efb1-761c-4898-95aa-050fde6d7b5a","properties":{"sectionText":"Frictionless and challenge flows"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3ba5986b-8f2f-49d6-baaf-13d23a52b548","properties":{"text":"Most payments are authenticated without the cardholder doing anything. This is the frictionless flow: the issuer is satisfied by the data it was sent and approves the authentication silently. When the issuer wants more assurance it runs a challenge flow instead, asking the cardholder to prove who they are, typically with a one-time passcode or a biometric check in their banking app. The payment goes ahead only if the cardholder passes, and fails if they do not."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"8a4ca0fc-d872-4c6f-98ed-f0fd22253f95","properties":{"text":"Whichever flow runs, the outcome travels back to the merchant as an authentication result, with a cryptographic value that proves the check took place. The merchant includes it when it requests authorization, and the issuer takes it into account in its decision. A fully authenticated payment is what moves liability for fraud from the merchant to the issuer."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4ae6da19-f21f-44ea-afd9-2f3d5fe0a272","properties":{"sectionText":"Authentication events record what happened"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ec5b2197-8f9e-4fbb-a905-5fa3464c559c","properties":{"text":"The platform records authentication events: what happened when a cardholder was actually challenged during a payment, and how it resolved. These are records of authentication attempts, and they are what you read when investigating a disputed or failed payment."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"a8f62fa7-9cf2-4a0f-8a12-a6022491bdab","properties":{"sectionText":"How 3-D Secure relates to other objects"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"babd913c-0b60-4261-ac4d-e4081a56b4bb","properties":{"text":"Successful authentication is what establishes a trusted merchant, which can then exempt the cardholder from re-authentication at that merchant. The thresholds deciding when authentication is demanded at all sit with the product\u0027s Strong Customer Authentication settings."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"c87578a6-317f-4146-973e-4d91ab5ec04c","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"99e3efbf-5f64-4a2e-95ba-0ac94549e5f3","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"dd94ccdf-8ffe-498e-85e7-6c823c65cd1c","properties":{"cardTitle":"Trusted Merchants","cardText":"Using a successful authentication to spare the cardholder the next challenge.","pageLink":{"contentType":"guidePage","name":"Trusted Merchants","createDate":"2026-09-16T06:24:40.2Z","updateDate":"2026-11-15T16:32:39.053Z","route":{"path":"/103/authentication-sca/trusted-merchants/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"09bbc81a-17c3-429c-b340-e9ec7579ee78","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"d6d4a83a-a1db-4b7c-ad8e-041e0595cc96","properties":{"cardTitle":"SCA Counters and Contactless Limits","cardText":"What a successful authentication resets, and what builds back up.","pageLink":{"contentType":"guidePage","name":"SCA Counters and Contactless Limits","createDate":"2026-09-18T11:31:20.097Z","updateDate":"2026-11-15T16:32:42.133Z","route":{"path":"/103/authentication-sca/sca-counters-and-contactless-limits/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2f69ffc6-6124-4eba-8a7d-9d7c316195c7","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"8e417569-261e-4d71-b388-cb2ec78867f0","properties":{"cardTitle":"Cards","cardText":"The card lifecycle and what each state means.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"37c51b9b-110b-467e-9139-25b974a332f0","properties":{"prevPageTitle":"SCA Counters and Contactless Limits","nextPageTitle":"Trusted Merchants"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Replacing a Card","createDate":"2026-11-14T13:45:44.953Z","updateDate":"2026-11-15T16:32:41.983Z","route":{"path":"/103/managing-cards/replacing-a-card/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2db9d6c2-7f22-452f-b105-e3f518240751","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"5c9fe69f-812b-4a0d-89b1-f37c5450612e","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"0d1a5eb9-6abf-4ac2-9d70-7ec4884e84e4","properties":{"title":"Replacing a Card","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"653b91e1-80bf-48a0-8ee2-5c818b62c977","properties":{"text":"A card is lost, stolen, damaged or never turned up. There are two separate things to do: stop the card that exists, and issue the one that takes its place. Neither requires the other, and doing only one of them is a real answer in some situations."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"31bfc9ec-dd7f-484b-a35f-5c79866f807c","properties":{"text":"Start with what is actually wrong, because it decides the rest. A card reported stolen is a security problem: the number is compromised and has to stop being usable immediately. A card that snapped in half is an inconvenience: nothing about it is compromised, and the cardholder would rather not re-enter a new number everywhere they have stored it. TXN handles both through the same two operations, but you make different choices inside them."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"f31fb56d-65c5-4341-b9c4-e963bad913bd","properties":{"sectionText":"Stopping the card that exists"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"c5848b33-3520-4f89-aae7-29f5f2c97b9e","properties":{"text":"A card is stopped through a transition, the same mechanism as any other status change. On hold is reversible and is the right choice while the cardholder is still looking for it. Closed is not reversible, and a closed card cannot be reopened, edited or brought back, so keep it for the cases where you are certain."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"1aca33fb-61e2-4529-9622-a30afc736694","properties":{"alertTitle":"Stopping the card does not stop its digital wallet tokens.","alertContent":"A card put on hold or closed leaves any Apple Pay or Google Pay token provisioned from it live and spendable, unless you explicitly ask the transition to propagate. For a card reported lost or stolen this is the step that matters most, and it is the one most easily missed: set applyToDigitalWallets on the transition. Propagation is queued rather than instant, so allow a short delay before the token actually stops working.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e628a11d-6ebd-4a2b-8bee-99d1fd1e6d38","properties":{"sectionText":"Recording why, not just what"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"d70ea220-7104-401d-b68b-c5441afe9032","properties":{"text":"Every transition carries a reason, and cards have their own set rather than sharing the one used by cardholders and accounts. Four of them cover this situation: the card was reported lost, the card was reported stolen, the card is physically unusable, or a physical card never arrived. TXN behaves identically whichever you choose. The reason is not a control, it is the record: the thing that tells you months later whether this was a fraud event or a broken card, and the thing a scheme or an auditor will ask about."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"1afa3bb0-4352-4169-b7bd-06bd23f14224","properties":{"sectionText":"Issuing the replacement"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"8f545914-6dd6-4116-a5bc-a80649931b33","properties":{"text":"There is no separate reissue operation. A replacement is created through the ordinary card creation call, naming the original as its source. Two settings do the work. One names the source card and asks for a new number; the other names the source card and asks to keep the existing one. They cannot both be used on the same request. A third setting closes the original as part of the same action, so you do not have to sequence a transition and a creation yourself."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"445c91d0-aa45-4b6c-8194-de925bc72266","properties":{"sectionText":"New number or the same one"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"36db433f-1433-4150-bf4b-a5aab1f1a9d0","properties":{"text":"This is not a preference. A card reported lost or stolen has to be replaced with a new number, because the old one is in circulation and the point of the exercise is to take it out. A card replaced because it is damaged or approaching expiry can keep its number, which spares the cardholder updating every merchant holding it on file. The physical card is remade either way: the question is only what is printed on it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"0836eb57-bb68-4724-9ec0-cf02cba81bf7","properties":{"alertTitle":"Every new number comes out of your range.","alertContent":"Issuing a replacement with a new number takes a card number from the BIN range assigned to the product, and it does not come back. That is unremarkable one card at a time and worth watching across a program: a fraud event that replaces a large batch of cards draws down the same range that new issuance depends on. Keep range utilization in view rather than discovering it during an incident.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e8729217-6294-405e-a083-09fe4903123d","properties":{"sectionText":"The replacement arrives inactive"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"c28f2b18-7b65-47d7-b9cb-65d0814e0c7a","properties":{"text":"A replacement is created in the same state as any other new card: inactive, and unusable until it is activated. For a physical replacement that fits the shape of the problem anyway, since the card has to reach the cardholder before it can be activated. Activation is a transition like any other."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"12c77bda-a87a-4ddc-9c1f-273fcd44dad1","properties":{"sectionText":"What activation triggers"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"33b06d9b-b558-4e03-9085-43e755e9f100","properties":{"text":"Activation is the point at which everything else moves. Digital wallet tokens that were provisioned from the original card are reassigned to the replacement automatically, with no separate call from you. Merchants holding the old number on file are told the new one through the account updater, if the program is enrolled and the cardholder has not opted out. Nothing about either happens at the moment you create the replacement."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"b81ea93a-1d5a-4efd-b42f-8836bfd93a8e","properties":{"alertTitle":"Between issuing and activating, the wallet still points at the old card.","alertContent":"Wallet tokens deliberately stay on the original card until the replacement is activated, so that a token is never attached to a card nobody is holding yet. The consequence is a gap: if you closed the original and propagated that to its tokens, the cardholder\u0027s wallet stops working and does not start again until the replacement card is in their hands and activated. For a stolen card that is correct and unavoidable. For a damaged card it is worth telling them to expect.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"26a49449-d131-4895-9939-85eb6a1ea4b1","properties":{"sectionText":"What the replacement does not inherit"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"605ad9fe-d517-4eec-9e8f-ad639e19141a","properties":{"text":"A replacement is a new card record, not a continuation of the old one. Behavior that comes from the product applies to it as it does to any card issued against that product. Anything set on the original card itself (your own attributes, any control set at card level) is worth checking on the replacement rather than assumed to have followed it across."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"c3ca2450-af74-4079-a90b-94afb9695bd8","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"ebbf8a25-d6ad-49fb-98a5-0f788c8b21cc","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"52186960-c2af-4f9b-9a87-d2ec2b62e3f1","properties":{"cardTitle":"Cards","cardText":"The card record, its states and everything a transition can carry.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"ef23bad1-2dbb-4a8c-bb5a-b08cea6c6fe5","properties":{"cardTitle":"Card Expiry","cardText":"What happens when a card reaches its expiry date.","pageLink":{"contentType":"guidePage","name":"Card Expiry","createDate":"2026-11-14T13:45:45.047Z","updateDate":"2026-11-15T16:32:45.757Z","route":{"path":"/103/managing-cards/card-expiry/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"c55e0510-91cf-417d-aac9-10de3a62db61","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"e1ea4201-c781-42e2-b4e3-e9f01b3ae1ec","properties":{"cardTitle":"Digital Wallet Tokens","cardText":"What happens to a token when the card underneath it is replaced.","pageLink":{"contentType":"guidePage","name":"Digital Wallet Tokens","createDate":"2026-11-14T13:46:40.313Z","updateDate":"2026-11-15T16:32:42.527Z","route":{"path":"/103/digital-wallet-tokens/digital-wallet-tokens/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"40b1a666-ed74-4f45-8745-d54c19dc8a2c","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"34f861d3-6aa2-4cfd-9981-3a32f004fbe2","properties":{"prevPageTitle":"Activating a Card","nextPageTitle":"Transferring a Card"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Error Code Reference","createDate":"2026-11-14T09:22:41.537Z","updateDate":"2026-11-15T16:32:44.333Z","route":{"path":"/103/api-essentials/error-code-reference/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"99385b25-c2d3-4426-88ce-b791adc5cc80","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"a3d8aeef-d9f6-4353-ae70-ada501b61724","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"12b4854c-6e42-48b2-97da-17a4a762a766","properties":{"title":"Error Code Reference","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"c4d4e9ad-db94-4e2d-ab48-59c254ac072d","properties":{"text":"Every HTTP status and TXN error code the API can return, in one searchable list."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3d441425-d90d-4641-b4cd-34005dbb76ff","properties":{"sectionText":"Reading an error response"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"c71cd1bb-f92c-4a24-a441-6d336c2cf647","properties":{"text":"When a request fails, the response keeps the standard TXN envelope: result is null, and error holds a TXN code (error.code) and a description (error.description). The HTTP status gives you the type of failure. The TXN code tells you exactly what went wrong."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"c006d206-6170-40c3-8113-afce9a5a8109","properties":{"sectionText":"All error codes"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ac74cf76-8ef4-40e3-b626-a67944897601","properties":{"text":"Search by HTTP status, TXN code or any word in the description. For example, enter 60305 to look up a code from a response, or cardholder to see every cardholder-related error. Each code is listed once, even when several endpoints can return it. The list is built from the current API specification, so it always matches the API Reference."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"errorCodeList","id":"56ec5fd8-4b73-47f5-8442-520971f297c7","properties":{"apiVersion":"1.0.3","apiGroups":null,"individualApiEndpoints":null,"filter":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"01d72240-8cfa-4bb6-9451-fbc4e8ccb0ef","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"69d40304-3f08-4e57-b166-f7d850b86304","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"0f4cf720-5c27-4b23-acfe-11030881abb3","properties":{"cardTitle":"Errors","cardText":"What each status means, and how to build error handling that lasts.","pageLink":{"contentType":"guidePage","name":"Errors","createDate":"2026-11-14T09:22:41.277Z","updateDate":"2026-11-15T16:32:46.777Z","route":{"path":"/103/api-essentials/errors/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dba005b5-8d0e-48ba-84b2-85c6855f7c5e","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"e32e4a59-e5f5-4e82-bdd3-57baf1b66db3","properties":{"cardTitle":"Rate Limits","cardText":"Why a 429 happens, and how to pace your integration so it does not.","pageLink":{"contentType":"guidePage","name":"Rate Limits","createDate":"2026-11-14T09:22:41.343Z","updateDate":"2026-11-15T16:32:47.413Z","route":{"path":"/103/api-essentials/rate-limits/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"eaf38fec-bda3-49d6-be92-41e32f25e364","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"306cd4fd-550a-4713-832d-34a12ba297da","properties":{"cardTitle":"Retries and Idempotency","cardText":"Which failures are safe to retry, and how to retry a write safely.","pageLink":{"contentType":"guidePage","name":"Retries and Idempotency","createDate":"2026-11-14T09:22:41.407Z","updateDate":"2026-11-15T16:32:39.84Z","route":{"path":"/103/api-essentials/retries-and-idempotency/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"182084cf-2e4d-406f-a1e4-9a1dcba5f19d","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"ae3cc38f-9bec-4ef5-b363-0becbe299059","properties":{"prevPageTitle":"Errors","nextPageTitle":"Rate Limits"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Environments","createDate":"2026-09-16T06:21:03.5Z","updateDate":"2026-11-15T16:32:45.067Z","route":{"path":"/103/getting-started/environments/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b230a635-a702-4570-a189-ce295a6165dc","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"adbe3669-397d-4b25-bb53-c58bdd496920","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"1c7f2fd3-a738-4998-93d8-5b71af4d936d","properties":{"title":"Environments","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"2313f3ed-807a-4b57-9ba6-73de56de292e","properties":{"text":"Building against a platform that can move real money is safer with somewhere to build that cannot. TXN gives you three separate environments, so you can develop an integration and prove it works before any card you issue is capable of touching real money. Each one answers a different question about how ready you are."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"730fd0c0-520d-44e5-a4c6-645001fc0052","properties":{"text":"The three are genuinely separate. Each has its own credentials and its own data, and nothing you create in one appears in another. That isolation is the point, and it shapes most of how you work across them."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"02a5b4d4-be37-4163-a965-2321873d56e1","properties":{"sectionText":"What each environment is for"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"6840fa36-8d3b-4748-9ce1-557160d2aa79","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"9c2204ba-df27-460f-8ed1-3ba11c0b4c21","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"c4df994f-eea2-4014-89a8-c0a56756005c","properties":{"cellContent":null}},"settings":null},{"content":{"contentType":"tableCell","id":"f31972bc-610c-4c1a-b78d-03595f8edd66","properties":{"cellContent":"Public Sandbox"}},"settings":null},{"content":{"contentType":"tableCell","id":"7ef2e3a8-a416-4373-87cc-f7bef3c12da9","properties":{"cellContent":"User Acceptance Testing"}},"settings":null},{"content":{"contentType":"tableCell","id":"20d52d6d-3bc1-4115-8391-0c155989a2ca","properties":{"cellContent":"Production"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"1b3caa83-8719-4a29-a187-fa267ec1e2fa","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"d30fa509-30ce-4e75-a314-fa07febd3c8e","properties":{"cellContent":"Data"}},"settings":null},{"content":{"contentType":"tableCell","id":"f809fdc6-fd5c-4075-8d1b-566d9eb763ed","properties":{"cellContent":"Entirely simulated"}},"settings":null},{"content":{"contentType":"tableCell","id":"3de80952-c892-44e3-9162-fc13b5fe6cfc","properties":{"cellContent":"Simulated, in a configuration shaped like your own program"}},"settings":null},{"content":{"contentType":"tableCell","id":"147b8f02-4a7a-4daa-9b98-9af5e2766f8f","properties":{"cellContent":"Real"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"55d94f04-7017-4db2-a12c-afa3d89fd1b3","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"03844047-5a97-493b-811a-040f546635b3","properties":{"cellContent":"Purpose"}},"settings":null},{"content":{"contentType":"tableCell","id":"a622b1bf-dec7-4563-8983-75d2b0d6f122","properties":{"cellContent":"Try the API and build against it"}},"settings":null},{"content":{"contentType":"tableCell","id":"6d988975-a4e0-4dee-adde-5e5abc32cf86","properties":{"cellContent":"Validate your integration end to end before launch"}},"settings":null},{"content":{"contentType":"tableCell","id":"2a546ae1-444e-44ac-bc85-9a9c4a8726a0","properties":{"cellContent":"Cards are real and transactions move real money"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"242bbf55-c55c-480a-8977-29a3b51e8f5c","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"955cfc54-d081-477a-8cb6-82559fc22762","properties":{"cellContent":"Access"}},"settings":null},{"content":{"contentType":"tableCell","id":"12205334-2014-4b8b-a1cb-0d56816f0e0f","properties":{"cellContent":"Available from the Knowledge Hub"}},"settings":null},{"content":{"contentType":"tableCell","id":"1361277f-2a31-424f-a063-6d5e16f0f06f","properties":{"cellContent":"Unlocked during commercial onboarding"}},"settings":null},{"content":{"contentType":"tableCell","id":"78c51d22-d759-4767-bc69-4e54cdfc1b7c","properties":{"cellContent":"Unlocked during commercial onboarding"}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"5730d0b1-3185-4002-858d-12401254edcf","properties":{"text":"The Public Sandbox is hosted at sandbox.txn.global, and the Knowledge Hub is where you use it. For UAT and Production, the address is issued alongside the credentials you create in Control Center."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"b68985ed-bca4-4792-9d6b-0edbc0888c5c","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"effa5bee-753b-46f0-aad3-81cd98926ffc","name":"Gs Environments Three Environments Dark","mediaType":"Image","url":"/media/mgilywks/gs-environments-three-environments-dark.png","extension":"png","width":2400,"height":1040,"bytes":239658,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"7697348d-67b6-40c0-96f9-3981dff7f961","name":"Gs Environments Three Environments Light","mediaType":"Image","url":"/media/al5ndqg5/gs-environments-three-environments-light.png","extension":"png","width":2400,"height":1040,"bytes":235293,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"cf84c5ad-67ee-4bf1-97af-2c2b8858af98","properties":{"sectionText":"Nothing carries across"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"0fab450b-cea0-4a5c-840e-de3a1fbd6320","properties":{"text":"Each environment holds its own data, and the data in one is invisible from the others. A cardholder or a card created in the Public Sandbox does not exist in UAT or in Production, and there is no promotion path that carries a specific record forward as you move between them. Credentials work the same way, which Authentication covers.\n\nThat means setting up your test scenarios separately in each environment you validate against, rather than assuming something you proved once is sitting ready in the next one. Treat each environment\u0027s setup as its own exercise."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"27097e1d-ee09-4d2b-b574-a836c79cd9ea","properties":{"sectionText":"Moving towards production"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"34008ba3-d353-4da5-83c7-b68037ff847c","properties":{"text":"Work through the environments in order. Each one answers a question the one before it cannot.\n\n1. Build in the Public Sandbox until your integration works end to end, including the paths that fail.\n2. Validate in UAT against the configuration you intend to run.\n3. Work through the Going Live checklist, then request production access."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"c8a9c4ae-b9f0-4b33-97c8-0d273f443271","properties":{"alertTitle":"Working in the sandbox is not the same as proven","alertContent":"Sandbox data is simulated and its configuration is not the one you will run. An integration that passes there can still fail in UAT against a configuration shaped like your own program. Sandbox success is not a reason to request production access.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"35b59f5a-26bc-49cd-a409-d3e916b17679","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"cf272415-9fc6-4d03-b556-b06d34673573","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"d73fe03c-4463-490e-87f7-e8748c48ce72","properties":{"cardTitle":"Your First Request","cardText":"Run a real call against the Public Sandbox without leaving the Hub.","pageLink":{"contentType":"guidePage","name":"Your First Request","createDate":"2026-09-16T06:21:15.68Z","updateDate":"2026-11-15T16:32:41.837Z","route":{"path":"/103/getting-started/your-first-request/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2dac4688-011a-484f-b2d5-da68a0413646","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"ae7752e2-277c-42a1-bb19-eb4570834c74","properties":{"cardTitle":"From First Call to Go-Live","cardText":"The path from your first sandbox call to production access.","pageLink":{"contentType":"guidePage","name":"From First Call to Go-Live","createDate":"2026-09-16T10:37:09.553Z","updateDate":"2026-11-15T16:32:46.457Z","route":{"path":"/103/working-with-txn/from-first-call-to-go-live/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"d6f8f50b-69d9-4bbf-8fe3-83fdbbe71cf6","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"0e185363-4af9-4e04-8a5e-3727f69e07e1","properties":{"cardTitle":"Go-Live Checklist","cardText":"What production access actually requires.","pageLink":{"contentType":"guidePage","name":"Go-Live Checklist","createDate":"2026-09-16T11:15:47.56Z","updateDate":"2026-11-15T16:32:39.463Z","route":{"path":"/103/going-live/go-live-checklist/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"12248e91-a4b4-4166-aa39-5c888cb4f7dc","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"789dc0ac-94f0-4d24-a7a5-51a99764d816","properties":{"prevPageTitle":"Core Objects","nextPageTitle":"Your First Request"}},"settings":null}},"cultures":{}},{"contentType":"baseGuidePage","name":"Payment Concepts","createDate":"2026-11-14T14:49:37.953Z","updateDate":"2026-11-16T06:59:26.377Z","route":{"path":"/103/payment-concepts/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2ca017c7-3c76-4ebf-b7b9-b8a8fe0f5834","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"7159fab4-49f8-4629-b61a-2e95a42fa738","name":"Payment Concepts 1","mediaType":"umbracoMediaVectorGraphics","url":"/media/izdpxe5d/payment-concepts_1.svg","extension":"svg","width":null,"height":null,"bytes":8158,"properties":{}}]},"cultures":{}},{"contentType":"newVersion","name":"1.0.3","createDate":"2026-06-03T07:52:13Z","updateDate":"2026-11-16T07:42:04.43Z","route":{"path":"/103/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b033dcec-036e-4701-8921-53fe13e5accd","properties":{"isLatest":true,"isBeta":false},"cultures":{}},{"contentType":"guidePage","name":"Merchant Controls","createDate":"2026-09-16T06:24:31.46Z","updateDate":"2026-11-15T16:32:42.82Z","route":{"path":"/103/card-controls/merchant-controls/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"51fd9837-c394-466d-8bcf-b1b71c811da2","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"24e78f0e-0649-43fe-a582-18f5bf10c4d7","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"8fa31309-ba14-4b67-828d-95ffa702e1a6","properties":{"title":"Merchant Controls","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"82962a3e-a5d5-44ac-b49d-e292517fbfdd","properties":{"text":"Spend controls decide how much a card can spend. Merchant controls decide where. The two run independently, and a transaction has to satisfy both."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"49f1d95f-9b27-4456-a3ff-705191053504","properties":{"text":"Merchant controls answer a different question from spend controls and are configured separately, but they work the same way underneath: rules attach at layers of a hierarchy, every applicable rule is evaluated during authorization, and a transaction is declined if any of them is violated. Nothing overrides anything else. Passing at one layer does not excuse failing at another."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"1c4a9111-f0db-43c3-8666-0daf2ccffe7f","properties":{"sectionText":"Start with the product\u0027s default posture"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"9f4126b8-0bf6-423e-bfb5-525408b9aec4","properties":{"text":"A product declares how it treats a merchant it has no specific rule for. Either it approves by default, making the model open with exceptions, or it declines by default, making it closed with allowances. That single choice frames everything else. An open posture means your controls are a blocklist and anything you have not thought of is permitted. A closed posture means they are an allowlist and anything you have not thought of is refused. Decide it deliberately, because retrofitting the other model to a live program means rewriting every control on it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"d97720da-34f0-4551-82aa-2a050167fd65","properties":{"sectionText":"A merchant control is a named, reusable rule"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"fff903cf-7a5c-4456-a9f3-d16cd862686e","properties":{"text":"A merchant control has a name, an active flag, and a scope describing the merchants it concerns. That scope can be expressed three ways: by merchant category code, by individual merchant identifier, or by referring to a merchant control group. A control can also carry a start and an end time, which is how a restriction that only applies during a defined period is expressed without anyone having to remember to remove it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"c75caae4-1f51-41ad-957e-f7e97c6432f4","properties":{"sectionText":"Where a control attaches"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"680584c3-3da0-442e-9351-da733983e7f9","properties":{"text":"Controls attach across the same ownership hierarchy that spend controls use, from the BIN sponsor at the top down through program manager, card program, product, cardholder group, parent cardholder, cardholder and account, to the individual card. Which layer a control belongs to is decided by where you create it rather than by a field inside it. At BIN sponsor level a control can apply to the whole sponsor, or be narrowed to a specific BIN or a specific BIN range."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"53eba394-043b-4e74-9eea-dbbee50d35c2","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"b3d51941-c671-4a9b-808d-9ecafc129bbf","name":"Cc Merchant Controls Layers Dark","mediaType":"Image","url":"/media/z1jjgbiy/cc-merchant-controls-layers-dark.png","extension":"png","width":2400,"height":1190,"bytes":284311,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"5fb41a98-cda4-42e4-8290-89568ced52d1","name":"Cc Merchant Controls Layers Light","mediaType":"Image","url":"/media/c5ipf0on/cc-merchant-controls-layers-light.png","extension":"png","width":2400,"height":1190,"bytes":277370,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"6ec379f0-d3c3-4076-9d42-808bea919fb1","properties":{"alertTitle":"A merchant decline can come from a layer you did not configure.","alertContent":"Every applicable control across the hierarchy is evaluated, and a violation at any one of them declines the transaction. So a card that fails at a merchant you explicitly allowed may be failing on a restriction set at the product, the program or the BIN sponsor: layers your team may not own. When a decline does not match the control you are looking at, look up the hierarchy rather than assuming the control is broken.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4227957c-f316-4bad-9a3f-c8aa8d2b8267","properties":{"sectionText":"Merchant control groups, and why they exist"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"e630a82a-87b0-4148-a8ca-c5006dd6d0da","properties":{"text":"A merchant control group is a reusable bundle of merchants: a set of merchant identifiers and a set of merchant category codes, defined once and referenced by any number of controls. Category codes can be given individually or as ranges. Group names have to be unique, which is what makes them dependable to refer to. The value is that \u0022the merchants we do not do business with\u0022 becomes one definition maintained in one place rather than a list duplicated across every control that needs it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"8f7ded53-7fc9-4ef1-a484-e501731186f2","properties":{"sectionText":"A group carries authorization rules too"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"73b9f4fb-35ff-4b63-9eba-ec3af8331019","properties":{"text":"Beyond membership, a group configures two things about how authorizations at those merchants behave. The first is how long an authorization stays valid before it expires if it has not settled. The second is whether an authorization may be increased and by how much: as a fixed amount, as a percentage, or by raising it to a stated figure. These are the settings that make a fuel pump or a hotel behave sensibly, where the final amount is not known when the card is first presented."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"39b93900-ce64-4d95-94fb-059631cefe59","properties":{"alertTitle":"Updating a group replaces its lists rather than adding to them.","alertContent":"The merchant identifiers and category codes you send on an update replace what was there, they do not merge with it. Sending a group update with one new merchant identifier and nothing else leaves the group containing exactly that one merchant. Always send the complete list you intend the group to hold. The audit history records the change element by element, so the damage is at least visible afterwards, but it is visible after the controls have already changed.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"194d8e3c-9f76-4f83-9f7a-ddaf557a3480","properties":{"sectionText":"Every change is versioned"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"33cf3928-8f1f-4574-909a-c622e84ee88a","properties":{"text":"Updating a control or a group creates a new version rather than overwriting the old one, and the previous version remains available. Activation and deactivation are recorded the same way. So the question a risk or audit conversation actually asks (what were the rules on this date, and who changed them) is answerable from the platform rather than from anyone\u0027s memory."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"8eb10fe0-8480-48fb-b561-a7dfe35c25ad","properties":{"sectionText":"Behavior during stand-in"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"5311f85d-20ed-41e8-9a21-f92729667b34","properties":{"text":"Each merchant control states how it behaves when a stand-in is deciding in place of your own system: evaluated during normal processing, during stand-in, or both. That matters because a stand-in is exactly when you are least able to intervene. A control that is not evaluated during stand-in is a restriction that lapses during an outage, which may be what you want for a convenience rule and is almost certainly not what you want for a fraud one."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"83f2ea56-5f70-4c14-8fc1-19f951cea4c1","properties":{"alertTitle":"Trusted merchants are a different mechanism with a similar name.","alertContent":"A trusted merchant concerns authentication, whether a cardholder has to be challenged at a merchant they have used before, and has nothing to do with whether a transaction is permitted. A merchant can be trusted for authentication and blocked by a merchant control at the same time, and the merchant control wins, because the transaction never gets as far as the question the trust was answering.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"8a4ee5ed-c00a-4276-858e-69ec5cf40d03","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"b330f01e-fbf1-4b43-aed9-1863b3852366","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"e4e73fc9-d3c8-4029-b7ba-473b35307ed1","properties":{"cardTitle":"Spend Controls","cardText":"The other half of the authorization decision: how much, rather than where.","pageLink":{"contentType":"guidePage","name":"Spend Controls","createDate":"2026-09-16T10:47:00.377Z","updateDate":"2026-11-15T16:32:45.233Z","route":{"path":"/103/card-controls/spend-controls/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b3eace44-6780-4c51-831b-164ca1d52e67","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"53bebb0f-3578-45a6-bbe5-12de1b54ccbf","properties":{"cardTitle":"Trusted Merchants","cardText":"The similarly named mechanism that governs authentication instead.","pageLink":{"contentType":"guidePage","name":"Trusted Merchants","createDate":"2026-09-16T06:24:40.2Z","updateDate":"2026-11-15T16:32:39.053Z","route":{"path":"/103/authentication-sca/trusted-merchants/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"09bbc81a-17c3-429c-b340-e9ec7579ee78","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"da06e7e0-dee5-4173-b3a9-65f9780aa85b","properties":{"cardTitle":"Transactions","cardText":"Where these controls are evaluated, and what a decline looks like.","pageLink":{"contentType":"guidePage","name":"Transactions","createDate":"2026-09-16T06:23:22.427Z","updateDate":"2026-11-15T16:32:47.27Z","route":{"path":"/103/money-movement/transactions/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e79295d5-99a5-4e5f-859c-c15d73178622","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"40d73964-671a-412a-81cf-e93cb7379a01","properties":{"prevPageTitle":"Spend Overrides","nextPageTitle":"Strong Customer Authentication"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Accounts","createDate":"2026-09-16T06:22:09.903Z","updateDate":"2026-11-15T16:32:43.31Z","route":{"path":"/103/foundational-objects/accounts/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"5c10167b-6790-43b8-8d90-d56c1a423a5c","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"2c98ab6b-c846-4a1a-95d0-7577908039f4","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"bffef12f-98df-4d5e-8477-0db991cd0e0b","properties":{"title":"Accounts","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"94ab1a12-a51c-4def-aff4-18f86323846d","properties":{"text":"In card issuing, an account is the object that holds money: a balance in a given currency, funded and owned in a defined way, that spending draws against. It sits underneath the cards a cardholder carries rather than beside them, which is why you open one as soon as a cardholder exists."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ba47d302-96c1-466c-9ec1-d2c50daf0fb9","properties":{"text":"On TXN, an account is created with a name, a single currency, an accountable owner and a funding type. Every card references an account rather than a cardholder directly, so a card\u0027s spending depends on the account\u0027s balance and status."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"c4f61594-3227-4bae-b714-ba6665564d8e","properties":{"sectionText":"Ownership: an owner, and optionally shared members"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"f0c17c7c-e590-40bc-8630-fbbc93d68277","properties":{"text":"Every account names one accountable owner. That is required, not a choice between models. On top of it, an account can additionally carry a set of members who share it, which is what turns a single person\u0027s account into a shared expense pool several cardholders draw against. That decision shapes how the account behaves for reporting and reconciliation afterwards, so an onboarding flow should settle it before creating the account. An account also carries optional free-form attributes alongside its required currency and funding type."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"ae43029d-d25f-4542-8b22-e811cfde94b3","properties":{"alertTitle":"Currency and account type are fixed at creation.","alertContent":"An account holds exactly one currency and one type, and neither can be changed afterwards. A program needing to hold several currencies for one cardholder needs several accounts, and an account created with the wrong type has to be closed and replaced rather than corrected. Settle both before you call.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3ebce59b-b047-449a-96c5-ebda31467fec","properties":{"sectionText":"How the account is funded"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"c0ee18f0-9e8a-4c1b-a7bb-a242d195c984","properties":{"text":"Funding type is required when you create an account and it decides where the authorization decision is made. There are two models.\n\nPlatform managed. TXN holds a balance and authorizes against it, so that figure decides whether a transaction is approved. You keep it in step as money moves on your side, and every transaction is approved or declined by TXN according to that balance and the controls on the product and card. This is the simpler model.\n\nDelegated approval. You hold the decision. TXN passes the authorization to your systems in real time and you approve or decline it, which lets you apply your own logic, your own balance, or rules TXN does not hold. It requires you to run a service that answers within the scheme\u0027s timeout, every time.\n\nWhich model you use is an architectural decision rather than a configuration flag, because the two put the authorization decision in different places and imply different systems on your side. Agree it with your TXN contact during onboarding rather than discovering it during integration. See Delegated Approvals for what running that model involves."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"81d5e3f8-3cfe-4e32-9bdf-49c2d4f08ce7","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"86325952-0c7c-4540-ac58-1da336d690b0","name":"Fo Accounts Funding Models Dark","mediaType":"Image","url":"/media/1wjhimav/fo-accounts-funding-models-dark.png","extension":"png","width":2400,"height":980,"bytes":218114,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"05c8df50-e468-4270-8fa8-2e27b0c2a138","name":"Fo Accounts Funding Models Light","mediaType":"Image","url":"/media/12kj3myb/fo-accounts-funding-models-light.png","extension":"png","width":2400,"height":980,"bytes":215473,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"b9eccabc-bceb-4ac6-bf00-6047c476c48e","properties":{"sectionText":"How accounts relate to other objects"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"5027411f-b4dd-4042-8461-808b3f7a0987","properties":{"text":"An account sits between the cardholder and the card, and each side connects differently.\n\nCardholders. One cardholder is the account\u0027s owner and is required. Others can be added as members, which is what makes an account shared. Ownership is recorded on the account, and the association is also carried on the cardholder, so keep the two consistent when you update either.\n\nCards. Cards reference the account, not the cardholder directly. A card\u0027s spending draws against the account\u0027s balance and is gated by the account\u0027s status, which is why an account on hold can stop a card working even though nothing about the card changed.\n\nProducts. The product governs how a card behaves: its limits, controls and capabilities. The account governs whether there is money and whether spending is allowed. Neither overrides the other, and a decline can come from either."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ae46c34c-54e8-4fa4-bfc0-a5ce6cd72633","properties":{"sectionText":"The account lifecycle"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"4eca2b1c-1e3a-45e0-95d4-da0f032d3b96","properties":{"text":"An account moves through three states: active, on hold and closed. Active and on hold are reversible. Closed is not: it is terminal, a closed account cannot be reopened and cannot fund spending again. Use on hold when you need to stop activity temporarily.\n\nFor an account, the lifecycle answers one question over time: is this account currently allowed to fund spending, and why did that change.\n\nAccounts, cardholders and cardholder groups all draw on the same set of transition reasons, listed in full on Cardholders. Cards have their own separate, card-specific set."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"4c0aa6b9-10de-44a9-9bd6-f741768e2b74","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"f7d36e28-29dc-4891-93f4-0a1745de1316","name":"Fo Accounts Lifecycle Dark","mediaType":"Image","url":"/media/u4sjkqnv/fo-accounts-lifecycle-dark.png","extension":"png","width":2400,"height":1400,"bytes":301619,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"46a0a2dd-34c8-4ab3-aba8-aef37653ffef","name":"Fo Accounts Lifecycle Light","mediaType":"Image","url":"/media/kjuon2fb/fo-accounts-lifecycle-light.png","extension":"png","width":2400,"height":1400,"bytes":298893,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"565519e1-6c28-4754-8828-3174f6225ffc","properties":{"sectionText":"Recording a transition"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"13d8f51b-5e85-44eb-92b7-2062df831d86","properties":{"text":"Moving an account between states is not a plain status edit. A transition captures the target status and a reason, and writes its own auditable record, readable individually or as a full history. That matters when you need to reconstruct why an account\u0027s access changed at a particular point."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ae294878-6518-43a4-9f02-dcfa8d153fb4","properties":{"sectionText":"Cascading to linked cards"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ef21568b-dd38-439b-a38f-76edc9c00716","properties":{"text":"A transition can optionally be applied to the account\u0027s linked cards in the same action, so putting an account on hold can put its cards on hold with it. The flag is optional and does not apply by default, which means an account transition on its own changes the account and leaves the cards as they were.\n\nThat is worth being deliberate about in both directions. Leaving it off keeps card states independent, which is what you want when the account change is administrative. Turning it on is the right call when the reason for the change is one that should reach everything the account funds, such as confirmed fraud.\n\nCards also have their own lifecycle, so a card can be in a state of its own regardless of the account above it. A cascade sets the cards\u0027 state at that moment; it does not bind them together afterwards."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"b6e87770-3a67-4832-b2ef-0903ab0d50a7","properties":{"sectionText":"Reading and adjusting balance"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"991ae904-0125-42bf-be6b-3c4d19d9694f","properties":{"text":"An account\u0027s balance read returns two figures, and the difference between them matters. The ledger balance is cleared, settled funds only. The available balance is what can actually be spent: the ledger balance less any pending transactions and holds. A cardholder-facing balance display wants the second, and reconciliation wants the first.\n\nAlongside that read, a balance adjustment is how you keep the balance on TXN\u0027s side in step with yours. The balance TXN holds is what every authorization is decided against, so it is the source of truth for whether a transaction is approved. It is not necessarily the cardholder\u0027s true balance: TXN sees card transactions, not transfers and other money movements happening elsewhere in your program. As funds move on your side you tell TXN what changed: set the balance to a figure, or increase or decrease it by an amount. This is routine operation, not an exception.\n"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"1cf1a31f-7168-4528-909e-3300e95f6def","properties":{"alertTitle":"The adjustment replaces the balance outright unless you explicitly ask it to increase or decrease.","alertContent":"An adjustment sent without that instruction overwrites the balance rather than moving it, which is rarely what you want when you are applying a movement that has already happened on your side. Always state the operation.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"6daf56db-73b3-442f-bd4e-4b9b1c510a81","properties":{"sectionText":"Updating an account"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"66926523-a691-484d-ae2e-a855c7e3bae2","properties":{"text":"Updating an account is a partial update, so fields you leave out are untouched and there is no need to send the record back whole. Status is the exception in the other direction: a PUT cannot change it. An account\u0027s status only moves through a transition, so that the change carries a reason and an audit record."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"b6c454b6-6e73-417c-938f-37c3ef33c5d8","properties":{"alertTitle":"The member list overwrites, it does not merge.","alertContent":"Account members are the exception to partial update. The list is an array, so whatever you send replaces the existing membership entirely and anyone not in it loses access to the account. Read the current members before you send a new list.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"65f85fd5-1e8d-4827-9e4d-fc68ac21024f","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"4a50e3df-26d5-400f-b2e9-05b45648668c","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"e0a3f96c-105e-4dc1-af2c-f4616419da22","properties":{"cardTitle":"Cardholders","cardText":"Who owns an account, and the full set of transition reasons.","pageLink":{"contentType":"guidePage","name":"Cardholders","createDate":"2026-09-16T06:22:18.73Z","updateDate":"2026-11-15T16:32:44.66Z","route":{"path":"/103/foundational-objects/cardholders/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"a615ed27-e2f2-4afe-b764-4fc583ef8f6c","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"4c849587-4497-4d22-8d57-2244100ae0d0","properties":{"cardTitle":"Cards","cardText":"What draws against an account, and how a card\u0027s own lifecycle differs.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"2f504341-f5b8-45ed-b243-b457625206c6","properties":{"cardTitle":"Delegated Approvals","cardText":"Running the model where you make the authorization decision.","pageLink":{"contentType":"guidePage","name":"How Delegated Approval Works","createDate":"2026-09-16T06:26:34.807Z","updateDate":"2026-11-15T16:32:47.123Z","route":{"path":"/103/delegated-approvals/how-delegated-approval-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"e47adf53-2c39-46bb-bb12-ff0c765b075c","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"16fa4bb6-d23c-486c-9581-9b30db5ddde1","properties":{"prevPageTitle":"Cardholder Groups","nextPageTitle":"Cards"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Rate Limits","createDate":"2026-11-14T09:22:41.343Z","updateDate":"2026-11-15T16:32:47.413Z","route":{"path":"/103/api-essentials/rate-limits/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"eaf38fec-bda3-49d6-be92-41e32f25e364","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"2c2f1216-6e02-415b-b16d-f7f890f1882e","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"c543ef9a-828d-40c6-a8c4-d046d88b9355","properties":{"title":"Rate Limits","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"27f507b1-71d9-454a-98fb-d258683373b1","properties":{"text":"TXN limits how many requests your integration can make in a given period. The limit protects the platform for everyone using it, and it is applied at the edge, before a request reaches the API."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"fbba7dcc-b5f2-43df-9266-dc516f6ed23b","properties":{"sectionText":"Why there is a limit"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"e3044ef3-31b0-4a2a-9982-d346a57f9ed2","properties":{"text":"A shared platform has to stay predictable for everyone on it. Rate limiting is how TXN stops one integration, whether through a genuine spike or a loop that got away, from degrading service for others. It also protects the platform against automated abuse. The limit is about sharing capacity. It has no bearing on who can see your data."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"bd486b1d-1b10-4cd2-9cc5-3808e5be781e","properties":{"sectionText":"How the limit is applied"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"1dd8a1b2-10b5-4071-a682-8fea0d47e1cb","properties":{"text":"Rate limiting is applied at the platform edge. A request that exceeds your limit is rejected before it reaches the API, so it has no effect on your Card Program and nothing is partially processed.\n\nThe limit applies to calls your integration makes to the Core API. Card authorizations from the card schemes do not count against it, so a rate-limited integration does not affect cardholders using their cards."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"7474f00e-e3ce-4ef5-b500-93f1dca5dad5","properties":{"alertTitle":"Your limit is shared by everything calling from the same address.","alertContent":"Requests are counted against the network address they originate from, not against your API credentials. If several services, workers or environments share one outbound IP address, they draw on a single allowance between them. Size your traffic against the total your address will generate, not against what any one service sends.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"fe0ca4c7-683f-47a9-9b71-ed15ef7e9c07","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"efe8cdc5-ae19-425b-985e-e27dd9772d9c","name":"Ae Rate Limits Where It Applies Dark","mediaType":"Image","url":"/media/jidl2wlq/ae-rate-limits-where-it-applies-dark.png","extension":"png","width":2400,"height":1200,"bytes":279951,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"9f3431e4-81dd-4c2f-81f5-ced221f666d9","name":"Ae Rate Limits Where It Applies Light","mediaType":"Image","url":"/media/np3heknu/ae-rate-limits-where-it-applies-light.png","extension":"png","width":2400,"height":1200,"bytes":277161,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4143ed0a-b102-4415-90c2-245cf06e35e4","properties":{"sectionText":"Reading your limit from a response"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b1089b5f-fa0f-4dff-9c06-56b3153bcd72","properties":{"text":"Responses carry headers stating the rate limit in force and the period it applies over. They are the authoritative statement of your limit, and they are the right thing to check if you are ever unsure what your integration is allowed.\n\nThese headers are fixed values. They tell you what the limit is. They do not tell you how much of it you have used, and there is no header reporting remaining requests or a reset time. A 429 does not carry a retry-after header either, so the length of the wait is yours to choose."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"c723f208-2b7b-4ed6-bd1e-6ec8292c3acd","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"c4df9d90-f420-4439-8707-22bb6a2201e7","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"6b296d80-eb80-4cd1-9b4c-076e8d107dda","properties":{"cellContent":"Header"}},"settings":null},{"content":{"contentType":"tableCell","id":"39b49a65-3c53-478b-8704-72d724694abc","properties":{"cellContent":"What it tells you"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"e79ffa2b-8f0a-4d1e-b4d9-46e15311dceb","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"8f2745ef-6bc9-4ada-b6d9-855b2658bf29","properties":{"cellContent":"x-rate-limit-limit"}},"settings":null},{"content":{"contentType":"tableCell","id":"b16fbe31-2339-40fe-a7c2-8cf1a2f7fdac","properties":{"cellContent":"The number of requests allowed in each window."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"945b8d1c-be60-48ee-ab2a-2936d86caa2b","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"86ce0a52-c531-4875-a57d-2c400445fd6a","properties":{"cellContent":"x-rate-limit-window"}},"settings":null},{"content":{"contentType":"tableCell","id":"60e12cf4-4e62-4f2d-bd7d-035045dcfec7","properties":{"cellContent":"The length of the window."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"d4045179-f003-42fb-b509-3dff1b5ed982","properties":{"sectionText":"When you go over"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3618e6ec-dda4-4286-bb64-dd7643113b0f","properties":{"text":"Requests over the limit are rejected with HTTP 429. Nothing is processed, so a rejected write has not partially happened and does not need unwinding.\n\nThe correct response is to stop, wait, and resume at a lower rate. Retrying immediately makes it worse: the retry consumes allowance you do not have, and a client that retries in a loop can keep itself locked out long after the original burst has passed."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"547971d1-3d41-4aec-bba0-a355ad3f6a2e","properties":{"alertTitle":"Do not retry a 429 immediately.","alertContent":"Back off before retrying, and increase the wait on each further failure. Add a small random delay so that multiple workers in your system do not all retry at the same instant. See Retries and Idempotency for the full pattern.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"9d61683b-e2ef-42b7-9de7-801f45598dc9","properties":{"sectionText":"Designing so you do not hit it"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"f4515f0c-f731-4200-9303-ebd2fa118486","properties":{"text":"Staying under the limit is mostly a matter of avoiding calls you do not need. Three things are worth checking.\n\n1. Polling for changes that have not happened. If you are checking an object every few seconds waiting for it to change, you are spending most of your allowance on responses that tell you nothing.\n\n2. Reading data you already have. Cardholder and product details change rarely. Cache them rather than fetching them again on every operation.\n\n3. Running bulk work at full speed. An import of ten thousand records does not need to finish in a minute. Pace it deliberately and it will finish without ever touching the limit.\n\nIf you expect sustained or bulk volumes beyond ordinary Card Program traffic, speak to TXN before you go live. The limit is set by TXN and can be reviewed."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"158de7ff-ac8f-41b2-b3ff-cbc37eb313dd","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"514b8538-72c4-4ccf-bb1e-ce8120f9582d","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"8cf060e6-301b-4f3c-924d-acdeb1c245d2","properties":{"cardTitle":"Retries and Idempotency","cardText":"How to back off after a 429, and how to repeat a write without creating it twice.","pageLink":{"contentType":"guidePage","name":"Retries and Idempotency","createDate":"2026-11-14T09:22:41.407Z","updateDate":"2026-11-15T16:32:39.84Z","route":{"path":"/103/api-essentials/retries-and-idempotency/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"182084cf-2e4d-406f-a1e4-9a1dcba5f19d","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"126402dc-5363-4813-92d3-eeeb22f6117a","properties":{"cardTitle":"Errors","cardText":"Every status the API returns, what each one means, and what to do about it.","pageLink":{"contentType":"guidePage","name":"Errors","createDate":"2026-11-14T09:22:41.277Z","updateDate":"2026-11-15T16:32:46.777Z","route":{"path":"/103/api-essentials/errors/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dba005b5-8d0e-48ba-84b2-85c6855f7c5e","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"92214726-0792-4f2e-a086-ea11e69bacf8","properties":{"cardTitle":"Requests and Responses","cardText":"The envelope, headers and pagination shared by every call.","pageLink":{"contentType":"guidePage","name":"Requests and Responses","createDate":"2026-11-14T09:22:41.207Z","updateDate":"2026-11-15T16:32:46.957Z","route":{"path":"/103/api-essentials/requests-and-responses/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dd68c2a5-1262-438b-adfb-f6bf84e3e336","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"3ab8385c-0b24-4c98-9123-88f7d6af2552","properties":{"prevPageTitle":"Error Code Reference","nextPageTitle":"Retries and Idempotency"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Transferring a Card","createDate":"2026-11-14T13:45:45.01Z","updateDate":"2026-11-15T16:32:41.157Z","route":{"path":"/103/managing-cards/transferring-a-card/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2bb52d5b-a405-4ca8-b3c0-13846ff1a92f","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"0cf61f36-b727-4fc9-9c83-4dfbdbf66e38","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"5e1e9d1f-39f4-49ea-8afa-ca8d88d2f271","properties":{"title":"Transferring a Card","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"1a49eda8-ee00-4494-a963-1669cb78103a","properties":{"text":"A card can move to a different cardholder without being reissued. The number stays, the account stays, the history stays, and nothing new is printed or posted."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"eccc7185-8bc2-4267-8f03-621864054b30","properties":{"text":"This exists for the situations where the card is fine and the person is not. Someone leaves and their card should pass to whoever takes the role. A card was issued against the wrong cardholder. A cardholder is being replaced rather than the card they hold. Reissuing in these cases would consume a card number, restart the history and put a new card in the post, none of which the situation calls for."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3342eb33-295b-47b5-83a0-29a115524dde","properties":{"sectionText":"How a transfer is done"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"c9206ad1-2fc8-46c5-93d9-d1299aac6a6d","properties":{"text":"Through the ordinary card update call, changing the cardholder the card is associated with. There is no dedicated transfer operation and nothing else in the request has to change. TXN validates that the card is eligible to move and that the new cardholder exists before making the change."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"b22c4331-af28-4355-a32e-39088c13bca7","properties":{"sectionText":"Only an active card can be transferred"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"0fe19b0a-7b65-49fa-8103-ec7e04154feb","properties":{"text":"The card has to be in an active state at the moment of the transfer. A card that is inactive, on hold or closed cannot be reassigned. That ordering matters more than it first appears, because the instinct when someone leaves is to stop the card immediately and work out what happens to it afterwards."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"c315d874-a076-455e-9990-3185a5682b19","properties":{"alertTitle":"Put the card on hold first and you cannot transfer it.","alertContent":"A transfer is only permitted on an active card, so the natural sequence of suspending a card when someone leaves and then reassigning it later does not work in that order. Either transfer first and apply whatever controls the new holder needs afterwards, or bring the card back to active before reassigning it. A closed card cannot be transferred at all, and cannot be reopened to allow it.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"5b8a35cd-e68e-44cf-9add-c5e83eecddb8","properties":{"sectionText":"What stays with the card"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"fdecbf69-da12-46d1-8f5b-c3496c566b9f","properties":{"text":"Everything except the cardholder. The card number, expiry and security code are untouched, so nothing has to be reprinted and the new holder has nothing to re-enter anywhere. The account the card draws on stays linked to it. The product it was issued against does not change, so its controls and behavior carry on exactly as before. Transaction history and lifecycle history stay attached to the card rather than following the previous cardholder. Your own attributes on the card remain as they were unless you change them yourself."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"18a80d8d-67e4-4087-8f5b-24290c648c3e","properties":{"alertTitle":"The account stays with the card, not the person.","alertContent":"Because the account linkage is preserved, the new cardholder spends against the same balance and the same history as the last one. That is usually exactly the point: the card is being handed on rather than reissued. Where it is not what you want, because this is a different person with a different budget rather than a successor in the same role, a new card is the right answer and a transfer is not.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"78f6d54a-3e90-4aae-a022-637c3a1a7e05","properties":{"sectionText":"Every transfer is logged in its own right"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"2c5c8df1-1bb2-4d7b-9dd4-673b95404660","properties":{"text":"The change of cardholder is written to the audit log as an event rather than left to be inferred from a differing value. Nothing in the card\u0027s existing account, transaction or lifecycle history is removed, altered or overwritten by the transfer. The record reads as one continuous card that changed hands, which is what makes the transfer defensible later."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"20f558da-0459-4de8-bf54-4eb3551efe82","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"03b4cf3c-0063-48ee-8a2d-2dfa6b918c78","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"1dbec99f-6db0-4fad-9c39-700e8d14641a","properties":{"cardTitle":"Cards","cardText":"What can and cannot be changed on a card after issuance.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"216fb79f-60c6-4069-92b9-871aebc2b2dc","properties":{"cardTitle":"Cardholders","cardText":"The record a card is being moved between.","pageLink":{"contentType":"guidePage","name":"Cardholders","createDate":"2026-09-16T06:22:18.73Z","updateDate":"2026-11-15T16:32:44.66Z","route":{"path":"/103/foundational-objects/cardholders/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"a615ed27-e2f2-4afe-b764-4fc583ef8f6c","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"f2a8d145-d346-403f-8514-5ac35be66620","properties":{"cardTitle":"Replacing a Card","cardText":"The other way to change who is holding a card, and when it is the right one.","pageLink":{"contentType":"guidePage","name":"Replacing a Card","createDate":"2026-11-14T13:45:44.953Z","updateDate":"2026-11-15T16:32:41.983Z","route":{"path":"/103/managing-cards/replacing-a-card/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2db9d6c2-7f22-452f-b105-e3f518240751","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"f4756a6c-ad6c-4d5c-bbe0-904b8114041e","properties":{"prevPageTitle":"Replacing a Card","nextPageTitle":"Card Expiry"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Your First Request","createDate":"2026-09-16T06:21:15.68Z","updateDate":"2026-11-15T16:32:41.837Z","route":{"path":"/103/getting-started/your-first-request/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2dac4688-011a-484f-b2d5-da68a0413646","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"28fc68df-7a8c-4ab9-9ff0-0594c27b03c3","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"8e8d670d-49c2-4122-b582-9fe9be06eabb","properties":{"title":"Your First Request","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"8274de0c-28ea-4b5e-a0c8-3ab3e309242f","properties":{"text":"The fastest way to understand an API is to call it once and look at what comes back. You can do that here and now, without credentials and without writing any code, because the Knowledge Hub calls the Public Sandbox for you. This guide takes you from nothing to a real response, and then to the smallest write flow that proves anything."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"db20f88f-40db-41f3-95f2-a223ec277f0c","properties":{"text":"Everything in this guide happens in the Public Sandbox, where nothing you create is real. You can work through all of it before you have an agreement with TXN, before you have credentials, and before you have written a line of code.\n\nFor the exact request shape, headers and status codes of any call, see the API Reference."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"3f0b5708-3a75-4d5d-a1f7-a713155febe3","properties":{"sectionText":"Make your first call"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"b2441561-9cf8-44ca-957b-9b258d31c279","properties":{"text":"Start with a read rather than a write. A list call needs nothing beyond the request itself, so it is the quickest way to confirm the whole loop works before anything more complicated is at stake. If a read fails, the problem is with the request rather than with the object you eventually want to create.\n\nOpen the API Reference, find the getAllAccounts operation, and switch from Reference to Playground. The Hub sends the call to the Public Sandbox and shows you what comes back."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"codeSnippet","id":"b4b1df56-95c5-4a52-a639-bad7a2af7ca5","properties":{"apiVersion":"1.0.3","apiCodeReference":"get:/accounts","snippetDisplayMode":"Request Only","snippetRespStatusCode":null,"hasResponse":true,"responseStatusCode":"200"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"4f05b547-a6eb-4198-bfeb-021fce4d5ddd","properties":{"text":"That is the same call written out. The Playground is the fastest way to see a response; the snippet is what the call looks like once you build it yourself."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e4b7d973-28be-439f-9dd5-09af3095f93b","properties":{"sectionText":"Reading what comes back"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"18ababa0-841e-4d7d-8a0f-7b3d7c44768c","properties":{"text":"Look past the data you asked for. Every response carries the same envelope whatever you called, so learning its shape once pays off on every call after this one.\n\nThe envelope echoes back the identifiers you sent, so you can confirm they arrived as intended, and adds identifiers and a timestamp of TXN\u0027s own. Alongside those sits either your result or a structured error.\n\nA list response carries its pagination alongside the data: how many records exist in total, which page you are looking at, how large a page is, and whether there is another one. That tells you whether you are seeing everything or only the first slice, which matters more than it sounds the first time a list comes back suspiciously short.\n\nRequests and Responses covers the full shape of the envelope and how pagination behaves across every call."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"f662114e-a358-45ed-8bf0-33e3880c44dd","properties":{"alertTitle":"A failed call still returns the envelope","alertContent":"An error is not an opaque failure. It comes back in the same envelope, with a structured error in place of the result, carrying a code, a description and the identifier of the call that produced it. Read it the same way you would read a successful response.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"bf507b80-d9a4-4320-b286-9790f6530b65","properties":{"sectionText":"A first write flow"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ecdaba66-5085-44b4-83a3-7c965977bb1d","properties":{"text":"A single write call proves an endpoint works. It does not prove the objects relate to each other properly, which is where integrations more often go wrong.\n\nThe smallest flow that proves something real is creating a cardholder, opening an account, then issuing a card against both. A card cannot exist until a cardholder, an account and a product all exist, so this chain exercises a dependency rather than an endpoint. Use a product that already exists rather than creating one: a product is program-wide configuration, not something to make per test.\n\nThe order is fixed by what each object depends on, not by convenience. Cardholder and account first, card last."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"b02c347b-01c7-4085-ae3b-fbb347eaa4fe","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"7f052c0b-ab1b-4257-9de2-1fffbb02fdfa","name":"Gs Your First Request First Write Flow Dark","mediaType":"Image","url":"/media/qttehsls/gs-your-first-request-first-write-flow-dark.png","extension":"png","width":2400,"height":1040,"bytes":198252,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"6a8a5aca-d04d-486e-82c7-1dd763a2751d","name":"Gs Your First Request First Write Flow Light","mediaType":"Image","url":"/media/iwimzxbe/gs-your-first-request-first-write-flow-light.png","extension":"png","width":2400,"height":1040,"bytes":194628,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"codeSnippet","id":"961b067f-3fca-4321-b1a5-cdc41812ca8a","properties":{"apiVersion":"1.0.3","apiCodeReference":"post:/cardholders","snippetDisplayMode":"Request Only","snippetRespStatusCode":null,"hasResponse":true,"responseStatusCode":"201"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"e0cc820f-78f9-4c9c-8c6f-5a7b1a990703","properties":{"text":"Keep the request identifier from each write call. If something looks wrong when you inspect the result, that identifier is what lets TXN find the exact call rather than you having to describe it afterwards. Set the same correlation identifier across all three, and the whole flow can be traced as one unit rather than three calls that are related only in your own notes.\n\nNone of this needs to become permanent tooling yet. The point is to prove the dependency and the tracing both work, not to build a production client in one sitting."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"0c17128c-4fa9-41f4-a5ba-26bb429d4520","properties":{"sectionText":"Moving to your own code"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"338213ed-ae10-433b-8427-a8e0104272f3","properties":{"text":"The Playground is the Hub calling the Public Sandbox on your behalf. It is the right tool for seeing responses and getting the shape of things in front of you. It is not a route to building against.\n\nWriting your own client means moving to UAT, which becomes available during commercial onboarding. At that point you create credentials in Control Center, and the address for that environment is issued alongside them.\n\nEverything you learned in the Playground still holds: the same envelope, the same identifiers, the same object dependencies in the same order. What changes is that your code now handles authentication itself. Authentication covers the token exchange and the headers every call carries, and the SDK handles the token lifecycle if you would rather not write that yourself."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"2e0e077d-ee52-4be6-952f-88b09f6f3ebd","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"3a0db5a7-ef93-45de-83d4-e5c4d55248a8","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"73bbf186-bf6b-4f75-abf4-f23251ba287b","properties":{"cardTitle":"Requests and Responses","cardText":"The shape of the envelope every call returns, and how pagination behaves.","pageLink":{"contentType":"guidePage","name":"Requests and Responses","createDate":"2026-11-14T09:22:41.207Z","updateDate":"2026-11-15T16:32:46.957Z","route":{"path":"/103/api-essentials/requests-and-responses/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dd68c2a5-1262-438b-adfb-f6bf84e3e336","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"c1ed4113-6c95-42ca-a6f9-525566dedd2d","properties":{"cardTitle":"Authentication","cardText":"How your integration authenticates once credentials are issued.","pageLink":{"contentType":"guidePage","name":"Authentication","createDate":"2026-09-16T06:20:42.913Z","updateDate":"2026-11-15T16:32:43.17Z","route":{"path":"/103/getting-started/authentication/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"56e49f8f-4cd4-44d1-acca-d5cda1431fc6","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"5ea9b63f-1c9a-487a-bfd3-3b2496fdd9b7","properties":{"cardTitle":"Cardholders","cardText":"The first object in the write flow, and what creating one captures.","pageLink":{"contentType":"guidePage","name":"Cardholders","createDate":"2026-09-16T06:22:18.73Z","updateDate":"2026-11-15T16:32:44.66Z","route":{"path":"/103/foundational-objects/cardholders/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"a615ed27-e2f2-4afe-b764-4fc583ef8f6c","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"07f7d8ee-528d-40e4-87a6-7665ebdf5de5","properties":{"prevPageTitle":"Environments","nextPageTitle":"Authentication"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Trusted Merchants","createDate":"2026-09-16T06:24:40.2Z","updateDate":"2026-11-15T16:32:39.053Z","route":{"path":"/103/authentication-sca/trusted-merchants/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"09bbc81a-17c3-429c-b340-e9ec7579ee78","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"6f228cc5-60a1-4a4e-9fec-0ac4acd88fec","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"1328a152-3e68-4bb4-b7a1-74fe1d9c7be2","properties":{"title":"Trusted Merchants","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"6573e87b-c551-49cd-b2c6-6c0300362aa7","properties":{"text":"Strong customer authentication protects a cardholder, but challenging them at the same merchant every time is friction they will not thank you for. A trusted merchant is how that repetition is avoided: once a cardholder has authenticated successfully at a merchant, that merchant can be recorded as trusted for their card, and later transactions there can be exempt from another challenge."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e7b81e1c-6a14-4bdd-bcc2-1a4261eca9fd","properties":{"sectionText":"A card-level relationship, established by authentication"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"e07decdf-8414-4ef7-93dd-fefd2dc1bb7b","properties":{"text":"A trusted merchant record ties one card to one merchant, naming the merchant and carrying a reference to the 3-D Secure authentication that established the relationship. That reference is the substance of the record: the trust exists because the cardholder proved who they were at that merchant, not because someone added an entry to a list.\n\nThis is a cardholder-experience feature rather than a risk-control one. Its purpose is to let a returning customer through without a second challenge at a merchant they have already been verified at."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertAlternative","id":"06899b14-3215-432e-904b-10f3c0af55d6","properties":{"alertTitle":null,"alertContent":"Note: A trusted merchant is scoped to a single card. It is not inherited by a replacement card, and it does not extend to the cardholder\u0027s other cards. Reissuing a card means the relationship has to be established again.","severity":"general info "}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"5c21d132-ce29-4811-8ac0-55a98810369f","properties":{"sectionText":"Trusted merchants and merchant controls are different mechanisms"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"4432fb03-e781-4ba4-95b9-b00cb604bb70","properties":{"text":"The names invite confusion, so it is worth being blunt about the distinction.\n\nA merchant control decides whether a transaction is allowed. A trusted merchant decides whether the cardholder has to authenticate again. They act at different points and answer different questions."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertAlternative","id":"5ba66d36-0b68-4abc-8872-aa63276c97ab","properties":{"alertTitle":null,"alertContent":"Warning: Marking a merchant as trusted does not override a merchant control. Authentication and authorization are separate checks. A trusted merchant skips the challenge and arrives at authorization as exempt, but a merchant control can still decline the transaction. A merchant your controls block stays blocked whether or not it is trusted. Do not reach for a trusted merchant as a way to let a blocked merchant through.","severity":"warning"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"40cccd62-9d54-42df-a14d-d94d14e4c6bc","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"01eedb30-4981-404b-aeae-d7a3f48e4026","name":"Sca Trusted Merchants Flow Dark","mediaType":"Image","url":"/media/x2ilrn5i/sca-trusted-merchants-flow-dark.png","extension":"png","width":2400,"height":830,"bytes":206340,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"66a8f4ad-f4cb-43fa-ac81-43b23eaea479","name":"Sca Trusted Merchants Flow Light","mediaType":"Image","url":"/media/ei5o3ufc/sca-trusted-merchants-flow-light.png","extension":"png","width":2400,"height":830,"bytes":203286,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"7637e740-e6ff-4992-ab6c-d1fee0cd8968","properties":{"sectionText":"How trusted merchants relate to other objects"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"45189078-819a-4f97-8c12-9469a2429e6c","properties":{"text":"A trusted merchant belongs to a card and points back at a 3-D Secure authentication event. Removing one deletes the record outright."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"030e9164-037a-4012-8aa2-57fc22a27c11","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"8a6114f3-e8c6-44b9-a48d-f879c18c54b6","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"3947e606-f5b6-4aa2-a5e6-a40bffbcd533","properties":{"cardTitle":"3-D Secure","cardText":"The authentication that establishes the relationship in the first place.","pageLink":{"contentType":"guidePage","name":"3-D Secure","createDate":"2026-09-16T06:24:47.867Z","updateDate":"2026-11-15T16:32:41.32Z","route":{"path":"/103/authentication-sca/3-d-secure/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2c14bfed-9803-44c3-a57c-6105c8c6131d","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"dea4810c-7757-4235-8c6b-a62f62aa7cb8","properties":{"cardTitle":"Merchant Controls","cardText":"Deciding whether a merchant is allowed at all, which is a separate question.","pageLink":{"contentType":"guidePage","name":"Merchant Controls","createDate":"2026-09-16T06:24:31.46Z","updateDate":"2026-11-15T16:32:42.82Z","route":{"path":"/103/card-controls/merchant-controls/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"51fd9837-c394-466d-8bcf-b1b71c811da2","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"f7f05e35-6825-4e13-85cc-68a165dd95e8","properties":{"cardTitle":"Strong Customer Authentication","cardText":"Why the challenge exists, and when a payment is exempt from it.","pageLink":{"contentType":"guidePage","name":"Strong Customer Authentication","createDate":"2026-09-18T11:31:11.723Z","updateDate":"2026-11-15T16:32:43.757Z","route":{"path":"/103/authentication-sca/strong-customer-authentication/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"6f1882ed-93f8-4f26-9cb9-b6b8a47e85b3","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"9beef1b7-f007-4908-b20a-996ec4f0fed2","properties":{"prevPageTitle":"3-D Secure","nextPageTitle":"Address Verification (AVS)"}},"settings":null}},"cultures":{}},{"contentType":"baseGuidePage","name":"API Essentials","createDate":"2026-11-14T09:22:41.083Z","updateDate":"2026-11-15T16:32:39.72Z","route":{"path":"/103/api-essentials/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"c9e56fe8-9ee8-45b7-a847-0b02feafa8ff","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"02031e36-05d4-47c9-8d5b-99c36e8b9684","name":"Api Essentials","mediaType":"umbracoMediaVectorGraphics","url":"/media/ysrldygp/api-essentials.svg","extension":"svg","width":null,"height":null,"bytes":8101,"properties":{}}]},"cultures":{}},{"contentType":"changelog","name":"Changelog","createDate":"2026-05-25T12:38:22Z","updateDate":"2026-11-14T06:23:07.26Z","route":{"path":"/","queryString":null,"startItem":{"id":"057f5aad-b705-4e19-ac80-136708268fd2","path":"changelog"}},"id":"057f5aad-b705-4e19-ac80-136708268fd2","properties":{"changelogTimelineContent":{"items":[{"content":{"contentType":"changeCardTimeline","id":"3e87e1ff-8393-4b96-aefa-8c072325a90f","properties":{"dateChanged":"2026-11-13T09:00:00","changeType":"Shipped","category":"API","versionNumber":"v1.0.3","cardTitle":"TXN 1.0.3: initial release","cardSummary":"TXN is the issuer-processor platform for building and running a Card Program. This is the first general release. It brings the Core API, the Knowledge Hub that documents it and a Public Sandbox to try it in, all on one platform.","endpointType":null,"affectedEndpoint":null,"changes":"- Foundational objects: cardholders, accounts, products and cards, all held inside a Card Program\n- Card controls: spend controls, merchant controls and spend overrides\n- Cardholder verification\n- Authentication, including Strong Customer Authentication and 3-D Secure\n- Digital wallet tokens\n- Delegated Approvals, with Stand-In rules for when your own systems cannot be reached\n- Card lifecycle transitions, each with a reason and an audit record\n- Money movement and balances\n- Keeping your records in step with TXN\n- A Go-Live Checklist to prepare for launch","changeLink":null,"attachedGuide":null,"image":null,"alertTitle":null,"alertText":null}},"settings":null}]},"changelogUpcomingContent":{"items":[{"content":{"contentType":"changelogCardUpcoming","id":"33ccbb2b-c289-4720-a069-da52422e72a0","properties":{"topic":"API","cardTitle":"Additional APIs for managing Card Programs","cardSummary":"We are extending the platform with further APIs for managing Card Programs and the entities beneath them. They will build on the Core API you use today. We will publish the detail, and the guides to go with it, as each part is released.","datePosted":"2026-11-13","externalLink":null}},"settings":null}]}},"cultures":{}},{"contentType":"guidePage","name":"Authentication","createDate":"2026-09-16T06:20:42.913Z","updateDate":"2026-11-15T16:32:43.17Z","route":{"path":"/103/getting-started/authentication/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"56e49f8f-4cd4-44d1-acca-d5cda1431fc6","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"03a88758-dece-4046-870b-58c6f13e6c3a","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"4f0e7f63-40c5-4825-be3b-85c0fe7adaad","properties":{"title":"Authentication","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"6f8fb2df-f9df-4a9c-b48d-8a0fdbd90970","properties":{"text":"Every request to the Core API carries a short-lived access token that proves who is calling. You do not send your credentials on each call. Your application exchanges them for a token, requests a new one as it expires, and sends the token instead. It is more setup than a plain API key, and much harder to leak something lasting."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"a4e8abce-0a16-4886-8f69-4cefc26e54f0","properties":{"text":"Your credentials are yours to create and manage in Control Center. They do not expire on their own, you rotate them when you choose to, and TXN can revoke them if they need to be stopped.\n\nThe Public Sandbox is the exception to all of this. You can use it from the Knowledge Hub without credentials or tokens, so nothing here stops you trying the API first.\n\nFor the full request and response schema of any operation, see the API Reference."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"a801d36d-6e97-4794-a7f7-1f786f1a2f87","properties":{"sectionText":"How authentication works"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"33750020-4991-4656-81e8-a6c1e9313b79","properties":{"text":"Authentication happens in two stages. Your credentials are long-lived and never travel with an API call. What travels is a short-lived access token you obtain using them.\n\n1. Create your credentials in Control Center.\n2. Use them to request an access token from the token endpoint. Your credentials determine which Card Program the token is for, so every call made with it goes to that Card Program.\n3. Send the access token with every call you make.\n4. When the access token expires, request a new one."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"089fee3b-bc93-4719-8ddb-a6fcf8460cd1","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"60071e34-f005-4d55-a4c5-6264e9019de2","name":"Gs Authentication Token Flow Dark","mediaType":"Image","url":"/media/xpkedvtm/gs-authentication-token-flow-dark.png","extension":"png","width":2400,"height":1000,"bytes":232680,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"af22754a-7a0e-489e-a056-de4a670523bc","name":"Gs Authentication Token Flow Light","mediaType":"Image","url":"/media/yw5higlh/gs-authentication-token-flow-light.png","extension":"png","width":2400,"height":1000,"bytes":230109,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"1dae8082-fbd2-4c8f-ac8c-4ab46d1b6bf3","properties":{"text":"The access token is deliberately short-lived, so one that leaks stops being useful quickly. When it expires you request a new one, so a token is only ever as old as its lifetime allows.\n\nTXN provides an SDK that handles this whole cycle for you: obtaining the first token, attaching it to each call, and renewing it before it expires. It is the recommended path, and you can download it from the [Resources](/resources) page. With the SDK you do not need to write any token handling yourself.\n\nThe token endpoint is available directly if you would rather manage it yourself. That is worth doing if you already have a token-handling layer, or you are working in a language the SDK does not cover. You take on renewing before expiry, and handling the case where a call is made with a token that has already expired."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"d7c5f84a-ae43-4c87-b7fe-2ee2c72ca4f2","properties":{"alertTitle":"Reuse the token until it expires","alertContent":"An access token is good for many calls. Requesting a fresh one on every request adds a round trip to everything you do, and it is easy to do by accident in a hand-rolled integration. Hold the token and request a new one only when it is close to expiring.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"8c78eaac-1b59-49d9-8d59-1c1716832a05","properties":{"sectionText":"Creating and managing your credentials"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"321772dc-6a3e-4db0-b227-c055304d98a8","properties":{"text":"You create credentials yourself in Control Center, for each environment you have access to.\n\nYou can hold more than one set at a time, and each set can be scoped to a subset of what the API can do. That is worth using rather than treating as an advanced feature. A credential used by a reporting job that only ever reads does not need permission to issue cards, and scoping it that way limits what a mistake or a leak can reach.\n\nCredentials do not expire on their own. Rotation is yours to initiate when you decide it is time, so you can plan it rather than react to an expiry you did not choose. TXN can revoke a credential, which is the route when one is compromised and needs stopping immediately."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"83b6fd9d-f0b2-4dae-8b69-c24dfbafdc1c","properties":{"sectionText":"What every call carries"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"codeSnippet","id":"08119e8e-9052-4306-8db5-231242ae7b9e","properties":{"apiVersion":"1.0.3","apiCodeReference":"get:/cardholders","snippetDisplayMode":"Request Only","snippetRespStatusCode":null,"hasResponse":false,"responseStatusCode":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"4ea5c4d1-d8ad-455e-a49c-cd2e2bf4f253","properties":{"text":"Every call carries your access token in the authorization header, sent as a bearer token. The other headers every call carries, including the request and correlation identifiers and the API version, are listed in Requests and Responses.\n\nThe version header is required on every call, not something to think about only before a release. Versions and Changes covers how breaking changes are communicated; what matters here is that every request declares the version it was built against."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"68519511-26b0-4d38-a127-8001805e28b5","properties":{"sectionText":"Keeping credentials safe"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"0091a17b-8f0b-42f9-a944-ec39b33dba3e","properties":{"text":"The token and the credential need different levels of care, and it is the credential that matters.\n\nAn access token is short-lived by design. One that leaks stops working shortly afterwards, which is most of the reason the model is built this way.\n\nA credential does not expire. One that leaks keeps working until somebody notices and revokes it, and in the meantime it lets another party make calls that look exactly like yours: creating cardholders, issuing cards and moving money in your program\u0027s name. Keep credentials server-side. They should never appear in client-side code, in a repository, or in anything that ships to an end user\u0027s device.\n\nThat holds in every environment, including the Public Sandbox. It is tempting to be looser where nothing is real, but a leaked sandbox credential still lets someone generate activity under your program, and the habits formed in the sandbox are the ones that reach production."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"12f7edfd-1022-421b-a480-6c4dcd87d83c","properties":{"alertTitle":"Revoke first, investigate afterwards","alertContent":"If a credential may have leaked, revoke it in Control Center before working out what happened. A credential does not expire on its own, so until it is revoked it keeps working. Rotating to a new credential is quick; undoing calls made with a leaked one is not.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"b1854ba9-90d9-44ae-af9b-182192eeebc9","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"5806f7cf-9aca-4035-884e-1fbdd065c648","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"51d33e5a-420c-4325-a0dd-8596095f51df","properties":{"cardTitle":"Your First Request","cardText":"Making a first call in the Public Sandbox, before you have credentials.","pageLink":{"contentType":"guidePage","name":"Your First Request","createDate":"2026-09-16T06:21:15.68Z","updateDate":"2026-11-15T16:32:41.837Z","route":{"path":"/103/getting-started/your-first-request/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2dac4688-011a-484f-b2d5-da68a0413646","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"e99af906-c646-4b09-a2f3-bcbb77f41f56","properties":{"cardTitle":"Requests and Responses","cardText":"Where the request and correlation identifiers show up in every response.","pageLink":{"contentType":"guidePage","name":"Requests and Responses","createDate":"2026-11-14T09:22:41.207Z","updateDate":"2026-11-15T16:32:46.957Z","route":{"path":"/103/api-essentials/requests-and-responses/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dd68c2a5-1262-438b-adfb-f6bf84e3e336","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"174da7c2-5ff0-4f38-9368-44160b9b9c56","properties":{"cardTitle":"Go-Live Checklist","cardText":"Making sure your credentials and configuration are genuinely production.","pageLink":{"contentType":"guidePage","name":"Go-Live Checklist","createDate":"2026-09-16T11:15:47.56Z","updateDate":"2026-11-15T16:32:39.463Z","route":{"path":"/103/going-live/go-live-checklist/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"12248e91-a4b4-4166-aa39-5c888cb4f7dc","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"ba0a492c-de0a-4e13-805c-e14b5a94dc46","properties":{"prevPageTitle":"Your First Request","nextPageTitle":"Control Center"}},"settings":null}},"cultures":{}},{"contentType":"baseGuidePage","name":"Foundational Objects","createDate":"2026-09-16T06:22:01.247Z","updateDate":"2026-11-15T16:32:41.463Z","route":{"path":"/103/foundational-objects/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"ae1da7ac-d0c3-4f0e-8906-2609acafc2ac","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"d6293163-bdbf-4568-87a9-4873da6257aa","name":"Foundational Objects","mediaType":"umbracoMediaVectorGraphics","url":"/media/sggiwnfe/foundational-objects.svg","extension":"svg","width":null,"height":null,"bytes":8132,"properties":{}}]},"cultures":{}},{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"581cb1b3-4351-4376-9a9a-abd45ecc7971","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"ddcdddf2-f0c6-4c42-a4be-f2fbcc3d0eee","properties":{"title":"Cards","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"138931b0-5a89-4752-9149-710943e3b6a0","properties":{"text":"A card is what a cardholder actually uses to pay: a physical card that can be swiped or tapped, or a virtual card living in an app or a digital wallet. Either form represents the same underlying spending instrument, drawing against the same account."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"33cc3fd5-7a54-41b6-bc24-6641070cf031","properties":{"text":"On TXN, a card is issued against a cardholder, an account and a product, and takes most of its behavior from the product referenced at issuance. It also carries a set of transaction controls of its own."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"c39bf279-0358-4650-bb96-8d63a8628029","properties":{"sectionText":"What a card needs before it can exist"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"8ebe0a0b-04de-4d98-87de-e32504063fdf","properties":{"text":"Issuing a card requires its cardholder, its account and its product to already exist, since a card is fundamentally a reference to all three: the cardholder it belongs to, the account its spending draws against, and the product supplying its behavior. A card has nothing to inherit behavior from without a product, nothing to belong to without a cardholder, and nothing to draw funds from without an account.\n\nCreating one also means declaring which type it is. Anything physical needs fulfillment details. Addresses resolve in order, taking the card\u0027s own if you supply one and otherwise falling back to the cardholder\u0027s and upwards from there, so you only set an address on the card when it differs from the one already held."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ebd7ae47-d47d-43ed-b2f5-19ae80359157","properties":{"sectionText":"Three card types"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"9920bf35-3b06-4332-bca3-638581a7c50b","properties":{"text":"A card is issued as one of three types, and the type is fixed for the life of the card. Changing form factor means issuing a new card, not updating the existing one.\n\nThe one exception runs in a single direction: a virtual card can be given physical fulfillment later, through a dedicated operation, without being reissued. A physical card cannot become virtual."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"19d9502b-e313-4545-953c-c0a1604f1788","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"b6584aba-3a90-495a-ac62-5b14390ce809","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"6baab663-9e63-4fe2-bfaa-3013cee02f71","properties":{"cellContent":"Type"}},"settings":null},{"content":{"contentType":"tableCell","id":"5eda83ae-7555-43b6-8c33-65527f3092b8","properties":{"cellContent":"What it is"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"8bbb7bff-d857-4704-a661-7da1409ace0f","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"3e6ed6b2-5892-463d-8693-e172fe721f00","properties":{"cellContent":"Virtual"}},"settings":null},{"content":{"contentType":"tableCell","id":"221ee223-4037-4fa2-8a07-94b832e113e8","properties":{"cellContent":"A complete, usable card with no physical form. Not a lesser version of a physical card."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"b9128e03-1d2f-4c27-a22e-a30bb34a8728","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"2111775d-b605-459f-bc14-aecef4ad4851","properties":{"cellContent":"Physical"}},"settings":null},{"content":{"contentType":"tableCell","id":"f19ffcc8-6be5-4dac-9f18-3a7a48b182c6","properties":{"cellContent":"A card that is manufactured and shipped, with fulfillment details attached."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"7e6da6c3-aeab-4bc3-9d55-1aa88ccef51b","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"bfc9ad58-9f06-4d44-b8a7-25d2fe61a57c","properties":{"cellContent":"Single-use virtual"}},"settings":null},{"content":{"contentType":"tableCell","id":"114f1f07-bec5-455a-a568-7c536511403a","properties":{"cellContent":"A disposable virtual card intended for one transaction."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"83ec72ad-c226-4ef2-84cb-0a477f95bf2e","properties":{"sectionText":"Getting a card into use"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"c964578a-3caa-40e3-9121-b02342e24b73","properties":{"text":"A card is created inactive and cannot transact until it is activated. Whether that happens on its own is a product decision. A product can auto-activate cards at issuance, which suits a virtual card the cardholder is expected to use immediately. Left to activate manually, the card waits until you transition it, which is the right model for a physical card that should not work until it is in the cardholder\u0027s hands.\n\nActivation can also be scheduled, so a card becomes active at a date and time you set rather than at the moment you call."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"d94efd3e-88a0-4c61-8517-889a10979a6a","properties":{"sectionText":"Where a card\u0027s behavior comes from"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"32a5e114-f936-446c-b38c-9ce5c7642985","properties":{"text":"Most of a card\u0027s behavior comes from its product, which is what makes two cards issued under the same product behave alike. The exception is the card\u0027s own transaction controls: nine toggles deciding which kinds of transaction it will accept, covering online, chip, contactless, ATM withdrawal, mail and telephone order, quasi-cash, account funding, original credit and cashback.\n\nAny control you do not set when you issue the card takes its value from the product. A card is not permissive by default; it inherits whatever the product allows, and you set a control on the card only to depart from that.\n\nThese controls can be changed at any time after issuance, and a change applies from the next transaction TXN receives for that card. There is no propagation delay and no need to reissue."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"831a5394-bb31-4520-a915-159db5e4c08e","properties":{"sectionText":"What you can change after issuance"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"acc2dccd-88f6-4717-b21f-6072124ced4f","properties":{"text":"A card can be updated, but only in part. The split is deliberate: anything that would make it a different card is fixed, and everything operational is open.\n\nReassigning a card to a different cardholder is allowed and is not a reissue. The card keeps its number, its full transaction history and its configuration, and the ownership change is captured in an audit record of its own. The cardholder does not receive a new card."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"4ad5f3d1-68b3-49a4-98d3-2906afc24214","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"d8744d96-2bbb-462a-bf83-92b374738c84","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"bd85c1d6-50ca-469f-9e2b-edf040af1759","properties":{"cellContent":"Can be changed"}},"settings":null},{"content":{"contentType":"tableCell","id":"07c5e653-2a32-4b78-bffe-fd7022d16a5b","properties":{"cellContent":"Fixed for the life of the card"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"24012016-adc6-4897-8a63-ba594c6251b1","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"31380d65-02e2-46bf-9ec8-62fc6a7f3988","properties":{"cellContent":"The transaction controls"}},"settings":null},{"content":{"contentType":"tableCell","id":"9274c5a9-4f53-4e1f-9781-84d23774bebe","properties":{"cellContent":"The card type"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"4e91dc44-22bd-43db-84ad-42b37a8195cb","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"cf3ddade-606b-482a-8239-199ffb48206d","properties":{"cellContent":"The cardholder it belongs to"}},"settings":null},{"content":{"contentType":"tableCell","id":"a6ff4e60-3da7-46b8-a926-be40abad0b57","properties":{"cellContent":"The product it was issued against"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"fdf8cb08-94eb-4ebc-b9e6-c7778bcaa83c","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"04e15a94-0441-4095-a91a-237a6bdedaf3","properties":{"cellContent":"Your own attributes on the card"}},"settings":null},{"content":{"contentType":"tableCell","id":"51b727e1-cb74-4193-af27-3aeeb2956bf6","properties":{"cellContent":"The card number, cvv and expiry"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"0a1545fd-5101-4502-a351-cfd49c64ced3","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"597dabb2-3cca-4d36-bee8-adc82335c675","properties":{"cellContent":"Physical fulfillment details, while the order is still with TXN"}},"settings":null},{"content":{"contentType":"tableCell","id":"4106335c-1d9e-4dc0-b8ec-eb353cf095a3","properties":{"cellContent":"Its status, which moves only through a transition"}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"a0bbe911-9030-4e7b-bbb7-9d620f08e77f","properties":{"text":"Card status governs whether a card can transact, not whether its record can be edited. An inactive or on-hold card can still be updated. Only a closed card is locked.\n\nPhysical fulfillment is the one field group with a time limit rather than a rule. Shipping and fulfillment details can be corrected while the order is still with TXN, and are locked once it has gone to the provider, because the card is by then already being made. Check the order status before assuming a correction will land."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"bc0eb348-62ca-4573-b24d-3b32ad216322","properties":{"sectionText":"Issuing a replacement"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"1c51a07a-2aae-4092-8c6c-42a8361e9f05","properties":{"text":"When a card is lost, stolen, damaged or expiring, a replacement is issued as a new card that names the original as its source. There is no separate reissue operation to call: a replacement goes through the ordinary card creation call, with the source card named in its issuance settings. You choose whether issuing it closes the original in the same action or leaves both live.\n\nWhether the replacement keeps the card number is not a free choice. A card reported lost or stolen must be replaced with a new number, because the old one is compromised. A card replaced for damage can keep its number, which spares the cardholder re-entering it everywhere they have stored it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4e2b913a-bb1f-4a58-b8cf-94028cc31d82","properties":{"sectionText":"The card lifecycle"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"29088f2b-d63d-4fa0-b802-16ac0fb7edf2","properties":{"text":"A card moves through four states: inactive, active, on hold and closed. Inactive is where it starts. Active and on hold are reversible in both directions. Closed is not.\n\nUnlike accounts, cardholders and groups, which share one set of transition reasons, a card has its own. Reading it tells you what a card\u0027s lifecycle actually tracks: most of these are physical events or things a cardholder reports, which the shared set has no way to express."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"09f22cb9-51e7-4752-8ed4-c8996cd77111","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"33118017-065b-4072-bf8e-0f23426fa983","name":"Fo Cards Lifecycle Dark","mediaType":"Image","url":"/media/tbffpbjs/fo-cards-lifecycle-dark.png","extension":"png","width":2400,"height":1332,"bytes":154252,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"a10a34ff-2a53-4d9f-864b-43467bb7fc4b","name":"Fo Cards Lifecycle Light","mediaType":"Image","url":"/media/od5eyfz0/fo-cards-lifecycle-light.png","extension":"png","width":2400,"height":1332,"bytes":153892,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"cc2c14cb-01a7-439b-8794-b3085bb81bb7","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"0fce4f89-4572-4a13-b97d-f082d4d394c7","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"22cc6851-36d1-4917-8105-c492b9f37251","properties":{"cellContent":"Card transition reason"}},"settings":null},{"content":{"contentType":"tableCell","id":"86f622d9-af2d-4db6-bf7d-9e863764e02a","properties":{"cellContent":"When it applies"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"8551f58f-fd06-4cbc-89c4-3d0f41b8b394","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"8430a1d6-680c-4d2e-845f-87d0a492cb50","properties":{"cellContent":"FIRST_TIME_ACTIVATION"}},"settings":null},{"content":{"contentType":"tableCell","id":"23391d12-d4ad-466e-be91-6b7350c95686","properties":{"cellContent":"The cardholder is activating a newly issued card."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"9d71e50b-a033-47de-b83e-71c950b6ce0c","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"e9124d37-f282-472d-a2b5-d307a1ca5be3","properties":{"cellContent":"USER_REQUESTED"}},"settings":null},{"content":{"contentType":"tableCell","id":"fc8204a7-ebc5-4eae-abb9-b86d0c2af3fc","properties":{"cellContent":"The cardholder asked for the change."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"9e1ca418-3388-4575-8858-13f7569e9ecc","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"f0b297e9-c4fb-4c43-b1a9-c1f99b043824","properties":{"cellContent":"CARD_UNBLOCK_REQUESTED"}},"settings":null},{"content":{"contentType":"tableCell","id":"d1c0d12c-8dac-4b9c-8d05-8b1105f8d486","properties":{"cellContent":"The cardholder has asked for a blocked card to be released."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"6e31f746-c827-4055-9cde-46b5f41d17b7","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ef2c4b7d-3f71-40f8-9f78-b052782c0843","properties":{"cellContent":"REPORTED_LOST"}},"settings":null},{"content":{"contentType":"tableCell","id":"aa1c075b-8610-4eb3-8091-efc9e090f6bb","properties":{"cellContent":"The cardholder has reported the card lost."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"4736eac8-7e70-4c70-ac4b-0d89d27f4461","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"639dc639-42a9-489d-913e-e6f4283899c5","properties":{"cellContent":"REPORTED_STOLEN"}},"settings":null},{"content":{"contentType":"tableCell","id":"3bbf1219-45dc-4744-9f2a-29492cc608df","properties":{"cellContent":"The cardholder has reported the card stolen."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"42e3cb4c-ba95-4a3f-8853-21766da0ed50","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"6c92c19a-c1c9-4f89-a5eb-f08fc9b241e6","properties":{"cellContent":"CARD_NOT_RECEIVED"}},"settings":null},{"content":{"contentType":"tableCell","id":"9ca90d7c-b390-487f-b05e-6fe50b4a3140","properties":{"cellContent":"A physical card never arrived."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"482d77fb-1621-489b-a881-bf0da9f1b634","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"61845d45-17a0-4acf-8d6e-b5e86728114e","properties":{"cellContent":"CARD_DAMAGED"}},"settings":null},{"content":{"contentType":"tableCell","id":"4867eaf7-79f5-4bb1-a34c-f9dd0b5454e7","properties":{"cellContent":"The card is physically unusable."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"e121a47c-b7fd-436c-94b8-4aab0df2a089","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"45953e47-091e-42a2-aa79-2a9ec93661a5","properties":{"cellContent":"CARD_EXPIRED"}},"settings":null},{"content":{"contentType":"tableCell","id":"da696862-294d-491a-906a-addbebb5141c","properties":{"cellContent":"The card has passed its expiry date."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"503c19bf-af38-464e-babb-d12709a7e899","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ad5a231a-e1fd-405f-b500-4694958fc88f","properties":{"cellContent":"PIN_RETRY_LIMIT_REACHED"}},"settings":null},{"content":{"contentType":"tableCell","id":"29400272-7c4c-4fe9-84d3-ed53bb76bec8","properties":{"cellContent":"The PIN has been entered incorrectly too many times."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"b0005263-d7fb-48ae-82c5-b1a9c80aa886","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"396d61e2-b8d8-46e8-a114-fc0da7c82f02","properties":{"cellContent":"SUSPICIOUS_ACTIVITY"}},"settings":null},{"content":{"contentType":"tableCell","id":"ceb6f5bf-4ceb-4bda-b040-90f62b6f7d8a","properties":{"cellContent":"Behavior has been flagged but not confirmed as fraud."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"4cc34714-10ef-4d3c-89a7-e99ff834cd55","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"4c4c17d1-451b-4c40-ac4f-3c93a0942e9a","properties":{"cellContent":"CONFIRMED_FRAUD"}},"settings":null},{"content":{"contentType":"tableCell","id":"e5e5c55f-28ee-4e80-aeaa-f5d84f34f712","properties":{"cellContent":"Fraud has been established."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"fc78bb95-b9ff-4e23-b353-df179a4f23c5","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"479b1a93-9148-415b-b6fb-c0c4f1568cad","properties":{"cellContent":"INITIATED_BY_PROCESSOR"}},"settings":null},{"content":{"contentType":"tableCell","id":"0cfa89ab-befa-46f0-8f6c-f621815a4c1b","properties":{"cellContent":"TXN initiated the change."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"efa545ce-d4d5-454f-b7cf-2c075a9ee0bf","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"97d9ba8d-c7ab-42f7-9ca2-2fb2fca35b48","properties":{"cellContent":"INITIATED_BY_ISSUER"}},"settings":null},{"content":{"contentType":"tableCell","id":"d467cf6b-45ca-4f73-95d9-11563c0b45c9","properties":{"cellContent":"The issuer initiated the change."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"bfc7499f-4f39-46ce-9e9b-87a7dbbaa331","properties":{"alertTitle":"Closing a card is permanent, and it locks the record.","alertContent":"Closed is a terminal state with no route back. A closed card cannot be reopened and no field on it can be edited afterwards. If the cardholder needs a working card again, issue a replacement. Use on hold when you only need to stop the card temporarily.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"480fc6e5-0cd6-4d92-b4d2-e3c5cb139e6d","properties":{"alertTitle":"A card transition does not reach its digital wallet tokens by default.","alertContent":"Putting a card on hold leaves any Apple Pay or Google Pay token provisioned from it live and usable unless you explicitly ask for the transition to propagate. Set applyToDigitalWallets when the reason is one that should stop all use of the card, such as a card reported lost or stolen. Propagation is queued rather than immediate, so allow for a short delay before the token stops working.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"dd1f6b14-0613-4d90-aa02-d57222f2fe0e","properties":{"sectionText":"Card data and PCI"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"83c10e3d-c289-468d-972c-bfcc4e0b08fc","properties":{"text":"The card number, security code and expiry date are PCI-protected. They are masked in standard API responses, including the response to creating the card, and none of them can be written to.\n\nThey are retrievable. TXN exposes dedicated PCI endpoints that return the full values, and access to them depends on your credentials carrying PCI permission. If your program needs to display a card number to a cardholder, that is the route. For everything else, build on the card\u0027s identifier rather than expecting to hold its number."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"c63532e5-226e-435c-bb04-f52c8097d56c","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"4f1d3f8a-2d82-443d-a1c0-75e5b23ad06b","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"dba98953-88cb-4eb2-910b-75e3c17e4f8f","properties":{"cardTitle":"Products","cardText":"Where a card\u0027s behavior is set, including the controls a card inherits.","pageLink":{"contentType":"guidePage","name":"Products","createDate":"2026-09-16T06:22:36.26Z","updateDate":"2026-11-15T16:32:42.283Z","route":{"path":"/103/foundational-objects/products/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"38067e3a-67a3-4525-b8e7-987c4c4c8b58","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"e1344282-c6f4-4e3a-b10b-6c8c8ed03844","properties":{"cardTitle":"PINs","cardText":"Setting and managing the PIN on a physical card.","pageLink":{"contentType":"guidePage","name":"PINs","createDate":"2026-09-16T06:22:49.75Z","updateDate":"2026-11-15T16:32:44.497Z","route":{"path":"/103/foundational-objects/pins/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"9ec97807-626f-4fb3-802f-8535f181814a","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"01d3c6dc-8b2f-4446-a6c1-4c81f62e4f71","properties":{"cardTitle":"Digital Wallet Tokens","cardText":"Provisioning a card into Apple Pay and Google Pay.","pageLink":{"contentType":"guidePage","name":"Digital Wallet Tokens","createDate":"2026-11-14T13:46:40.313Z","updateDate":"2026-11-15T16:32:42.527Z","route":{"path":"/103/digital-wallet-tokens/digital-wallet-tokens/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"40b1a666-ed74-4f45-8745-d54c19dc8a2c","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"32abd2c5-e5f3-49bc-8865-89fa66d5626e","properties":{"prevPageTitle":"Accounts","nextPageTitle":"PINs"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Retries and Idempotency","createDate":"2026-11-14T09:22:41.407Z","updateDate":"2026-11-15T16:32:39.84Z","route":{"path":"/103/api-essentials/retries-and-idempotency/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"182084cf-2e4d-406f-a1e4-9a1dcba5f19d","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"c29faae0-2020-458d-abc5-934722649d85","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"8ee78aec-d350-4d22-9960-847599c957fb","properties":{"title":"Retries and idempotency","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"195a8689-52ca-4539-b975-760428d678c8","properties":{"text":"Network calls fail in ways that leave you uncertain. A timeout tells you a response did not come back. It does not tell you whether the request was processed. Retrying a read costs nothing, but retrying a write can create the same cardholder, card or transfer twice. Idempotency is how TXN lets you retry a write without that risk."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"f22bc5fb-8997-4ecc-8a5f-a5bcc6a2b9d7","properties":{"sectionText":"The problem with retrying a write"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"4bec397c-b729-4410-b9fd-b0014936dcd6","properties":{"text":"Reads are safe to repeat. If a call to fetch a cardholder fails, you call it again and nothing in your Card Program has changed.\n\nWrites are different, and the difficulty is not that they fail. It is that some failures do not tell you what happened. A connection that drops, a request that times out, a gateway error: in each case the request may have been processed in full, processed in part, or never reached the platform at all. The response that would have told you never arrived.\n\nWithout a way to identify a repeat, that leaves two bad options. Retry, and risk issuing a second card or moving money twice. Do not retry, and risk an operation your customer believes happened not existing at all."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"69e96065-05a0-43e8-a0ff-37e06de4ce89","properties":{"alertTitle":"A duplicate is a real card or real money.","alertContent":"A duplicate record in a reporting system is untidy. A duplicate card is a real card in someone\u0027s hand, and a duplicate transfer is real money that has moved. Treat write retries as something to design, not something to add when a problem appears.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"e461a9e5-4406-45b6-9fc2-fd93e2b91b71","properties":{"sectionText":"How a repeated write is detected"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3215e615-9104-40e1-9beb-cbfbe2d91883","properties":{"text":"Every request to the Core API already carries a requestId. It is a required header and a UUID that you generate. That value is what TXN uses to recognize a repeated write.\n\nTXN stores the requestId against the result of the operation it performed. If a request arrives carrying a requestId that has been seen before, with the same body, the platform does not do the work again. It returns the result of the original request, whether or not you ever saw that first response.\n\nA stored result is kept for 24 hours by default. A repeat sent after that is not recognized as a replay.\n\nIf the same requestId arrives with a different body, TXN does not replay anything. It returns 422 with error code 42201.\n\nOnly a completed, successful request is stored. If a request is rejected, for example with a 400 or a 422, nothing is kept against its requestId. You can correct the request and send it again with the same requestId, and it will be processed as normal.\n\nSo there is nothing extra to send and no new header to adopt. Idempotency turns entirely on how you choose the value you are already sending."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"0b75d9fd-229e-4afb-97e6-21c44e262e33","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"8b848ae6-2d47-470a-bfa1-2ef2db9f9a26","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"fb1a0dc5-5bce-41e3-bdc9-c00cfa311935","properties":{"cellContent":"Header"}},"settings":null},{"content":{"contentType":"tableCell","id":"b54fe364-fe98-4a94-a641-54beb72b37e8","properties":{"cellContent":"What it carries"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"323408d4-4581-4d4b-b1f8-e7b3118e80e0","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"b26f1cc4-44cb-422d-bf51-70d116b83022","properties":{"cellContent":"requestId"}},"settings":null},{"content":{"contentType":"tableCell","id":"ab514cfd-7ffc-467c-ba5d-f523b07fc622","properties":{"cellContent":"A UUID identifying the operation. Required on every request. Send the same value on every retry of the same operation."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"333670f8-8458-41e9-8cc0-517e03ce64bf","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"349382c4-ab01-4409-acd9-27946871d480","properties":{"cellContent":"x-idempotent-replayed"}},"settings":null},{"content":{"contentType":"tableCell","id":"b21d87bd-b68b-4cec-a67d-65f1bd9cc78e","properties":{"cellContent":"Returned on writes. true when the response came from a replay, false when the work was performed. Not set on reads."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"86d78e67-f843-40ce-92b3-da6fbd9ed4c2","properties":{"alertTitle":"Choose the value once per operation.","alertContent":"Generate the requestId before the first attempt and send that same value on every retry of that operation. Sending a new one is not an error, but it describes a different write, so the platform will perform the work again. This is worth deciding deliberately, because requestId is often generated in a client\u0027s HTTP layer, which is usually also where retry logic sits.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"88d235b6-a67a-4136-a0af-74b903aa375b","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"5475b284-fa0f-4ca1-814b-52ad83600b85","name":"Ae Retries And Idempotency Safe Retry Dark","mediaType":"Image","url":"/media/bn2dhytg/ae-retries-and-idempotency-safe-retry-dark.png","extension":"png","width":2400,"height":1080,"bytes":265590,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"dd827cda-81d5-410c-9864-1d61283a9f95","name":"Ae Retries And Idempotency Safe Retry Light","mediaType":"Image","url":"/media/kw1mi032/ae-retries-and-idempotency-safe-retry-light.png","extension":"png","width":2400,"height":1080,"bytes":262820,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"fa275914-071f-4d7e-9190-381dd7926b46","properties":{"sectionText":"Knowing a response was replayed"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"609a89c4-558f-42aa-ba4c-11d280da58df","properties":{"text":"A replayed request returns HTTP 200 with x-idempotent-replayed set to true. On a write the header is always present, so you read its value rather than checking whether it is there. On a read it is not set, because reads are not replayed.\n\nThe body and every identifier in it are the ones the original attempt produced. The status can differ: the first attempt that creates something returns 201, and its replay returns 200. Accept both as success and your code can handle a replayed response exactly as it handles the first one, which is the point of the mechanism. It is worth logging: it tells you during reconciliation that a record came from a retry rather than a second operation, and it is the simplest way to confirm in testing that your retry logic does what you think."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"1cdce10e-77da-4f6b-8561-1305e6edc578","properties":{"alertTitle":"A replayed response is the original response.","alertContent":"If the first attempt created a card, the replay returns that same card and its identifier. It does not create a second one, and it does not return an error telling you the first exists.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3eaea205-3fbd-4f0c-adf1-4757c1b579a2","properties":{"text":"A 409 is a different thing and it is worth not confusing the two. A 409 means the request conflicts with the current state of something on the platform, for example creating an entity that already exists. It is about what you are trying to create or change, not about whether TXN has seen your requestId before. A replay returns the original result, not a 409."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"c0f56860-d8b6-4d8c-8134-8ab19c9c3510","properties":{"sectionText":"Retrying safely"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"00c1b084-9c2b-4450-b43d-d9ba51943e75","properties":{"text":"Errors covers which statuses mean the request was wrong and which mean come back later. This is about performing the retry itself.\n\nWait before retrying, and wait longer on each successive failure. Add a small random delay to each wait so that several workers failing at the same moment do not all retry at the same instant and recreate the spike. Cap the number of attempts and surface the failure rather than retrying indefinitely.\n\nEvery retry counts against your rate limit, so a retry loop that does not back off will turn one failure into a rate limit rejection and then into a longer outage than the original problem caused."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"550112d9-bafc-4272-967f-450e4e18a46d","properties":{"text":"The case worth planning for is the one where you got no response at all. You cannot know whether the write happened, and there is nothing to inspect. If you send the request again with the same requestId within the 24-hour window, you do not need to know: you will either get the original result back or have the operation performed once. If you send it with a new one, your only safe option is to go and look for the record before deciding, and for some operations there is no reliable way to do that."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"f82a53c8-5be3-4051-b8f1-bf67d28e0d30","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"2b6a0312-eb15-4ff7-b7b1-32f579700f25","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"8900fdef-6628-4078-9134-9a3c90a216c9","properties":{"cardTitle":"Rate Limits","cardText":"Pace your retries so that backing off does not put you over the limit.","pageLink":{"contentType":"guidePage","name":"Rate Limits","createDate":"2026-11-14T09:22:41.343Z","updateDate":"2026-11-15T16:32:47.413Z","route":{"path":"/103/api-essentials/rate-limits/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"eaf38fec-bda3-49d6-be92-41e32f25e364","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"d4a65d64-dd13-4b03-ae89-c15bd9b0ebe0","properties":{"cardTitle":"Errors","cardText":"Which statuses are worth retrying, and which will fail again unchanged.","pageLink":{"contentType":"guidePage","name":"Errors","createDate":"2026-11-14T09:22:41.277Z","updateDate":"2026-11-15T16:32:46.777Z","route":{"path":"/103/api-essentials/errors/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dba005b5-8d0e-48ba-84b2-85c6855f7c5e","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"0e06edbb-9089-4edb-a783-92d093d161bb","properties":{"cardTitle":"Requests and Responses","cardText":"The envelope and headers every response carries, including on a replay.","pageLink":{"contentType":"guidePage","name":"Requests and Responses","createDate":"2026-11-14T09:22:41.207Z","updateDate":"2026-11-15T16:32:46.957Z","route":{"path":"/103/api-essentials/requests-and-responses/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dd68c2a5-1262-438b-adfb-f6bf84e3e336","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"975d2a52-4f9d-469b-8119-ecdb14674830","properties":{"prevPageTitle":"Rate Limits","nextPageTitle":"The API Specification"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"The API Specification","createDate":"2026-09-18T11:04:41.003Z","updateDate":"2026-11-15T16:32:43.903Z","route":{"path":"/103/api-essentials/the-api-specification/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"86681cfa-032f-4305-a091-440b22b55b10","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"a6c1737a-abad-4efe-9394-9de5cda1fd8c","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"91a78a82-d845-4446-bd99-184512e00ea2","properties":{"title":"The API Specification","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"ef8da200-69a1-4d39-866c-21c86541b73f","properties":{"text":"The Core API is described by a single OpenAPI specification covering the whole public surface. The API Reference in this portal is that file rendered. This page is about the file itself: where to get it, which version you are looking at, how it is organized, and what it will and will not tell you."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"d7ad6143-324d-4764-913b-3ce11afc23f4","properties":{"text":"One specification covers the whole public API. It is not split by domain or by version into files you have to merge, so there is one artifact to download, one to diff and one to generate a client from. Every operation the platform offers to you is in it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"68ff8d1c-bea8-4e0b-8b16-240df043ce8c","properties":{"sectionText":"The API Reference is the specification, rendered"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"a1a9d13d-7517-42ac-86c4-f72c653d04fd","properties":{"text":"The Reference you can browse in this portal is not a second document maintained alongside the API. It is the specification, retrieved from the platform and rendered for reading. What you see there is generated from the same file your tooling would consume, so there is no separate copy to fall out of step with."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4714e0a9-a423-42c7-889e-654b46a95332","properties":{"sectionText":"Getting the specification"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"986bb447-50a6-46b8-8ef1-daede6ca4566","properties":{"text":"There are two places to get the specification.\n\nFrom your own environment, request /api-specification.yml or /api-specification.json. You get the release currently deployed in that environment.\n\nThe Public Sandbox (sandbox.txn.global) and the Knowledge Hub (developer.txn.global) serve the same two paths. Compare the info.version field of what each returns to see which release it is serving.\n\nIt is the file the API Reference is rendered from, so a client generated from it matches what you see in the Reference. Check the info.version field of the file you have to see which version it is."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"1c8c5f2e-f54b-474b-90ce-6049f5b490b7","properties":{"sectionText":"Which version you are looking at"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"f4937ddf-5eb4-4362-b641-38b78d03ef1b","properties":{"text":"The version identifier sits in the info.version field of the document and follows semantic versioning, so the file tells you what it is without you tracking it separately. Versions are deployed per environment, so do not assume the version running in the Public Sandbox is the one running in production. Request the specification from the environment you are about to release against and check its info.version."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"21456d5d-1d21-42d1-b9a7-b785726aab47","properties":{"sectionText":"How it is organized"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"75430002-36f7-4383-b935-89048ff515f6","properties":{"text":"Operations are grouped with OpenAPI tags by the resource they act on rather than by HTTP method. Each operation carries an operationId, a summary and a description. The descriptions are written for a developer with no prior TXN knowledge and cover what has to exist before you call an operation, what it changes, and notes on integrating with it. Those descriptions are part of what you are integrating against, not decoration."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"952da82b-fd4c-4427-9e12-8d54e0282788","properties":{"sectionText":"What the specification will not tell you"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"2cd19a21-df74-4c5b-b75d-75c21b632b08","properties":{"text":"The specification describes shape: paths, schemas, fields and formats. It does not describe sequence or consequence. It will not tell you that an account has to exist before a card can reference it, that closing an account is terminal, or which of two balance figures a cardholder should see. That is what these guides are for. Generate your client from the specification and learn the behavior here."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"d99a8043-5b8b-4b13-8ea9-2cf07d043b52","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"f8103787-97bc-4a4d-b901-dfd7107687a8","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"78870c93-0586-410e-8f98-61553ebae3f0","properties":{"cardTitle":"Versions and Changes","cardText":"How versions are announced, and what counts as a breaking change.","pageLink":{"contentType":"guidePage","name":"Versions and Changes","createDate":"2026-09-16T11:13:56.453Z","updateDate":"2026-11-15T16:32:44.057Z","route":{"path":"/103/going-live/versions-and-changes/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"8f1cb6b9-3dda-4ea5-9498-87379b576efb","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"4b1fa623-45c3-4335-be0a-782d95d19e09","properties":{"cardTitle":"Requests and Responses","cardText":"The shape of every call and every reply, including the required headers.","pageLink":{"contentType":"guidePage","name":"Requests and Responses","createDate":"2026-11-14T09:22:41.207Z","updateDate":"2026-11-15T16:32:46.957Z","route":{"path":"/103/api-essentials/requests-and-responses/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dd68c2a5-1262-438b-adfb-f6bf84e3e336","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"17bfa027-1476-42c1-899f-74932f791763","properties":{"cardTitle":"Environments","cardText":"The three environments and what each one serves.","pageLink":{"contentType":"guidePage","name":"Environments","createDate":"2026-09-16T06:21:03.5Z","updateDate":"2026-11-15T16:32:45.067Z","route":{"path":"/103/getting-started/environments/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b230a635-a702-4570-a189-ce295a6165dc","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"9918516b-9fdf-40ef-9cc9-e4640c0a50ed","properties":{"prevPageTitle":"Retries and Idempotency","nextPageTitle":"Products"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Control Center","createDate":"2026-09-17T10:20:00.54Z","updateDate":"2026-11-15T16:32:46.61Z","route":{"path":"/103/getting-started/control-center/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dad6c052-ee94-4769-96a3-4ecef68cef59","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"c4d3ee31-ac3a-4ef5-9759-ddd329497a4a","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"64d3f16e-23c8-4808-93f0-b9e3b44c6407","properties":{"title":"Control Center","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"74d6480e-7b7f-4d07-bdad-5487410a49c7","properties":{"text":"The Core API is how your systems talk to TXN. Control Center is how your people do. It is the operational interface for your Card Program: configuration, monitoring, approvals and investigation in one place, with every action governed by role and recorded. This page explains what it is and what it covers. The detail of each screen lives in Control Center itself."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ba8f8625-e718-47c1-ade8-ff185bda44ce","properties":{"sectionText":"What Control Center is for"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"6c03014c-71aa-4002-930c-b589ad237e00","properties":{"text":"Running a Card Program generates work that does not belong in code. Someone has to configure a product before cards can be issued against it, approve a change to a spend limit, investigate why a transaction declined, and watch for the things that need a human to look at them.\n\nIn most issuing setups that work is scattered across spreadsheets, internal tools and email threads, and none of it is reliably recorded. Control Center exists to put it in one place, behind role-based access, with an audit trail.\n\nIt is not a replacement for the Core API and it is not a fallback for integrations that are not finished. The two are different surfaces onto the same platform, for different users."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"86f04492-b192-4c43-b037-a8be3076dc1e","properties":{"sectionText":"How Control Center and the Core API relate"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"60fbb275-eba2-41f0-8d02-66ac9f84dd4f","properties":{"text":"Control Center and the Core API act on the same platform and the same objects. A product configured in Control Center is the product your cards are issued against through the Core API. A spend control changed in Control Center takes effect on the next authorization, with no redeploy on your side.\n\nThe difference is governance. Actions in Control Center are tied to a named user and a role, some require approval before they take effect, and all of them are recorded. That is deliberate: the operations that most need a human decision are also the ones that most need an audit trail."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"34713948-5220-4298-9f86-c632fcf46417","properties":{"alertTitle":"Three things developers need Control Center for","alertContent":"Your environment addresses and API credentials are issued there. Webhook endpoints are configured there. Feature enablement for your program is set there. Everything else on this page is your operations team\u0027s day-to-day rather than yours.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"edeb0bfc-6515-4277-8990-35556115f9d8","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"71d754a5-506f-483b-b0f8-34838deabc43","name":"Gs Control Center Core Api And Control Center Dark","mediaType":"Image","url":"/media/fkpjdryg/gs-control-center-core-api-and-control-center-dark.png","extension":"png","width":2400,"height":1200,"bytes":266912,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"97960c5e-6299-440a-b619-b71841b84139","name":"Gs Control Center Core Api And Control Center Light","mediaType":"Image","url":"/media/0hdnaipq/gs-control-center-core-api-and-control-center-light.png","extension":"png","width":2400,"height":1200,"bytes":265191,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"b4cee9a9-a187-4206-ac4b-894039a1bc8e","properties":{"sectionText":"What you can do there"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"5e4dd8ed-4199-4dba-b323-a1f5c82f4b86","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"deac58e5-56fd-41e4-aae4-aa6f69d1a376","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"adbcf457-d2a5-497e-8598-3efa9872f8f3","properties":{"cellContent":"Area"}},"settings":null},{"content":{"contentType":"tableCell","id":"643f25d5-79c8-4fbd-a961-7d9812ae5eaf","properties":{"cellContent":"What it covers"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"989cf086-5209-4d22-9938-6e582d554b83","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"d8ed5a48-2e8c-4800-a5a9-29234ad188fe","properties":{"cellContent":"Users and access"}},"settings":null},{"content":{"contentType":"tableCell","id":"a8e92ce3-d0d3-471e-aaca-ee7e6062c29d","properties":{"cellContent":"Sign-in and identity, adding and removing users, roles and permissions, and what each role is allowed to see and do."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"ddcf8c32-820a-4685-ab00-a8d798f0eff7","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"2aae5777-fa5a-45f0-8d07-f074e22670d5","properties":{"cellContent":"Program setup"}},"settings":null},{"content":{"contentType":"tableCell","id":"2b0ea495-44ea-4254-bb03-ac55f82085f5","properties":{"cellContent":"Card Program configuration and lifecycle, structured onboarding, BIN allocation, product configuration, and the entities beneath a program."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"a89e07fa-1cf4-400c-b01d-03d3961c6755","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ae48cdf7-2b09-4e21-84f1-f9c11386b98e","properties":{"cellContent":"Controls and risk"}},"settings":null},{"content":{"contentType":"tableCell","id":"8c73f7f9-c611-48f6-89af-95717aae756e","properties":{"cellContent":"Risk controls at BIN Sponsor and program level, card-level exceptions and spend overrides, 3-D Secure policy, and Delegated Approval including Stand-In arrangements."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"e9a00566-85de-4757-af88-88f2d43b2c07","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"f5cfc30a-c6e7-4730-80b8-9c8938fae4c1","properties":{"cellContent":"Environments and integration"}},"settings":null},{"content":{"contentType":"tableCell","id":"093ef99b-5c0f-401a-82ab-658d63f8d086","properties":{"cellContent":"Environment provisioning, credentials, webhook configuration, feature enablement per program, and environment readiness checks."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"a1fc66c4-b0e3-48ed-9868-0eb95c9f86db","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"5a7ac9ca-1071-407d-a245-2b21136adf7e","properties":{"cellContent":"Operations"}},"settings":null},{"content":{"contentType":"tableCell","id":"34a8050a-e4a9-41a4-9430-af30827950bc","properties":{"cellContent":"The tools an operations team uses to investigate cardholders, accounts and cards, handle cases and incidents, respond to alerts, and report on operations."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"f13d0ec9-661f-4c8b-bbd7-a47b1c888d28","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"e7066fe3-4abe-44c9-b2f1-90c72c4d7722","properties":{"cellContent":"Governance and audit"}},"settings":null},{"content":{"contentType":"tableCell","id":"8e9c3cd0-9f1f-4d2e-bbd9-f10e11030191","properties":{"cellContent":"Approval workflows for changes that need a second pair of eyes, and a central audit trail across everything done in Control Center."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"25e827c8-4ecb-480a-b55c-c8b04b59b612","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"cc80689c-07f8-4388-af8a-b0ed017c0c9f","properties":{"cellContent":"AI assistance"}},"settings":null},{"content":{"contentType":"tableCell","id":"d6100d17-e847-4ac3-877f-cb8132a9eec4","properties":{"cellContent":"Natural-language querying and reporting, embedded guidance, and anomaly and fraud intelligence, each governed per program."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"dcfc5c30-5eeb-429b-acce-b3ec0e729932","properties":{"sectionText":"Getting access"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ee28c0d9-a440-4268-8294-e262076f72a0","properties":{"text":"Control Center access is set up as part of onboarding, and your permissions depend on the role you are given. If you need access, or need a colleague added, that is a conversation with your TXN contact rather than something you can self-serve."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"95fcc396-2459-46d4-ae97-78cba404369c","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"2ee6909a-e05c-46de-ac26-36fb22c77fe4","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"2b289e53-f949-41d9-8fc8-70f2b2be8d1e","properties":{"cardTitle":"From First Call to Go-Live","cardText":"When each environment and level of access becomes available to you.","pageLink":{"contentType":"guidePage","name":"From First Call to Go-Live","createDate":"2026-09-16T10:37:09.553Z","updateDate":"2026-11-15T16:32:46.457Z","route":{"path":"/103/working-with-txn/from-first-call-to-go-live/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"d6f8f50b-69d9-4bbf-8fe3-83fdbbe71cf6","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"12b44a00-0939-49e1-a93b-9fea60b9cdfe","properties":{"cardTitle":"Intelligent Assistant","cardText":"The reasoning layer that works alongside your operations team in Control Center.","pageLink":{"contentType":"guidePage","name":"Intelligent Assistant","createDate":"2026-09-17T10:41:28.027Z","updateDate":"2026-11-15T16:32:38.773Z","route":{"path":"/103/getting-started/intelligent-assistant/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"062f45f3-7255-4872-b13b-514b87f1744e","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"0552746f-b445-477c-afb1-acc81e13ffc6","properties":{"cardTitle":"Authentication","cardText":"How your integration authenticates once credentials are issued.","pageLink":{"contentType":"guidePage","name":"Authentication","createDate":"2026-09-16T06:20:42.913Z","updateDate":"2026-11-15T16:32:43.17Z","route":{"path":"/103/getting-started/authentication/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"56e49f8f-4cd4-44d1-acca-d5cda1431fc6","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"9c184fa9-1ab8-44b9-8a42-fd9081e6d703","properties":{"prevPageTitle":"Authentication","nextPageTitle":"Intelligent Assistant"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"PINs","createDate":"2026-09-16T06:22:49.75Z","updateDate":"2026-11-15T16:32:44.497Z","route":{"path":"/103/foundational-objects/pins/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"9ec97807-626f-4fb3-802f-8535f181814a","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"e71b27f6-19bd-4041-a212-b5a16b3361e5","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"e3319338-f3a6-489d-b952-4aafe75e9b8f","properties":{"title":"PINs","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"f689392d-ac67-4ea0-91de-daf080d9b51d","properties":{"text":"A card PIN is one of the more sensitive pieces of data an issuing platform handles: it is what proves, at a terminal, that the person presenting a card is entitled to use it, and the handling rules around setting, viewing and recovering one are correspondingly strict."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"c3350605-8902-4167-9c18-2d917c256f97","properties":{"text":"On TXN, PIN handling is a deliberately narrow set of operations, separate from the card record itself, that set, view and unblock a card\u0027s PIN. PINs are four digits."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4a6bdbe8-c02b-4dbe-b7e9-fc4c807a31ae","properties":{"sectionText":"Who handles the PIN"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"3721904a-ecaf-4b93-a78c-265afa843e65","properties":{"text":"Before anything else, work out which side of the PCI line your program sits on, because it changes how you build.\n\nIf your program is PCI-certified, you call the PIN operations directly and take on handling the data that comes with them.\n\nIf it is not, you do not need to become certified to offer PIN management. TXN provides hosted, PCI-compliant screens your cardholders use to set, reset and reveal their PIN. Your application hands the cardholder over and never sees or stores PIN data itself. Every action is logged for audit either way."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"c4b88c75-7b8d-4dd8-bfc3-4bdd96bbb1a4","properties":{"sectionText":"How a PIN is first set"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"5ce0566c-0aca-437b-b17c-6e81f9d3fd4f","properties":{"text":"A card may already have a PIN by the time it reaches the cardholder. A product can generate one automatically at issuance, which suits physical cards that ship with a PIN mailer. That generated PIN can be overridden at card level if a particular card needs a specific one.\n\nWhere a product does not auto-generate, the card is issued without a PIN and one is set afterwards, either by your application or by the cardholder through the hosted screens."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"f13888d7-f668-4de6-9c67-61828b182875","properties":{"sectionText":"The PIN operations"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"8d2c22d4-0760-483f-a284-03c9671aa1c5","properties":{"text":"Every PIN operation follows the same shape: obtain a short-lived authentication token scoped to one card and to the action you intend, then present that token to the operation itself.\n\nSetting a PIN takes the card, the token and the new PIN. The PIN must satisfy the platform\u0027s composition rules, which rule out sequential and repeated digits. Unblocking clears a lock caused by too many failed attempts. Viewing a PIN returns it, in clear text over the encrypted channel, and resets the PIN retry counter as it does so.\n\nAll three operations can optionally lift a related card suspension in the same request, and a view can additionally clear a PIN block, so a single call can resolve both a blocked PIN and a suspended card without a separate unblock first."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"e3641de7-9c34-4924-9ab0-65980c3bc31e","properties":{"alertTitle":"Reading a PIN puts PIN data in your systems.","alertContent":"The view operation returns the PIN in clear text. That is fine if your program is PCI-certified and is the reason the operation exists. If it is not, do not call it: use the hosted screens instead, where the cardholder sees their PIN and it never touches your infrastructure. Calling the API to display a PIN in your own application is the shortest route into PCI scope.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"1b73372f-8eca-4bf1-8d50-ad3dc05ebdd8","properties":{"sectionText":"Online and offline PINs"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"94a42008-c909-4075-9b3f-3d90eff058ba","properties":{"text":"The same PIN is verified two different ways depending on where it is used. An online PIN is checked by TXN in real time as part of the authorization. An offline PIN is checked by the chip on the card itself, at the terminal, without reaching TXN.\n\nThey are tracked separately. Each has its own retry counter and its own configurable limit, so a card can have an exhausted offline counter while its online counter is untouched. Attempts of both kinds are monitored in real time and can be delivered to your systems as events.\n\nThat separation is useful when a cardholder locks themselves out offline. A successful online PIN entry can clear the offline try limit, which means an ATM or an online-verified transaction restores the card rather than forcing a reissue."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"ba466f42-59e5-4f66-a883-f1afa14ac1a9","properties":{"alertTitle":"A PIN change does not reach the chip until the card is next used.","alertContent":"Changing or unblocking a PIN queues a script that runs at the card\u0027s next chip-capable authorization. Until that happens, the chip still holds the previous PIN for offline verification. Tell cardholders their new PIN is active straight away for online use, and that the first chip transaction completes the change.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"87f31389-944e-4e62-832b-8c2764ec7c20","properties":{"sectionText":"When the retry limit is reached"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"0ee62b03-9f9f-4cd7-8009-5ab9b3f80007","properties":{"text":"Exceeding the retry limit does not just block the PIN. The platform suspends the card, which is why PIN_RETRY_LIMIT_REACHED appears in the card transition reasons (see Cards). Recovering from it means clearing both, which is what the combined options on the PIN operations are for.\n\nCardholders can also resolve it themselves at a supported ATM, where both a PIN change and a PIN unblock stay synchronized with the platform."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"bf452c7d-b724-49d0-bad5-0399b988aff5","properties":{"sectionText":"Choosing the right operation"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"b05ecfd0-262a-4db7-ae7a-fdaedeb5d677","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"c38bd422-8271-4439-ab01-9ebb6ac65ee3","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"e3adad08-aca9-4651-a588-3d2a841658f1","properties":{"cellContent":"Situation"}},"settings":null},{"content":{"contentType":"tableCell","id":"0155ca23-4d26-4a57-b5a2-64f2e0bf3d26","properties":{"cellContent":"Sequence"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"09a23b1a-aa9a-416e-86be-a14e67e3f933","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"b51d5f43-5fdd-408c-87fe-c5c3f49ad917","properties":{"cellContent":"Card issued without a PIN, or cardholder wants to change theirs"}},"settings":null},{"content":{"contentType":"tableCell","id":"d5bbe072-deca-4bdd-a1ae-ac792c4744e5","properties":{"cellContent":"Obtain a token, then set the PIN"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"f95c59ed-0df0-498a-8399-0190e35287ce","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"5cca246e-141a-4af5-9ad5-7b5d0564db82","properties":{"cellContent":"Cardholder has forgotten their PIN and needs to see it again"}},"settings":null},{"content":{"contentType":"tableCell","id":"da8c290a-bd1b-4b7f-8a30-7e58cfb4d3fa","properties":{"cellContent":"Obtain a token, then view the PIN"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"978a76b8-4a0e-4977-84f6-6fb1493be40b","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"69d961ed-aab7-49dd-827f-78fa461366f5","properties":{"cellContent":"PIN entry has failed too many times and the card is blocked"}},"settings":null},{"content":{"contentType":"tableCell","id":"17ea0805-9d3d-48dd-b325-499434b0e17a","properties":{"cellContent":"Obtain a token, then unblock the PIN"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"3766ec6f-d947-40a2-b22d-4923eae8a793","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"5041a03f-b250-4ff8-9e4a-54d43ff1cb41","properties":{"cellContent":"Blocked PIN and a suspended card need clearing together"}},"settings":null},{"content":{"contentType":"tableCell","id":"3561b6da-62e1-4d9a-92fe-44b609d40bbf","properties":{"cellContent":"Obtain a token, then unblock or view with the suspension option set"}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"1f8e5512-48ca-4cfa-8666-60671b4c8198","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"f2010b2c-dccd-4fba-8a2b-9e923d0013d2","properties":{"cellContent":"Cardholder is locked out offline but can transact online"}},"settings":null},{"content":{"contentType":"tableCell","id":"22622bb2-880e-45fc-b380-2cbf6736fc0e","properties":{"cellContent":"A successful online PIN entry clears the offline limit, no call needed"}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"2e3cc81b-a683-4ffe-9628-17e491f66ace","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"2e7e4e6f-df0c-4506-80e9-9441f8ba3748","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"7a8dde63-833c-49a4-adb3-09db2378ddd0","properties":{"cardTitle":"Cards","cardText":"Card lifecycle, including the suspension a PIN retry limit triggers.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"cfbdf042-c95f-45cd-b281-688f89a8d9c6","properties":{"cardTitle":"Products","cardText":"Where automatic PIN generation at issuance is configured.","pageLink":{"contentType":"guidePage","name":"Products","createDate":"2026-09-16T06:22:36.26Z","updateDate":"2026-11-15T16:32:42.283Z","route":{"path":"/103/foundational-objects/products/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"38067e3a-67a3-4525-b8e7-987c4c4c8b58","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"5b768e55-04d7-4606-bea7-8142859aeca3","properties":{"cardTitle":"Controls \u0026 Security","cardText":"The wider set of controls governing how a card can be used.","pageLink":{"contentType":"guidePage","name":"Spend Controls","createDate":"2026-09-16T10:47:00.377Z","updateDate":"2026-11-15T16:32:45.233Z","route":{"path":"/103/card-controls/spend-controls/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"b3eace44-6780-4c51-831b-164ca1d52e67","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"35914220-5e2e-4d7d-a81e-37c6a4d24d7c","properties":{"prevPageTitle":"Cards","nextPageTitle":"Transactions"}},"settings":null}},"cultures":{}},{"contentType":"guidePage","name":"Card Expiry","createDate":"2026-11-14T13:45:45.047Z","updateDate":"2026-11-15T16:32:45.757Z","route":{"path":"/103/managing-cards/card-expiry/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"c55e0510-91cf-417d-aac9-10de3a62db61","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"a8356a5d-0a13-445e-9c9e-673ba03f8c2d","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"4a8994ac-8f0c-4cf4-a485-52e66533013d","properties":{"title":"Card Expiry","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"1f185453-9007-41d5-ba4d-b24b4bf02732","properties":{"text":"Every card carries an expiry date and TXN acts on it without being asked. What it does is simple; the useful part is knowing the one thing that stops it, and how late is too late."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ad193765-9fa9-40b5-90d3-fc5a9400fe1e","properties":{"text":"When a card reaches its expiry date TXN closes it automatically. There is no call from you, no job to run on your side, and no setting that leaves a card open past its date. It is applied the same way to every card that reaches the date, and it is deliberately not optional: an expired card must not be usable, and scheme rules rather than platform preference are what make that so."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"b4b1a21d-af4e-4da0-b257-b26f157d94e7","properties":{"sectionText":"Closed on expiry is closed for good"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"f4ae7337-a957-4235-91e9-8ec2fa209ca2","properties":{"text":"Expiry closes the card, and closed is terminal. It cannot be reopened and no field on it can be edited afterwards. Nothing about expiry produces a gentler form of closure that can be undone once someone notices. If the cardholder is to keep spending, the replacement has to exist before the date rather than after it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"ce1d63e9-a1ac-4668-a361-d751575e73ec","properties":{"alertTitle":"After the date, there is nothing left to renew.","alertContent":"Once a card has closed on expiry there is no route back to it, which means the cardholder has no working card until a replacement has been issued, delivered and activated. For a physical card that is a delivery cycle, not an afternoon. Drive your renewal process from the expiry date rather than from the moment someone notices a card has stopped.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"964f82c2-55b9-4704-b92e-8a6ebef6b557","properties":{"sectionText":"The one thing that stops automatic closure"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"997f7494-ddd7-49a2-ae79-8f607f1a2d9d","properties":{"text":"A card is not automatically closed at its expiry date where a reissue has already been scheduled or completed for it. That is the whole of the exception, and it is why renewal is not a separate operation in TXN: you issue the replacement ahead of the date, and the expiry process leaves the original alone rather than closing a card that has already been superseded."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"f18ca52a-c409-4341-a128-8b339f0b9a1c","properties":{"sectionText":"What carries over on a renewal"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"d459dafc-704a-4853-a8d0-eec920afb38b","properties":{"text":"A replacement issued before expiry keeps continuity in digital wallet token provisioning and in card controls, following the reissue settings used to create it. That continuity is what makes a renewal close to invisible from the cardholder\u0027s side: the wallet keeps working and the card behaves as it did, rather than the cardholder discovering a set of changed behaviors alongside a new card."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"b44e7483-e7a2-4937-b0ff-196b6ba1b207","properties":{"alertTitle":"A renewal and a lost-card replacement are the same operation.","alertContent":"TXN has one replacement mechanism, not a separate renewal one. What differs is the timing and whether the number changes: a renewal happens ahead of the expiry date and can keep the existing number, while a card reported lost or stolen has to take a new one. If you are building a renewal process, you are building on the same call: worth knowing before designing two.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"fe13a103-cf7e-4035-8736-a899b4872a4d","properties":{"sectionText":"Your systems find out through a webhook"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"a90655e7-50f9-4821-bf6a-705e03753fd5","properties":{"text":"Closing a card on expiry raises a webhook event carrying the card lifecycle information downstream systems need. That is the intended route rather than a fallback: there is no expiry report to fetch and nothing to poll for. If something on your side has to react to a cardholder\u0027s card stopping, this event is where that reaction belongs."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"f5ca37d9-c213-4811-a8e8-5fe3a21a2d6a","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"7298f8a5-4a55-4c07-89bc-c65db13f8c1b","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"58c1880c-43b2-473e-a767-3fb38c880e9e","properties":{"cardTitle":"Replacing a Card","cardText":"The call a renewal is built on, and the choice of whether the number changes.","pageLink":{"contentType":"guidePage","name":"Replacing a Card","createDate":"2026-11-14T13:45:44.953Z","updateDate":"2026-11-15T16:32:41.983Z","route":{"path":"/103/managing-cards/replacing-a-card/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2db9d6c2-7f22-452f-b105-e3f518240751","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"8e7ab22b-b719-4caa-a73f-64fd301d263e","properties":{"cardTitle":"Cards","cardText":"Card states, and why closed is the one with no way back.","pageLink":{"contentType":"guidePage","name":"Cards","createDate":"2026-09-16T06:22:42.88Z","updateDate":"2026-11-15T16:32:41.61Z","route":{"path":"/103/foundational-objects/cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2d7cefe7-d58d-41b1-b53e-7f1d7f1d6a95","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"40e3babe-d868-4a28-ac4e-3e6a8839a418","properties":{"cardTitle":"Webhooks","cardText":"How the expiry event reaches your systems.","pageLink":{"contentType":"guidePage","name":"Webhooks","createDate":"2026-11-14T13:47:02.143Z","updateDate":"2026-11-15T16:32:40.257Z","route":{"path":"/103/staying-in-sync/webhooks/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1c117316-3d0f-42ce-9780-e5051e263d76","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"8c5ff94e-a60d-48ed-a781-990e4457df34","properties":{"prevPageTitle":"Transferring a Card","nextPageTitle":"Spend Controls"}},"settings":null}},"cultures":{}},{"contentType":"baseGuidePage","name":"Money Movement","createDate":"2026-09-16T06:23:12.5Z","updateDate":"2026-11-15T16:32:39.997Z","route":{"path":"/103/money-movement/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"891c3cdd-7506-4007-bb12-6538d2ada0ef","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"077f87c9-f9cc-40d9-a305-7f7369172f38","name":"Money Movement","mediaType":"umbracoMediaVectorGraphics","url":"/media/hm3n1zox/money-movement.svg","extension":"svg","width":null,"height":null,"bytes":8118,"properties":{}}]},"cultures":{}},{"contentType":"baseGuidePage","name":"Managing Cards","createDate":"2026-11-14T13:45:44.73Z","updateDate":"2026-11-15T16:32:41.053Z","route":{"path":"/103/managing-cards/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"fda6e55e-2df4-4caa-a098-6525d5ccf944","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"549470ed-aa84-4881-b2c2-e805f26e8d0f","name":"Managing Cards","mediaType":"umbracoMediaVectorGraphics","url":"/media/d5gdnnu5/managing-cards.svg","extension":"svg","width":null,"height":null,"bytes":8124,"properties":{}}]},"cultures":{}},{"contentType":"guidePage","name":"Intelligent Assistant","createDate":"2026-09-17T10:41:28.027Z","updateDate":"2026-11-15T16:32:38.773Z","route":{"path":"/103/getting-started/intelligent-assistant/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"062f45f3-7255-4872-b13b-514b87f1744e","properties":{"pageActionBar":{"content":{"contentType":"pageContextHeader","id":"0fc5613c-9d25-41d3-b6a7-02d2835fbf0e","properties":{"hideBreadcrumbs":false,"enableFeedback":true,"enableDownloadBtn":true}},"settings":null},"pageHeaderSection":{"items":[{"content":{"contentType":"mainHeader","id":"4f5c951e-02aa-45e8-9efa-2ffdd28ac32a","properties":{"title":"Intelligent Assistant","headerMedia":null}},"settings":null},{"content":{"contentType":"pageSubHeader","id":"66945521-691e-4c3c-a6c3-33f3f60894e6","properties":{"text":"The Intelligent Assistant is the platform\u0027s reasoning layer. It answers questions in plain language, works alongside your operations team inside Control Center and lets your own AI systems act on TXN through a governed interface. Everything it does runs under the same permissions, approvals and audit trail as any other action on the platform."}},"settings":null}]},"mainPageContent":{"gridColumns":12,"items":[{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"349d4b43-49dd-4620-9eec-ed59ba41205b","properties":{"sectionText":"What it does"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"ce80dbf0-8cd2-40ad-af01-b4a7e4c56017","properties":{"text":"The Intelligent Assistant runs across TXN rather than inside any one part of it. The same layer answers a developer\u0027s question in these guides, summarizes a transaction for a support agent in Control Center, and handles a request from a Program Owner\u0027s own AI system.\n\nIt covers four kinds of work. Answering questions and finding information. Operational analysis, including trend and anomaly detection, forecasting and decision support. Configuration guidance, including validating a Card Program setup and flagging conflicts or policy violations before they cause problems. And governed action, where an AI system requests a change and the platform decides whether it can proceed."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"ff64437c-f621-4f85-af3a-b80afb0d65d1","properties":{"sectionText":"Asking questions in plain language"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"483ec5fd-e188-48fe-9e07-9a0c7d8cdb5a","properties":{"text":"You can ask the Intelligent Assistant a question the way you would ask a colleague, and it answers from TXN\u0027s own documentation and platform data rather than returning a list of search results. It understands what you are trying to do rather than matching keywords, so a question phrased in your terms finds the right guide even when it does not use the same words.\n\nAnswers cite the sources they came from, so you can check them. When a question is ambiguous it asks what you meant rather than guessing. When it does not have enough grounding to answer confidently it says so and routes you to support, rather than producing something plausible."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"44470b06-20bf-4e38-ba2d-79d860e00934","properties":{"alertTitle":"AI is added to the platform, never in the way of it","alertContent":"Documentation navigation, the API Reference and the Playground all work exactly as they do without the Intelligent Assistant. Semantic search improves how quickly you find things; it does not replace the deterministic route to them.","severity":"general info ","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"4ece297a-a542-4829-ad04-671fa8f47d68","properties":{"sectionText":"Connecting your own AI agents"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"80e0d94a-a3af-4eba-8023-e00d475011f2","properties":{"text":"If you run your own AI systems, they can act on TXN directly. A system that watches your operational data can adjust spend limits across card products, change operational thresholds, respond to a risk condition it has detected, or apply the same adjustment across several programs at once.\n\nThose requests come in through the Model Context Protocol. Your systems never reach TXN\u0027s internal services: MCP is the governed boundary between them, and every request passes through it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"imageSelector","id":"633525b2-4a08-4b77-a134-d568f5690f75","properties":{"darkModeImage":[{"focalPoint":null,"crops":[],"id":"adbe5efa-d708-40b5-b2a8-f7551c8e7db1","name":"Gs Ai Intelligence Governed Request Dark","mediaType":"Image","url":"/media/owkpqg1b/gs-ai-intelligence-governed-request-dark.png","extension":"png","width":2400,"height":1140,"bytes":249992,"properties":{}}],"lightModeImage":[{"focalPoint":null,"crops":[],"id":"b06088fd-2302-4f22-865d-d360ab7ef9da","name":"Gs Ai Intelligence Governed Request Light","mediaType":"Image","url":"/media/ojbcmbtl/gs-ai-intelligence-governed-request-light.png","extension":"png","width":2400,"height":1140,"bytes":247529,"properties":{}}]}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"dynamicTable","id":"eac4c3cb-d25f-429b-b3b8-4825ba5cc224","properties":{"isHeader":true,"initialDefinedRow":{"content":{"contentType":"tableRow","id":"4030530d-f984-4a12-ac17-7d3190d55cd5","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"be40c06e-80f3-4bbc-b718-d3a101e6af18","properties":{"cellContent":"Step"}},"settings":null},{"content":{"contentType":"tableCell","id":"2f7f0744-5d7e-422b-a45b-b37d2fc77514","properties":{"cellContent":"What happens"}},"settings":null}]}}},"settings":null},"tableContentDef":{"items":[{"content":{"contentType":"tableRow","id":"68481d33-a23c-4cd7-9a13-11f56c396886","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"c87c1618-dca5-4999-986b-64a16faec6ba","properties":{"cellContent":"Request"}},"settings":null},{"content":{"contentType":"tableCell","id":"eeb3b913-e1d3-4376-9930-f0f3f753113f","properties":{"cellContent":"Your AI system submits an operational request through MCP with its identity, credentials and permission scope. TXN validates that it is authorized to request that action in that scope."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"ee16838b-1ae3-4ce0-8a25-0145fdb28831","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"4e4a7e0f-42e6-47fc-8682-15a424cd6b4d","properties":{"cellContent":"Interpretation"}},"settings":null},{"content":{"contentType":"tableCell","id":"0935b70a-d485-4b9c-921c-833257a0f256","properties":{"cellContent":"MCP maps the request to the TXN API capabilities behind it, and establishes what would actually change and how widely."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"ecfb1a8c-8e0f-4053-b5f7-3b132fabde6f","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"b8d53075-b343-4196-bd41-79841b2bfaf2","properties":{"cellContent":"Governance"}},"settings":null},{"content":{"contentType":"tableCell","id":"183aa726-4f69-4029-a5c9-f8f7c16a6d0f","properties":{"cellContent":"The request is checked against role-based permissions, your program access scope, the risk classification of the action, and whether it is aimed at sandbox or production."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"e2ca059c-7b36-4c53-9461-844929d49881","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"ba1ea84a-c239-4f7e-bbba-7af4f36ecb45","properties":{"cellContent":"Approval"}},"settings":null},{"content":{"contentType":"tableCell","id":"2ccbf0c3-7a19-4fd0-b594-29564cf8346e","properties":{"cellContent":"High-impact changes are surfaced in Control Center for a named person to approve, with a summary of the change, its scope and the reason the AI system gave."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"3acddce6-e152-4fd5-b6a3-6253595cd6f7","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"baf38149-5b11-4331-8fec-8fc2b4765740","properties":{"cellContent":"Execution"}},"settings":null},{"content":{"contentType":"tableCell","id":"9bcbb250-475e-41e0-9906-49e09a5da1cf","properties":{"cellContent":"Once checks and any approval are satisfied, the action runs and the resulting state is verified."}},"settings":null}]}}},"settings":null},{"content":{"contentType":"tableRow","id":"47609f74-7f08-4e96-9d46-9351e53223d6","properties":{"rowContent":{"items":[{"content":{"contentType":"tableCell","id":"d4b208c3-f92e-4d8b-9818-07611bd8f393","properties":{"cellContent":"Audit"}},"settings":null},{"content":{"contentType":"tableCell","id":"d8d07593-7334-4d34-b7b4-9b2a8ac925c6","properties":{"cellContent":"The requesting system, any approvals, the configuration changed, the timestamp and the environment are all written to an immutable record."}},"settings":null}]}}},"settings":null}]}}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"alertDefault","id":"b578d9ff-fc6f-419c-aa21-03171a7a8fbe","properties":{"alertTitle":"High-impact changes need a person","alertContent":"An AI system can request a change to your Card Program configuration. It cannot make a high-impact one on its own. Those are routed to an authorized operator in Control Center, who sees the scope and impact before deciding. This is deliberate, and it is not configurable away.","severity":"warning","cardButton":null}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"c5b198d1-cec2-400a-b114-f773083ee064","properties":{"sectionText":"How it stays trustworthy"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"bodyText","id":"c72cbec6-15ce-4f0d-a29f-e5c1aab7cbd0","properties":{"text":"Three things hold it together. The Intelligent Assistant only ever sees data the requesting user or system is already permitted to see, so AI access cannot become a route around your permission model. Answers are grounded in authoritative platform sources rather than generated freely, which is why they can be cited. And every query, recommendation and action is logged with immutable, tamper-evident records, so any AI-initiated change can be traced back to what asked for it and who approved it."}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"sectionHeader","id":"d4b05932-77d4-47a5-b1a8-5d7bb119450f","properties":{"sectionText":"Related Reads"}},"settings":null},{"rowSpan":1,"columnSpan":12,"areaGridColumns":12,"areas":[],"content":{"contentType":"ThreeGridSystem","id":"bb16b9f0-595e-4d75-9856-b61117449e94","properties":{"enableConnector":false,"leftContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"06416de8-10ac-4681-9ccf-d36e2b66ed25","properties":{"cardTitle":"Control Center","cardText":"Where AI-initiated changes are reviewed and approved by your team.","pageLink":{"contentType":"guidePage","name":"Control Center","createDate":"2026-09-17T10:20:00.54Z","updateDate":"2026-11-15T16:32:46.61Z","route":{"path":"/103/getting-started/control-center/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dad6c052-ee94-4769-96a3-4ecef68cef59","properties":{}}}},"settings":null}]},"middleContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"da191534-6e7f-4ec1-a89c-231ff69b9b94","properties":{"cardTitle":"How TXN Works","cardText":"The four surfaces of the platform and how they fit together.","pageLink":{"contentType":"guidePage","name":"How TXN Works","createDate":"2026-09-16T10:34:03.717Z","updateDate":"2026-11-15T16:32:40.527Z","route":{"path":"/103/working-with-txn/how-txn-works/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1e283b0f-5937-4e57-87cb-9402b1cf9f3b","properties":{}}}},"settings":null}]},"rightContainer":{"items":[{"content":{"contentType":"navigationalCard","id":"670fb34c-9dbb-438c-ae2b-6126bf95d5b5","properties":{"cardTitle":"Authentication","cardText":"How systems authenticate against TXN.","pageLink":{"contentType":"guidePage","name":"Authentication","createDate":"2026-09-16T06:20:42.913Z","updateDate":"2026-11-15T16:32:43.17Z","route":{"path":"/103/getting-started/authentication/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"56e49f8f-4cd4-44d1-acca-d5cda1431fc6","properties":{}}}},"settings":null}]}}},"settings":null}]},"footerContainer":{"content":{"contentType":"footerPageNavigation","id":"7cbb1f93-8a6f-4fe8-8838-5c630ff84208","properties":{"prevPageTitle":"Control Center","nextPageTitle":"How TXN Works"}},"settings":null}},"cultures":{}},{"contentType":"guideRoot","name":"Guides","createDate":"2026-06-01T09:33:56Z","updateDate":"2026-11-16T06:51:25.057Z","route":{"path":"/guides/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"dafda755-144d-448b-91d5-9282597a9595","properties":{},"cultures":{}},{"contentType":"baseGuidePage","name":"Card Controls","createDate":"2026-09-16T06:24:05.05Z","updateDate":"2026-11-15T16:32:40.943Z","route":{"path":"/103/card-controls/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"2262786d-7a41-4c45-8bd8-aebd8a9c23a6","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"c73a26ed-825e-44c2-bbe3-25167179e66e","name":"Card Controls","mediaType":"umbracoMediaVectorGraphics","url":"/media/d4njqjkf/card-controls.svg","extension":"svg","width":null,"height":null,"bytes":8233,"properties":{}}]},"cultures":{}},{"contentType":"baseGuidePage","name":"Authentication \u0026 SCA","createDate":"2026-09-18T11:28:07.417Z","updateDate":"2026-11-15T16:32:38.947Z","route":{"path":"/103/authentication-sca/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"1a0dd32c-76a7-4072-8a09-88478505dcd2","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"daa27d01-1491-40b9-8dd1-f36c48c631d7","name":"Authentication Sca","mediaType":"umbracoMediaVectorGraphics","url":"/media/4paaaoek/authentication-sca.svg","extension":"svg","width":null,"height":null,"bytes":8143,"properties":{}}]},"cultures":{}},{"contentType":"baseGuidePage","name":"Cardholder Verification","createDate":"2026-09-18T13:01:18.273Z","updateDate":"2026-11-15T16:32:38.477Z","route":{"path":"/103/cardholder-verification/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"00fdcf90-aef7-42a8-95b6-f691c93ede5f","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"ff952237-d74c-4cc7-8765-373e9e20ee88","name":"Cardholder Verification","mediaType":"umbracoMediaVectorGraphics","url":"/media/ywpdohkx/cardholder-verification.svg","extension":"svg","width":null,"height":null,"bytes":8168,"properties":{}}]},"cultures":{}},{"contentType":"baseGuidePage","name":"Delegated Approvals","createDate":"2026-09-16T06:26:09.367Z","updateDate":"2026-11-15T16:32:45.897Z","route":{"path":"/103/delegated-approvals/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"cac083fe-ffa0-4484-b4e3-460cc0ac4bbf","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"a2ccedf3-f99f-40ff-8894-3619f9df8084","name":"Delegated Approvals","mediaType":"umbracoMediaVectorGraphics","url":"/media/afig2qee/delegated-approvals.svg","extension":"svg","width":null,"height":null,"bytes":8166,"properties":{}}]},"cultures":{}},{"contentType":"baseGuidePage","name":"Digital Wallet Tokens","createDate":"2026-11-14T13:46:40.263Z","updateDate":"2026-11-15T16:32:42.413Z","route":{"path":"/103/digital-wallet-tokens/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"ed0c7e19-e70c-401e-8990-67861dbc3606","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"ecc82513-211d-4478-8c5b-32201f69a265","name":"Digital Wallet Tokens","mediaType":"umbracoMediaVectorGraphics","url":"/media/2gmgudqg/digital-wallet-tokens.svg","extension":"svg","width":null,"height":null,"bytes":8175,"properties":{}}]},"cultures":{}},{"contentType":"baseGuidePage","name":"Staying In Sync","createDate":"2026-11-14T13:47:02.017Z","updateDate":"2026-11-15T16:32:39.62Z","route":{"path":"/103/staying-in-sync/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"17b2e586-a060-4e5e-be96-9fdd5c4a836c","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"abb5806e-ab19-459f-8ded-975e8dd6764c","name":"Staying In Sync","mediaType":"umbracoMediaVectorGraphics","url":"/media/tq4bosic/staying-in-sync.svg","extension":"svg","width":null,"height":null,"bytes":8157,"properties":{}}]},"cultures":{}},{"contentType":"baseGuidePage","name":"Going Live","createDate":"2026-11-14T09:49:53.907Z","updateDate":"2026-11-15T16:32:39.35Z","route":{"path":"/103/going-live/","queryString":null,"startItem":{"id":"dafda755-144d-448b-91d5-9282597a9595","path":"guides"}},"id":"77315748-2327-4301-bfce-43c40ef21a07","properties":{"iconPicker":[{"focalPoint":null,"crops":[],"id":"21996414-fba2-4685-9e06-bc54fa83cc0b","name":"Going Live","mediaType":"umbracoMediaVectorGraphics","url":"/media/21mdxq3z/going-live.svg","extension":"svg","width":null,"height":null,"bytes":8216,"properties":{}}]},"cultures":{}}],"baseUrl":"https://txncms.euwest01.umbraco.io"}