Complete a sandbox payment with the test API or Sepolia test ETH, then verify callbacks.
Sandbox and production have separate API hosts and credentials. For a custom
integration, test against https://api-sandbox.billions.works before switching
to production. You can finish a sandbox invoice either with the test API or
by sending Sepolia test ETH to a TETH invoice. Neither option moves real funds.
Configure your backend with the sandbox API URL and sandbox key. Keep both
explicit; the TypeScript SDK defaults to production if
baseUrl is omitted.
Make your callback endpoint reachable over HTTPS. Create an invoice with a
unique order_no, a stable idempotencyKey, a small supported amount, and
callbackUrl. Store the returned id and expires_at.
Open the returned invoice_url to check the hosted checkout. The app’s
Sandbox Demo Shop creates a separate invoice; it does not test your
callback endpoint.
Option 1: Mark an invoice as paid with the sandbox API
Send the invoice id returned by the create endpoint to
POST /public/v1/invoices/mark-as-paid on the sandbox host. Use the same
merchant’s sandbox API key. This simulates a successful payment, updates the
invoice to completed, and queues the normal invoice.paid callback when the
invoice has a callbackUrl. No blockchain transfer is required.
In the TypeScript example, invoice is the result of your earlier create call;
for cURL, set BILLIONS_INVOICE_ID to that response’s id.
The invoice must belong to the authenticated merchant, have a valid UUID,
still be unexpired, and be in pending or processing. A repeated call, an
expired invoice, or another status returns 409. An invalid UUID returns
400; an unknown invoice or a request outside sandbox returns 404.
This endpoint is for testing only. It is unavailable in production; do not
put it in a production payment or fulfillment flow.
Option 2: Pay with Sepolia test ETH
The sandbox currency TETH is native test ETH on Ethereum Sepolia (chain
ID 11155111, internal ticker ETH_TEST5). It has no ERC-20 contract address.
To exercise a real testnet transfer:
Create a sandbox invoice with currency: "TETH" and your callbackUrl.
Open its invoice_url and use the displayed Sepolia payment address and
amount. Obtain Sepolia test ETH from a testnet faucet if needed.
From a wallet connected to Sepolia, send the requested test ETH to that
address. Do not use Ethereum mainnet or send real ETH.
Wait for network confirmation, then retrieve the invoice from the API and
check that your callback handler processed the update.
Only TETH is listed as a Sepolia payment currency by the current
sandbox currencies endpoint.
Do not assume that other testnet ERC-20 tokens sent to the same address will
pay this invoice.
Verify the end-to-end result
With either option, retrieve GET /public/v1/invoices/{id} using the sandbox
API key. Confirm the invoice ID, order_no, amount, and
settlement_currency match your stored attempt, then require completed
before fulfillment. If you set callbackUrl, verify that your endpoint
received the notification and still performed its own authenticated API
lookup. The simulated payment tests your callback and order-state logic; the
Sepolia transfer additionally tests the on-chain payment path.Repeat with duplicate callbacks, an abandoned checkout, expiration, and an
API timeout. Verify that no test can create duplicate fulfillment.See the go-live checklist before replacing
the sandbox host and credentials with production values.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Billions","description":"Integrate Billions payments into your application, store, or billing platform.","colors":{"primary":"#FC4C07","light":"#FC4C07","dark":"#FF7138"},"logo":{"light":"https://mintcdn.com/billions/GmnorJJmmpzZPFoc/logo/logo-black.svg?fit=max\u0026auto=format\u0026n=GmnorJJmmpzZPFoc\u0026q=85\u0026s=e47ff33b3137a04e2ae4b8773ec5e5af","dark":"https://mintcdn.com/billions/GmnorJJmmpzZPFoc/logo/logo-white.svg?fit=max\u0026auto=format\u0026n=GmnorJJmmpzZPFoc\u0026q=85\u0026s=81016c8b19a97e7ddecb5ae8a5681578","href":"https://billions.works"},"api":{"playground":{"display":"simple"}},"appearance":{"default":"system","strict":false},"background":{"color":{"light":"#FFFFFF","dark":"#111110"}},"navbar":{"links":[{"href":"https://app.billions.works","label":"Dashboard"}]},"footer":{"socials":{"github":"https://github.com/billions-works"}},"seo":{"metatags":{"og:image":"https://billions.works/images/og/og-image.png","twitter:image":"https://billions.works/images/og/og-image.png","twitter:card":"summary_large_image"},"indexing":"all"},"fonts":{"family":"Instrument Sans"},"styling":{"eyebrows":"breadcrumbs","codeblocks":{"theme":{"light":"github-dark","dark":"github-dark"}},"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"billions","hasAudioNarration":false,"actualSubdomain":"billions","customDomains":["docs.billions.works"],"gitSource":{"type":"github","owner":"billions-works","repo":"mintlify-docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6b00203dde75caffbb015865","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Developer","count":25},{"language":"default","tag":"Integration guide","count":6},{"language":"default","tag":"Public API","count":5},{"language":"default","tag":"Platform integrations","count":5},{"language":"default","tag":"SDKs","count":4},{"language":"default","tag":"Examples","count":3},{"language":"default","tag":"Legal","count":2},{"language":"default","tag":"Overview","count":1},{"language":"default","tag":"Introduction","count":1},{"language":"default","tag":"Testing","count":1}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","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":"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":"site-roles","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":"editor-metadata","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":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":true},"customCss":[{"filePath":"style.css","content":":root{--billions-accent: #fc4c07;--billions-accent-hover: #e24406;--billions-accent-soft: #f6e4dd;--billions-background: #ffffff;--billions-surface: #fafafa;--billions-surface-raised: #ffffff;--billions-border: #ededed;--billions-heading: #000000;--billions-text: #555555;--billions-muted: #737373;--billions-code: #222221;--billions-shadow: 0 10px 30px rgb(0 0 0 / 4%)}html.dark{--billions-accent: #ff7138;--billions-accent-hover: #ff8657;--billions-accent-soft: rgb(252 76 7 / 16%);--billions-background: #111110;--billions-surface: #181817;--billions-surface-raised: #1e1e1c;--billions-border: #30302d;--billions-heading: #ffffff;--billions-text: #c8c8c8;--billions-muted: #92928d;--billions-code: #222221;--billions-shadow: 0 12px 36px rgb(0 0 0 / 24%)}html,body,#body-content{background-color:var(--billions-background)}body{color:var(--billions-text);font-variation-settings:\"wdth\" 100;text-rendering:optimizeLegibility}#navbar{min-height:76px;border-bottom-color:var(--billions-border);background-color:color-mix(in srgb, var(--billions-background) 92%, transparent);backdrop-filter:blur(16px)}#sidebar-content{scrollbar-color:var(--billions-border) transparent}#sidebar-content li[data-active]{color:var(--billions-accent);background:var(--billions-accent-soft);border-radius:10px}toc-item[data-active],toc-item[data-active-deepest]{color:var(--billions-accent)}[data-component-name=\"theme-toggle\"],#topbar-cta-button{border-color:var(--billions-border);border-radius:16px}#topbar-cta-button{box-shadow:none}#content-area{padding-top:48px}#content{max-width:712px}#page-title{color:var(--billions-heading);font-size:clamp(2.5rem, 4vw, 3rem);font-weight:500;line-height:1.04;letter-spacing:-0.035em}#content h2{color:var(--billions-heading);font-size:2rem;font-weight:500;line-height:1.125;letter-spacing:-0.025em}#content h3,#content h4{color:var(--billions-heading);font-weight:550;letter-spacing:-0.015em}#content p,#content li{line-height:1.625}#content a:not([class]){text-decoration-color:color-mix(in srgb, var(--billions-accent) 38%, transparent);text-underline-offset:3px}html[data-current-path$=\"/integration/unified-merchant-api\"] #content [data-as=\"p\"]:has(>em:only-child){color:var(--billions-muted);font-size:0.75rem}card,.card{border-color:var(--billions-border)!important;border-radius:24px!important;background:var(--billions-surface)!important;box-shadow:none!important;transition:border-color 160ms ease, transform 160ms ease, box-shadow 160ms ease}card:hover,.card:hover{border-color:color-mix(in srgb, var(--billions-accent) 38%, var(--billions-border))!important;box-shadow:var(--billions-shadow)!important;transform:translateY(-1px)}callout,.callout{border-radius:16px!important;border-width:1px!important;border-style:solid!important}.callout[data-callout-type=\"note\"]{border-color:#bfd4ff!important}.callout[data-callout-type=\"tip\"]{border-color:#9edfc4!important}.callout[data-callout-type=\"info\"]{border-color:#d4d4d4!important}.callout[data-callout-type=\"warning\"]{border-color:#f3c985!important}.callout[data-callout-type=\"danger\"]{border-color:#f4aaa6!important}html.dark .callout[data-callout-type=\"note\"]{border-color:#315ca8!important}html.dark .callout[data-callout-type=\"tip\"]{border-color:#277253!important}html.dark .callout[data-callout-type=\"info\"]{border-color:#575757!important}html.dark .callout[data-callout-type=\"warning\"]{border-color:#8c5c17!important}html.dark .callout[data-callout-type=\"danger\"]{border-color:#963e39!important}steps,.steps{--tw-prose-counters: var(--billions-accent)}.step [data-component-part=\"step-line\"]{display:none}.step [data-component-part=\"step-number\"]{color:inherit;background:transparent;border:0;border-radius:0}.step [data-component-part=\"step-number\"]>div{width:28px;height:28px;color:var(--billions-accent);background:var(--billions-accent-soft);border:0;border-radius:9999px}code-block,code-group,.code-block,.code-group{overflow:hidden;border-color:color-mix(in srgb, var(--billions-code) 82%, white)!important;border-radius:12px!important;background:var(--billions-code)!important}#content .code-block [data-component-part=\"code-block-root\"],#content .code-group [data-component-part=\"code-block-root\"],.code-block pre.shiki,.code-group pre.shiki{color:var(--shiki-dark, #d4d4d4)!important;background-color:var(--billions-code)!important}.code-block pre.shiki span,.code-group pre.shiki span{color:var(--shiki-dark, inherit)!important}.code-block [data-fade-overlay],.code-group [data-fade-overlay]{--fade-color-light: var(--billions-code) !important;--fade-color-dark: var(--billions-code) !important}.code-block [data-floating-buttons] button,.code-group [data-floating-buttons] button{color:#a3a3a3;background:var(--billions-code)!important}.code-block [data-floating-buttons] button:hover,.code-group [data-floating-buttons] button:hover{color:#ffffff}.code-block [data-floating-buttons] button svg,.code-group [data-floating-buttons] button svg{color:inherit!important}#content :not(pre)>code{color:var(--billions-heading);background:var(--billions-surface);border:1px solid var(--billions-border);border-radius:7px}#content table{overflow:hidden;border:1px solid var(--billions-border);border-radius:16px;border-collapse:separate;border-spacing:0}#content thead{color:var(--billions-heading);background:var(--billions-surface)}#content th,#content td{border-color:var(--billions-border)}#content th{padding-top:8px}#content th:first-child,#content td:first-child{padding-left:16px}#content th:last-child,#content td:last-child{padding-right:16px}::selection{color:var(--billions-heading);background:var(--billions-accent-soft)}@media (max-width: 1023px){#content-area{padding-top:36px}}@media (max-width: 767px){#navbar{min-height:64px}#content-area{padding-top:28px}#page-title{font-size:2.25rem;line-height:1.08}#content h2{font-size:1.75rem}card,.card{border-radius:20px!important}}@media (prefers-reduced-motion: reduce){card,.card{transition:none}}"}]}
{"page":{"pagePath":"integration/sandbox-testing","slug":"/integration/sandbox-testing","pageMetadata":{"title":"Sandbox testing","description":"Complete a sandbox payment with the test API or Sepolia test ETH, then verify callbacks.","icon":"flask","href":"/integration/sandbox-testing"},"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: \"Complete a sandbox payment with the test API or Sepolia test ETH, then verify callbacks.\"\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`,ol:`ol`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,..._provideComponents(),...props.components},{CodeBlock,CodeGroup,Heading,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!CodeGroup)_missingMdxReference(`CodeGroup`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Sandbox and production have separate API hosts and credentials. For a custom\nintegration, test against `,_jsx(_components.code,{children:`https://api-sandbox.billions.works`}),` before switching\nto production. You can finish a sandbox invoice either with the test API or\nby sending Sepolia test ETH to a TETH invoice. Neither option moves real funds.`]}),`\n`,_jsx(Heading,{level:`2`,id:`prepare-your-test`,children:`Prepare your test`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`https://app.billions.works`,children:`Sign in to the Billions app`}),`, switch to\n`,_jsx(_components.strong,{children:`Sandbox`}),`, and create a sandbox API key under `,_jsx(_components.strong,{children:`Settings → API`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Configure your backend with the sandbox API URL and sandbox key. Keep both\nexplicit; the `,_jsx(_components.a,{href:`/sdks/typescript`,children:`TypeScript SDK`}),` defaults to production if\n`,_jsx(_components.code,{children:`baseUrl`}),` is omitted.`]}),`\n`,_jsxs(_components.li,{children:[`Make your callback endpoint reachable over HTTPS. Create an invoice with a\nunique `,_jsx(_components.code,{children:`order_no`}),`, a stable `,_jsx(_components.code,{children:`idempotencyKey`}),`, a small supported amount, and\n`,_jsx(_components.code,{children:`callbackUrl`}),`. Store the returned `,_jsx(_components.code,{children:`id`}),` and `,_jsx(_components.code,{children:`expires_at`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Open the returned `,_jsx(_components.code,{children:`invoice_url`}),` to check the hosted checkout. The app’s\nSandbox `,_jsx(_components.strong,{children:`Demo Shop`}),` creates a separate invoice; it does not test your\ncallback endpoint.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`option-1-mark-an-invoice-as-paid-with-the-sandbox-api`,children:`Option 1: Mark an invoice as paid with the sandbox API`}),`\n`,_jsxs(_components.p,{children:[`Send the invoice `,_jsx(_components.code,{children:`id`}),` returned by the create endpoint to\n`,_jsx(_components.code,{children:`POST /public/v1/invoices/mark-as-paid`}),` on the `,_jsx(_components.strong,{children:`sandbox host`}),`. Use the same\nmerchant’s sandbox API key. This simulates a successful payment, updates the\ninvoice to `,_jsx(_components.code,{children:`completed`}),`, and queues the normal `,_jsx(_components.code,{children:`invoice.paid`}),` callback when the\ninvoice has a `,_jsx(_components.code,{children:`callbackUrl`}),`. No blockchain transfer is required.\nIn the TypeScript example, `,_jsx(_components.code,{children:`invoice`}),` is the result of your earlier create call;\nfor cURL, set `,_jsx(_components.code,{children:`BILLIONS_INVOICE_ID`}),` to that response’s `,_jsx(_components.code,{children:`id`}),`.`]}),`\n`,_jsxs(CodeGroup,{children:[_jsx(CodeBlock,{filename:`TypeScript`,numberOfLines:`13`,language:`typescript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-dark github-dark`,style:{backgroundColor:`#24292e`,\"--shiki-dark-bg\":`#24292e`,color:`#e1e4e8`,\"--shiki-dark\":`#e1e4e8`},language:`typescript`,children:_jsxs(_components.code,{language:`typescript`,numberOfLines:`13`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#F97583`,\"--shiki-dark\":`#F97583`},children:`const`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` baseUrl = `}),_jsx(_components.span,{style:{color:`#9ECBFF`,\"--shiki-dark\":`#9ECBFF`},children:`'https://api-sandbox.billions.works'`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:`;`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#F97583`,\"--shiki-dark\":`#F97583`},children:`const`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` response = `}),_jsx(_components.span,{style:{color:`#F97583`,\"--shiki-dark\":`#F97583`},children:`await`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` fetch(`}),_jsx(_components.span,{style:{color:`#9ECBFF`,\"--shiki-dark\":`#9ECBFF`},children:\"`${baseUrl}/public/v1/invoices/mark-as-paid`\"}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:`, {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` method: `}),_jsx(_components.span,{style:{color:`#9ECBFF`,\"--shiki-dark\":`#9ECBFF`},children:`'POST'`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` headers: {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9ECBFF`,\"--shiki-dark\":`#9ECBFF`},children:` 'Content-Type'`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:`: `}),_jsx(_components.span,{style:{color:`#9ECBFF`,\"--shiki-dark\":`#9ECBFF`},children:`'application/json'`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9ECBFF`,\"--shiki-dark\":`#9ECBFF`},children:` 'x-api-key'`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:`: process.env.BILLIONS_API_KEY!,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` },`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` body: JSON.stringify({ invoiceId: invoice.id }),`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:`});`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#F97583`,\"--shiki-dark\":`#F97583`},children:`if`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` (!response.ok) `}),_jsx(_components.span,{style:{color:`#F97583`,\"--shiki-dark\":`#F97583`},children:`throw`}),_jsx(_components.span,{style:{color:`#F97583`,\"--shiki-dark\":`#F97583`},children:` new`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` Error(`}),_jsx(_components.span,{style:{color:`#9ECBFF`,\"--shiki-dark\":`#9ECBFF`},children:\"`Sandbox payment failed: ${response.status}`\"}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:`);`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#F97583`,\"--shiki-dark\":`#F97583`},children:`const`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` paidInvoice = `}),_jsx(_components.span,{style:{color:`#F97583`,\"--shiki-dark\":`#F97583`},children:`await`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` response.json();`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:`console.log(paidInvoice.status); `}),_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`// completed`})]}),`\n`]})})}),_jsx(CodeBlock,{filename:`cURL`,numberOfLines:`5`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-dark github-dark`,style:{backgroundColor:`#24292e`,\"--shiki-dark-bg\":`#24292e`,color:`#e1e4e8`,\"--shiki-dark\":`#e1e4e8`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`5`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#B392F0`,\"--shiki-dark\":`#B392F0`},children:`curl`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` --request POST \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` --url `}),_jsx(_components.span,{style:{color:`#9ECBFF`,\"--shiki-dark\":`#9ECBFF`},children:`'https://api-sandbox.billions.works/public/v1/invoices/mark-as-paid'`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` --header `}),_jsx(_components.span,{style:{color:`#9ECBFF`,\"--shiki-dark\":`#9ECBFF`},children:`'Content-Type: application/json'`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` --header `}),_jsx(_components.span,{style:{color:`#9ECBFF`,\"--shiki-dark\":`#9ECBFF`},children:`\"x-api-key: $BILLIONS_API_KEY\"`}),_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#E1E4E8`,\"--shiki-dark\":`#E1E4E8`},children:` --data `}),_jsx(_components.span,{style:{color:`#9ECBFF`,\"--shiki-dark\":`#9ECBFF`},children:`\"{\\\\\"invoiceId\\\\\":\\\\\"$BILLIONS_INVOICE_ID\\\\\"}\"`})]}),`\n`]})})})]}),`\n`,_jsxs(_components.p,{children:[`The invoice must belong to the authenticated merchant, have a valid UUID,\nstill be unexpired, and be in `,_jsx(_components.code,{children:`pending`}),` or `,_jsx(_components.code,{children:`processing`}),`. A repeated call, an\nexpired invoice, or another status returns `,_jsx(_components.code,{children:`409`}),`. An invalid UUID returns\n`,_jsx(_components.code,{children:`400`}),`; an unknown invoice or a request outside sandbox returns `,_jsx(_components.code,{children:`404`}),`.`]}),`\n`,_jsx(Warning,{children:_jsx(_components.p,{children:`This endpoint is for testing only. It is unavailable in production; do not\nput it in a production payment or fulfillment flow.`})}),`\n`,_jsx(Heading,{level:`2`,id:`option-2-pay-with-sepolia-test-eth`,children:`Option 2: Pay with Sepolia test ETH`}),`\n`,_jsxs(_components.p,{children:[`The sandbox currency `,_jsx(_components.code,{children:`TETH`}),` is `,_jsx(_components.strong,{children:`native test ETH on Ethereum Sepolia`}),` (chain\nID `,_jsx(_components.code,{children:`11155111`}),`, internal ticker `,_jsx(_components.code,{children:`ETH_TEST5`}),`). It has no ERC-20 contract address.\nTo exercise a real testnet transfer:`]}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[`Create a sandbox invoice with `,_jsx(_components.code,{children:`currency: \"TETH\"`}),` and your `,_jsx(_components.code,{children:`callbackUrl`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Open its `,_jsx(_components.code,{children:`invoice_url`}),` and use the displayed Sepolia payment address and\namount. Obtain Sepolia test ETH from a testnet faucet if needed.`]}),`\n`,_jsxs(_components.li,{children:[`From a wallet connected to `,_jsx(_components.strong,{children:`Sepolia`}),`, send the requested test ETH to that\naddress. Do not use Ethereum mainnet or send real ETH.`]}),`\n`,_jsx(_components.li,{children:`Wait for network confirmation, then retrieve the invoice from the API and\ncheck that your callback handler processed the update.`}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`Only TETH is listed as a Sepolia payment currency by the current\n`,_jsx(_components.a,{href:`https://api-sandbox.billions.works/public/v1/currencies`,children:`sandbox currencies endpoint`}),`.\nDo not assume that other testnet ERC-20 tokens sent to the same address will\npay this invoice.`]}),`\n`,_jsx(Heading,{level:`2`,id:`verify-the-end-to-end-result`,children:`Verify the end-to-end result`}),`\n`,_jsxs(_components.p,{children:[`With either option, retrieve `,_jsx(_components.code,{children:`GET /public/v1/invoices/{id}`}),` using the sandbox\nAPI key. Confirm the invoice ID, `,_jsx(_components.code,{children:`order_no`}),`, `,_jsx(_components.code,{children:`amount`}),`, and\n`,_jsx(_components.code,{children:`settlement_currency`}),` match your stored attempt, then require `,_jsx(_components.code,{children:`completed`}),`\nbefore fulfillment. If you set `,_jsx(_components.code,{children:`callbackUrl`}),`, verify that your endpoint\nreceived the notification and still performed its own authenticated API\nlookup. The simulated payment tests your callback and order-state logic; the\nSepolia transfer additionally tests the on-chain payment path.`]}),`\n`,_jsx(_components.p,{children:`Repeat with duplicate callbacks, an abandoned checkout, expiration, and an\nAPI timeout. Verify that no test can create duplicate fulfillment.`}),`\n`,_jsxs(_components.p,{children:[`See the `,_jsx(_components.a,{href:`/integration/go-live-checklist`,children:`go-live checklist`}),` before replacing\nthe sandbox host and credentials with production values.`]})]})}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":{"codeStyling":{"theme":{"light":"github-dark","dark":"github-dark"}},"config":{},"pageMetadata":{"title":"Sandbox testing","description":"Complete a sandbox payment with the test API or Sepolia test ETH, then verify callbacks.","icon":"flask","href":"/integration/sandbox-testing"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Prepare your test","slug":"prepare-your-test","depth":2,"children":[]},{"title":"Option 1: Mark an invoice as paid with the sandbox API","slug":"option-1-mark-an-invoice-as-paid-with-the-sandbox-api","depth":2,"children":[]},{"title":"Option 2: Pay with Sepolia test ETH","slug":"option-2-pay-with-sepolia-test-eth","depth":2,"children":[]},{"title":"Verify the end-to-end result","slug":"verify-the-end-to-end-result","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"billions","siteName":"Billions","title":"Sandbox testing - Billions","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-09T15:20:39.044Z","originalFileLocation":"integration/sandbox-testing.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=\"Complete a sandbox payment with the test API or Sepolia test ETH, then verify callbacks.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Billions\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/billions/_generated/favicon/apple-touch-icon.png?v=3\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/billions/_generated/favicon/favicon-32x32.png?v=3\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/billions/_generated/favicon/favicon-16x16.png?v=3\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/billions/_generated/favicon/favicon.ico?v=3\">\u003cmeta data-mint-head property=\"og:title\" content=\"Sandbox testing - Billions\">\u003cmeta data-mint-head property=\"og:description\" content=\"Complete a sandbox payment with the test API or Sepolia test ETH, then verify callbacks.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Billions\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.billions.works/integration/sandbox-testing\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://billions.works/images/og/og-image.png\">\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=\"Sandbox testing - Billions\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Complete a sandbox payment with the test API or Sepolia test ETH, then verify callbacks.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://billions.works/images/og/og-image.png\">\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=\"https://mintlify.s3.us-west-1.amazonaws.com/billions/_generated/favicon/browserconfig.xml?v=3\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Billions\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#FC4C07\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.billions.works/integration/sandbox-testing\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/integration/sandbox-testing.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.billions.works/#organization\",\"name\":\"Billions\",\"url\":\"https://docs.billions.works\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/billions/GmnorJJmmpzZPFoc/logo/logo-black.svg?fit=max\u0026auto=format\u0026n=GmnorJJmmpzZPFoc\u0026q=85\u0026s=e47ff33b3137a04e2ae4b8773ec5e5af\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.billions.works#website\",\"name\":\"Billions\",\"url\":\"https://docs.billions.works\",\"publisher\":{\"@id\":\"https://docs.billions.works/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.billions.works/integration/sandbox-testing#webpage\",\"url\":\"https://docs.billions.works/integration/sandbox-testing\",\"name\":\"Sandbox testing\",\"description\":\"Complete a sandbox payment with the test API or Sepolia test ETH, then verify callbacks.\",\"dateModified\":\"2026-11-09T15:20:39.044Z\",\"isPartOf\":{\"@id\":\"https://docs.billions.works#website\"},\"breadcrumb\":{\"@id\":\"https://docs.billions.works/integration/sandbox-testing#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.billions.works/integration/sandbox-testing#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Billions\",\"item\":\"https://docs.billions.works\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Sandbox testing\",\"item\":\"https://docs.billions.works/integration/sandbox-testing\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.billions.works/integration/sandbox-testing#article\",\"headline\":\"Sandbox testing\",\"name\":\"Sandbox testing\",\"description\":\"Complete a sandbox payment with the test API or Sepolia test ETH, then verify callbacks.\",\"url\":\"https://docs.billions.works/integration/sandbox-testing\",\"mainEntityOfPage\":{\"@id\":\"https://docs.billions.works/integration/sandbox-testing#webpage\"},\"image\":\"https://billions.works/images/og/og-image.png\",\"dateModified\":\"2026-11-09T15:20:39.044Z\",\"publisher\":{\"@id\":\"https://docs.billions.works/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.billions.works#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Billions\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Billions\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/integration/sandbox-testing.md","siteName":"Billions","nav":{"global":null,"tabs":[{"tab":"Introduction","pages":[{"title":"Introduction","href":""}]},{"tab":"Developer","groups":[{"group":"Overview","pages":[{"title":"Developer documentation","icon":"code","href":"/developer/overview"}]},{"group":"Integration guide","pages":[{"title":"Integration overview","icon":"diagram-project","href":"/integration/overview"},{"title":"Prerequisites","icon":"list-check","href":"/integration/prerequisites"},{"title":"Payment flow","icon":"credit-card","href":"/integration/payment-flow"},{"title":"Unified Merchant API","icon":"plug","href":"/integration/unified-merchant-api"},{"title":"Callbacks and security","icon":"shield-halved","href":"/integration/callbacks-and-security"},{"title":"Go-live checklist","description":"Verify reliability and security before accepting production payments.","icon":"rocket","href":"/integration/go-live-checklist"}]},{"group":"Testing","pages":[{"title":"Sandbox testing","icon":"flask","href":"/integration/sandbox-testing"}]},{"group":"Public API","pages":[{"title":"Public API overview","description":"Environments, authentication, and endpoints available in Billions Public API v1.","icon":"brackets-curly","href":"/api/overview"},{"title":"Create an invoice API","icon":"file-invoice","href":"/api/create-invoice"},{"title":"Statuses and lifecycle","icon":"list-check","href":"/api/statuses"},{"title":"Request signing","icon":"signature","href":"/api/request-signing"},{"title":"Withdrawals and refunds","icon":"money-bill-transfer","href":"/api/withdrawals-and-refunds"}]},{"group":"Examples","pages":[{"title":"Create an invoice","icon":"file-invoice","href":"/examples/create-an-invoice"},{"title":"Handle a callback","icon":"webhook","href":"/examples/handle-a-callback"},{"title":"Get invoices from the API","icon":"rotate","href":"/examples/get-invoices-from-api"}]},{"group":"SDKs","pages":[{"title":"SDK overview","icon":"boxes-stacked","href":"/sdks/overview"},{"title":"TypeScript SDK","icon":"js","href":"/sdks/typescript"},{"title":"Python SDK","icon":"python","href":"/sdks/python"},{"title":"PHP SDK","icon":"php","href":"/sdks/php"}]},{"group":"Platform integrations","pages":[{"title":"Platform integrations","icon":"store","href":"/store-integrations/overview"},{"title":"WooCommerce","icon":"wordpress","href":"/store-integrations/woocommerce"},{"title":"BILLmanager","icon":"server","href":"/store-integrations/billmanager"},{"title":"WHMCS","icon":"server","href":"/store-integrations/whmcs"},{"title":"Tilda","icon":"cart-shopping","href":"/store-integrations/tilda"}]}]},{"tab":"Legal","pages":[{"title":"Legal","href":"/legal/overview"}]}]},"basePath":"","title":"Sandbox testing - Billions","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":[],"chunks":[]}