Drive a sandbox payment to a terminal status immediately, whatever its amount and payment method. Sandbox only: a production API key is rejected with 403 FORBIDDEN, and a production payment id is not visible to a sandbox key, so it returns 404. REFUNDED marks the payment paid if it is not already and then issues a full refund, which follows the sandbox refund matrix: a payment whose amount ends in .02 fails with 400 PSP_REFUND_FAILED; DISPUTED marks it paid if it is not already and then moves it to CHARGEBACK, which is a chargeback and not a MED.
YuvexPay API key. Include as Authorization: Bearer ypk_<env>_<kid>_<secret> where <env> is test (sandbox) or live (production). Create and manage keys in the dashboard under Settings > API Keys.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"YuvexPay","colors":{"primary":"#16A34A","light":"#07C983","dark":"#15803D"},"logo":{"light":"https://mintcdn.com/yuvexpay/_p0fopc5ZJwqr6Ao/logo/light.png?fit=max\u0026auto=format\u0026n=_p0fopc5ZJwqr6Ao\u0026q=85\u0026s=85eb8014f41b3db8d62050d2ff2d17eb","dark":"https://mintcdn.com/yuvexpay/_p0fopc5ZJwqr6Ao/logo/dark.png?fit=max\u0026auto=format\u0026n=_p0fopc5ZJwqr6Ao\u0026q=85\u0026s=bb76c5782cd7c2617b6337f945d8ce09"},"favicon":"https://mintcdn.com/yuvexpay/y4ZbUn0Z_aeTofU3/favicon.svg?fit=max\u0026auto=format\u0026n=y4ZbUn0Z_aeTofU3\u0026q=85\u0026s=149e82b739356ac0368489279ddb2785","api":{},"navbar":{"links":[{"href":"mailto:support@yuvexpay.com","label":"Support"}],"primary":{"type":"button","label":"Dashboard","href":"https://app.yuvexpay.com"}},"footer":{"socials":{"github":"https://github.com/yuvexpay"}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":false},"navigation":{"global":{"anchors":[{"anchor":"Dashboard","icon":"gauge","href":"https://app.yuvexpay.com"},{"anchor":"API status","icon":"signal","href":"https://status.yuvexpay.com"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"yuvexpay","hasAudioNarration":false,"actualSubdomain":"yuvexpay","customDomains":["docs.yuvexpay.com"],"gitSource":{"type":"github","owner":"yuvexpay","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6add2ecb41bc09b755441f21","collectionId":"f7c0a0d1-3dc0-4c6f-9c35-f75bb0f47542","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6add2ecb41bc09b755441f21"},"entitlements":{},"buildId":"6add2ecb41bc09b755441f21","clientVersion":"0.0.4043","searchFilterCounts":[{"language":"default","tag":"API reference","count":33},{"language":"default","tag":"Products","count":13},{"language":"default","tag":"Guides","count":13},{"language":"default","tag":"Payments","count":8},{"language":"default","tag":"Core concepts","count":6},{"language":"default","tag":"Customers","count":5},{"language":"default","tag":"Withdrawals","count":4},{"language":"default","tag":"Documents","count":3},{"language":"default","tag":"Getting started","count":2},{"language":"default","tag":"Authentication","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":"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":"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":"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":"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":"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}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/payments/simulate","slug":"/api-reference/payments/simulate","pageMetadata":{"title":"Simulate a payment","openapi":"POST /v1/payments/{paymentId}/simulate","description":"Drive a sandbox payment to a terminal status immediately, whatever its amount and payment method. Sandbox only: a production API key is rejected with `403 FORBIDDEN`, and a production payment id is not visible to a sandbox key, so it returns `404`. `REFUNDED` marks the payment paid if it is not already and then issues a full refund, which follows the sandbox refund matrix: a payment whose amount ends in `.02` fails with `400 PSP_REFUND_FAILED`; `DISPUTED` marks it paid if it is not already and then moves it to `CHARGEBACK`, which is a chargeback and not a MED.","href":"/api-reference/payments/simulate"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_components.p, {\n children: [\"Drive a sandbox payment to a terminal status immediately, whatever its amount and payment method. Sandbox only: a production API key is rejected with \", _jsx(_components.code, {\n children: \"403 FORBIDDEN\"\n }), \", and a production payment id is not visible to a sandbox key, so it returns \", _jsx(_components.code, {\n children: \"404\"\n }), \". \", _jsx(_components.code, {\n children: \"REFUNDED\"\n }), \" marks the payment paid if it is not already and then issues a full refund, which follows the sandbox refund matrix: a payment whose amount ends in \", _jsx(_components.code, {\n children: \".02\"\n }), \" fails with \", _jsx(_components.code, {\n children: \"400 PSP_REFUND_FAILED\"\n }), \"; \", _jsx(_components.code, {\n children: \"DISPUTED\"\n }), \" marks it paid if it is not already and then moves it to \", _jsx(_components.code, {\n children: \"CHARGEBACK\"\n }), \", which is a chargeback and not a MED.\"]\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":"Simulate a payment","openapi":"POST /v1/payments/{paymentId}/simulate","description":"Drive a sandbox payment to a terminal status immediately, whatever its amount and payment method. Sandbox only: a production API key is rejected with `403 FORBIDDEN`, and a production payment id is not visible to a sandbox key, so it returns `404`. `REFUNDED` marks the payment paid if it is not already and then issues a full refund, which follows the sandbox refund matrix: a payment whose amount ends in `.02` fails with `400 PSP_REFUND_FAILED`; `DISPUTED` marks it paid if it is not already and then moves it to `CHARGEBACK`, which is a chargeback and not a MED.","href":"/api-reference/payments/simulate"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"simulatePayment","summary":"Simulate a payment","description":"Drive a sandbox payment to a terminal status immediately, whatever its amount and payment method. Sandbox only: a production API key is rejected with `403 FORBIDDEN`, and a production payment id is not visible to a sandbox key, so it returns `404`. `REFUNDED` marks the payment paid if it is not already and then issues a full refund, which follows the sandbox refund matrix: a payment whose amount ends in `.02` fails with `400 PSP_REFUND_FAILED`; `DISPUTED` marks it paid if it is not already and then moves it to `CHARGEBACK`, which is a chargeback and not a MED.","tags":["Payments"],"parameters":["f98338a5-c618-4216-ac4c-b19b82c7e33a","d7e00521-625c-455d-9627-fff27ff6b80e"],"requestBody":"a2336952-0720-45fd-8eb9-94c99118a750","responses":{"200":"ce268e01-6a20-4adf-aac4-64319c82ac48","400":"6448be82-4644-4c6a-a8ee-489f47f94b9a","401":"7778f21d-8931-4757-9438-124532b9c74d","403":"34644849-8055-43a5-bcb4-6bab02543230","404":"91617ae1-da7c-436d-965c-e914d58fe071","409":"5431cd7e-679d-4aa1-bef8-3794be49593c"},"method":"post","type":"path","servers":["30caf778-26b8-4811-87ad-19a2f5724d43"],"security":["2137f48b-cc8e-489b-84f6-226ef7e46562"],"path":"/v1/payments/{paymentId}/simulate","baseUrlOptions":["https://api.yuvexpay.com"],"title":"Simulate a payment","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"f98338a5-c618-4216-ac4c-b19b82c7e33a":{"name":"paymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid","isRequired":true,"description":"The sandbox payment ID to simulate.","uniqueKey":"","typeLabel":"string\u003cuuid>"},"description":"The sandbox payment ID to simulate."},"d7e00521-625c-455d-9627-fff27ff6b80e":{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":100,"isRequired":false,"description":"Optional for this endpoint. Honoured when sent — replay and payload check apply — but omitting it is not rejected.","uniqueKey":"","typeLabel":"string"},"description":"Optional for this endpoint. Honoured when sent — replay and payload check apply — but omitting it is not rejected."}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["PAID","CANCELLED","EXPIRED","REFUNDED","DISPUTED"],"default":"PAID","description":"Terminal outcome to apply. Defaults to `PAID` when the body is empty or omitted.","uniqueKey":"status","typeLabel":"enum\u003cstring>"}},"uniqueKey":"","typeLabel":"object"},"example":{"status":"CANCELLED"},"examples":{"Example":{"title":"Example","value":{"status":"CANCELLED"}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"ce268e01-6a20-4adf-aac4-64319c82ac48":{"description":"The payment after the simulated transition.","content":{"application/json":{"schema":{"type":"object","properties":{"payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","uniqueKey":"payment.id","typeLabel":"string\u003cuuid>"},"txId":{"type":"string","description":"YuvexPay transaction ID.","uniqueKey":"payment.txId","typeLabel":"string"},"amount":{"type":"number","description":"Merchant-requested base amount, in BRL. This is the seller's intended receivable.","uniqueKey":"payment.amount","typeLabel":"number"},"feeAmount":{"type":"number","description":"YuvexPay platform fee, in BRL. When `feePassedToPayer` is true, this equals `payerFeeAmount` and is charged on top of `amount`. When false, this is deducted from `amount` to produce `netAmount`.","uniqueKey":"payment.feeAmount","typeLabel":"number"},"netAmount":{"type":"number","description":"Merchant's net receivable, in BRL. Equals `amount` when `feePassedToPayer` is true; equals `amount - feeAmount` otherwise. This figure is pre-split: when the payment carries `splits`, the originating company keeps `netAmount` minus the sum of the splits and the rest is credited to the recipients on settlement.","uniqueKey":"payment.netAmount","typeLabel":"number"},"feePassedToPayer":{"type":"boolean","description":"Resolved decision (after applying the per-payment override, company default, and sub-R$1 forced passthrough) on whether the fee was added on top for the payer.","uniqueKey":"payment.feePassedToPayer","typeLabel":"boolean"},"payerFeeAmount":{"oneOf":[{"type":"number","description":"Fee amount added to the payer's total charge. Null when `feePassedToPayer` is false. When true, payer-charged total = `amount + payerFeeAmount`.","uniqueKey":"payment.payerFeeAmount.oneOf.0","typeLabel":"number"},{"type":"null","description":"Fee amount added to the payer's total charge. Null when `feePassedToPayer` is false. When true, payer-charged total = `amount + payerFeeAmount`.","uniqueKey":"payment.payerFeeAmount.oneOf.1","typeLabel":"null"}],"uniqueKey":"payment.payerFeeAmount","typeLabel":"number | null"},"splits":{"type":"array","items":{"type":"object","description":"A split recorded on a payment. Immutable once the payment is created.","properties":{"id":{"type":"string","format":"uuid","description":"Identifier of this split entry.","isRequired":true,"uniqueKey":"payment.splits.items.[INDEX].id","typeLabel":"string\u003cuuid>"},"recipientCompanyId":{"type":"string","format":"uuid","description":"Company id of the YuvexPay account that receives this share.","isRequired":true,"uniqueKey":"payment.splits.items.[INDEX].recipientCompanyId","typeLabel":"string\u003cuuid>"},"type":{"type":"string","enum":["PERCENTAGE","FIXED"],"description":"Whether `value` is a percentage of `amount` or a fixed BRL amount.","isRequired":true,"uniqueKey":"payment.splits.items.[INDEX].type","typeLabel":"enum\u003cstring>"},"value":{"type":"number","description":"The percentage or the BRL amount, exactly as it was sent at creation.","isRequired":true,"uniqueKey":"payment.splits.items.[INDEX].value","typeLabel":"number"}},"required":["id","recipientCompanyId","type","value"],"uniqueKey":"payment.splits.items.[INDEX]","typeLabel":"object"},"description":"Splits recorded on this payment, in the order they were sent. `[]` when the payment has none. Only the originating company can read them: a recipient calling `GET /v1/payments/{paymentId}` for this payment gets `404`.","uniqueKey":"payment.splits","typeLabel":"object[]"},"status":{"type":"string","enum":["NEW","PENDING_METHOD_SELECTION","PROCESSING","CONFIRMED","PAID","CANCELLED","EXPIRED","REFUNDED","PARTIAL_REFUND","CHARGEBACK","MED_FROZEN"],"description":"Possible payment statuses.","uniqueKey":"payment.status","typeLabel":"enum\u003cstring>"},"paymentMethod":{"type":"string","enum":["PIX","CARD","BOLETO"],"description":"Available public payment methods.","uniqueKey":"payment.paymentMethod","typeLabel":"enum\u003cstring>"},"currency":{"type":"string","enum":["BRL"],"description":"Supported currencies.","uniqueKey":"payment.currency","typeLabel":"enum\u003cstring>"},"description":{"type":"string","uniqueKey":"payment.description","typeLabel":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string","uniqueKey":"payment.metadata.additionalProperties","typeLabel":"string"},"uniqueKey":"payment.metadata","typeLabel":"object"},"expiresAt":{"type":"string","format":"date-time","uniqueKey":"payment.expiresAt","typeLabel":"string\u003cdate-time>"},"createdAt":{"type":"string","format":"date-time","uniqueKey":"payment.createdAt","typeLabel":"string\u003cdate-time>"},"methodData":{"oneOf":[{"type":"object","description":"Payment method-specific data (QR code for PIX, masked card data for CARD, barcode for boleto). `null` while the payment has no method data: a boleto payment that is `PROCESSING` after a `502`, a card payment that is `PROCESSING` before the outcome of its charge is known, a payment recorded `CANCELLED` or `EXPIRED` before a charge was created, or a hosted payment still in `PENDING_METHOD_SELECTION`. For CARD, `cardFundingType` is `credit` or `debit`, and `null` when the funding type is not known, including older payments.","properties":{"type":{"type":"string","enum":["PIX","CARD","BOLETO"],"description":"Available public payment methods.","uniqueKey":"payment.methodData.oneOf.0.type","typeLabel":"enum\u003cstring>"},"cardFundingType":{"oneOf":[{"type":"string","enum":["credit","debit",null],"description":"CARD only. `credit` when the card was charged as a credit card in a single installment, `debit` when it was charged as a debit card. `null` when the funding type is not known, including older payments.","uniqueKey":"payment.methodData.oneOf.0.cardFundingType.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["credit","debit",null],"description":"CARD only. `credit` when the card was charged as a credit card in a single installment, `debit` when it was charged as a debit card. `null` when the funding type is not known, including older payments.","uniqueKey":"payment.methodData.oneOf.0.cardFundingType.oneOf.1","typeLabel":"null"}],"uniqueKey":"payment.methodData.oneOf.0.cardFundingType","typeLabel":"enum\u003cstring> | null"}},"additionalProperties":true,"uniqueKey":"payment.methodData.oneOf.0","typeLabel":"object"},{"type":"null","description":"Payment method-specific data (QR code for PIX, masked card data for CARD, barcode for boleto). `null` while the payment has no method data: a boleto payment that is `PROCESSING` after a `502`, a card payment that is `PROCESSING` before the outcome of its charge is known, a payment recorded `CANCELLED` or `EXPIRED` before a charge was created, or a hosted payment still in `PENDING_METHOD_SELECTION`. For CARD, `cardFundingType` is `credit` or `debit`, and `null` when the funding type is not known, including older payments.","properties":{"type":{"type":"string","enum":["PIX","CARD","BOLETO"],"description":"Available public payment methods."},"cardFundingType":{"oneOf":[{"type":"string","enum":["credit","debit",null],"description":"CARD only. `credit` when the card was charged as a credit card in a single installment, `debit` when it was charged as a debit card. `null` when the funding type is not known, including older payments."},{"type":"null","enum":["credit","debit",null],"description":"CARD only. `credit` when the card was charged as a credit card in a single installment, `debit` when it was charged as a debit card. `null` when the funding type is not known, including older payments."}]}},"additionalProperties":true,"uniqueKey":"payment.methodData.oneOf.1","typeLabel":"null"}],"uniqueKey":"payment.methodData","typeLabel":"object | null"},"paidAt":{"oneOf":[{"type":"string","format":"date-time","description":"Timestamp when the payment was confirmed paid. Null until paid.","uniqueKey":"payment.paidAt.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"Timestamp when the payment was confirmed paid. Null until paid.","uniqueKey":"payment.paidAt.oneOf.1","typeLabel":"null"}],"uniqueKey":"payment.paidAt","typeLabel":"string\u003cdate-time> | null"},"payer":{"oneOf":[{"type":"object","description":"Payer (debtor) identity captured from the PIX network once the charge is paid. Null for historical records or open-payer charges where no payer data was captured.","properties":{"name":{"oneOf":[{"type":"string","description":"Payer full name.","uniqueKey":"payment.payer.oneOf.0.name.oneOf.0","typeLabel":"string"},{"type":"null","description":"Payer full name.","uniqueKey":"payment.payer.oneOf.0.name.oneOf.1","typeLabel":"null"}],"uniqueKey":"payment.payer.oneOf.0.name","typeLabel":"string | null"},"document":{"oneOf":[{"type":"string","description":"Payer CPF or CNPJ, as digits. Some PIX participants report the document masked (for example `***405566**`); when that is all the network gave us, the masked string is what this field carries — a full document wins whenever one is on file. `null` when no document of either kind was captured, which for an open-payer charge is common. Match on `*` before parsing the value as a CPF or CNPJ.","uniqueKey":"payment.payer.oneOf.0.document.oneOf.0","typeLabel":"string"},{"type":"null","description":"Payer CPF or CNPJ, as digits. Some PIX participants report the document masked (for example `***405566**`); when that is all the network gave us, the masked string is what this field carries — a full document wins whenever one is on file. `null` when no document of either kind was captured, which for an open-payer charge is common. Match on `*` before parsing the value as a CPF or CNPJ.","uniqueKey":"payment.payer.oneOf.0.document.oneOf.1","typeLabel":"null"}],"uniqueKey":"payment.payer.oneOf.0.document","typeLabel":"string | null"},"documentType":{"oneOf":[{"type":"string","enum":["CPF","CNPJ",null],"description":"Payer document type. `null` when the network did not say which kind of document it reported, which is the usual case alongside a masked `document`.","uniqueKey":"payment.payer.oneOf.0.documentType.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["CPF","CNPJ",null],"description":"Payer document type. `null` when the network did not say which kind of document it reported, which is the usual case alongside a masked `document`.","uniqueKey":"payment.payer.oneOf.0.documentType.oneOf.1","typeLabel":"null"}],"uniqueKey":"payment.payer.oneOf.0.documentType","typeLabel":"enum\u003cstring> | null"},"institutionName":{"oneOf":[{"type":"string","description":"Payer bank/institution name.","uniqueKey":"payment.payer.oneOf.0.institutionName.oneOf.0","typeLabel":"string"},{"type":"null","description":"Payer bank/institution name.","uniqueKey":"payment.payer.oneOf.0.institutionName.oneOf.1","typeLabel":"null"}],"uniqueKey":"payment.payer.oneOf.0.institutionName","typeLabel":"string | null"},"institutionIspb":{"oneOf":[{"type":"string","description":"Payer bank ISPB (Banco Central participant identifier).","uniqueKey":"payment.payer.oneOf.0.institutionIspb.oneOf.0","typeLabel":"string"},{"type":"null","description":"Payer bank ISPB (Banco Central participant identifier).","uniqueKey":"payment.payer.oneOf.0.institutionIspb.oneOf.1","typeLabel":"null"}],"uniqueKey":"payment.payer.oneOf.0.institutionIspb","typeLabel":"string | null"}},"uniqueKey":"payment.payer.oneOf.0","typeLabel":"object"},{"type":"null","description":"Payer (debtor) identity captured from the PIX network once the charge is paid. Null for historical records or open-payer charges where no payer data was captured.","properties":{"name":{"oneOf":[{"type":"string","description":"Payer full name."},{"type":"null","description":"Payer full name."}]},"document":{"oneOf":[{"type":"string","description":"Payer CPF or CNPJ, as digits. Some PIX participants report the document masked (for example `***405566**`); when that is all the network gave us, the masked string is what this field carries — a full document wins whenever one is on file. `null` when no document of either kind was captured, which for an open-payer charge is common. Match on `*` before parsing the value as a CPF or CNPJ."},{"type":"null","description":"Payer CPF or CNPJ, as digits. Some PIX participants report the document masked (for example `***405566**`); when that is all the network gave us, the masked string is what this field carries — a full document wins whenever one is on file. `null` when no document of either kind was captured, which for an open-payer charge is common. Match on `*` before parsing the value as a CPF or CNPJ."}]},"documentType":{"oneOf":[{"type":"string","enum":["CPF","CNPJ",null],"description":"Payer document type. `null` when the network did not say which kind of document it reported, which is the usual case alongside a masked `document`."},{"type":"null","enum":["CPF","CNPJ",null],"description":"Payer document type. `null` when the network did not say which kind of document it reported, which is the usual case alongside a masked `document`."}]},"institutionName":{"oneOf":[{"type":"string","description":"Payer bank/institution name."},{"type":"null","description":"Payer bank/institution name."}]},"institutionIspb":{"oneOf":[{"type":"string","description":"Payer bank ISPB (Banco Central participant identifier)."},{"type":"null","description":"Payer bank ISPB (Banco Central participant identifier)."}]}},"uniqueKey":"payment.payer.oneOf.1","typeLabel":"null"}],"uniqueKey":"payment.payer","typeLabel":"object | null"}},"uniqueKey":"payment","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"payment":{"id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","txId":"\u003cstring>","amount":123,"feeAmount":123,"netAmount":123,"feePassedToPayer":true,"payerFeeAmount":123,"splits":[{"id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","recipientCompanyId":"3c90c3cc-0d44-4b50-8888-8dd25736052a","type":"PERCENTAGE","value":123}],"status":"NEW","paymentMethod":"PIX","currency":"BRL","description":"\u003cstring>","metadata":{},"expiresAt":"2023-11-07T05:31:56Z","createdAt":"2023-11-07T05:31:56Z","methodData":{"type":"PIX","cardFundingType":"credit"},"paidAt":"2023-11-07T05:31:56Z","payer":{"name":"\u003cstring>","document":"\u003cstring>","documentType":"CPF","institutionName":"\u003cstring>","institutionIspb":"\u003cstring>"}}}}},"exampleType":"generated"}},"exampleType":"generated"},"6448be82-4644-4c6a-a8ee-489f47f94b9a":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code.","uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable error message.","uniqueKey":"error.message","typeLabel":"string"},"details":{"type":"object","description":"Additional error context.","uniqueKey":"error.details","typeLabel":"object"}},"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"VALIDATION_ERROR","message":"Invalid request body","details":{"amount":"Must be greater than 0.01"}}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"VALIDATION_ERROR","message":"Invalid request body","details":{"amount":"Must be greater than 0.01"}}}}},"exampleType":"examples"}},"exampleType":"examples"},"7778f21d-8931-4757-9438-124532b9c74d":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code.","uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable error message.","uniqueKey":"error.message","typeLabel":"string"},"details":{"type":"object","description":"Additional error context.","uniqueKey":"error.details","typeLabel":"object"}},"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"INVALID_API_KEY","message":"Invalid or revoked API key"}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"INVALID_API_KEY","message":"Invalid or revoked API key"}}}},"exampleType":"examples"}},"exampleType":"examples"},"34644849-8055-43a5-bcb4-6bab02543230":{"description":"The API key is a production key. Only sandbox API keys can simulate.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code.","uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable error message.","uniqueKey":"error.message","typeLabel":"string"},"details":{"type":"object","description":"Additional error context.","uniqueKey":"error.details","typeLabel":"object"}},"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"FORBIDDEN","message":"Only sandbox payments can be simulated"}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"FORBIDDEN","message":"Only sandbox payments can be simulated"}}}},"exampleType":"examples"}},"exampleType":"examples"},"91617ae1-da7c-436d-965c-e914d58fe071":{"description":"Resource not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code.","uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable error message.","uniqueKey":"error.message","typeLabel":"string"},"details":{"type":"object","description":"Additional error context.","uniqueKey":"error.details","typeLabel":"object"}},"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"NOT_FOUND","message":"Resource not found"}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"NOT_FOUND","message":"Resource not found"}}}},"exampleType":"examples"}},"exampleType":"examples"},"5431cd7e-679d-4aa1-bef8-3794be49593c":{"description":"Idempotency conflict, raised by the idempotency middleware. `IDEMPOTENCY_PAYLOAD_MISMATCH` means the key was already used with a different request body, at any point in the 24-hour window, including by a request still in flight. `IDEMPOTENCY_CONFLICT` means a request with the same key and the same body is still being processed. Both use the **flat** envelope: `error` is the HTTP reason phrase and the machine-readable code is the top-level `code`. Note that `IDEMPOTENCY_CONFLICT` raised later by the withdrawal service on an idempotency-key collision uses the nested `Error` envelope instead.","content":{"application/json":{"schema":{"type":"object","description":"The flat error envelope used by low-level guards that reply before the API error envelope is applied — today the idempotency middleware. The machine-readable code is the top-level `code`; `error` is only the HTTP reason phrase.","properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","uniqueKey":"statusCode","typeLabel":"integer"},"error":{"type":"string","description":"HTTP reason phrase, for example `Conflict` or `Bad Request`. Not a machine-readable code.","uniqueKey":"error","typeLabel":"string"},"message":{"type":"string","description":"Human-readable error message.","uniqueKey":"message","typeLabel":"string"},"code":{"type":"string","description":"Machine-readable error code.","uniqueKey":"code","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"payloadMismatch":{"title":"payloadMismatch","value":{"statusCode":409,"error":"Conflict","message":"This idempotency key was already used with a different request payload","code":"IDEMPOTENCY_PAYLOAD_MISMATCH"}},"inFlight":{"title":"inFlight","value":{"statusCode":409,"error":"Conflict","message":"A request with this idempotency key is already being processed","code":"IDEMPOTENCY_CONFLICT"}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"2137f48b-cc8e-489b-84f6-226ef7e46562":{"bearerAuth":{"type":"http","scheme":"bearer","description":"YuvexPay API key. Include as `Authorization: Bearer ypk_\u003cenv>_\u003ckid>_\u003csecret>` where `\u003cenv>` is `test` (sandbox) or `live` (production). Create and manage keys in the dashboard under **Settings > API Keys**.","scopes":[],"schemeName":"bearerAuth"}}},"servers":{"30caf778-26b8-4811-87ad-19a2f5724d43":{"url":"https://api.yuvexpay.com","description":"Same base URL serves both sandbox and production. Send a `ypk_test_*` key for sandbox or a `ypk_live_*` key for production."}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"YuvexPay API key. Include as `Authorization: Bearer ypk_\u003cenv>_\u003ckid>_\u003csecret>` where `\u003cenv>` is `test` (sandbox) or `live` (production). Create and manage keys in the dashboard under **Settings > API Keys**.","scopes":[],"schemeName":"bearerAuth"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"YuvexPay API key. Include as `Authorization: Bearer ypk_\u003cenv>_\u003ckid>_\u003csecret>` where `\u003cenv>` is `test` (sandbox) or `live` (production). Create and manage keys in the dashboard under **Settings > API Keys**.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"bearerAuth","name":"Authorization"}],"title":"bearerAuth"}]},"originalFileLocation":"api-reference/openapi.json"},"subdomain":"yuvexpay","siteName":"YuvexPay","title":"Simulate a payment - YuvexPay","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-04T05:42:58.061Z","originalFileLocation":"api-reference/payments/simulate.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=\"Drive a sandbox payment to a terminal status immediately, whatever its amount and payment method. Sandbox only: a production API key is rejected with 403 FORBIDDEN, and a production payment id is not visible to a sandbox key, so it returns 404. REFUNDED marks the payment paid if it is not already and then issues a full refund, which follows the sandbox refund matrix: a payment whose amount ends in .02 fails with 400 PSP_REFUND_FAILED; DISPUTED marks it paid if it is not already and then moves it to CHARGEBACK, which is a chargeback and not a MED.\">\u003cmeta data-mint-head name=\"application-name\" content=\"YuvexPay\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/yuvexpay/qrsJ3VUJ-racyQUp/_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/yuvexpay/qrsJ3VUJ-racyQUp/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/yuvexpay/qrsJ3VUJ-racyQUp/_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/yuvexpay/qrsJ3VUJ-racyQUp/_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/yuvexpay/qrsJ3VUJ-racyQUp/_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/yuvexpay/qrsJ3VUJ-racyQUp/_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/yuvexpay/qrsJ3VUJ-racyQUp/_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/yuvexpay/qrsJ3VUJ-racyQUp/_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/yuvexpay/qrsJ3VUJ-racyQUp/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Simulate a payment - YuvexPay\">\u003cmeta data-mint-head property=\"og:description\" content=\"Drive a sandbox payment to a terminal status immediately, whatever its amount and payment method. Sandbox only: a production API key is rejected with 403 FORBIDDEN, and a production payment id is not visible to a sandbox key, so it returns 404. REFUNDED marks the payment paid if it is not already and then issues a full refund, which follows the sandbox refund matrix: a payment whose amount ends in .02 fails with 400 PSP_REFUND_FAILED; DISPUTED marks it paid if it is not already and then moves it to CHARGEBACK, which is a chargeback and not a MED.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"YuvexPay\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.yuvexpay.com/api-reference/payments/simulate\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://yuvexpay.mintlify.app/_mintlify/api/og/v2?division=Payments\u0026amp;title=Simulate+a+payment\u0026amp;description=Drive+a+sandbox+payment+to+a+terminal+status+immediately%2C+whatever+its+amount+and+payment+method.+Sandbox+only%3A+a+production+API+key+is+rejected+with+%60403+FORBI\u0026amp;theme=e1bc7c37ec59feb92a55994b\u0026amp;signature=99955f2e31487ae637d3c2c7ebc6a1f3999351116260386ecc149a9efcc5fcfe\">\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=\"Simulate a payment - YuvexPay\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Drive a sandbox payment to a terminal status immediately, whatever its amount and payment method. Sandbox only: a production API key is rejected with 403 FORBIDDEN, and a production payment id is not visible to a sandbox key, so it returns 404. REFUNDED marks the payment paid if it is not already and then issues a full refund, which follows the sandbox refund matrix: a payment whose amount ends in .02 fails with 400 PSP_REFUND_FAILED; DISPUTED marks it paid if it is not already and then moves it to CHARGEBACK, which is a chargeback and not a MED.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://yuvexpay.mintlify.app/_mintlify/api/og/v2?division=Payments\u0026amp;title=Simulate+a+payment\u0026amp;description=Drive+a+sandbox+payment+to+a+terminal+status+immediately%2C+whatever+its+amount+and+payment+method.+Sandbox+only%3A+a+production+API+key+is+rejected+with+%60403+FORBI\u0026amp;theme=e1bc7c37ec59feb92a55994b\u0026amp;signature=99955f2e31487ae637d3c2c7ebc6a1f3999351116260386ecc149a9efcc5fcfe\">\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/yuvexpay/qrsJ3VUJ-racyQUp/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"YuvexPay\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#16A34A\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.yuvexpay.com/api-reference/payments/simulate\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/payments/simulate.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.yuvexpay.com/#organization\",\"name\":\"YuvexPay\",\"url\":\"https://docs.yuvexpay.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/yuvexpay/_p0fopc5ZJwqr6Ao/logo/light.png?fit=max\u0026auto=format\u0026n=_p0fopc5ZJwqr6Ao\u0026q=85\u0026s=85eb8014f41b3db8d62050d2ff2d17eb\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.yuvexpay.com#website\",\"name\":\"YuvexPay\",\"url\":\"https://docs.yuvexpay.com\",\"publisher\":{\"@id\":\"https://docs.yuvexpay.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.yuvexpay.com/api-reference/payments/simulate#webpage\",\"url\":\"https://docs.yuvexpay.com/api-reference/payments/simulate\",\"name\":\"Simulate a payment\",\"description\":\"Drive a sandbox payment to a terminal status immediately, whatever its amount and payment method. Sandbox only: a production API key is rejected with 403 FORBIDDEN, and a production payment id is not visible to a sandbox key, so it returns 404. REFUNDED marks the payment paid if it is not already and then issues a full refund, which follows the sandbox refund matrix: a payment whose amount ends in .02 fails with 400 PSP_REFUND_FAILED; DISPUTED marks it paid if it is not already and then moves it to CHARGEBACK, which is a chargeback and not a MED.\",\"dateModified\":\"2026-10-04T05:42:58.061Z\",\"isPartOf\":{\"@id\":\"https://docs.yuvexpay.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.yuvexpay.com/api-reference/payments/simulate#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.yuvexpay.com/api-reference/payments/simulate#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Payments\",\"item\":\"https://docs.yuvexpay.com/api-reference/payments/create\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Simulate a payment\",\"item\":\"https://docs.yuvexpay.com/api-reference/payments/simulate\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.yuvexpay.com/api-reference/payments/simulate#apireference\",\"headline\":\"Simulate a payment\",\"name\":\"Simulate a payment\",\"description\":\"Drive a sandbox payment to a terminal status immediately, whatever its amount and payment method. Sandbox only: a production API key is rejected with 403 FORBIDDEN, and a production payment id is not visible to a sandbox key, so it returns 404. REFUNDED marks the payment paid if it is not already and then issues a full refund, which follows the sandbox refund matrix: a payment whose amount ends in .02 fails with 400 PSP_REFUND_FAILED; DISPUTED marks it paid if it is not already and then moves it to CHARGEBACK, which is a chargeback and not a MED.\",\"url\":\"https://docs.yuvexpay.com/api-reference/payments/simulate\",\"mainEntityOfPage\":{\"@id\":\"https://docs.yuvexpay.com/api-reference/payments/simulate#webpage\"},\"dateModified\":\"2026-10-04T05:42:58.061Z\",\"publisher\":{\"@id\":\"https://docs.yuvexpay.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.yuvexpay.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"YuvexPay\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"YuvexPay","nav":{"global":{"anchors":[{"anchor":"Dashboard","icon":"gauge","href":"https://app.yuvexpay.com"},{"anchor":"API status","icon":"signal","href":"https://status.yuvexpay.com"}]},"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"API reference","groups":[{"group":"Overview","pages":[{"title":"API reference","href":"/api-reference/introduction"}]},{"group":"Authentication","pages":[{"title":"Inspect the current API key","openapi":"GET /v1/auth/self","href":"/api-reference/auth/self"}]},{"group":"Payments","pages":[{"title":"Create a payment","openapi":"POST /v1/payments","href":"/api-reference/payments/create"},{"title":"List payments","openapi":"GET /v1/payments","href":"/api-reference/payments/list"},{"title":"Get a payment","openapi":"GET /v1/payments/{paymentId}","href":"/api-reference/payments/get"},{"title":"Get a payment by transaction ID","openapi":"GET /v1/payments/txid/{txId}","href":"/api-reference/payments/get-by-txid"},{"title":"Download boleto PDF","openapi":"GET /v1/payments/{paymentId}/boleto","href":"/api-reference/payments/get-boleto"},{"title":"Refund a payment","openapi":"POST /v1/payments/{paymentId}/refund","href":"/api-reference/payments/refund"},{"title":"List payment refunds","openapi":"GET /v1/payments/{paymentId}/refunds","description":"Retrieve all refunds for a specific payment.","href":"/api-reference/payments/list-refunds"},{"title":"Simulate a payment","openapi":"POST /v1/payments/{paymentId}/simulate","href":"/api-reference/payments/simulate"}]},{"group":"Withdrawals","pages":[{"title":"Create a withdrawal","openapi":"POST /v1/withdrawals","description":"Create a PIX withdrawal to transfer BRL funds from your YuvexPay balance. Requires an idempotency key.\n\nThe PIX key type (CPF, CNPJ, e-mail, phone, or random key) is detected automatically from `destination.pixKey` — you do not need to declare it. `INVALID_PIX_KEY` covers format only. Whether the key exists on the PIX network is not checked before acceptance: depending on when the network rejects, a well-formed key that belongs to nobody surfaces either as a synchronous `400 PROVIDER_ERROR` on this call or later as a `WITHDRAWAL_FAILED` webhook.\n\nThe creditor document sent to the PIX network is resolved in three steps, in order: (1) `destination.recipientDocument` when you send it; (2) the PIX key itself when `destination.pixKey` is a CPF or CNPJ key; (3) your own verified tax id — company CNPJ for business accounts, owner CPF for individual accounts. Step 3 is a fallback, not a default: if you pay a third party on an e-mail, phone or random key and omit `destination.recipientDocument`, the network is told your own document is the creditor, and the payout may be rejected downstream by the receiving institution.\n\nWithdrawals may be blocked outside business hours or if your account has restrictions.\n\n`creditorDocumentSource` is a dashboard-only field and is not accepted here: sending it returns `400 CREDITOR_DOCUMENT_SOURCE_NOT_SUPPORTED` rather than being silently ignored. Use `destination.recipientDocument` to put a specific document on the payout.","href":"/api-reference/withdrawals/create"},{"title":"List withdrawals","openapi":"GET /v1/withdrawals","href":"/api-reference/withdrawals/list"},{"title":"Get a withdrawal","openapi":"GET /v1/withdrawals/{withdrawalId}","href":"/api-reference/withdrawals/get"},{"title":"Get withdrawal limits","openapi":"GET /v1/withdrawals/limits","href":"/api-reference/withdrawals/limits"}]},{"group":"Balance","pages":[{"title":"Get account balance","openapi":"GET /v1/balance","href":"/api-reference/balance/get"}]},{"group":"Splits","pages":[{"title":"List split partners","openapi":"GET /v1/splits/partners","href":"/api-reference/splits/partners"}]},{"group":"Products","pages":[{"title":"Create a product","openapi":"POST /v1/products","href":"/api-reference/products/create"},{"title":"List products","openapi":"GET /v1/products","href":"/api-reference/products/list"},{"title":"Get a product","openapi":"GET /v1/products/{productId}","href":"/api-reference/products/get"},{"title":"Get a product by external ID","openapi":"GET /v1/products/external/{externalId}","href":"/api-reference/products/get-by-external-id"},{"title":"Update a product","openapi":"PATCH /v1/products/{productId}","href":"/api-reference/products/update"},{"title":"Delete a product","openapi":"DELETE /v1/products/{productId}","href":"/api-reference/products/delete"},{"title":"Upload product image","openapi":"POST /v1/products/{productId}/image","href":"/api-reference/products/upload-image"},{"title":"Delete product image","openapi":"DELETE /v1/products/{productId}/image","href":"/api-reference/products/delete-image"}]},{"group":"Customers","pages":[{"title":"Create a customer","openapi":"POST /v1/customers","href":"/api-reference/customers/create"},{"title":"List customers","openapi":"GET /v1/customers","href":"/api-reference/customers/list"},{"title":"Get a customer","openapi":"GET /v1/customers/{customerId}","href":"/api-reference/customers/get"},{"title":"Update a customer","openapi":"PATCH /v1/customers/{customerId}","href":"/api-reference/customers/update"},{"title":"Delete a customer","openapi":"DELETE /v1/customers/{customerId}","href":"/api-reference/customers/delete"}]},{"group":"Documents","pages":[{"title":"Get payment receipt","openapi":"GET /v1/documents/payments/{paymentId}/receipt","href":"/api-reference/documents/payment-receipt"},{"title":"Get withdrawal receipt","openapi":"GET /v1/documents/withdrawals/{withdrawalId}/receipt","href":"/api-reference/documents/withdrawal-receipt"},{"title":"Get account statement","openapi":"GET /v1/documents/statements","href":"/api-reference/documents/statement"}]},{"group":"Public","pages":[{"title":"Get standard pricing","openapi":"GET /public/pricing","href":"/api-reference/public/pricing"}]}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/changelog"}]}]},"basePath":"","title":"Simulate a payment - YuvexPay","buildId":"dpl_G9nrg4qeJSZtah1Ziwbc2n6WkLch","deploymentId":"dpl_G9nrg4qeJSZtah1Ziwbc2n6WkLch","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-B7XKH4J3.js","utils-lOYzL7z-.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-DF6jUUIM.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-Dpsj5f7C.js","snippetPresets-CYeiDe8v.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-CUFz1YZ_.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-D8H_iLS4.js","shallow-DdluZBHX.js","getApiPlaygroundDisplay-B9922vev.js","CodeSnippet-CMoRNGYs.js","CodeSnippets-DwyrPHuw.js","Page-DSVu9Ucl.js","getPastedJson-G-zIvlHh.js","icon-B03fnEy0.js","MethodPill-CW7teklc.js","DuplicateIcon-CtO8eekd.js","createIcon-DZTKdM_A.js","DynamicMarkdown-D5M2At0B.js","SectionHeading-C_2NaA2U.js","axios-vUo_bRtp.js","Markdown-D7QRHV3m.js","clsx-D1Z-ELXV.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-lvhuD9Du.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-CKfC4ywL.js"]}