> ## Documentation Index > Fetch the complete documentation index at: https://docs.yuvexpay.com/llms.txt > Use this file to discover all available pages before exploring further. # Simulate a payment > Drive a sandbox payment to a terminal status immediately, whatever its amount and payment method. Sandbox only: a production API key and a production payment id are both rejected with 403. `REFUNDED` marks the payment paid if it is not already and then issues a full refund; `DISPUTED` marks it paid if it is not already and then moves it to `CHARGEBACK`, which is a chargeback and not a MED. ## OpenAPI ````yaml POST /v1/payments/{paymentId}/simulate openapi: 3.1.0 info: title: YuvexPay API description: >- The YuvexPay API allows you to accept payments, process withdrawals, manage products and customers programmatically. All API access is over HTTPS and uses JSON request/response bodies. version: 1.0.0 contact: name: YuvexPay Support email: support@yuvexpay.com url: https://docs.yuvexpay.com servers: - 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. security: - bearerAuth: [] tags: - name: Authentication description: Inspect the API key in use - name: Payments description: Create and manage payments - name: Withdrawals description: Create and manage withdrawals - name: Products description: Manage product catalog - name: Customers description: Manage customer records - name: Documents description: Generate receipts and statements - name: Balance description: Inspect the current account balance paths: /v1/payments/{paymentId}/simulate: post: tags: - Payments 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 and a production payment id are both rejected with 403. `REFUNDED` marks the payment paid if it is not already and then issues a full refund; `DISPUTED` marks it paid if it is not already and then moves it to `CHARGEBACK`, which is a chargeback and not a MED. operationId: simulatePayment parameters: - name: paymentId in: path required: true schema: type: string format: uuid description: The sandbox payment ID to simulate. - name: X-Idempotency-Key in: header required: false schema: type: string maxLength: 100 description: >- Optional for this endpoint. Honoured when sent — replay and payload check apply — but omitting it is not rejected. requestBody: content: application/json: schema: $ref: '#/components/schemas/SimulatePaymentRequest' example: status: CANCELLED responses: '200': description: The payment after the simulated transition. content: application/json: schema: type: object properties: payment: $ref: '#/components/schemas/Payment' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': description: The API key is a production key. Only sandbox API keys can simulate. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: FORBIDDEN message: Only sandbox payments can be simulated '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/IdempotencyConflict' components: schemas: SimulatePaymentRequest: 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. Payment: type: object properties: id: type: string format: uuid txId: type: string description: YuvexPay transaction ID. amount: type: number description: >- Merchant-requested base amount, in BRL. This is the seller's intended receivable. 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`. netAmount: type: number description: >- Merchant's net receivable, in BRL. Equals `amount` when `feePassedToPayer` is true; equals `amount - feeAmount` otherwise. 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. payerFeeAmount: type: - number - 'null' description: >- Fee amount added to the payer's total charge. Null when `feePassedToPayer` is false. When true, payer-charged total = `amount + payerFeeAmount`. status: $ref: '#/components/schemas/PaymentStatus' paymentMethod: $ref: '#/components/schemas/PaymentMethod' currency: $ref: '#/components/schemas/Currency' description: type: string metadata: type: object additionalProperties: type: string expiresAt: type: string format: date-time createdAt: type: string format: date-time methodData: type: object description: >- Payment method-specific data (QR code for PIX, barcode for boleto, etc.). properties: type: $ref: '#/components/schemas/PaymentMethod' additionalProperties: true paidAt: type: - string - 'null' format: date-time description: Timestamp when the payment was confirmed paid. Null until paid. payer: type: - object - 'null' description: >- Payer (debtor) identity captured from the PIX network once the charge is paid. Provider-agnostic. Null for historical records or open-payer charges where no payer data was captured. properties: name: type: - string - 'null' description: Payer full name. document: type: - string - '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: type: - string - '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: type: - string - 'null' description: Payer bank/institution name. institutionIspb: type: - string - 'null' description: Payer bank ISPB (Banco Central participant identifier). Error: type: object properties: error: type: object properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable error message. details: type: object description: Additional error context. PaymentStatus: type: string enum: - NEW - PENDING_METHOD_SELECTION - PROCESSING - CONFIRMED - PAID - CANCELLED - EXPIRED - REFUNDED - PARTIAL_REFUND - CHARGEBACK - MED_FROZEN description: Possible payment statuses. PaymentMethod: type: string enum: - PIX - CARD - BOLETO description: Available public payment methods. Currency: type: string enum: - BRL description: Supported currencies. FlatError: 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. error: type: string description: >- HTTP reason phrase, for example `Conflict` or `Bad Request`. Not a machine-readable code. message: type: string description: Human-readable error message. code: type: string description: Machine-readable error code. responses: ValidationError: description: Validation error. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: VALIDATION_ERROR message: Invalid request body details: amount: Must be greater than 0.01 Unauthorized: description: Missing or invalid authentication token. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_API_KEY message: Invalid or revoked API key NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found IdempotencyConflict: 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: $ref: '#/components/schemas/FlatError' examples: payloadMismatch: summary: The key was reused with a different body value: statusCode: 409 error: Conflict message: >- This idempotency key was already used with a different request payload code: IDEMPOTENCY_PAYLOAD_MISMATCH inFlight: summary: The same request is still being processed value: statusCode: 409 error: Conflict message: A request with this idempotency key is already being processed code: IDEMPOTENCY_CONFLICT securitySchemes: bearerAuth: type: http scheme: bearer description: >- YuvexPay API key. Include as `Authorization: Bearer ypk___` where `` is `test` (sandbox) or `live` (production). Create and manage keys in the dashboard under **Settings > API Keys**. ````