Create a new charge.
An idempotency key is required in the request header to ensure safe retries without creating duplicate charges.
This endpoint initializes a payment attempt for the specified amount and channel, returning a charge object that represents the transaction status and payment instructions (e.g., QR string or redirect URL).
{"docsConfig":{"theme":"mint","$schema":"https://docs.monxa.co/docs.json","name":"Monxa Product Guide and API","colors":{"primary":"#009689","light":"#00BBA7","dark":"#00BBA7"},"logo":{"light":"https://mintcdn.com/monxa/y96lbD1hVO-HZGAz/logo/light.svg?fit=max\u0026auto=format\u0026n=y96lbD1hVO-HZGAz\u0026q=85\u0026s=0c030a0ad1290b5f5aaed9b9bdd21338","dark":"https://mintcdn.com/monxa/y96lbD1hVO-HZGAz/logo/dark.svg?fit=max\u0026auto=format\u0026n=y96lbD1hVO-HZGAz\u0026q=85\u0026s=263ad8aedc50bbc565dfe08b5debf66a"},"favicon":"/favicon.svg","navbar":{"links":[{"label":"Support","href":"mailto:support@monxa.co"}],"primary":{"type":"button","label":"Home","href":"https://www.monxa.co"}},"footer":{"socials":{"x":"https://x.com/monxadev","github":"https://github.com/monxadev","linkedin":"https://linkedin.com/company/monxadev"}},"contextual":{"options":["chatgpt","claude","perplexity"]},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"monxa","hasAudioNarration":false,"actualSubdomain":"monxa","customDomains":["docs.monxa.co"],"gitSource":{"type":"github","owner":"monxadev","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6a21f66174bd683e723c42e0","collectionId":"c8946567-acd9-48b0-a991-774ef14eb9eb","schemaVersion":"v2"},"entitlements":{},"buildId":"6a21f66174bd683e723c42e0:success","clientVersion":"0.0.3971","searchFilterCounts":[{"language":"default","tag":"Get started","count":30},{"language":"default","tag":"API Reference","count":16},{"language":"default","tag":"ACCEPT PAYMENTS","count":15},{"language":"default","tag":"REFERENCES","count":8},{"language":"default","tag":"Payment Methods","count":7},{"language":"default","tag":"Security","count":7},{"language":"default","tag":"customers","count":5},{"language":"default","tag":"PAYOUTS","count":4},{"language":"default","tag":"INTRODUCTION","count":3},{"language":"default","tag":"charges","count":3}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-v7-file-tree","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"pause-universal-search-reconcile","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"per-site-search-delta","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-private-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-nav-generations","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-agent-model-picker","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"isAtlas":false,"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/charges/create-a-charge","slug":"/api-reference/charges/create-a-charge","pageMetadata":{"title":"Create a Charge","description":"Create a new charge.\nAn idempotency key is required in the request header to ensure safe retries without creating duplicate charges.\nThis endpoint initializes a payment attempt for the specified amount and channel, returning a charge object that represents the transaction status and payment instructions (e.g., QR string or redirect URL).","deprecated":false,"version":null,"openapi":"api-reference/openapi.json post /v1/charges","href":"/api-reference/charges/create-a-charge","autogeneratedByOpenApi":true},"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: \"Create a new charge.\\nAn idempotency key is required in the request header to ensure safe retries without creating duplicate charges.\\nThis endpoint initializes a payment attempt for the specified amount and channel, returning a charge object that represents the transaction status and payment instructions (e.g., QR string or redirect URL).\"\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":{"config":{},"pageMetadata":{"title":"Create a Charge","description":"Create a new charge.\nAn idempotency key is required in the request header to ensure safe retries without creating duplicate charges.\nThis endpoint initializes a payment attempt for the specified amount and channel, returning a charge object that represents the transaction status and payment instructions (e.g., QR string or redirect URL).","deprecated":false,"version":null,"openapi":"api-reference/openapi.json post /v1/charges","href":"/api-reference/charges/create-a-charge","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"summary":"Create a Charge","deprecated":false,"description":"Create a new charge.\nAn idempotency key is required in the request header to ensure safe retries without creating duplicate charges.\nThis endpoint initializes a payment attempt for the specified amount and channel, returning a charge object that represents the transaction status and payment instructions (e.g., QR string or redirect URL).","tags":["charges"],"parameters":["25184e9e-27ac-45eb-aa78-26a6cd2a1623"],"requestBody":"d8b63078-70f1-457d-9fbf-3ad5c4c11b73","responses":{"200":"c76ebbcf-5127-499a-b81a-a505dd013557","409":"44b58a1d-bc05-4550-b5f4-dc64313eeb95"},"security":["82f0c8b3-8eda-47ea-83bf-efce70ee9203"],"method":"post","type":"path","servers":[],"path":"/v1/charges","baseUrlOptions":[],"title":"Create a Charge","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"25184e9e-27ac-45eb-aa78-26a6cd2a1623":{"name":"x-idempotency-key","in":"header","description":"","required":false,"example":"0XGGG99RP0D90","schema":{"type":"string","isRequired":false,"uniqueKey":"","typeLabel":"string"}}},"requestBody":{"content":{"application/json":{"schema":{"required":["amount","currency","channel_code","action_flow"],"type":"object","properties":{"amount":{"type":"number","description":"The amount to be charged, expressed in minor units (e.g., 10000 = 100.00).","format":"double","isRequired":true,"uniqueKey":"amount","typeLabel":"number\u003cdouble>"},"currency":{"type":"string","description":"The three-letter ISO 4217 currency code (e.g., IDR, MYR, SGD).","isRequired":true,"uniqueKey":"currency","typeLabel":"string"},"channel_code":{"type":"string","enum":["qr_qris"],"description":"The payment channel to be used, such as qr_qris, bank_redirect_fpx, wallet_dana, etc.","isRequired":true,"uniqueKey":"channel_code","typeLabel":"enum\u003cstring>"},"action_flow":{"type":"string","enum":["payload","redirection","embedded"],"description":"The type of payment flow, e.g.redirect, or show. Determines how Merchant presents the payment experience to the user.","isRequired":true,"uniqueKey":"action_flow","typeLabel":"enum\u003cstring>"},"reference_id":{"oneOf":[{"type":"string","description":"Merchant’s unique reference ID for this charge (e.g., order number or invoice ID). Used for reconciliation and idempotency tracking.","uniqueKey":"reference_id.oneOf.0","typeLabel":"string"},{"type":"null","description":"Merchant’s unique reference ID for this charge (e.g., order number or invoice ID). Used for reconciliation and idempotency tracking.","uniqueKey":"reference_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"reference_id","typeLabel":"string | null"},"description":{"oneOf":[{"type":"string","description":"Optional short text describing the purpose of the payment or charge. Useful for invoices or customer-facing receipts.","uniqueKey":"description.oneOf.0","typeLabel":"string"},{"type":"null","description":"Optional short text describing the purpose of the payment or charge. Useful for invoices or customer-facing receipts.","uniqueKey":"description.oneOf.1","typeLabel":"null"}],"uniqueKey":"description","typeLabel":"string | null"},"metadata":{"oneOf":[{"type":"object","additionalProperties":{"type":"string","uniqueKey":"metadata.oneOf.0.additionalProperties","typeLabel":"string"},"description":"Optional custom key–value pairs for additional information","properties":{},"uniqueKey":"metadata.oneOf.0","typeLabel":"object"},{"type":"null","additionalProperties":{"type":"string","uniqueKey":"metadata.oneOf.1.additionalProperties","typeLabel":"string"},"description":"Optional custom key–value pairs for additional information","properties":{},"uniqueKey":"metadata.oneOf.1","typeLabel":"null"}],"uniqueKey":"metadata","typeLabel":"object | null"}},"uniqueKey":"","typeLabel":"object"},"example":{"amount":5300,"currency":"IDR","channel_code":"qr_qris","reference_id":"merchant_26","description":"Viridis cogo aureus. Tollo eum antepono administratio cupressus dolore uredo. Amissio decet vir subvenio asperiores. Degusto vesper aer.","metadata":{"qui6":"culpa elit","cillum9b":"amet in dolore","dolor74":"deserunt reprehenderit magna do"}},"examples":{"Example":{"title":"Example","value":{"amount":5300,"currency":"IDR","channel_code":"qr_qris","reference_id":"merchant_26","description":"Viridis cogo aureus. Tollo eum antepono administratio cupressus dolore uredo. Amissio decet vir subvenio asperiores. Degusto vesper aer.","metadata":{"qui6":"culpa elit","cillum9b":"amet in dolore","dolor74":"deserunt reprehenderit magna do"}}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"c76ebbcf-5127-499a-b81a-a505dd013557":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the charge","isRequired":true,"uniqueKey":"id","typeLabel":"string"},"code":{"type":"string","description":"nique charge code generated by Monxa for tracking or reconciliation. (e.g. chg_2510BBFC2A3A6CE22F1B).","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"reference_id":{"type":"string","description":"Merchant-provided identifier such as invoice or order number.","isRequired":true,"uniqueKey":"reference_id","typeLabel":"string"},"merchant_id":{"type":"string","description":"Unique ID of the merchant who created the charge.","isRequired":true,"uniqueKey":"merchant_id","typeLabel":"string"},"amount":{"type":"integer","description":"Charge amount in minor units (e.g., 3500 = IDR 35.00).","isRequired":true,"uniqueKey":"amount","typeLabel":"integer"},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., IDR, MYR, SGD).","isRequired":true,"uniqueKey":"currency","typeLabel":"string"},"channel_code":{"type":"string","description":"The selected payment channel (e.g., qr_qris, bank_redirect_fpx, wallet_dana).","isRequired":true,"uniqueKey":"channel_code","typeLabel":"string"},"action_flow":{"type":"string","description":"Defines how the charge is presented — e.g., payload, redirection, or embedded.","isRequired":true,"uniqueKey":"action_flow","typeLabel":"string"},"status":{"type":"string","description":"Current charge status (PENDING, SUCCEEDED, FAILED, etc.).","isRequired":true,"uniqueKey":"status","typeLabel":"string"},"description":{"type":"string","description":"Merchant’s description of the charge or transaction.","isRequired":true,"uniqueKey":"description","typeLabel":"string"},"metadata":{"type":"object","properties":{},"description":"Custom key–value pairs provided in the request for additional context.","isRequired":true,"uniqueKey":"metadata","typeLabel":"object"},"action":{"type":"object","properties":{"qr_image_url":{"type":"string","description":"URL to a hosted QR image to be displayed for payment.","isRequired":true,"uniqueKey":"action.qr_image_url","typeLabel":"string"},"qr_payload":{"type":"string","description":"The QR string payload used for QR-based payment apps (e.g., QRIS).","isRequired":true,"uniqueKey":"action.qr_payload","typeLabel":"string"},"simulation_url":{"type":"string","description":"Sandbox/testing link to simulate the payment flow (only returned in sandbox environment).","isRequired":true,"uniqueKey":"action.simulation_url","typeLabel":"string"},"type":{"type":"string","description":"Instruction type for client handling. For example, PRESENT_TO_CUSTOMER indicates the merchant should display or redirect the user to complete payment.","isRequired":true,"uniqueKey":"action.type","typeLabel":"string"}},"required":["qr_image_url","qr_payload","simulation_url","type"],"description":"Contains payment instructions or URLs to be presented to the customer.","isRequired":true,"uniqueKey":"action","typeLabel":"object"},"embedded_url":{"type":"string","isRequired":true,"uniqueKey":"embedded_url","typeLabel":"string"},"created_by":{"type":"string","description":"Identifier of the user or API key that created the charge.","isRequired":true,"uniqueKey":"created_by","typeLabel":"string"},"created_on":{"type":"string","description":"Timestamp when the charge was created.","isRequired":true,"uniqueKey":"created_on","typeLabel":"string"},"updated_by":{"type":"string","description":"Identifier of the user or process that last updated the charge.","isRequired":true,"uniqueKey":"updated_by","typeLabel":"string"},"updated_on":{"type":"string","description":"Timestamp of the last update to this charge.","isRequired":true,"uniqueKey":"updated_on","typeLabel":"string"}},"required":["action","metadata","action_flow","amount","channel_code","code","currency","description","merchant_id","reference_id","status","created_by","created_on","updated_by","updated_on","id","embedded_url"],"uniqueKey":"","typeLabel":"object"},"examples":{"1":{"title":"1","value":{"action":{"embedded_url":"https://checkout.monxa.dev/payments/019a058a-0a86-7c35-969e-f883a56f1e10","simulation_url":"https://checkout.monxa.dev/payments/simulation/019a058a-0a86-7c35-969e-f883a56f1e10","type":"PRESENT_TO_CUSTOMER"},"meta_data":{"qui6":"culpa elit","cillum9b":"amet in dolore","dolor74":"deserunt reprehenderit magna do"},"action_flow":"EMBEDDED","amount":4300,"channel_code":"QR_QRIS","code":"CHG_2510969EF883A56F1E10","currency":"IDR","description":"Viridis cogo aureus. Tollo eum antepono administratio cupressus dolore uredo. Amissio decet vir subvenio asperiores. Degusto vesper aer.","merchant_id":"019a0423-2941-735f-9a93-819df469ad39","reference_id":"merchant_26","status":"PENDING","created_by":"drunk@sandbox.dev","created_on":"2025-10-21T06:52:04.1021719+00:00","updated_by":"drunk@sandbox.dev","updated_on":"2025-10-21T06:52:04.365363+00:00","id":"019a058a-0a86-7c35-969e-f883a56f1e10"}},"3":{"title":"3","value":{"action":{"checkout_url":"https://checkout.monxa.dev/payments/019a0625-3a69-7279-99a4-50ac66afa159","embedded_url":"https://checkout.monxa.dev/payments/019a0625-3a69-7279-99a4-50ac66afa159","qr_image_url":"https://checkout.monxa.dev/api/payments/qr/019a0625-3a69-7279-99a4-50ac66afa159","qr_payload":"000THIS IS A DUMMY QR00012345000GO TO SIMULATE PAGE ON DASHBOARD TO COMPLETE PAYMENT00012345000COM.PROVIDER.WWW00012345000ID.CO.QRIS.WWW000123000THIS IS A DUMMY QR00012345000GO TO SIMULATE PAGE ON DASHBOARD TO COMPLETE PAYMENT00012345.0001234ID1234Durianpay1234KOTA JAKARTA12345000","type":"PRESENT_TO_CUSTOMER"},"metadata":{"qui6":"culpa elit","cillum9b":"amet in dolore","dolor74":"deserunt reprehenderit magna do"},"amount":5300,"channel_code":"QR_QRIS","code":"CHG_251099A450AC66AFA159","currency":"IDR","description":"Viridis cogo aureus. Tollo eum antepono administratio cupressus dolore uredo. Amissio decet vir subvenio asperiores. Degusto vesper aer.","merchant_id":"019a0423-2941-735f-9a93-819df469ad39","reference_id":"merchant_26","status":"PENDING","created_by":"drunk@sandbox.dev","created_on":"2025-10-21T09:41:34.4412661+00:00","updated_by":"drunk@sandbox.dev","updated_on":"2025-10-21T09:41:35.1766779+00:00","id":"019a0625-3a69-7279-99a4-50ac66afa159"}}},"exampleType":"examples"}},"headers":{},"exampleType":"examples"},"44b58a1d-bc05-4550-b5f4-dc64313eeb95":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the error type, following RFC 9110. Usually points to a documentation reference for this error class.","isRequired":true,"uniqueKey":"type","typeLabel":"string"},"title":{"type":"string","description":"A short, human-readable summary of the error (e.g., \"Bad Request\").","isRequired":true,"uniqueKey":"title","typeLabel":"string"},"status":{"type":"integer","description":"The HTTP status code associated with this error (e.g., 400, 401, 404, 500).","isRequired":true,"uniqueKey":"status","typeLabel":"integer"},"detail":{"type":"string","description":"A detailed explanation of what caused the error, typically describing the missing or invalid field.","isRequired":true,"uniqueKey":"detail","typeLabel":"string"},"instance":{"type":"string","description":"The specific API endpoint or operation where the error occurred.","isRequired":true,"uniqueKey":"instance","typeLabel":"string"},"traceId":{"type":"string","description":"A unique identifier for the request trace, used for internal debugging and log correlation.","isRequired":true,"uniqueKey":"traceId","typeLabel":"string"},"trace-id":{"type":"string","description":"An alternative field name used by some systems for backward compatibility with tracing tools.","isRequired":true,"uniqueKey":"trace-id","typeLabel":"string"}},"required":["type","title","status","detail","instance","traceId","trace-id"],"uniqueKey":"","typeLabel":"object"},"example":{"type":"https://tools.ietf.org/html/rfc9110#section-15.5.1","title":"Bad Request","status":400,"detail":"x-idempotency-key header is required.","instance":"POST /v1/charges","traceId":"00-4ea955e3444de0f268b5b8cb03d3a4f9-5e01236bea69f1b9-00","trace-id":"0HNGG99RP0D72:00000001"},"examples":{"Example":{"title":"Example","value":{"type":"https://tools.ietf.org/html/rfc9110#section-15.5.1","title":"Bad Request","status":400,"detail":"x-idempotency-key header is required.","instance":"POST /v1/charges","traceId":"00-4ea955e3444de0f268b5b8cb03d3a4f9-5e01236bea69f1b9-00","trace-id":"0HNGG99RP0D72:00000001"}}},"exampleType":"examples"}},"headers":{},"exampleType":"examples"}},"security":{"82f0c8b3-8eda-47ea-83bf-efce70ee9203":{"Bearer":{"type":"http","scheme":"bearer","scopes":[]}}},"servers":{},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","scopes":[]},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Bearer authentication header of the form `Bearer \u003ctoken>`, where `\u003ctoken>` is your auth token.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"Bearer","name":"Authorization"}],"title":"Bearer"}]},"originalFileLocation":"api-reference/openapi.json"},"subdomain":"monxa","siteName":"Monxa Product Guide and API","title":"Create a Charge - Monxa Product Guide and API","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2025-10-22T09:48:59.680Z","originalFileLocation":"api-reference/charges/create-a-charge.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=\"Create a new charge. An idempotency key is required in the request header to ensure safe retries without creating duplicate charges. This endpoint initializes a payment attempt for the specified amount and channel, returning a charge object that represents the transaction status and payment instructions (e.g., QR string or redirect URL).\">\u003cmeta data-mint-head name=\"application-name\" content=\"Monxa Product Guide and API\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/monxa/bg4auHYDU6x7wxB7/_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/monxa/bg4auHYDU6x7wxB7/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/monxa/bg4auHYDU6x7wxB7/_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/monxa/bg4auHYDU6x7wxB7/_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/monxa/bg4auHYDU6x7wxB7/_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/monxa/bg4auHYDU6x7wxB7/_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/monxa/bg4auHYDU6x7wxB7/_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/monxa/bg4auHYDU6x7wxB7/_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/monxa/bg4auHYDU6x7wxB7/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create a Charge - Monxa Product Guide and API\">\u003cmeta data-mint-head property=\"og:description\" content=\"Create a new charge. An idempotency key is required in the request header to ensure safe retries without creating duplicate charges. This endpoint initializes a payment attempt for the specified amount and channel, returning a charge object that represents the transaction status and payment instructions (e.g., QR string or redirect URL).\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Monxa Product Guide and API\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.monxa.co/api-reference/charges/create-a-charge\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://monxa.mintlify.app/_mintlify/api/og/v2?division=charges\u0026amp;title=Create+a+Charge\u0026amp;description=Create+a+new+charge.%0AAn+idempotency+key+is+required+in+the+request+header+to+ensure+safe+retries+without+creating+duplicate+charges.%0AThis+endpoint+initializes+a\u0026amp;theme=3256a49d8e8b58ef47f88a2b\u0026amp;signature=c54054a0716c4079ab15bfe78aa4dcce0ba58ce25e857d786da6224e4a071dda\">\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=\"Create a Charge - Monxa Product Guide and API\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Create a new charge. An idempotency key is required in the request header to ensure safe retries without creating duplicate charges. This endpoint initializes a payment attempt for the specified amount and channel, returning a charge object that represents the transaction status and payment instructions (e.g., QR string or redirect URL).\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://monxa.mintlify.app/_mintlify/api/og/v2?division=charges\u0026amp;title=Create+a+Charge\u0026amp;description=Create+a+new+charge.%0AAn+idempotency+key+is+required+in+the+request+header+to+ensure+safe+retries+without+creating+duplicate+charges.%0AThis+endpoint+initializes+a\u0026amp;theme=3256a49d8e8b58ef47f88a2b\u0026amp;signature=c54054a0716c4079ab15bfe78aa4dcce0ba58ce25e857d786da6224e4a071dda\">\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/monxa/bg4auHYDU6x7wxB7/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Monxa Product Guide and API\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#009689\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.monxa.co/api-reference/charges/create-a-charge\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/charges/create-a-charge.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.monxa.co/#organization\",\"name\":\"Monxa Product Guide and API\",\"url\":\"https://docs.monxa.co\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/monxa/y96lbD1hVO-HZGAz/logo/light.svg?fit=max\u0026auto=format\u0026n=y96lbD1hVO-HZGAz\u0026q=85\u0026s=0c030a0ad1290b5f5aaed9b9bdd21338\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.monxa.co#website\",\"name\":\"Monxa Product Guide and API\",\"url\":\"https://docs.monxa.co\",\"publisher\":{\"@id\":\"https://docs.monxa.co/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.monxa.co/api-reference/charges/create-a-charge#webpage\",\"url\":\"https://docs.monxa.co/api-reference/charges/create-a-charge\",\"name\":\"Create a Charge\",\"description\":\"Create a new charge. An idempotency key is required in the request header to ensure safe retries without creating duplicate charges. This endpoint initializes a payment attempt for the specified amount and channel, returning a charge object that represents the transaction status and payment instructions (e.g., QR string or redirect URL).\",\"dateModified\":\"2025-10-22T09:48:59.680Z\",\"isPartOf\":{\"@id\":\"https://docs.monxa.co#website\"},\"breadcrumb\":{\"@id\":\"https://docs.monxa.co/api-reference/charges/create-a-charge#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.monxa.co/api-reference/charges/create-a-charge#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"charges\",\"item\":\"https://docs.monxa.co/api-reference/charges/get-all-charges\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create a Charge\",\"item\":\"https://docs.monxa.co/api-reference/charges/create-a-charge\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.monxa.co/api-reference/charges/create-a-charge#apireference\",\"headline\":\"Create a Charge\",\"name\":\"Create a Charge\",\"description\":\"Create a new charge. An idempotency key is required in the request header to ensure safe retries without creating duplicate charges. This endpoint initializes a payment attempt for the specified amount and channel, returning a charge object that represents the transaction status and payment instructions (e.g., QR string or redirect URL).\",\"url\":\"https://docs.monxa.co/api-reference/charges/create-a-charge\",\"mainEntityOfPage\":{\"@id\":\"https://docs.monxa.co/api-reference/charges/create-a-charge#webpage\"},\"dateModified\":\"2025-10-22T09:48:59.680Z\",\"publisher\":{\"@id\":\"https://docs.monxa.co/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.monxa.co#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Monxa Product Guide and API\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Monxa Product Guide and API","nav":{"global":null,"tabs":[{"tab":"Get started","pages":[{"title":"Get started","href":"/welcome"}]},{"tab":"API Reference","groups":[{"group":"balances","pages":[{"title":"Get All Balances","deprecated":false,"version":null,"openapi":"api-reference/openapi.json get /v1/balances","href":"/api-reference/balances/get-all-balances"},{"title":"Get Balance By Currency","deprecated":false,"version":null,"openapi":"api-reference/openapi.json get /v1/balances/{currency}","href":"/api-reference/balances/get-balance-by-currency"}]},{"group":"customers","pages":[{"title":"Get All Customers","deprecated":false,"version":null,"openapi":"api-reference/openapi.json get /v1/customers","href":"/api-reference/customers/get-all-customers"},{"title":"Update Customer","deprecated":false,"version":null,"openapi":"api-reference/openapi.json put /v1/customers","href":"/api-reference/customers/update-customer"},{"title":"Create a Customer","deprecated":false,"version":null,"openapi":"api-reference/openapi.json post /v1/customers","href":"/api-reference/customers/create-a-customer"},{"title":"Delete Customer","deprecated":false,"version":null,"openapi":"api-reference/openapi.json delete /v1/customers","href":"/api-reference/customers/delete-customer"},{"title":"Get Customer Detail","deprecated":false,"version":null,"openapi":"api-reference/openapi.json get /v1/customers/{id}","href":"/api-reference/customers/get-customer-detail"}]},{"group":"merchants","pages":[{"title":"Get Merchant Detail (Self)","deprecated":false,"version":null,"openapi":"api-reference/openapi.json get /v1/merchants/me","href":"/api-reference/merchants/get-merchant-detail-self"},{"title":"Get Payment Channels (Self)","deprecated":false,"version":null,"openapi":"api-reference/openapi.json get /v1/merchants/me/channels","href":"/api-reference/merchants/get-payment-channels-self"},{"title":"/v1/merchants/me/web-hook","deprecated":false,"version":null,"openapi":"api-reference/openapi.json post /v1/merchants/me/web-hook","href":"/api-reference/merchants/v1merchantsmeweb-hook"}]},{"group":"charges","pages":[{"title":"Get All Charges","description":"Retrieve a paginated list of charges.\nThis endpoint returns all charge objects created under the merchant account, optionally filtered by date range, currency, status, payment method, or search text.\nUse pagination parameters to navigate through results efficiently.\n\nKey Notes:\n- Supports flexible filtering and sorting via query parameters.\n- Results include both succeeded and pending charges.\n- Useful for reconciliation, reporting, and transaction monitoring dashboards.","deprecated":false,"version":null,"openapi":"api-reference/openapi.json get /v1/charges","href":"/api-reference/charges/get-all-charges"},{"title":"Create a Charge","deprecated":false,"version":null,"openapi":"api-reference/openapi.json post /v1/charges","href":"/api-reference/charges/create-a-charge"},{"title":"Get Charge Detail","description":"Retrieve the details of a specific charge by its unique Charge ID.\nThis endpoint returns the full charge object, including its current status, amounts, payment channel, timestamps, and metadata.\nUse this endpoint to check the latest state of a transaction — for example, whether a payment has succeeded, failed, or is still pending.","deprecated":false,"version":null,"openapi":"api-reference/openapi.json get /v1/charges/{id}","href":"/api-reference/charges/get-charge-detail"}]},{"group":"payouts","pages":[{"title":"Get All Payouts","deprecated":false,"version":null,"openapi":"api-reference/openapi.json get /v1/payouts","href":"/api-reference/payouts/get-all-payouts"},{"title":"Create a Payout","deprecated":false,"version":null,"openapi":"api-reference/openapi.json post /v1/payouts","href":"/api-reference/payouts/create-a-payout"},{"title":"Get Payout Detail","deprecated":false,"version":null,"openapi":"api-reference/openapi.json get /v1/payouts/{id}","href":"/api-reference/payouts/get-payout-detail"}]}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/changelog"}]}]},"title":"Create a Charge - Monxa Product Guide and API","buildId":"dpl_DFJrtvUi8HS5F9nkooKuDJsuD5BM","deploymentId":"dpl_DFJrtvUi8HS5F9nkooKuDJsuD5BM","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-rfhihCWU.js","utils-BmH1XFxk.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-BcNsxPKB.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-BAES3tkd.js","snippetPresets-DCMQBKLP.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-D6l_bzE9.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-BOktbnNh.js","shallow-BCs8SgM7.js","getApiPlaygroundDisplay-DEmW5bJB.js","CodeSnippet-CpZOpB9C.js","CodeSnippets-BOBDqibl.js","Page-D5fEM6aW.js","getPastedJson-DH2JBvmr.js","icon-BBJH-kKh.js","MethodPill-D2Sd5NLC.js","DuplicateIcon-CGgfL2qN.js","createIcon-BKudBBzi.js","DynamicMarkdown-85clUA0i.js","SectionHeading-D0JiMgDx.js","axios-vUo_bRtp.js","Markdown-Cfiy0xZO.js","clsx-rL8ZCCw4.js","lib--scc4DXi.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-aeztFa9U.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-BywkCr5C.js"]}