How the Payments-Version header works, what counts as a breaking change, and how versions roll.
The Payments API is versioned by date. A version is a contract: the shape of every request and response under that version does not change in a breaking way.
These changes ship inside the current version, without notice. Build your integration to tolerate them:
New endpoints and new resources.
New optional request parameters.
New fields in responses.
New values in response enums. Enums marked x-extensible-enum in the OpenAPI document are open: treat an unknown status, reason or error code as a value you did not plan for, not as a failure of your parser.
New error codes. Existing error codes are never renamed.
A breaking change gets a new dated version. Examples: removing or renaming a field, changing a field’s type, adding a required request parameter, changing the meaning of a status. A new version is only created when a response shape changes.Every change to the API’s OpenAPI document is checked for breaking changes before it merges.
When a second version exists, the API will keep serving the older one to callers that pin it in the header. The upgrade guide for that version will list every change and the code to update. There is only one version today, so there is nothing to upgrade.
The Commerce API (V2, https://api.tagada.io/api/public/v1) does not use Payments-Version. Its contract evolves additively. @tagadapay/node-sdk sends an X-Tagada-Api-Version header (option apiVersion), but the Commerce API does not read it today. See V2 or V3.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"TagadaPay Documentation","colors":{"primary":"#16A34A","light":"#07C983","dark":"#15803D"},"logo":{"light":"https://mintcdn.com/tagadapay/dAEln3JcPtxwff8y/logo/tagadalogo.png?fit=max\u0026auto=format\u0026n=dAEln3JcPtxwff8y\u0026q=85\u0026s=4dc2eb4eff0b0ba948b28de0226b7c95","dark":"https://mintcdn.com/tagadapay/dAEln3JcPtxwff8y/logo/tagadalogo.png?fit=max\u0026auto=format\u0026n=dAEln3JcPtxwff8y\u0026q=85\u0026s=4dc2eb4eff0b0ba948b28de0226b7c95"},"favicon":"https://mintcdn.com/tagadapay/Ps9CiAHh3vY6Nvlu/favicon.svg?fit=max\u0026auto=format\u0026n=Ps9CiAHh3vY6Nvlu\u0026q=85\u0026s=efbc04eeaada7549e650570bcfc8ce6d","api":{"playground":{}},"navbar":{"links":[{"href":"https://help.tagada.io","label":"Help Center"},{"href":"https://feedback.tagada.io/roadmap","label":"Roadmap"},{"href":"https://feedback.tagada.io/changelog","label":"Changelog"},{"href":"mailto:api-support@tagadapay.com","label":"Support"}],"primary":{"type":"button","label":"Dashboard","href":"https://crm.tagadapay.com"}},"footer":{"socials":{"website":"https://tagadapay.com","github":"https://github.com/tagadapay"}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":true},"navigation":{"global":{"anchors":[{"anchor":"Help Center","icon":"book-open","href":"https://help.tagada.io"},{"anchor":"Roadmap","icon":"map","href":"https://feedback.tagada.io/roadmap"},{"anchor":"Changelog","icon":"list","href":"https://feedback.tagada.io/changelog"},{"anchor":"Dashboard","icon":"chart-line","href":"https://crm.tagadapay.com"},{"anchor":"Support","icon":"life-ring","href":"mailto:api-support@tagadapay.com"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"tagadapay","hasAudioNarration":false,"actualSubdomain":"tagadapay","customDomains":["docs.tagada.io"],"gitSource":{"type":"gitlab","owner":"tagadapay","repo":"tagadapay-app","deployBranch":"main","contentDirectory":"mintlify","isPrivate":true,"projectId":61148103,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6ad14dd4ea0cc68b75afac77","collectionId":"e427d11d-be31-4146-98c1-2411f9694656","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6ad14dd4ea0cc68b75afac77"},"entitlements":{},"buildId":"6ae0a8dab558859ea6ffe276","clientVersion":"0.0.3971","searchFilterCounts":[{"language":"default","tag":"API Reference","count":191},{"language":"default","tag":"Developer Tools","count":95},{"language":"default","tag":"plugins-v2","count":31},{"language":"default","tag":"portal","count":22},{"language":"default","tag":"Node SDK","count":18},{"language":"default","tag":"Headless SDK","count":14},{"language":"default","tag":"Tagada Rx","count":14},{"language":"default","tag":"Plugin SDK","count":12},{"language":"default","tag":"plugins","count":11},{"language":"default","tag":"payments","count":10}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-v7-file-tree","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"pause-universal-search-reconcile","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"per-site-search-delta","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-private-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-nav-generations","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-agent-model-picker","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"isAtlas":false,"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"payments-api/versioning","slug":"/payments-api/versioning","pageMetadata":{"title":"API versions","sidebarTitle":"Versioning","description":"How the Payments-Version header works, what counts as a breaking change, and how versions roll.","icon":"code-branch","tag":"Preview","href":"/payments-api/versioning"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"How the Payments-Version header works, what counts as a breaking change, and how versions roll.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Table,Tip}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Tip)_missingMdxReference(`Tip`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`The Payments API is versioned by date. A version is a contract: the shape of every request and response under that version does not change in a breaking way.`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{}),_jsx(_components.th,{})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Current version`}),_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`2026-11-01`})})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Header`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`Payments-Version`})})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Versions accepted today`}),_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`2026-11-01`})})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`send-the-version`,children:`Send the version`}),`\n`,_jsx(_components.p,{children:`Send the version you built against on every request:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://api.tagada.io/v1/payments/pay_0123456789ab`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer tsk_test_...\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Payments-Version: 2026-11-01\"`})]}),`\n`]})})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`No header:`}),` the request runs on the current version.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`A version the API does not support:`}),` `,_jsx(_components.code,{children:`400`}),` with code `,_jsx(_components.code,{children:`parameter_invalid`}),` and `,_jsx(_components.code,{children:`param: \"Payments-Version\"`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Every response`}),` carries `,_jsx(_components.code,{children:`Payments-Version`}),` with the version that served it.`]}),`\n`]}),`\n`,_jsx(Tip,{children:_jsx(_components.p,{children:`Always send the header. Without it, your integration follows the current version, so a future version could change a response your code reads.`})}),`\n`,_jsxs(_components.p,{children:[`The official clients send the header for you: `,_jsx(_components.code,{children:`@tagadapay/core-js/payments-v3`}),` sends the version it was generated from. See `,_jsx(_components.a,{href:`/developer-tools/sdk-versions`,children:`SDK versions`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`what-is-not-a-breaking-change`,children:`What is not a breaking change`}),`\n`,_jsx(_components.p,{children:`These changes ship inside the current version, without notice. Build your integration to tolerate them:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`New endpoints and new resources.`}),`\n`,_jsx(_components.li,{children:`New optional request parameters.`}),`\n`,_jsx(_components.li,{children:`New fields in responses.`}),`\n`,_jsxs(_components.li,{children:[`New values in response enums. Enums marked `,_jsx(_components.code,{children:`x-extensible-enum`}),` in the `,_jsx(_components.a,{href:`/payments-api/reference/introduction`,children:`OpenAPI document`}),` are open: treat an unknown status, reason or error code as a value you did not plan for, not as a failure of your parser.`]}),`\n`,_jsx(_components.li,{children:`New error codes. Existing error codes are never renamed.`}),`\n`,_jsx(_components.li,{children:`A different order of fields in a response.`}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`what-is-a-breaking-change`,children:`What is a breaking change`}),`\n`,_jsx(_components.p,{children:`A breaking change gets a new dated version. Examples: removing or renaming a field, changing a field’s type, adding a required request parameter, changing the meaning of a status. A new version is only created when a response shape changes.`}),`\n`,_jsx(_components.p,{children:`Every change to the API’s OpenAPI document is checked for breaking changes before it merges.`}),`\n`,_jsx(Heading,{level:`2`,id:`how-versions-roll`,children:`How versions roll`}),`\n`,_jsx(_components.p,{children:`When a second version exists, the API will keep serving the older one to callers that pin it in the header. The upgrade guide for that version will list every change and the code to update. There is only one version today, so there is nothing to upgrade.`}),`\n`,_jsx(Heading,{level:`2`,id:`version-history`,children:`Version history`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Version`}),_jsx(_components.th,{children:`Status`}),_jsx(_components.th,{children:`Changes`})]})}),_jsx(_components.tbody,{children:_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`2026-11-01`})}),_jsx(_components.td,{children:`Current (Preview)`}),_jsx(_components.td,{children:`First version of the Payments API.`})]})})]}),`\n`,_jsx(Heading,{level:`2`,id:`v2-is-not-dated`,children:`V2 is not dated`}),`\n`,_jsxs(_components.p,{children:[`The Commerce API (V2, `,_jsx(_components.code,{children:`https://api.tagada.io/api/public/v1`}),`) does not use `,_jsx(_components.code,{children:`Payments-Version`}),`. Its contract evolves additively. `,_jsx(_components.code,{children:`@tagadapay/node-sdk`}),` sends an `,_jsx(_components.code,{children:`X-Tagada-Api-Version`}),` header (option `,_jsx(_components.code,{children:`apiVersion`}),`), but the Commerce API does not read it today. See `,_jsx(_components.a,{href:`/payments-api/v2-or-v3`,children:`V2 or V3`}),`.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"API versions","sidebarTitle":"Versioning","description":"How the Payments-Version header works, what counts as a breaking change, and how versions roll.","icon":"code-branch","tag":"Preview","href":"/payments-api/versioning"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Send the version","slug":"send-the-version","depth":2,"children":[]},{"title":"What is not a breaking change","slug":"what-is-not-a-breaking-change","depth":2,"children":[]},{"title":"What is a breaking change","slug":"what-is-a-breaking-change","depth":2,"children":[]},{"title":"How versions roll","slug":"how-versions-roll","depth":2,"children":[]},{"title":"Version history","slug":"version-history","depth":2,"children":[]},{"title":"V2 is not dated","slug":"v2-is-not-dated","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/tagadapay/81c11c0e163f81a7/utm-forward.js","/_mintlify/custom/tagadapay/d423b707fd32127b/x-pixel.js"],"subdomain":"tagadapay","siteName":"TagadaPay Documentation","title":"API versions - TagadaPay Documentation","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-27T13:36:53.382Z","originalFileLocation":"payments-api/versioning.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"How the Payments-Version header works, what counts as a breaking change, and how versions roll.\">\u003cmeta data-mint-head name=\"application-name\" content=\"TagadaPay Documentation\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/tagadapay/0wRzSlWnlFmgp7vD/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/tagadapay/0wRzSlWnlFmgp7vD/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/tagadapay/0wRzSlWnlFmgp7vD/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/tagadapay/0wRzSlWnlFmgp7vD/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/tagadapay/0wRzSlWnlFmgp7vD/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/tagadapay/0wRzSlWnlFmgp7vD/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/tagadapay/0wRzSlWnlFmgp7vD/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/tagadapay/0wRzSlWnlFmgp7vD/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/tagadapay/0wRzSlWnlFmgp7vD/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"API versions - TagadaPay Documentation\">\u003cmeta data-mint-head property=\"og:description\" content=\"How the Payments-Version header works, what counts as a breaking change, and how versions roll.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"TagadaPay Documentation\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.tagada.io/payments-api/versioning\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://tagadapay.mintlify.app/_mintlify/api/og/v2?division=Core+concepts\u0026amp;title=API+versions\u0026amp;description=How+the+Payments-Version+header+works%2C+what+counts+as+a+breaking+change%2C+and+how+versions+roll.\u0026amp;theme=4a795dedb4e93ebd54a8d8c9\u0026amp;signature=c0fe3ad659d8ef0c4ea5ae7c6cb1066264b0039f11288e09150e78d221b71eb4\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"API versions - TagadaPay Documentation\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"How the Payments-Version header works, what counts as a breaking change, and how versions roll.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://tagadapay.mintlify.app/_mintlify/api/og/v2?division=Core+concepts\u0026amp;title=API+versions\u0026amp;description=How+the+Payments-Version+header+works%2C+what+counts+as+a+breaking+change%2C+and+how+versions+roll.\u0026amp;theme=4a795dedb4e93ebd54a8d8c9\u0026amp;signature=c0fe3ad659d8ef0c4ea5ae7c6cb1066264b0039f11288e09150e78d221b71eb4\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/tagadapay/0wRzSlWnlFmgp7vD/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"TagadaPay Documentation\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#16A34A\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.tagada.io/payments-api/versioning\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/payments-api/versioning.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.tagada.io/#organization\",\"name\":\"TagadaPay Documentation\",\"url\":\"https://docs.tagada.io\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/tagadapay/dAEln3JcPtxwff8y/logo/tagadalogo.png?fit=max\u0026auto=format\u0026n=dAEln3JcPtxwff8y\u0026q=85\u0026s=4dc2eb4eff0b0ba948b28de0226b7c95\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.tagada.io#website\",\"name\":\"TagadaPay Documentation\",\"url\":\"https://docs.tagada.io\",\"publisher\":{\"@id\":\"https://docs.tagada.io/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.tagada.io/payments-api/versioning#webpage\",\"url\":\"https://docs.tagada.io/payments-api/versioning\",\"name\":\"API versions\",\"description\":\"How the Payments-Version header works, what counts as a breaking change, and how versions roll.\",\"dateModified\":\"2026-10-27T13:36:53.382Z\",\"isPartOf\":{\"@id\":\"https://docs.tagada.io#website\"},\"breadcrumb\":{\"@id\":\"https://docs.tagada.io/payments-api/versioning#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.tagada.io/payments-api/versioning#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Core concepts\",\"item\":\"https://docs.tagada.io/payments-api/authentication\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"API versions\",\"item\":\"https://docs.tagada.io/payments-api/versioning\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.tagada.io/payments-api/versioning#article\",\"headline\":\"API versions\",\"name\":\"API versions\",\"description\":\"How the Payments-Version header works, what counts as a breaking change, and how versions roll.\",\"url\":\"https://docs.tagada.io/payments-api/versioning\",\"mainEntityOfPage\":{\"@id\":\"https://docs.tagada.io/payments-api/versioning#webpage\"},\"dateModified\":\"2026-10-27T13:36:53.382Z\",\"publisher\":{\"@id\":\"https://docs.tagada.io/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.tagada.io#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"TagadaPay Documentation\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"TagadaPay Documentation","nav":{"global":{"anchors":[{"anchor":"Help Center","icon":"book-open","href":"https://help.tagada.io"},{"anchor":"Roadmap","icon":"map","href":"https://feedback.tagada.io/roadmap"},{"anchor":"Changelog","icon":"list","href":"https://feedback.tagada.io/changelog"},{"anchor":"Dashboard","icon":"chart-line","href":"https://crm.tagadapay.com"},{"anchor":"Support","icon":"life-ring","href":"mailto:api-support@tagadapay.com"}]},"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":""}]},{"tab":"Developer Tools","pages":[{"title":"Developer Tools","href":"/developer-tools"}]},{"tab":"Partners","hidden":true,"pages":[{"title":"Partners","href":"/developer-tools/partners/introduction"}]},{"tab":"Tagada Rx","pages":[{"title":"Tagada Rx","href":"/developer-tools/rx/introduction"}]},{"tab":"Payments API (V3)","groups":[{"group":"Get started","pages":[{"title":"Payments API overview","sidebarTitle":"Overview","icon":"bolt","tag":"Preview","href":"/payments-api/overview"},{"title":"V2 or V3: which one should I use?","sidebarTitle":"V2 or V3?","icon":"code-compare","href":"/payments-api/v2-or-v3"},{"title":"Migrate from V2 to the Payments API","sidebarTitle":"Migrate from V2","icon":"route","tag":"Preview","href":"/payments-api/migrate-from-v2"}]},{"group":"Core concepts","pages":[{"title":"Authentication and keys","sidebarTitle":"Authentication","description":"Secret keys for your server, publishable keys for the browser, test and live modes.","icon":"key","tag":"Preview","href":"/payments-api/authentication"},{"title":"API versions","sidebarTitle":"Versioning","icon":"code-branch","tag":"Preview","href":"/payments-api/versioning"},{"title":"Idempotent requests","sidebarTitle":"Idempotency","description":"Retry any write safely with the Idempotency-Key header.","icon":"repeat","tag":"Preview","href":"/payments-api/idempotency"},{"title":"Errors","icon":"triangle-exclamation","tag":"Preview","href":"/payments-api/errors"},{"title":"Payment lifecycle","icon":"arrows-spin","tag":"Preview","href":"/payments-api/payment-lifecycle"},{"title":"3D Secure","icon":"shield-check","tag":"Preview","href":"/payments-api/three-d-secure"},{"title":"Webhooks","icon":"webhook","tag":"Coming soon","href":"/payments-api/webhooks"}]},{"group":"Guides","pages":[{"title":"Accept a payment in the browser","sidebarTitle":"Browser client","icon":"window-maximize","tag":"Preview","href":"/payments-api/browser-client"}]},{"group":"API reference","pages":[{"title":"Payments API reference","sidebarTitle":"Introduction","icon":"book","tag":"Preview","href":"/payments-api/reference/introduction"}]},{"group":"Payments","pages":[{"title":"Create a payment","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/payments","href":"/payments-api/reference/payments/create-a-payment"},{"title":"Retrieve a payment","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/payments/{id}","href":"/payments-api/reference/payments/retrieve-a-payment"},{"title":"List payments","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/payments","href":"/payments-api/reference/payments/list-payments"},{"title":"Confirm a payment","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/payments/{id}/confirm","href":"/payments-api/reference/payments/confirm-a-payment"},{"title":"Capture an authorized payment","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/payments/{id}/capture","href":"/payments-api/reference/payments/capture-an-authorized-payment"},{"title":"Cancel a payment","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/payments/{id}/cancel","href":"/payments-api/reference/payments/cancel-a-payment"},{"title":"Retry a failed customer payment","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/payments/{id}/retry","href":"/payments-api/reference/payments/retry-a-failed-customer-payment"},{"title":"Report a finished 3DS step","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/payments/{id}/authentication","href":"/payments-api/reference/payments/report-a-finished-3ds-step"},{"title":"Read payment timeline","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/payments/{id}/timeline","href":"/payments-api/reference/payments/read-payment-timeline"}]},{"group":"Refunds","pages":[{"title":"Refund a payment","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/refunds","href":"/payments-api/reference/refunds/refund-a-payment"},{"title":"Retrieve a refund","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/refunds/{id}","href":"/payments-api/reference/refunds/retrieve-a-refund"},{"title":"List refunds","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/refunds","href":"/payments-api/reference/refunds/list-refunds"}]},{"group":"Disputes","pages":[{"title":"Retrieve a dispute on a payment","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/disputes/{id}","href":"/payments-api/reference/disputes/retrieve-a-dispute-on-a-payment"},{"title":"List disputes on payments","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/disputes","href":"/payments-api/reference/disputes/list-disputes-on-payments"}]},{"group":"Customers","pages":[{"title":"Create a customer of a store","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/customers","href":"/payments-api/reference/customers/create-a-customer-of-a-store"},{"title":"Retrieve a customer","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/customers/{id}","href":"/payments-api/reference/customers/retrieve-a-customer"},{"title":"Update a customer","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json patch /v1/customers/{id}","href":"/payments-api/reference/customers/update-a-customer"},{"title":"List customers","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/customers","href":"/payments-api/reference/customers/list-customers"}]},{"group":"Payment methods","pages":[{"title":"Create a payment method from a vault token","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/payment-methods","href":"/payments-api/reference/payment_methods/create-a-payment-method-from-a-vault-token"},{"title":"Retrieve a payment method","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/payment-methods/{id}","href":"/payments-api/reference/payment_methods/retrieve-a-payment-method"},{"title":"List a customer's payment methods","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/payment-methods","href":"/payments-api/reference/payment_methods/list-a-customers-payment-methods"},{"title":"Detach a payment method","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/payment-methods/{id}/detach","href":"/payments-api/reference/payment_methods/detach-a-payment-method"}]},{"group":"Renewal cycles","pages":[{"title":"Create a renewal cycle","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/renewal-cycles","href":"/payments-api/reference/renewal_cycles/create-a-renewal-cycle"},{"title":"Retrieve a renewal cycle","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/renewal-cycles/{id}","href":"/payments-api/reference/renewal_cycles/retrieve-a-renewal-cycle"},{"title":"List renewal cycles","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/renewal-cycles","href":"/payments-api/reference/renewal_cycles/list-renewal-cycles"},{"title":"Ask for a try now","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/renewal-cycles/{id}/try-now","href":"/payments-api/reference/renewal_cycles/ask-for-a-try-now"},{"title":"Replace the card of an open renewal cycle","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/renewal-cycles/{id}/payment-method","href":"/payments-api/reference/renewal_cycles/replace-the-card-of-an-open-renewal-cycle"},{"title":"Confirm the cardholder notice was sent","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/renewal-cycles/{id}/notice-sent","href":"/payments-api/reference/renewal_cycles/confirm-the-cardholder-notice-was-sent"},{"title":"Cancel a renewal cycle","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/renewal-cycles/{id}/cancel","href":"/payments-api/reference/renewal_cycles/cancel-a-renewal-cycle"}]},{"group":"Browser","pages":[{"title":"Get a store's publishable key, made on the first call","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/publishable-keys","href":"/payments-api/reference/publishable-keys/get-a-stores-publishable-key-made-on-the-first-call"},{"title":"Read the browser SDK configuration","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/client-config","href":"/payments-api/reference/eligibility/read-the-browser-sdk-configuration"},{"title":"List the payment methods to show","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/eligible-methods","href":"/payments-api/reference/eligibility/list-the-payment-methods-to-show"}]},{"group":"Payment policies","pages":[{"title":"Create a payment policy draft","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/payment-policies","href":"/payments-api/reference/policies/create-a-payment-policy-draft"},{"title":"Retrieve a payment policy","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/payment-policies/{id}","href":"/payments-api/reference/policies/retrieve-a-payment-policy"},{"title":"Replace a payment policy draft","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json patch /v1/payment-policies/{id}","href":"/payments-api/reference/policies/replace-a-payment-policy-draft"},{"title":"List payment policies","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/payment-policies","href":"/payments-api/reference/policies/list-payment-policies"},{"title":"Publish a payment policy version","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/payment-policies/{id}/publish","href":"/payments-api/reference/policies/publish-a-payment-policy-version"},{"title":"Assign a policy to a checkout or store default","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/payment-policies/{id}/assign","href":"/payments-api/reference/policies/assign-a-policy-to-a-checkout-or-store-default"},{"title":"List the published versions of a payment policy","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/payment-policies/{id}/versions","href":"/payments-api/reference/policies/list-the-published-versions-of-a-payment-policy"},{"title":"Build policy drafts from a store's V2 payment flows","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/payment-policies/import-v2","href":"/payments-api/reference/policies/build-policy-drafts-from-a-stores-v2-payment-flows"},{"title":"Publish a saved V2 flow import after reading its losses","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/payment-policies/import-v2/{id}/publish","href":"/payments-api/reference/policies/publish-a-saved-v2-flow-import-after-reading-its-losses"},{"title":"Retrieve the policy facts","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/policy-facts","href":"/payments-api/reference/policies/retrieve-the-policy-facts"}]},{"group":"Processors","pages":[{"title":"List processors","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/processors","href":"/payments-api/reference/processors/list-processors"},{"title":"Retrieve a processor","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/processors/{id}","href":"/payments-api/reference/processors/retrieve-a-processor"},{"title":"Refresh a processor profile","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/processors/{id}/sync","href":"/payments-api/reference/processors/refresh-a-processor-profile"},{"title":"Resume a processor","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/processors/{id}/resume","href":"/payments-api/reference/processors/resume-a-processor"},{"title":"Request a payment method","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/processors/{id}/method-requests","href":"/payments-api/reference/processors/request-a-payment-method"}]},{"group":"Block list","pages":[{"title":"Block an email, IP address or range, card or card range","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/block-list","href":"/payments-api/reference/block_list/block-an-email-ip-address-or-range-card-or-card-range"},{"title":"List block list entries","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json get /v1/block-list","href":"/payments-api/reference/block_list/list-block-list-entries"},{"title":"Lift a block","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/block-list/{id}/lift","href":"/payments-api/reference/block_list/lift-a-block"}]},{"group":"Test helpers","pages":[{"title":"Create a frozen test clock","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/test-helpers/clocks","href":"/payments-api/reference/test_helpers/create-a-frozen-test-clock"},{"title":"Advance a test clock","deprecated":null,"version":null,"openapi":"/payments-api/openapi.json post /v1/test-helpers/clocks/{id}/advance","href":"/payments-api/reference/test_helpers/advance-a-test-clock"}]}]},{"tab":"Commerce API (V2)","pages":[{"title":"Commerce API (V2)","href":"/api-reference/introduction"}]}]},"title":"API versions - TagadaPay Documentation","buildId":"dpl_DFJrtvUi8HS5F9nkooKuDJsuD5BM","deploymentId":"dpl_DFJrtvUi8HS5F9nkooKuDJsuD5BM","dynamics":[],"chunks":[]}
