Where your payment is in its lifecycle. One payment reads the same however you ask
about it.
pending: accepted and in progress. Nothing has reached the recipient yet.
finalizing: the transaction paying your recipient is on chain, but its chain has
not yet judged it final. NOT FINAL, see below.
completed: delivered and final on the destination chain.
failed: did not complete. Any funds held in escrow are returned, and error
describes what went wrong.
refunding: the settler will not deliver this payment and your funds are being
returned from escrow. NOT FINAL: it becomes refund_available or refunded, and it
can still become completed or failed.
refund_available: the settler did not deliver and the refund is authorized for you
to submit. GET /v1/payments/{paymentId}/status returns refund_signature, which you
submit to the source escrow to return your funds. The other responses report this
status without the signature. NOT FINAL: the funds are still in escrow, so it becomes
refunded once the refund lands, or completed if the settler delivers late and is
paid first. Do not pay again while it is refund_available.
refunded: your funds were returned from the source escrow. transactions.refund is
the refund transaction, when it is known.
completed, failed and refunded are final and will not change afterwards.
pending, finalizing, refunding and refund_available will.
Do not treat finalizing as delivered. It says the payment has been made on
chain but is not yet irreversible, much as a card authorization is not yet a
settlement. It normally becomes completed, after seconds on some chains and minutes
on others. If a chain reorganization drops the transaction before it is final, your
funds are refunded instead. Acting on
finalizing — releasing goods, crediting an account — means accepting that risk
deliberately, at whatever threshold suits you rather than the one we wait for.
finalizing is about paying the recipient. While your own funds are still being
committed on the source chain the payment is pending, because nothing has reached
the recipient yet.
The transactions a payment has produced, one entry per stage, added as each becomes
known. A stage absent here has produced no transaction yet.
These are the movements that decide whether your payment happened: your funds being
committed, your recipient being paid, and your funds being returned when the payment
is refunded. Present on every outcome, so a payment that did not complete can still be
traced on chain.
Where a stage is attempted more than once, the entry describes the attempt that
counts — the one that succeeded, or the last one if none did.
The winning quote's ID. Present once a quote has been awarded for this payment;
absent while the payment is still collecting or awarding. Cross-references the
quote_id returned by GET /v1/payments/quote-requests/{quoteRequestId}.
The settler-signed FulfillmentQuote for the winning quote, returned verbatim as an
opaque signed document (structurally the canonical FulfillmentQuote/v1 declaration at
https://schemas.atum.xyz/declarations/FulfillmentQuote/v1). Present once a quote has
been awarded — including after the payment completes and transactions.fulfillment is
populated, since that is precisely when a consumer verifies.
This is the PREIMAGE of the quote_hash committed on-chain in the escrow deposit and
reserve witnesses. On-chain we commit only the hash, so a quote-selector consumer
recomputes quote_hash over these bytes and compares it against the on-chain commitment
to confirm the payment settled against the quote it selected ("trust but verify"), and
verifies the settler signature over the same bytes.
quote_hash is canonicalization-based (URDNA2015), so it is stable across JSON
key-order/whitespace normalization and across JSON string-escaping differences. The
returned bytes are hash-equivalent to, but not necessarily byte-identical with, what
the settler emitted (quotes are stored as JSONB, which normalizes on write). The
gateway still never re-serializes the quote through a typed struct (that renormalizes
timestamp values and WOULD change quote_hash), so the Go binding exposes it as a raw
JSON passthrough.
The settler-signed FulfillmentAuthorization for this payment, returned verbatim as an
opaque signed document (structurally the canonical FulfillmentAuthorization/v1 declaration at
https://schemas.atum.xyz/declarations/FulfillmentAuthorization/v1; see also
#/components/schemas/FulfillmentAuthorization). The inner declaration requires
version, scheme, authorization (the signed EIP-3009 transfer, in authorization.message_prehash), fulfillment_quote_json,
and evidence (the on-chain authorizeFulfillment transaction). On the wire the settler
typically wraps that declaration in JSON-LD with @context, type, and proof — those
envelope fields ride alongside the declaration and MUST be preserved byte-for-byte.
Present when the settler authorized an originator fulfill. Until the originator
fulfills, transactions.fulfillment is absent.
The service returns these bytes verbatim and does not re-serialize through a typed
representation (which would normalize timestamps and reorder JSON-LD envelope fields).
Why a payment failed, or why its settler gave up. As error it is present only when
status is failed, as refund_reason only on the refund statuses, and it is identical
however you ask about the payment.
code is the stable, machine-readable identity of the failure — branch on it
rather than on message, which is written for a person and may be reworded.
docs_url points at the page describing that code.
Why the settler did not deliver, as it reported when it gave up. Present only when
status is refunding, refund_available or refunded, and absent when the refund
started without a reason from the settler. status decides what to do next: its
retry_classification and request_id_reusable describe the settler's error, not
this payment, and never mean paying again while it is refunding or refund_available.
Why the payment drew few or no quotes. Read from the same settler reports as the
quote-request endpoints, keyed by this payment, so a payment that failed on an expired
quote deadline can say WHY nobody funded it instead of only that nobody did.
Every declining agent is counted exactly once under its most recent reason. Empty means
no agent declined against this payment, absent means the breakdown could not be read. A
payment awarded out of a quote-request batch was bid on at quote time, so its declines
are keyed to that batch and are read from the batch's status endpoint rather than here.
As on the quote-request endpoints, the free-form decline detail is never relayed.
Show child attributes
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Atum Docs","description":"Documentation for Atum, an open payments network for tokenized-currency payments. You submit a signed payment request; Atum selects a settlement operator's price quote, the operator delivers on the destination rail, and Atum verifies delivery.","colors":{"primary":"#24450d","light":"#b3e78d","dark":"#7fcb49"},"logo":{"light":"https://mintcdn.com/atumlabs/eBwMdhd0uJ6cwbY0/images/assets/wordmark-light.svg?fit=max\u0026auto=format\u0026n=eBwMdhd0uJ6cwbY0\u0026q=85\u0026s=6ba7458a7e4528e698e48cbf8e15c375","dark":"https://mintcdn.com/atumlabs/eBwMdhd0uJ6cwbY0/images/assets/wordmark-dark.svg?fit=max\u0026auto=format\u0026n=eBwMdhd0uJ6cwbY0\u0026q=85\u0026s=023ac107f39c390813f415746157f405"},"favicon":"https://mintcdn.com/atumlabs/eBwMdhd0uJ6cwbY0/favicon.svg?fit=max\u0026auto=format\u0026n=eBwMdhd0uJ6cwbY0\u0026q=85\u0026s=0d5cc391c59a2f5739384e8520536a1a","api":{"playground":{"display":"simple"}},"appearance":{"default":"dark"},"background":{"color":{"light":"#f1f0e9","dark":"#171d15"}},"navbar":{"primary":{"type":"button","label":"Community chat","href":"https://discord.gg/a5mbNjnDNj"}},"footer":{"socials":{"discord":"https://discord.gg/a5mbNjnDNj"},"links":[{"header":"Legal","items":[{"label":"Privacy Policy","href":"https://atum.xyz/privacy-policy"}]}]},"fonts":{"heading":{"family":"Newsreader"},"body":{"family":"Public Sans"}},"styling":{"codeblocks":{"theme":"github-dark"},"latex":false},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"interaction":{"drilldown":false},"variables":{"paymentGatewayTestnet":"https://payment-gw.production-testnet.atum.xyz","paymentGatewayMainnet":"https://payment-gw.production-mainnet.atum.xyz","x402FacilitatorTestnet":"https://payment-gw.production-testnet.atum.xyz/x402/v1","x402FacilitatorMainnet":"https://payment-gw.production-mainnet.atum.xyz/x402/v1","veriFillTestnet":"https://veri-fill.production-testnet.atum.xyz","veriFillMainnet":"https://veri-fill.production-mainnet.atum.xyz"},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"atumlabs","hasAudioNarration":false,"actualSubdomain":"atumlabs","customDomains":["docs.atum.xyz"],"gitSource":{"type":"github","owner":"atum-labs","repo":"atum-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6ae8b017ca78e468455a2e68","collectionId":"f90bb902-a0bb-4b51-a5f6-05f506a97595","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6ae8b017ca78e468455a2e68"},"feedback":{"thumbs":true,"agentFeedback":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6aed33e649d4102da1fae20b","clientVersion":"0.0.4076","searchFilterCounts":[{"language":"default","tag":"Get started","count":35},{"language":"default","tag":"Overview","count":24},{"language":"default","tag":"Settle payments","count":21},{"language":"default","tag":"API Reference","count":17},{"language":"default","tag":"Core concepts","count":15},{"language":"default","tag":"Start building","count":14},{"language":"default","tag":"Payment protocols","count":13},{"language":"default","tag":"Payment Gateway","count":8},{"language":"default","tag":"Settlement Reference","count":6},{"language":"default","tag":"Configuration","count":6}]},"assistantConfig":{},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"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":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","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":"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":"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":"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":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","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":"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":"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":"turbopuffer-dual-write","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},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"comment-mode","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"privacy":{"consentBanner":{"enabled":true}},"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":"@import url(\"https://fonts.googleapis.com/css2?family=Host+Grotesk:wght@300..800\u0026display=swap\");@import url(\"https://use.typekit.net/xnt1dnq.css\");:root{--color-dark-charcoal: #2b2a28;--color-tofu: #f1f0e9;--color-tofu-light: #f1efe7;--color-young-green: #97e162;--color-young-green-deep: #7fcb49;--color-green-house: #24450d;--color-dark-teal: #2f6460;--color-pale-green: #f0fbe8;--color-full-white: #ffffff;--color-dark-charcoal-12: rgb(43 42 40 / 12%);--color-dark-charcoal-40: rgb(43 42 40 / 40%);--color-dark-charcoal-65: rgb(43 42 40 / 65%);--ink: #171d15;--ink-2: #1e261c;--ink-line: #2c342b;--ink-muted: #9aa396;--ink-dim: #6b7266;--ink-green: #b3e78d;--ink-fg: #f7f6f2;--font-display: \"hardcover-vf\", \"Newsreader\", \"Iowan Old Style\", Georgia, serif;--font-ui: \"Host Grotesk\", \"host-grotesk\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", sans-serif;--font-prose: \"Public Sans\", \"public-sans\", var(--font-ui);--font-mono: ui-monospace, \"SF Mono\", SFMono-Regular, Menlo, Consolas, monospace;--ring: 0 0 0 3px rgb(151 225 98 / 45%);--radius-field: 6px;--fg: var(--color-dark-charcoal);--fg-2: #3a3936;--fg-3: #605f5b;--fg-muted: #83827c;--fg-dim: #b0afa8;--bg: var(--color-tofu);--bg-nav: var(--color-tofu);--hairline: var(--color-dark-charcoal-12);--surface: var(--color-full-white);--surface-line: var(--color-dark-charcoal-12);--label-fg: var(--color-dark-charcoal-65);--link-fg: var(--color-dark-teal);--link-hover: var(--color-green-house);--accent-text: var(--color-green-house);--inline-code-bg: var(--color-full-white);--ok-fg: var(--color-green-house);--ok-bg: var(--color-pale-green);--ok-line: rgb(36 69 13 / 22%);--info-fg: var(--color-dark-teal);--info-bg: #e9f0ef;--info-line: rgb(47 100 96 / 25%);--warn-fg: #7a4e00;--warn-bg: #fbf3e0;--warn-line: rgb(122 78 0 / 25%);--err-fg: #9b2c2c;--err-bg: #fbeae7;--err-line: rgb(155 44 44 / 25%);--muted-fg: var(--color-dark-charcoal-65);--muted-line: var(--color-dark-charcoal-12);--shadow-lg: 0 24px 48px rgb(43 42 40 / 18%)}html.dark{--fg: var(--ink-fg);--fg-2: #e3e4dd;--fg-3: #c9ccc2;--fg-muted: var(--ink-muted);--fg-dim: var(--ink-dim);--bg: var(--ink);--bg-nav: var(--ink-2);--hairline: var(--ink-line);--surface: var(--ink-2);--surface-line: var(--ink-line);--label-fg: var(--ink-muted);--link-fg: var(--ink-green);--link-hover: var(--color-young-green);--accent-text: var(--ink-green);--inline-code-bg: var(--ink-2);--ok-fg: var(--ink-green);--ok-bg: rgb(151 225 98 / 12%);--ok-line: rgb(151 225 98 / 35%);--info-fg: #9fd3ce;--info-bg: rgb(47 100 96 / 25%);--info-line: rgb(47 100 96 / 60%);--warn-fg: #f0c674;--warn-bg: rgb(122 78 0 / 28%);--warn-line: rgb(240 198 116 / 40%);--err-fg: #f3b7b7;--err-bg: rgb(155 44 44 / 30%);--err-line: rgb(243 183 183 / 40%);--muted-fg: var(--ink-muted);--muted-line: var(--ink-line);--shadow-lg: 0 24px 48px rgb(0 0 0 / 45%)}body{-webkit-font-smoothing:antialiased;font-family:var(--font-ui)}::selection{background:var(--color-young-green);color:var(--color-dark-charcoal)}:root{--gray-50: 247 246 242;--gray-100: 241 239 231;--gray-200: 229 228 221;--gray-300: 215 214 207;--gray-400: 176 175 168;--gray-500: 131 130 124;--gray-600: 96 95 91;--gray-700: 58 57 54;--gray-800: 43 42 40;--gray-900: 30 29 27;--gray-950: 21 20 18}html.dark{--gray-50: 247 246 242;--gray-100: 227 228 221;--gray-200: 201 204 194;--gray-300: 181 185 174;--gray-400: 154 163 150;--gray-500: 107 114 102;--gray-600: 76 84 73;--gray-700: 58 67 56;--gray-800: 44 52 43;--gray-900: 30 38 28;--gray-950: 23 29 21}#content,#content .prose,#header .prose{font-family:var(--font-prose);font-weight:400}#content a.link,#header .prose a{color:var(--link-fg);border-bottom:0;text-decoration:underline;text-decoration-thickness:1px;text-underline-offset:2px}#content a.link:hover,#header .prose a:hover{color:var(--link-hover)}#page-title,#content h1,#content h2:not([data-component-part]),#content h3:not([data-component-part]){font-family:var(--font-display);font-weight:300;letter-spacing:-0.02em;color:var(--fg)}#content h4,#content h5,#content h6{font-family:var(--font-ui);font-weight:600;letter-spacing:-0.01em;color:var(--fg)}#page-title{font-size:clamp(2rem, 4vw, 2.75rem);line-height:1.08}#page-title::before{content:\"\";display:block;width:28px;height:3px;margin-bottom:16px;background:var(--color-young-green)}#page-title code{font:500 0.68em/1 var(--font-mono);letter-spacing:0;background:transparent;border:0;padding:0;vertical-align:0.06em}#content h2:not([data-component-part]){font-size:1.75rem;margin-top:2.5rem;padding-top:1.25rem;border-top:1px solid var(--hairline)}#content h2#overview:not([data-component-part]){margin-top:0;padding-top:0;border-top:0}#content h3:not([data-component-part]){font-size:1.35rem}#content :is(h2,h3,h4)>div>a>div{background:transparent;box-shadow:none;--tw-ring-color: transparent;color:var(--label-fg)}#content :is(h2,h3,h4)>div>a>div svg{display:none}#content :is(h2,h3,h4)>div>a>div::before{content:\"¶\";font:400 0.9rem/1 var(--font-ui)}#content :is(h2,h3,h4)>div>a:hover>div::before{color:var(--color-young-green-deep)}#header .prose p{font-family:var(--font-prose);font-weight:300;color:var(--fg-3)}.eyebrow{font:600 10.5px/1.3 var(--font-mono);letter-spacing:0.08em;text-transform:uppercase;color:var(--accent-text)!important;height:auto}.sidebar-group-header,#table-of-contents h2 button,#content th{font:600 10.5px/1.3 var(--font-mono)!important;letter-spacing:0.08em;text-transform:uppercase;color:var(--label-fg)!important}#navbar>div:first-child{background:var(--bg-nav)!important;border-bottom:1px solid var(--hairline)!important;backdrop-filter:none}#navbar a:has(img.nav-logo){display:inline-flex;align-items:center;gap:12px;text-decoration:none;white-space:nowrap}#navbar img.nav-logo,#footer img.nav-logo{height:20px!important;width:auto!important;max-width:none}#navbar a:has(img.nav-logo)::after{content:\"Docs\";display:inline-block;font:600 10.5px/1 var(--font-mono);letter-spacing:0.08em;text-transform:uppercase;color:var(--label-fg);border:1px solid var(--surface-line);border-radius:999px;padding:6px 10px;white-space:nowrap}@media (max-width: 50rem){#navbar a:has(img.nav-logo)::after{display:none}}#navbar .nav-tabs-item,#navbar .navbar-link,#navbar a,#navbar button{font-family:var(--font-ui)}#navbar .nav-tabs-item{font-weight:500;text-shadow:none!important}#navbar .nav-tabs-item[class*=\"text-gray-800\"]{color:var(--fg)}#navbar .nav-tabs-item>div[class*=\"bg-primary\"],#navbar .nav-tabs-item>span[class*=\"bg-primary\"]{background:var(--color-young-green)!important}#search-bar-entry,#search-bar-entry-mobile{background:var(--surface)!important;border:1px solid var(--surface-line);border-radius:999px;color:var(--label-fg);box-shadow:none!important;--tw-ring-color: transparent !important;filter:none!important}#search-bar-entry:hover{border-color:var(--color-dark-charcoal-40)}html.dark #search-bar-entry:hover{border-color:var(--ink-dim)}#search-bar-entry kbd{background:transparent;border:1px solid var(--surface-line);font-family:var(--font-mono)}#topbar-cta-button a{font-family:var(--font-ui);font-weight:500;letter-spacing:-0.01em}#topbar-cta-button a>span[class*=\"absolute\"]{background:var(--color-young-green)!important;border-radius:999px!important;opacity:1!important}#topbar-cta-button a:hover>span[class*=\"absolute\"]{background:var(--color-young-green-deep)!important}#topbar-cta-button a span[class*=\"text-white\"],#topbar-cta-button a svg{color:var(--color-dark-charcoal)!important}#sidebar{border-inline-end:1px solid var(--hairline)}.sidebar-group-header{padding-top:0.4rem;padding-bottom:0.4rem}#sidebar-content a,#sidebar-content button{font-family:var(--font-ui);border-radius:0!important}#sidebar-content a{color:var(--fg-3)}#sidebar-content a[aria-current=\"page\"],#sidebar-content a[aria-current=\"page\"]:hover,#sidebar-content a[aria-current=\"page\"]:focus{background:transparent!important;box-shadow:inset 3px 0 0 var(--color-young-green);color:var(--fg)!important;font-weight:500;text-shadow:none!important}#sidebar-content a:hover:not([aria-current=\"page\"]){background:transparent!important;color:var(--fg);box-shadow:inset 3px 0 0 var(--hairline)}#sidebar-content [class*=\"border-l\"],#sidebar-content ul ul{border-color:var(--hairline)}#table-of-contents-layout{border-inline-start:1px solid var(--hairline)}#table-of-contents a{font-family:var(--font-ui);color:var(--fg-3);text-shadow:none!important}#table-of-contents li[data-active]>a{color:var(--fg)!important;font-weight:500}#table-of-contents h2 button svg{color:var(--label-fg)}#page-context-menu>button,#page-context-menu>div>button{background:var(--surface)!important;border-color:var(--surface-line)!important;color:var(--fg);font:500 13px/1.2 var(--font-ui);letter-spacing:-0.01em}#page-context-menu>button:first-child{border-radius:999px 0 0 999px!important}#page-context-menu>:last-child,#page-context-menu>:last-child button{border-radius:0 999px 999px 0!important}#page-context-menu button:hover{border-color:var(--color-young-green-deep)!important}.code-block,.code-block [data-component-part=\"code-block-root\"],.code-block pre.shiki,.code-group{border-radius:0!important;box-shadow:none!important}.code-block{border:1px solid var(--ink-line);background-color:var(--ink)!important;--tw-ring-color: transparent !important}.code-block [data-component-part=\"code-block-root\"],.code-block pre.shiki,.code-block pre.shiki code{background-color:var(--ink)!important;--shiki-dark-bg: var(--ink) !important;color:var(--ink-fg)}.code-block pre.shiki,.code-block pre.shiki code,.code-block .font-mono{font-family:var(--font-mono)!important;font-size:0.85rem;line-height:1.65}.code-block pre.shiki ::selection{background:rgb(151 225 98 / 30%);color:inherit}.code-block [data-component-part=\"code-block-header\"],.code-group>div:first-child{background:var(--ink-2)!important;border-bottom:1px solid var(--ink-line);border-radius:0!important;color:var(--ink-muted);font:500 0.75rem/1.4 var(--font-ui)}.code-group [role=\"tab\"][aria-selected=\"true\"]{color:var(--ink-fg)!important;box-shadow:inset 0 2px 0 var(--color-young-green)}.code-block-copy-button button,.code-block [data-floating-buttons] button{border-radius:999px!important;background:var(--ink-2)!important;border:1px solid var(--ink-line);color:#c9ccc2!important}.code-block [data-floating-buttons] button:hover{border-color:var(--color-young-green-deep)}#ask-assistant-code-block-button{border-radius:999px!important}#content code:not(pre code),#header .prose code{font-family:var(--font-mono);font-size:0.86em;font-weight:500;color:var(--fg)!important;background:var(--inline-code-bg)!important;border:1px solid var(--surface-line);border-radius:4px;padding:0.1em 0.35em}#content code:not(pre code)::before,#content code:not(pre code)::after{content:none}#content .callout{position:relative;display:grid;grid-template-columns:16px minmax(0, 1fr);column-gap:0.55rem;row-gap:0.45rem;align-items:center;margin-block:1.25rem;padding:0.9rem 1.1rem 0.9rem 1.25rem;border:1px solid var(--aside-line)!important;border-inline-start:3px solid var(--aside-rule)!important;border-radius:0!important;background:var(--aside-bg)!important;color:var(--fg)!important;--aside-rule: var(--color-dark-teal);--aside-fg: var(--info-fg);--aside-bg: var(--info-bg);--aside-line: var(--info-line);--aside-glyph: \"i\";--aside-badge-fg: #fff}#content .callout[data-callout-type=\"tip\"],#content .callout[data-callout-type=\"check\"]{--aside-rule: var(--color-young-green-deep);--aside-fg: var(--ok-fg);--aside-bg: var(--ok-bg);--aside-line: var(--ok-line);--aside-glyph: \"✓\";--aside-badge-fg: var(--color-dark-charcoal)}#content .callout[data-callout-type=\"warning\"]{--aside-rule: #d99a2b;--aside-fg: var(--warn-fg);--aside-bg: var(--warn-bg);--aside-line: var(--warn-line);--aside-glyph: \"!\"}#content .callout[data-callout-type=\"danger\"]{--aside-rule: #c94c4c;--aside-fg: var(--err-fg);--aside-bg: var(--err-bg);--aside-line: var(--err-line);--aside-glyph: \"✕\"}#content .callout>[data-component-part=\"callout-icon\"]{grid-column:1;grid-row:1;width:16px;height:16px;margin:0;border-radius:999px;background:var(--aside-rule);color:var(--aside-badge-fg);font:700 10px/16px var(--font-ui);text-align:center}#content .callout>[data-component-part=\"callout-icon\"] svg{display:none}#content .callout>[data-component-part=\"callout-icon\"]::before{content:var(--aside-glyph)}#content .callout::before{content:attr(aria-label);grid-column:2;grid-row:1;font:600 10.5px/1.3 var(--font-mono);letter-spacing:0.08em;text-transform:uppercase;color:var(--aside-fg)}#content .callout>[data-component-part=\"callout-content\"]{grid-column:1 / -1;grid-row:2;color:var(--fg)!important;font-size:0.875rem;line-height:1.6}#content .callout a{color:var(--link-fg)!important;border-color:currentColor}#content .callout a:hover{color:var(--link-hover)!important}#content .callout strong{color:var(--fg)!important}#content .callout code:not(pre code){background:var(--surface)!important}#content .card,.card{position:relative;border-radius:0!important;background:var(--surface)!important;border:1px solid var(--surface-line)!important;box-shadow:none!important;--tw-ring-color: transparent !important;transition:border-color 0.15s}.card::before{content:\"\";position:absolute;top:10px;left:10px;width:5px;height:5px;background:var(--surface-line);z-index:1}.card:hover{border-color:var(--color-young-green-deep)!important}.card h2,.card h3,.card [class*=\"font-semibold\"]{font-family:var(--font-ui);font-weight:600;letter-spacing:-0.01em;color:var(--fg)}.card [data-component-part=\"card-icon\"] svg,.card svg[style*=\"mask\"]{background-color:var(--accent-text)}details.accordion,.accordion-group{border-radius:0!important;border:1px solid var(--surface-line)!important;background:var(--surface)!important;box-shadow:none!important}.accordion-group details.accordion{border:0!important;border-top:1px solid var(--surface-line)!important}.accordion-group details.accordion:first-child{border-top:0!important}details.accordion>summary{font:500 0.875rem/1.4 var(--font-ui);color:var(--fg);background:transparent!important}details.accordion>summary:hover{color:var(--link-hover)}details.accordion>summary [data-component-part=\"accordion-title\"]{font:inherit;color:inherit}details.accordion>summary [data-component-part=\"accordion-caret-right\"]{color:var(--color-young-green-deep)}details.accordion>summary::after{content:\"show\";margin-left:auto;font:600 10.5px/1 var(--font-mono);letter-spacing:0.08em;text-transform:uppercase;color:var(--label-fg)}details.accordion[open]>summary::after{content:\"hide\"}details.accordion[open]>summary{border-bottom:1px solid var(--surface-line)}details.accordion>[data-component-part=\"accordion-content\"]{padding-top:0.9rem}.tabs [role=\"tablist\"]{border-color:var(--hairline)!important}.tabs [data-component-part=\"tab-button\"]{font-family:var(--font-ui);font-weight:500;color:var(--fg-3)}.tabs [data-component-part=\"tab-button\"][data-active=\"true\"]{color:var(--fg)!important;border-color:var(--color-young-green)!important;border-bottom-width:2px}.steps [data-component-part=\"step-indicator\"]{background:var(--surface)!important;border:1px solid var(--surface-line);color:var(--fg)!important;font:600 11px/1 var(--font-mono)}.steps [data-component-part=\"step-line\"]{background:var(--hairline)!important}.steps [data-component-part=\"step-title\"]{font-family:var(--font-ui);font-weight:600;letter-spacing:-0.01em;color:var(--fg)!important}#content table{font-family:var(--font-ui);font-size:0.875rem;border-collapse:collapse}#content th,#content td{border:0;border-bottom:1px solid var(--hairline);padding:0.6rem 1rem 0.6rem 0;vertical-align:top}#content th{white-space:nowrap}#content tr:nth-child(2n){background:transparent}#content tbody tr:hover{background:transparent}.frame,#content img,.expandable,.tile{border-radius:0!important}.frame{background:var(--surface)!important;border:1px solid var(--surface-line)!important;box-shadow:none!important}#pagination{font-family:var(--font-ui);font-weight:500}#pagination [data-component-part=\"pagination-title\"]{color:var(--fg-3)}#pagination a:hover [data-component-part=\"pagination-title\"]{color:var(--fg)!important}.feedback-toolbar button,#feedback-thumbs-up,#feedback-thumbs-down{border-radius:999px!important;border:1px solid var(--surface-line);background:var(--surface);color:var(--fg-3)}.method-pill,.method-nav-pill{font-family:var(--font-mono);letter-spacing:0.04em;border-radius:999px!important}#footer{background:var(--bg-nav);border-top:1px solid var(--hairline)!important;font-family:var(--font-ui);position:relative;z-index:25}#footer .footer-inner>.h-px,#footer .footer-inner>[class*=\"h-[1px]\"]{display:none!important}#footer .footer-inner,footer .footer-inner{max-width:none!important;width:100%;padding-top:1.25rem!important;padding-bottom:1.25rem!important;gap:0!important}#footer .footer-divider,footer .footer-divider{display:none!important}#footer .footer-mintlify,footer .footer-mintlify{display:flex!important;flex-direction:row!important;align-items:center!important;justify-content:flex-end!important;gap:0.75rem!important;flex:0 0 auto!important;width:auto!important;min-width:0!important}#footer .footer-row,footer .footer-row{display:flex!important;flex-direction:row!important;flex-wrap:wrap;align-items:center!important;justify-content:flex-start!important;gap:1rem 1.5rem!important;width:100%}#footer .footer-row>:not(.audited-by),footer .footer-row>:not(.audited-by){flex:0 0 auto!important;min-width:0!important;max-width:none!important;width:auto!important}#footer .footer-row>:nth-child(3),footer .footer-row>:nth-child(3){margin-left:auto}.audited-by{display:flex;flex-wrap:nowrap;align-items:center;justify-content:flex-start;gap:0.75rem 1rem;flex:0 0 auto;width:auto;min-width:0;padding:0}.audited-by-label{font:600 10.5px/1.3 var(--font-mono);letter-spacing:0.08em;text-transform:uppercase;color:var(--label-fg);text-decoration:none;box-shadow:none}a.audited-by-label:hover{color:var(--fg);opacity:1}.audited-by a[data-auditor]{display:inline-flex;align-items:center;line-height:0;opacity:0.9;text-decoration:none;box-shadow:none}.audited-by a[data-auditor] button,.audited-by a[data-auditor]+button,.audited-by button{display:none}.audited-by a[data-auditor]:hover{opacity:1}.audited-by-logo{width:auto;max-width:none}.audited-by a[data-auditor=\"cantina\"] .audited-by-logo{height:22px}.audited-by a[data-auditor=\"cyfrin\"] .audited-by-logo{height:28px}.audited-by .logo-dark{display:none}.dark .audited-by .logo-light,[data-theme=\"dark\"] .audited-by .logo-light{display:none}.dark .audited-by .logo-dark,[data-theme=\"dark\"] .audited-by .logo-dark{display:block}.pay-timeline{--p1: 12.5%;--p2: 37.5%;--p3: 62.5%;--p4: 87.5%;--rail: var(--fg-dim);--dot-event: var(--fg);--dot-quote: var(--warn-fg);--dot-delivery: var(--err-fg);--bar-quote: var(--ok-fg);--bar-process: var(--warn-fg);--bar-settle: var(--info-fg);margin:1.25rem 0 1.5rem;padding:1.5rem 1.25rem 1.2rem;background:var(--surface);border:1px solid var(--surface-line);border-radius:16px}.pay-timeline-title{margin:0 0 1.75rem;text-align:center;font-family:var(--font-ui);font-size:1.05rem;font-weight:600;color:var(--fg)}.pay-timeline-stage{position:relative;height:196px}.pay-timeline-label,.pay-timeline-caption{position:absolute;margin:0;transform:translateX(-50%);text-align:center;font-family:var(--font-ui);font-weight:500;line-height:1.25}.pay-timeline-label{top:0;font-size:0.78rem;color:var(--fg-2)}.pay-timeline-label--1{left:var(--p1)}.pay-timeline-label--2{left:var(--p2)}.pay-timeline-label--3{left:var(--p3)}.pay-timeline-label--4{left:var(--p4)}.pay-timeline-guide{position:absolute;top:36px;bottom:52px;width:0;border-left:1px dashed var(--fg-dim)}.pay-timeline-guide--1{left:var(--p1)}.pay-timeline-guide--2{left:var(--p2);border-left-color:var(--dot-quote)}.pay-timeline-guide--3{left:var(--p3);border-left-color:var(--dot-delivery)}.pay-timeline-guide--4{left:var(--p4)}.pay-timeline-rail{position:absolute;top:70px;left:var(--p1);width:calc(var(--p4) - var(--p1));height:3px;background:var(--rail);border-radius:2px}.pay-timeline-dot{position:absolute;top:64px;z-index:2;width:14px;height:14px;border-radius:50%;transform:translateX(-50%);background:var(--dot-event)}.pay-timeline-dot--1{left:var(--p1)}.pay-timeline-dot--2{left:var(--p2);background:var(--dot-quote)}.pay-timeline-dot--3{left:var(--p3);background:var(--dot-delivery)}.pay-timeline-dot--4{left:var(--p4)}.pay-timeline-bar{position:absolute;top:92px;height:14px;border-radius:3px}.pay-timeline-bar--quote{left:var(--p1);width:calc(var(--p2) - var(--p1));background:var(--bar-quote)}.pay-timeline-bar--process{left:var(--p2);width:calc(var(--p3) - var(--p2));background:var(--bar-process)}.pay-timeline-bar--settle{left:var(--p3);width:calc(var(--p4) - var(--p3));background:var(--bar-settle)}.pay-timeline-caption{top:114px;font-size:0.75rem;color:var(--fg-3)}.pay-timeline-caption--quote{left:calc((var(--p1) + var(--p2)) / 2)}.pay-timeline-caption--process{left:calc((var(--p2) + var(--p3)) / 2)}.pay-timeline-caption--settle{left:calc((var(--p3) + var(--p4)) / 2)}.pay-timeline-note{margin:0.5rem 0 0;text-align:left;font-family:var(--font-ui);font-size:0.86rem;line-height:1.45;color:var(--fg-3)}.pay-timeline-note p{margin:0}.pay-timeline-note ul{margin:0.4rem 0 0;padding-left:1.15rem}.pay-timeline-note li{margin:0.35rem 0 0}.pay-timeline-note li:first-child{margin-top:0}.changelog-toc{margin:0.25rem 0 0.5rem 1.75rem;padding-left:0.75rem;border-left:1px solid var(--surface-line);list-style:none}.changelog-toc-date{margin:0.6rem 0 0.2rem;font-family:var(--font-ui);font-size:0.72rem;letter-spacing:0.04em;color:var(--fg-muted)}.changelog-toc-date:first-child{margin-top:0.2rem}.changelog-toc a{display:block;padding:0.2rem 0;font-size:0.82rem;line-height:1.35;color:var(--fg-2)}.changelog-toc a:hover{color:var(--accent-text)}.update-container [data-component-part=\"update-tag\"]{padding:0.1rem 0.55rem;border:1px solid var(--surface-line);border-radius:999px;font-family:var(--font-ui);font-size:0.78rem;white-space:nowrap;color:var(--fg-2);cursor:pointer;transition:border-color 120ms ease, color 120ms ease}.update-container [data-component-part=\"update-tag\"]:hover{border-color:var(--accent-text);color:var(--accent-text)}.update-container [data-component-part=\"update-tag\"][aria-pressed=\"true\"]{border-color:rgb(var(--primary));background:rgb(var(--primary));color:rgb(255 255 255 / 0.9)}.update-container [data-component-part=\"update-tag\"]:focus-visible{outline:none;box-shadow:var(--ring)}@media (min-width: 1280px){[class*=\"max-w-8xl\"]{max-width:1600px!important}body:has(#table-of-contents,#changelog-filters) #content-area{width:calc(100% - 20rem)!important;max-width:none!important}}#header :is(h1,p),#content :is(p,ul,ol,blockquote,h1,h2,h3,h4,h5,h6):not(td *,th *,li *){max-width:38em}@media (min-width: 1024px){.update-container>div:first-child{width:150px!important}}.update-container .prose-sm{font-size:1rem;line-height:1.75}"}],"page":{"pagePath":"api-reference/payment-gateway/get-payment-status","slug":"/api-reference/payment-gateway/get-payment-status","pageMetadata":{"title":"Get payment status","description":"Poll a payment's current status by payment_id: pending, finalizing, completed, failed, or one of the refund statuses.","openapi":"GET /v1/payments/{paymentId}/status","href":"/api-reference/payment-gateway/get-payment-status"},"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: \"Poll a payment’s current status by payment_id: pending, finalizing, completed, failed, or one of the refund statuses.\"\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}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"codeStyling":{"theme":"github-dark"},"config":{},"pageMetadata":{"title":"Get payment status","description":"Poll a payment's current status by payment_id: pending, finalizing, completed, failed, or one of the refund statuses.","openapi":"GET /v1/payments/{paymentId}/status","href":"/api-reference/payment-gateway/get-payment-status"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":["/_mintlify/custom/atumlabs/ea8598561a186193/audited-by.js","/_mintlify/custom/atumlabs/946086a3f73c7db3/webmcp.js","/_mintlify/custom/atumlabs/28a7e63cae1e14fd/changelog-tags.js","/_mintlify/custom/atumlabs/f97675e153f577c9/changelog-toc.js"],"openApiReferenceData":{"operation":{"summary":"Get payment status","description":"Poll a payment's current status by payment_id: pending, finalizing, completed, failed, or one of the refund statuses.","operationId":"getPaymentStatus","tags":["Payments"],"parameters":["8d812513-12ee-430d-8ac1-6229d2a17f39"],"responses":{"200":"fdfcb87e-621b-46dd-8073-4c654ab28fe6","404":"1c6e6fe0-67fd-473e-86e6-5203ca6ef1fd","500":"797eff3c-061c-47d0-9c67-7d55a84ed55a"},"method":"get","type":"path","servers":["33df3309-b84e-48a9-94c1-aac200cf674f","fa558170-4e9e-4663-9e9b-39906523216e"],"security":[],"path":"/v1/payments/{paymentId}/status","baseUrlOptions":["https://payment-gw.production-mainnet.atum.xyz","https://payment-gw.production-testnet.atum.xyz"],"title":"Get payment status","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"8d812513-12ee-430d-8ac1-6229d2a17f39":{"name":"paymentId","in":"path","required":true,"description":"The ID of the payment to query","schema":{"type":"string","isRequired":true,"description":"The ID of the payment to query","uniqueKey":"","typeLabel":"string"}}},"responses":{"fdfcb87e-621b-46dd-8073-4c654ab28fe6":{"description":"Payment status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"payment_id":{"type":"string","description":"The payment ID you're checking status for.\n","example":"0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f","uniqueKey":"payment_id","typeLabel":"string"},"status":{"type":"string","description":"Where your payment is in its lifecycle. One payment reads the same however you ask\nabout it.\n\n- `pending`: accepted and in progress. Nothing has reached the recipient yet.\n- `finalizing`: the transaction paying your recipient is on chain, but its chain has\n not yet judged it final. NOT FINAL, see below.\n- `completed`: delivered and final on the destination chain.\n- `failed`: did not complete. Any funds held in escrow are returned, and `error`\n describes what went wrong.\n- `refunding`: the settler will not deliver this payment and your funds are being\n returned from escrow. NOT FINAL: it becomes `refund_available` or `refunded`, and it\n can still become `completed` or `failed`.\n- `refund_available`: the settler did not deliver and the refund is authorized for you\n to submit. GET /v1/payments/{paymentId}/status returns `refund_signature`, which you\n submit to the source escrow to return your funds. The other responses report this\n status without the signature. NOT FINAL: the funds are still in escrow, so it becomes\n `refunded` once the refund lands, or `completed` if the settler delivers late and is\n paid first. Do not pay again while it is `refund_available`.\n- `refunded`: your funds were returned from the source escrow. `transactions.refund` is\n the refund transaction, when it is known.\n\n`completed`, `failed` and `refunded` are final and will not change afterwards.\n`pending`, `finalizing`, `refunding` and `refund_available` will.\n\n**Do not treat `finalizing` as delivered.** It says the payment has been made on\nchain but is not yet irreversible, much as a card authorization is not yet a\nsettlement. It normally becomes `completed`, after seconds on some chains and minutes\non others. If a chain reorganization drops the transaction before it is final, your\nfunds are refunded instead. Acting on\n`finalizing` — releasing goods, crediting an account — means accepting that risk\ndeliberately, at whatever threshold suits you rather than the one we wait for.\n\n`finalizing` is about paying the recipient. While your own funds are still being\ncommitted on the source chain the payment is `pending`, because nothing has reached\nthe recipient yet.\n","enum":["pending","finalizing","completed","failed","refunding","refund_available","refunded"],"example":"pending","uniqueKey":"status","typeLabel":"enum\u003cstring>"},"transactions":{"type":"object","description":"The transactions a payment has produced, one entry per stage, added as each becomes\nknown. A stage absent here has produced no transaction yet.\n\nThese are the movements that decide whether your payment happened: your funds being\ncommitted, your recipient being paid, and your funds being returned when the payment\nis refunded. Present on every outcome, so a payment that did not complete can still be\ntraced on chain.\n\nWhere a stage is attempted more than once, the entry describes the attempt that\ncounts — the one that succeeded, or the last one if none did.\n","properties":{"deposit":{"type":"object","description":"Committing your funds on the source chain.","required":["transaction_hash","chain_id"],"properties":{"transaction_hash":{"type":"string","description":"The transaction's hash on its chain. Hex hashes carry the `0x` prefix, including on\nTron, whose own tooling omits it.\n","pattern":"^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{32,88})$","example":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","isRequired":true,"uniqueKey":"transactions.deposit.transaction_hash","typeLabel":"string"},"chain_id":{"type":"string","description":"CAIP-2 identifier of the chain the transaction is on.","pattern":"^[a-z0-9]+:[a-zA-Z0-9_-]+$","example":"eip155:42161","isRequired":true,"uniqueKey":"transactions.deposit.chain_id","typeLabel":"string"},"block_number":{"type":"integer","description":"The block the transaction landed in. Absent until it has been mined.\n\nProvisional while `status` is `finalizing`: a reorganization can still move the\ntransaction to a different block. Settled once `status` is `completed` — keep it as\na final record only from then.\n","example":61234567,"uniqueKey":"transactions.deposit.block_number","typeLabel":"integer"}},"uniqueKey":"transactions.deposit","typeLabel":"object"},"fulfillment":{"type":"object","description":"Paying your recipient on the destination chain.","required":["transaction_hash","chain_id"],"properties":{"transaction_hash":{"type":"string","description":"The transaction's hash on its chain. Hex hashes carry the `0x` prefix, including on\nTron, whose own tooling omits it.\n","pattern":"^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{32,88})$","example":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","isRequired":true,"uniqueKey":"transactions.fulfillment.transaction_hash","typeLabel":"string"},"chain_id":{"type":"string","description":"CAIP-2 identifier of the chain the transaction is on.","pattern":"^[a-z0-9]+:[a-zA-Z0-9_-]+$","example":"eip155:42161","isRequired":true,"uniqueKey":"transactions.fulfillment.chain_id","typeLabel":"string"},"block_number":{"type":"integer","description":"The block the transaction landed in. Absent until it has been mined.\n\nProvisional while `status` is `finalizing`: a reorganization can still move the\ntransaction to a different block. Settled once `status` is `completed` — keep it as\na final record only from then.\n","example":61234567,"uniqueKey":"transactions.fulfillment.block_number","typeLabel":"integer"}},"uniqueKey":"transactions.fulfillment","typeLabel":"object"},"refund":{"type":"object","description":"Returning your funds from the escrow on the source chain. Can be absent on a\n`refunded` payment when the refund transaction is not known.\n","required":["transaction_hash","chain_id"],"properties":{"transaction_hash":{"type":"string","description":"The transaction's hash on its chain. Hex hashes carry the `0x` prefix, including on\nTron, whose own tooling omits it.\n","pattern":"^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{32,88})$","example":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","isRequired":true,"uniqueKey":"transactions.refund.transaction_hash","typeLabel":"string"},"chain_id":{"type":"string","description":"CAIP-2 identifier of the chain the transaction is on.","pattern":"^[a-z0-9]+:[a-zA-Z0-9_-]+$","example":"eip155:42161","isRequired":true,"uniqueKey":"transactions.refund.chain_id","typeLabel":"string"},"block_number":{"type":"integer","description":"The block the transaction landed in. Absent until it has been mined.\n\nProvisional while `status` is `finalizing`: a reorganization can still move the\ntransaction to a different block. Settled once `status` is `completed` — keep it as\na final record only from then.\n","example":61234567,"uniqueKey":"transactions.refund.block_number","typeLabel":"integer"}},"uniqueKey":"transactions.refund","typeLabel":"object"}},"uniqueKey":"transactions","typeLabel":"object"},"updated_at":{"type":"string","format":"date-time","description":"When the status was last updated","uniqueKey":"updated_at","typeLabel":"string\u003cdate-time>"},"quote_id":{"type":"string","description":"The winning quote's ID. Present once a quote has been awarded for this payment;\nabsent while the payment is still collecting or awarding. Cross-references the\n`quote_id` returned by GET /v1/payments/quote-requests/{quoteRequestId}.\n","example":"0x9a3b...e8d4","uniqueKey":"quote_id","typeLabel":"string"},"fulfillment_quote":{"type":"object","description":"The settler-signed FulfillmentQuote for the winning quote, returned verbatim as an\nopaque signed document (structurally the canonical FulfillmentQuote/v1 declaration at\nhttps://schemas.atum.xyz/declarations/FulfillmentQuote/v1). Present once a quote has\nbeen awarded — including after the payment completes and `transactions.fulfillment` is\npopulated, since that is precisely when a consumer verifies.\n\nThis is the PREIMAGE of the `quote_hash` committed on-chain in the escrow deposit and\nreserve witnesses. On-chain we commit only the hash, so a quote-selector consumer\nrecomputes quote_hash over these bytes and compares it against the on-chain commitment\nto confirm the payment settled against the quote it selected (\"trust but verify\"), and\nverifies the settler signature over the same bytes.\n\nquote_hash is canonicalization-based (URDNA2015), so it is stable across JSON\nkey-order/whitespace normalization and across JSON string-escaping differences. The\nreturned bytes are hash-equivalent to, but not necessarily byte-identical with, what\nthe settler emitted (quotes are stored as JSONB, which normalizes on write). The\ngateway still never re-serializes the quote through a typed struct (that renormalizes\ntimestamp values and WOULD change quote_hash), so the Go binding exposes it as a raw\nJSON passthrough.\n","uniqueKey":"fulfillment_quote","typeLabel":"object"},"fulfillment_authorization":{"type":"object","description":"The settler-signed FulfillmentAuthorization for this payment, returned verbatim as an\nopaque signed document (structurally the canonical FulfillmentAuthorization/v1 declaration at\nhttps://schemas.atum.xyz/declarations/FulfillmentAuthorization/v1; see also\n`#/components/schemas/FulfillmentAuthorization`). The inner declaration requires\n`version`, `scheme`, `authorization` (the signed EIP-3009 transfer, in `authorization.message_prehash`), `fulfillment_quote_json`,\nand `evidence` (the on-chain authorizeFulfillment transaction). On the wire the settler\ntypically wraps that declaration in JSON-LD with `@context`, `type`, and `proof` — those\nenvelope fields ride alongside the declaration and MUST be preserved byte-for-byte.\n\nPresent when the settler authorized an originator fulfill. Until the originator\nfulfills, `transactions.fulfillment` is absent.\n\nThe service returns these bytes verbatim and does not re-serialize through a typed\nrepresentation (which would normalize timestamps and reorder JSON-LD envelope fields).\n","uniqueKey":"fulfillment_authorization","typeLabel":"object"},"error":{"type":"object","description":"Why a payment failed, or why its settler gave up. As `error` it is present only when\n`status` is `failed`, as `refund_reason` only on the refund statuses, and it is identical\nhowever you ask about the payment.\n\n`code` is the stable, machine-readable identity of the failure — branch on it\nrather than on `message`, which is written for a person and may be reworded.\n`docs_url` points at the page describing that code.\n","required":["code","message"],"properties":{"code":{"type":"string","description":"Public error category in SCREAMING_SNAKE_CASE. Common codes:\n- `SETTLEMENT_FAILED`: the settlement could not be completed\n- `NO_QUOTES_RECEIVED`: no quotes arrived within the auction window\n- `QUOTES_EXPIRED`: quotes arrived but none could be selected\n- `NO_SETTLER_FOR_CORRIDOR`: no settler serves this source and destination pair\n- `INSUFFICIENT_FUNDS`: the paying account held too little of the source token to fund the deposit\n- `MISSING_TOKEN_APPROVAL`: the paying account had not approved Permit2 for enough of the source token\n- `INTERNAL_ERROR`: an unexpected error occurred\n\nAn auction that closes without a usable quote fails the payment here, under\n`status` `failed`, never as an HTTP error on `POST /v1/payments`. These outcomes\nare terminal for the `request_id`, so a genuine re-attempt needs a new one.\n","example":"SETTLEMENT_FAILED","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of the failure, for a person reading it. Do not\nbranch on this text.\n","example":"No quotes received within the auction window","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"domain":{"type":"string","description":"Which part of the system reported the failure.\n","enum":["PAYMENT_GATEWAY","SETTLER_GATEWAY","SETTLER_AGENT","WALLET_ORCHESTRATION","VERIFICATION_SERVICE","BLOCKCHAIN","EXTERNAL_SERVICE"],"example":"PAYMENT_GATEWAY","uniqueKey":"error.domain","typeLabel":"enum\u003cstring>"},"docs_url":{"type":"string","format":"uri","description":"Link to the documentation page for this public code.","uniqueKey":"error.docs_url","typeLabel":"string\u003curi>"},"retry_classification":{"type":"string","description":"What the caller should do next. Absent means the condition has not been classified, which is not the same as safe to retry.\nRe-sending the same `request_id` is an idempotent replay and always safe. This value is about submitting a new one, which starts a new payment. See https://docs.atum.xyz/errors for the value set.","example":"RECONCILE_THEN_DECIDE","uniqueKey":"error.retry_classification","typeLabel":"string"},"request_id_reusable":{"type":"boolean","description":"Whether the caller may re-send the `request_id` this payment was created under. On this shape it is almost always false, because a payment exists by definition, but it is carried rather than assumed so a caller reads the same field here as on a synchronous error. Absent means undetermined, which a caller should read as false.","example":false,"uniqueKey":"error.request_id_reusable","typeLabel":"boolean"},"blockchain_context":{"type":"object","description":"Where on chain a failed payment failed. Present only when the failure happened\non chain — an escrow revert, or a fulfillment that could not be delivered — so a\npayment that failed before any transaction was sent carries no context here.","properties":{"chain_id":{"type":"string","description":"CAIP-2 chain identifier","pattern":"^[a-z0-9]+:[a-zA-Z0-9_-]+$","uniqueKey":"error.blockchain_context.chain_id","typeLabel":"string"},"transaction_hash":{"type":"string","description":"Failed transaction hash","pattern":"^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{32,88})$","uniqueKey":"error.blockchain_context.transaction_hash","typeLabel":"string"},"block_number":{"type":"integer","description":"Block number where error occurred","uniqueKey":"error.blockchain_context.block_number","typeLabel":"integer"},"contract_address":{"type":"string","description":"Contract that caused the error","pattern":"^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$","uniqueKey":"error.blockchain_context.contract_address","typeLabel":"string"},"revert_reason":{"type":"string","description":"Smart contract revert reason","uniqueKey":"error.blockchain_context.revert_reason","typeLabel":"string"},"gas_used":{"type":"string","description":"Gas consumed before failure","uniqueKey":"error.blockchain_context.gas_used","typeLabel":"string"},"estimated_gas_needed":{"type":"string","description":"Estimated gas needed for success","uniqueKey":"error.blockchain_context.estimated_gas_needed","typeLabel":"string"}},"uniqueKey":"error.blockchain_context","typeLabel":"object"}},"uniqueKey":"error","typeLabel":"object"},"refund_reason":{"type":"object","description":"Why the settler did not deliver, as it reported when it gave up. Present only when\n`status` is `refunding`, `refund_available` or `refunded`, and absent when the refund\nstarted without a reason from the settler. `status` decides what to do next: its\n`retry_classification` and `request_id_reusable` describe the settler's error, not\nthis payment, and never mean paying again while it is `refunding` or `refund_available`.\n","required":["code","message"],"properties":{"code":{"type":"string","description":"Public error category in SCREAMING_SNAKE_CASE. Common codes:\n- `SETTLEMENT_FAILED`: the settlement could not be completed\n- `NO_QUOTES_RECEIVED`: no quotes arrived within the auction window\n- `QUOTES_EXPIRED`: quotes arrived but none could be selected\n- `NO_SETTLER_FOR_CORRIDOR`: no settler serves this source and destination pair\n- `INSUFFICIENT_FUNDS`: the paying account held too little of the source token to fund the deposit\n- `MISSING_TOKEN_APPROVAL`: the paying account had not approved Permit2 for enough of the source token\n- `INTERNAL_ERROR`: an unexpected error occurred\n\nAn auction that closes without a usable quote fails the payment here, under\n`status` `failed`, never as an HTTP error on `POST /v1/payments`. These outcomes\nare terminal for the `request_id`, so a genuine re-attempt needs a new one.\n","example":"SETTLEMENT_FAILED","isRequired":true,"uniqueKey":"refund_reason.code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of the failure, for a person reading it. Do not\nbranch on this text.\n","example":"No quotes received within the auction window","isRequired":true,"uniqueKey":"refund_reason.message","typeLabel":"string"},"domain":{"type":"string","description":"Which part of the system reported the failure.\n","enum":["PAYMENT_GATEWAY","SETTLER_GATEWAY","SETTLER_AGENT","WALLET_ORCHESTRATION","VERIFICATION_SERVICE","BLOCKCHAIN","EXTERNAL_SERVICE"],"example":"PAYMENT_GATEWAY","uniqueKey":"refund_reason.domain","typeLabel":"enum\u003cstring>"},"docs_url":{"type":"string","format":"uri","description":"Link to the documentation page for this public code.","uniqueKey":"refund_reason.docs_url","typeLabel":"string\u003curi>"},"retry_classification":{"type":"string","description":"What the caller should do next. Absent means the condition has not been classified, which is not the same as safe to retry.\nRe-sending the same `request_id` is an idempotent replay and always safe. This value is about submitting a new one, which starts a new payment. See https://docs.atum.xyz/errors for the value set.","example":"RECONCILE_THEN_DECIDE","uniqueKey":"refund_reason.retry_classification","typeLabel":"string"},"request_id_reusable":{"type":"boolean","description":"Whether the caller may re-send the `request_id` this payment was created under. On this shape it is almost always false, because a payment exists by definition, but it is carried rather than assumed so a caller reads the same field here as on a synchronous error. Absent means undetermined, which a caller should read as false.","example":false,"uniqueKey":"refund_reason.request_id_reusable","typeLabel":"boolean"},"blockchain_context":{"type":"object","description":"Where on chain a failed payment failed. Present only when the failure happened\non chain — an escrow revert, or a fulfillment that could not be delivered — so a\npayment that failed before any transaction was sent carries no context here.","properties":{"chain_id":{"type":"string","description":"CAIP-2 chain identifier","pattern":"^[a-z0-9]+:[a-zA-Z0-9_-]+$","uniqueKey":"refund_reason.blockchain_context.chain_id","typeLabel":"string"},"transaction_hash":{"type":"string","description":"Failed transaction hash","pattern":"^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{32,88})$","uniqueKey":"refund_reason.blockchain_context.transaction_hash","typeLabel":"string"},"block_number":{"type":"integer","description":"Block number where error occurred","uniqueKey":"refund_reason.blockchain_context.block_number","typeLabel":"integer"},"contract_address":{"type":"string","description":"Contract that caused the error","pattern":"^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$","uniqueKey":"refund_reason.blockchain_context.contract_address","typeLabel":"string"},"revert_reason":{"type":"string","description":"Smart contract revert reason","uniqueKey":"refund_reason.blockchain_context.revert_reason","typeLabel":"string"},"gas_used":{"type":"string","description":"Gas consumed before failure","uniqueKey":"refund_reason.blockchain_context.gas_used","typeLabel":"string"},"estimated_gas_needed":{"type":"string","description":"Estimated gas needed for success","uniqueKey":"refund_reason.blockchain_context.estimated_gas_needed","typeLabel":"string"}},"uniqueKey":"refund_reason.blockchain_context","typeLabel":"object"}},"uniqueKey":"refund_reason","typeLabel":"object"},"refund_signature":{"type":"object","description":"Present only when `status` is `refund_available`.","required":["signature","message_hash","message_prehash"],"properties":{"signature":{"type":"string","description":"The verifier's signature over `message_hash`. Hex with the `0x` prefix on EVM and\nTron chains, hex without it on Solana.\n","isRequired":true,"uniqueKey":"refund_signature.signature","typeLabel":"string"},"message_hash":{"type":"string","description":"The signed digest, hex without the `0x` prefix.","isRequired":true,"uniqueKey":"refund_signature.message_hash","typeLabel":"string"},"message_prehash":{"type":"string","description":"The signed message as JSON. On EVM and Tron chains it carries the RefundWitness the\nescrow's `refund` takes.\n","isRequired":true,"uniqueKey":"refund_signature.message_prehash","typeLabel":"string"}},"uniqueKey":"refund_signature","typeLabel":"object"},"requested_count":{"type":"integer","description":"How many settler agents this payment's auction was broadcast to. Absent means\nunknown, never zero.\n","example":8,"uniqueKey":"requested_count","typeLabel":"integer"},"decline_summary":{"type":"array","description":"Why the payment drew few or no quotes. Read from the same settler reports as the\nquote-request endpoints, keyed by this payment, so a payment that failed on an expired\nquote deadline can say WHY nobody funded it instead of only that nobody did.\n\nEvery declining agent is counted exactly once under its most recent reason. Empty means\nno agent declined against this payment, absent means the breakdown could not be read. A\npayment awarded out of a quote-request batch was bid on at quote time, so its declines\nare keyed to that batch and are read from the batch's status endpoint rather than here.\nAs on the quote-request endpoints, the free-form decline detail is never relayed.\n","items":{"type":"object","required":["reason","count"],"properties":{"reason":{"type":"string","description":"A settler's reason for not bidding, projected from its internal reason code through\nthe shared decline catalog (`apis/decline/v1/catalog.json`), which is the single\nsource of truth for the reason set. Several internal codes may map to one public\nreason.\n\nDeliberately a pattern-constrained string rather than a closed enum. The set grows\nwhenever a settler gains a cause worth naming, and a consumer whose generated client\ncloses the set rejects the whole response on a value it has not seen. Treat an\nunrecognised value as `OTHER`.\n\n`OTHER` covers a reason whose detail is settler-authored free text, and any reason\nthis gateway does not recognise. Both are counted so the summary stays exhaustive,\nwithout relaying text we neither author nor validate.\n","pattern":"^[A-Z][A-Z0-9_]*$","example":"INSUFFICIENT_LIQUIDITY","isRequired":true,"uniqueKey":"decline_summary.items.[INDEX].reason","typeLabel":"string"},"count":{"type":"integer","description":"Agents whose most recent decline reason was this one. Counts agents, never rows, and an\nagent appears under one reason only.\n","example":4,"isRequired":true,"uniqueKey":"decline_summary.items.[INDEX].count","typeLabel":"integer"},"retry_classification":{"type":"string","description":"What would have to change for a settler giving this reason to submit a price quote,\ndrawn from the same closed set as the `retry_classification` on an error response so\na caller reads one vocabulary.\n\nIt describes the decline only. The authoritative instruction for the payment is the\n`retry_classification` on its own error response: a payment can fail for a reason no\nsettler named, and it can succeed while some settlers declined.\n\nOptional, and a pattern-constrained string for the same reason `DeclineReason` is.\n","pattern":"^[A-Z][A-Z0-9_]*$","example":"RETRY_AFTER_DELAY","uniqueKey":"decline_summary.items.[INDEX].retry_classification","typeLabel":"string"},"docs_url":{"type":"string","format":"uri","description":"Link to the documentation for this reason. Absent rather than empty when no page is\npublished, so a reader never follows a link to the site root.\n","example":"https://docs.atum.xyz/decline-reasons#insufficient-liquidity","uniqueKey":"decline_summary.items.[INDEX].docs_url","typeLabel":"string\u003curi>"}},"uniqueKey":"decline_summary.items.[INDEX]","typeLabel":"object"},"uniqueKey":"decline_summary","typeLabel":"object[]"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"payment_id":"0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f","status":"pending","transactions":{"deposit":{"transaction_hash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","chain_id":"eip155:42161","block_number":61234567},"fulfillment":{"transaction_hash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","chain_id":"eip155:42161","block_number":61234567},"refund":{"transaction_hash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","chain_id":"eip155:42161","block_number":61234567}},"updated_at":"2023-11-07T05:31:56Z","quote_id":"0x9a3b...e8d4","fulfillment_quote":{},"fulfillment_authorization":{},"error":{"code":"SETTLEMENT_FAILED","message":"No quotes received within the auction window","domain":"PAYMENT_GATEWAY","docs_url":"\u003cstring>","retry_classification":"RECONCILE_THEN_DECIDE","request_id_reusable":false,"blockchain_context":{"chain_id":"\u003cstring>","transaction_hash":"\u003cstring>","block_number":123,"contract_address":"\u003cstring>","revert_reason":"\u003cstring>","gas_used":"\u003cstring>","estimated_gas_needed":"\u003cstring>"}},"refund_reason":{"code":"SETTLEMENT_FAILED","message":"No quotes received within the auction window","domain":"PAYMENT_GATEWAY","docs_url":"\u003cstring>","retry_classification":"RECONCILE_THEN_DECIDE","request_id_reusable":false,"blockchain_context":{"chain_id":"\u003cstring>","transaction_hash":"\u003cstring>","block_number":123,"contract_address":"\u003cstring>","revert_reason":"\u003cstring>","gas_used":"\u003cstring>","estimated_gas_needed":"\u003cstring>"}},"refund_signature":{"signature":"\u003cstring>","message_hash":"\u003cstring>","message_prehash":"\u003cstring>"},"requested_count":8,"decline_summary":[{"reason":"INSUFFICIENT_LIQUIDITY","count":4,"retry_classification":"RETRY_AFTER_DELAY","docs_url":"https://docs.atum.xyz/decline-reasons#insufficient-liquidity"}]}}},"exampleType":"generated"}},"exampleType":"generated"},"1c6e6fe0-67fd-473e-86e6-5203ca6ef1fd":{"description":"Payment not found","content":{"application/json":{"schema":{"type":"object","description":"Safe, outward-facing error. Derived from an internal error through the shared error catalog. The public code identifies the category and the message is a curated, safe description.\n\nA panic is caught by shared middleware that responds `{\"error\": \"Internal server error occurred\"}` instead, so a 500 is not guaranteed to carry this shape.","required":["code","message"],"properties":{"code":{"type":"string","description":"Public, machine-readable error category in SCREAMING_SNAKE_CASE.","pattern":"^[A-Z][A-Z0-9_]*$","example":"INVALID_SOURCE_ASSET","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Curated, safe, human-readable message.","maxLength":500,"example":"The source asset identifier is not a valid CAIP-19 asset.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"request_id":{"type":"string","description":"Correlation id to quote to support to locate the internal error record.","example":"req_123456789","uniqueKey":"request_id","typeLabel":"string"},"payment_id":{"type":"string","description":"The payment this error was raised against. Absent when the error is not about a specific payment.","example":"0xc7108e200d11580e7e75185991084b42a535af588ba8267cd0d1e7df089e5c9c","uniqueKey":"payment_id","typeLabel":"string"},"docs_url":{"type":"string","format":"uri","description":"Link to the documentation page for this public code.","uniqueKey":"docs_url","typeLabel":"string\u003curi>"},"domain":{"type":"string","description":"Originating service domain.","example":"PAYMENT_GATEWAY","uniqueKey":"domain","typeLabel":"string"},"retry_classification":{"type":"string","description":"What the caller should do next. Absent means the condition has not been classified, which is not the same as safe to retry.\nRe-sending the same `request_id` is an idempotent replay and always safe. This value is about submitting a new one, which starts a new operation. See https://docs.atum.xyz/errors for the value set.","example":"RECONCILE_THEN_DECIDE","uniqueKey":"retry_classification","typeLabel":"string"},"request_id_reusable":{"type":"boolean","description":"Whether the caller may re-send this same request_id. True means no payment was created for it, so the id is still free. False means a payment exists for it, so the id is spent and re-sending only replays this outcome. Absent means undetermined, which a caller should read as false. Separate from retry_classification, which answers what the caller must change rather than whether the id survived.","example":false,"uniqueKey":"request_id_reusable","typeLabel":"boolean"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"INVALID_SOURCE_ASSET","message":"The source asset identifier is not a valid CAIP-19 asset.","request_id":"req_123456789","payment_id":"0xc7108e200d11580e7e75185991084b42a535af588ba8267cd0d1e7df089e5c9c","docs_url":"\u003cstring>","domain":"PAYMENT_GATEWAY","retry_classification":"RECONCILE_THEN_DECIDE","request_id_reusable":false}}},"exampleType":"generated"}},"exampleType":"generated"},"797eff3c-061c-47d0-9c67-7d55a84ed55a":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","description":"Safe, outward-facing error. Derived from an internal error through the shared error catalog. The public code identifies the category and the message is a curated, safe description.\n\nA panic is caught by shared middleware that responds `{\"error\": \"Internal server error occurred\"}` instead, so a 500 is not guaranteed to carry this shape.","required":["code","message"],"properties":{"code":{"type":"string","description":"Public, machine-readable error category in SCREAMING_SNAKE_CASE.","pattern":"^[A-Z][A-Z0-9_]*$","example":"INVALID_SOURCE_ASSET","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Curated, safe, human-readable message.","maxLength":500,"example":"The source asset identifier is not a valid CAIP-19 asset.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"request_id":{"type":"string","description":"Correlation id to quote to support to locate the internal error record.","example":"req_123456789","uniqueKey":"request_id","typeLabel":"string"},"payment_id":{"type":"string","description":"The payment this error was raised against. Absent when the error is not about a specific payment.","example":"0xc7108e200d11580e7e75185991084b42a535af588ba8267cd0d1e7df089e5c9c","uniqueKey":"payment_id","typeLabel":"string"},"docs_url":{"type":"string","format":"uri","description":"Link to the documentation page for this public code.","uniqueKey":"docs_url","typeLabel":"string\u003curi>"},"domain":{"type":"string","description":"Originating service domain.","example":"PAYMENT_GATEWAY","uniqueKey":"domain","typeLabel":"string"},"retry_classification":{"type":"string","description":"What the caller should do next. Absent means the condition has not been classified, which is not the same as safe to retry.\nRe-sending the same `request_id` is an idempotent replay and always safe. This value is about submitting a new one, which starts a new operation. See https://docs.atum.xyz/errors for the value set.","example":"RECONCILE_THEN_DECIDE","uniqueKey":"retry_classification","typeLabel":"string"},"request_id_reusable":{"type":"boolean","description":"Whether the caller may re-send this same request_id. True means no payment was created for it, so the id is still free. False means a payment exists for it, so the id is spent and re-sending only replays this outcome. Absent means undetermined, which a caller should read as false. Separate from retry_classification, which answers what the caller must change rather than whether the id survived.","example":false,"uniqueKey":"request_id_reusable","typeLabel":"boolean"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"INVALID_SOURCE_ASSET","message":"The source asset identifier is not a valid CAIP-19 asset.","request_id":"req_123456789","payment_id":"0xc7108e200d11580e7e75185991084b42a535af588ba8267cd0d1e7df089e5c9c","docs_url":"\u003cstring>","domain":"PAYMENT_GATEWAY","retry_classification":"RECONCILE_THEN_DECIDE","request_id_reusable":false}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{},"servers":{"33df3309-b84e-48a9-94c1-aac200cf674f":{"url":"https://payment-gw.production-mainnet.atum.xyz","description":"Mainnet"},"fa558170-4e9e-4663-9e9b-39906523216e":{"url":"https://payment-gw.production-testnet.atum.xyz","description":"Testnet"}}},"originalFileLocation":"api-reference/payment-gateway/openapi.yaml"},"subdomain":"atumlabs","siteName":"Atum Docs","title":"Get payment status - Atum Docs","relatedPagesConfig":{"enabled":true,"limit":5,"mode":"automatic"},"navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-20T11:27:28.077Z","originalFileLocation":"api-reference/payment-gateway/get-payment-status.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=\"dark\"}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=\"Poll a payment\u0026#x27;s current status by payment_id: pending, finalizing, completed, failed, or one of the refund statuses.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Atum Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/atumlabs/Pqh0GSDdyRfy-YKa/_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/atumlabs/Pqh0GSDdyRfy-YKa/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/atumlabs/Pqh0GSDdyRfy-YKa/_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/atumlabs/Pqh0GSDdyRfy-YKa/_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/atumlabs/Pqh0GSDdyRfy-YKa/_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/atumlabs/Pqh0GSDdyRfy-YKa/_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/atumlabs/Pqh0GSDdyRfy-YKa/_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/atumlabs/Pqh0GSDdyRfy-YKa/_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/atumlabs/Pqh0GSDdyRfy-YKa/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Get payment status - Atum Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Poll a payment\u0026#x27;s current status by payment_id: pending, finalizing, completed, failed, or one of the refund statuses.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Atum Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.atum.xyz/api-reference/payment-gateway/get-payment-status\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://atumlabs.mintlify.site/_mintlify/api/og/v2?division=Payment+Gateway\u0026amp;title=Get+payment+status\u0026amp;description=Poll+a+payment%27s+current+status+by+payment_id%3A+pending%2C+finalizing%2C+completed%2C+failed%2C+or+one+of+the+refund+statuses.\u0026amp;theme=2455e481a76f39e16fb336fe\u0026amp;signature=76e6f60ebf9f21b3dc74ac26d7a7dbabfa62a12bc76105c57e3a0623798752a5\">\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=\"Get payment status - Atum Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Poll a payment\u0026#x27;s current status by payment_id: pending, finalizing, completed, failed, or one of the refund statuses.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://atumlabs.mintlify.site/_mintlify/api/og/v2?division=Payment+Gateway\u0026amp;title=Get+payment+status\u0026amp;description=Poll+a+payment%27s+current+status+by+payment_id%3A+pending%2C+finalizing%2C+completed%2C+failed%2C+or+one+of+the+refund+statuses.\u0026amp;theme=2455e481a76f39e16fb336fe\u0026amp;signature=76e6f60ebf9f21b3dc74ac26d7a7dbabfa62a12bc76105c57e3a0623798752a5\">\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/atumlabs/Pqh0GSDdyRfy-YKa/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Atum Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#24450d\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.atum.xyz/api-reference/payment-gateway/get-payment-status\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/payment-gateway/get-payment-status.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.atum.xyz/#organization\",\"name\":\"Atum Docs\",\"url\":\"https://docs.atum.xyz\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/atumlabs/eBwMdhd0uJ6cwbY0/images/assets/wordmark-light.svg?fit=max\u0026auto=format\u0026n=eBwMdhd0uJ6cwbY0\u0026q=85\u0026s=6ba7458a7e4528e698e48cbf8e15c375\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.atum.xyz#website\",\"name\":\"Atum Docs\",\"url\":\"https://docs.atum.xyz\",\"publisher\":{\"@id\":\"https://docs.atum.xyz/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.atum.xyz/api-reference/payment-gateway/get-payment-status#webpage\",\"url\":\"https://docs.atum.xyz/api-reference/payment-gateway/get-payment-status\",\"name\":\"Get payment status\",\"description\":\"Poll a payment's current status by payment_id: pending, finalizing, completed, failed, or one of the refund statuses.\",\"dateModified\":\"2026-10-20T11:27:28.077Z\",\"isPartOf\":{\"@id\":\"https://docs.atum.xyz#website\"},\"breadcrumb\":{\"@id\":\"https://docs.atum.xyz/api-reference/payment-gateway/get-payment-status#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.atum.xyz/api-reference/payment-gateway/get-payment-status#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Payment Gateway\",\"item\":\"https://docs.atum.xyz/api-reference/payment-gateway/introduction\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Get payment status\",\"item\":\"https://docs.atum.xyz/api-reference/payment-gateway/get-payment-status\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.atum.xyz/api-reference/payment-gateway/get-payment-status#apireference\",\"headline\":\"Get payment status\",\"name\":\"Get payment status\",\"description\":\"Poll a payment's current status by payment_id: pending, finalizing, completed, failed, or one of the refund statuses.\",\"url\":\"https://docs.atum.xyz/api-reference/payment-gateway/get-payment-status\",\"mainEntityOfPage\":{\"@id\":\"https://docs.atum.xyz/api-reference/payment-gateway/get-payment-status#webpage\"},\"dateModified\":\"2026-10-20T11:27:28.077Z\",\"publisher\":{\"@id\":\"https://docs.atum.xyz/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.atum.xyz#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Atum Docs\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Atum Docs","nav":{"global":null,"tabs":[{"tab":"Get started","icon":"rocket","pages":[{"title":"Get started","href":"/get-started/overview/what-is-atum"}]},{"tab":"Payment protocols","icon":"route","pages":[{"title":"Payment protocols","href":"/payment-protocols/overview"}]},{"tab":"Settle payments","icon":"handshake","pages":[{"title":"Settle payments","href":"/settle-payments/what-is-an-atum-settlement"}]},{"tab":"API Reference","icon":"code","groups":[{"group":"Introduction","pages":[{"title":"API Reference","sidebarTitle":"Overview","icon":"code","href":"/api-reference/overview"},{"title":"auth.md","sidebarTitle":"How agents authenticate","hidden":true,"href":"/auth"},{"title":"Idempotency","sidebarTitle":"Idempotency","icon":"arrows-rotate","href":"/api-reference/idempotency"}]},{"group":"Error handling","icon":"circle-exclamation","pages":[{"title":"Error codes","icon":"circle-exclamation","href":"/errors"},{"title":"Decline reasons","icon":"hand","href":"/decline-reasons"}]},{"group":"Payment Gateway","pages":[{"title":"Overview","href":"/api-reference/payment-gateway/introduction"},{"title":"Submit payment request","description":"Submit a signed payment request to the Atum Payment Gateway. request_id is the idempotency key that makes a retry safe.","openapi":"POST /v1/payments","href":"/api-reference/payment-gateway/submit-payment"},{"title":"Get payment status","openapi":"GET /v1/payments/{paymentId}/status","href":"/api-reference/payment-gateway/get-payment-status"},{"title":"Resolve a payment request","description":"Look a payment up by the request_id you submitted, for when you lost the submit response but kept your idempotency key.","openapi":"GET /v1/payments/resolve","href":"/api-reference/payment-gateway/resolve-payment"},{"title":"Get payment timeline","openapi":"GET /v1/payments/{paymentId}/timeline","href":"/api-reference/payment-gateway/payment-timeline"},{"title":"Create a quote-request","openapi":"POST /v1/payments/quote-requests","href":"/api-reference/payment-gateway/create-quote-request"},{"title":"Get quote-request status","openapi":"GET /v1/payments/quote-requests/{quoteRequestId}","href":"/api-reference/payment-gateway/quote-request-status"},{"title":"Get chain defaults","openapi":"GET /v1/defaults","href":"/api-reference/payment-gateway/chain-defaults"}]},{"group":"x402 Facilitator","pages":[{"title":"Overview","href":"/api-reference/x402/introduction"},{"title":"Verify payment","openapi":"POST /verify","href":"/api-reference/x402/verify"},{"title":"Settle payment","openapi":"POST /settle","href":"/api-reference/x402/settle"},{"title":"Supported kinds","openapi":"GET /supported","href":"/api-reference/x402/supported"}]},{"group":"Veri-Fill","pages":[{"title":"Veri-Fill API","sidebarTitle":"Overview","href":"/api-reference/veri-fill/introduction"}]}]},{"tab":"Changelog","icon":"clock-rotate-left","pages":[{"title":"Changelog","href":"/changelog"}]}]},"basePath":"","title":"Get payment status - Atum Docs","buildId":"dpl_8LJbrAiZvr1K98WQNZXCyY5AvT34","deploymentId":"dpl_8LJbrAiZvr1K98WQNZXCyY5AvT34","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-i2a3QZ8E.js","utils-ChLwp8m0.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-DRktVTDc.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-CA2pEs4T.js","snippetPresets-ClQ6XrKD.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-Ct_Lv36y.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-Cn2PYw9e.js","shallow-rkyymjXQ.js","getApiPlaygroundDisplay-BB9vkXtE.js","CodeSnippet-Bm5RU7m1.js","CodeSnippets-BgU9Deuz.js","Page-BUDYNlhG.js","getPastedJson-BD-6NNum.js","icon-8Z6tud2e.js","MethodPill-Tuzr4g3V.js","DuplicateIcon-0ceWFYhN.js","createIcon-FBXow_ST.js","DynamicMarkdown-CD8713Yy.js","SectionHeading-7zgzQbH-.js","axios-vUo_bRtp.js","Markdown-D7Ofw1oz.js","clsx-eKJ4rcii.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-CwjSCXIK.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-9EK5IAXV.js"]}