> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pawpayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulate a payment on a sandbox invoice



## OpenAPI

````yaml /api-reference/openapi.json post /api/v2/invoices/{invoice_id}/simulate
openapi: 3.1.0
info:
  title: PawPayments API
  description: >-
    Public REST API for the PawPayments crypto payment gateway.


    All `/api/v2/*` endpoints require an `x-api-key` header issued in the
    merchant dashboard. Responses are wrapped in `{"ok": true, "result": ...}`
    on success and `{"ok": false, "error": {code, message, details?}}` on
    failure.
  version: 2.0.0
servers:
  - url: https://api.pawpayments.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Catalog
  - name: Merchant
  - name: Invoices
  - name: Sandbox
  - name: Payouts
  - name: Notifications
  - name: Permanent addresses
paths:
  /api/v2/invoices/{invoice_id}/simulate:
    post:
      tags:
        - Sandbox
      summary: Simulate a payment on a sandbox invoice
      operationId: post__api_v2_invoices_{invoice_id}_simulate
      parameters:
        - name: invoice_id
          in: path
          required: true
          schema:
            type: string
          description: Unique 24-character hex invoice id.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateInvoiceV2.a1ea1bf'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulatedInvoiceEnvelope.d4a12ff'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope.d4a12ff'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope.d4a12ff'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope.d4a12ff'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope.d4a12ff'
components:
  schemas:
    SimulateInvoiceV2.a1ea1bf:
      description: >-
        Drive a SANDBOX invoice into a terminal (or partial) status.


        Sandbox only — there is nothing to simulate on a live invoice, whose
        status

        is determined by the chain.
      properties:
        status:
          description: Status to move the invoice into.
          enum:
            - success
            - partially_paid
            - paid_over
            - expired
            - cancelled
            - failed
            - refunded
          title: Status
          type: string
        paid_amount:
          anyOf:
            - exclusiveMinimum: 0
              type: number
            - type: string
            - type: 'null'
          default: null
          description: >-
            Amount paid in the invoice's `fiat_currency`. Defaults to a sensible
            value for the chosen status: the full amount for `success`, half for
            `partially_paid`, 125% for `paid_over`.
          title: Paid Amount
        send_webhook:
          default: true
          description: Whether to deliver the webhook for this transition.
          title: Send Webhook
          type: boolean
        notify_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Override the webhook destination for this call only.
          title: Notify Url
      required:
        - status
      title: SimulateInvoiceV2
      type: object
    SimulatedInvoiceEnvelope.d4a12ff:
      properties:
        ok:
          const: true
          title: Ok
          type: boolean
        result:
          $ref: >-
            #/components/schemas/SimulatedInvoiceEnvelope.d4a12ff.SimulatedInvoice
      required:
        - ok
        - result
      title: SimulatedInvoiceEnvelope
      type: object
    ErrorEnvelope.d4a12ff:
      example:
        error:
          code: VALIDATION_ERROR
          details:
            - field: amount
              message: Field required
          message: Validation failed
        ok: false
      properties:
        ok:
          const: false
          title: Ok
          type: boolean
        error:
          $ref: '#/components/schemas/ErrorEnvelope.d4a12ff.ErrorBody'
      required:
        - ok
        - error
      title: ErrorEnvelope
      type: object
    SimulatedInvoiceEnvelope.d4a12ff.SimulatedInvoice:
      description: Result of driving a sandbox invoice into a new status.
      example:
        invoice:
          accepted_coins:
            - usdt_tron
            - usdc_eth
          address_from: null
          address_to: TXk2Y5...redacted
          amount: 49.5
          asset: usdt_tron
          billing_type: fiat
          created_at: 1763398800
          description: 1 month subscription
          excluded_coins: null
          expires_at: 1763400600
          external_id: f2c8a3d1-4b7e-4f8a-9c1d-2e3b4a5c6d7e
          extra: order-12345
          fee_bearer: merchant
          fiat_amount: 50
          fiat_currency: USD
          initial_amount: 49.5
          initial_asset: usdt_tron
          initial_fiat_amount: 50
          metadata:
            customer_id: u_42
          notify_url: https://shop.example.com/webhook/paw
          on_cancel_url: https://shop.example.com/cancel
          on_paid_url: https://shop.example.com/thanks
          order_id: 65f1c3a4e8b1c2d3a4b5c6d7
          original_amount: 50
          payer_info: null
          payment_url: >-
            https://pay.pawpayments.com/checkout/f2c8a3d1-4b7e-4f8a-9c1d-2e3b4a5c6d7e
          permanent_address_id: null
          price_modifier: -1
          processed_at: null
          received_amount: 0
          status: created
          title: Premium plan
          txid: null
          type: token
          underpay_tolerance: 0.01
          user_id: null
        webhook:
          delivered: true
          error: null
          status_code: 200
          url: https://shop.example.com/webhook/paw
      properties:
        invoice:
          $ref: '#/components/schemas/SimulatedInvoiceEnvelope.d4a12ff.Invoice'
        webhook:
          anyOf:
            - $ref: >-
                #/components/schemas/SimulatedInvoiceEnvelope.d4a12ff.WebhookProbe
            - type: 'null'
          default: null
          description: >-
            Delivery result of the webhook fired for this transition, if one was
            requested.
      required:
        - invoice
      title: SimulatedInvoice
      type: object
    ErrorEnvelope.d4a12ff.ErrorBody:
      properties:
        code:
          description: Machine-readable error code (e.g. NOT_FOUND, VALIDATION_ERROR).
          title: Code
          type: string
        message:
          title: Message
          type: string
        details:
          anyOf:
            - {}
            - type: 'null'
          default: null
          description: >-
            Optional context. For VALIDATION_ERROR contains a list of {field,
            message}.
          title: Details
      required:
        - code
        - message
      title: ErrorBody
      type: object
    SimulatedInvoiceEnvelope.d4a12ff.Invoice:
      example:
        accepted_coins:
          - usdt_tron
          - usdc_eth
        address_from: null
        address_to: TXk2Y5...redacted
        amount: 49.5
        asset: usdt_tron
        billing_type: fiat
        created_at: 1763398800
        description: 1 month subscription
        excluded_coins: null
        expires_at: 1763400600
        external_id: f2c8a3d1-4b7e-4f8a-9c1d-2e3b4a5c6d7e
        extra: order-12345
        fee_bearer: merchant
        fiat_amount: 50
        fiat_currency: USD
        initial_amount: 49.5
        initial_asset: usdt_tron
        initial_fiat_amount: 50
        metadata:
          customer_id: u_42
        notify_url: https://shop.example.com/webhook/paw
        on_cancel_url: https://shop.example.com/cancel
        on_paid_url: https://shop.example.com/thanks
        order_id: 65f1c3a4e8b1c2d3a4b5c6d7
        original_amount: 50
        payer_info: null
        payment_url: >-
          https://pay.pawpayments.com/checkout/f2c8a3d1-4b7e-4f8a-9c1d-2e3b4a5c6d7e
        permanent_address_id: null
        price_modifier: -1
        processed_at: null
        received_amount: 0
        status: created
        title: Premium plan
        txid: null
        type: token
        underpay_tolerance: 0.01
        user_id: null
      properties:
        order_id:
          description: Unique 24-character hex invoice id.
          title: Order Id
          type: string
        external_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Public checkout id (UUID).
          title: External Id
        status:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            One of: created, confirming, partially_paid, paid_over, success,
            failed, high_risk, expired, cancelled, refunded. Terminal-expiry
            split: `cancelled` is reachable only from `partially_paid` +
            `billing_type=STATIC` (merchant was already credited the partial
            amount at AML time; the credit is kept on expiry — `cancelled`
            reports the final under-paid state without reversal). Everything
            else still in `created` at TTL (including the sub-$2 tiny-payment
            deferral path that stored `received_amount` without enqueueing AML)
            → `expired`. `partially_paid` + `billing_type=VARY` is terminal at
            AML time and never transitions on TTL.
          title: Status
        asset:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Asset
        initial_asset:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Asset originally requested at invoice creation. Immutable after
            first assignment — if the customer changes the payment currency on
            the hosted checkout, `asset` reflects the new choice while
            `initial_asset` keeps the original one.
          title: Initial Asset
        type:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: 'Asset type: `native` or `token`.'
          title: Type
        amount:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: Originally requested amount in `asset`.
          title: Amount
        initial_amount:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: >-
            Snapshot of the originally requested crypto amount (immutable;
            equals `amount`).
          title: Initial Amount
        fiat_amount:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: >-
            Cumulative amount paid in `fiat_currency`. Updated on each on-chain
            payment.
          title: Fiat Amount
        initial_fiat_amount:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: >-
            Originally requested amount in `fiat_currency` (immutable; useful
            when `fiat_amount` becomes a partial sum).
          title: Initial Fiat Amount
        fiat_currency:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Fiat Currency
        billing_type:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Settlement mode: `STATIC` (fixed-price service — `partially_paid`
            keeps the invoice open for top-ups until
            `success`/`paid_over`/`expires_at`) or `VARY` (any incoming payment
            finalises the invoice — used for balance top-ups and for invoices
            bound to permanent addresses).
          title: Billing Type
        address_to:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Address To
        address_from:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Sender address of the (last) on-chain payment, when known.
          title: Address From
        extra:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Extra
        title:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Description
        expires_at:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          description: Unix timestamp when the invoice stops accepting new deposits.
          title: Expires At
        metadata:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Metadata
        fee_bearer:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Fee Bearer
        underpay_tolerance:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          title: Underpay Tolerance
        accepted_coins:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          default: null
          title: Accepted Coins
        excluded_coins:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          default: null
          title: Excluded Coins
        on_paid_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: On Paid Url
        on_cancel_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: On Cancel Url
        notify_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Notify Url
        price_modifier:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          title: Price Modifier
        original_amount:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: Set only when price_modifier was applied.
          title: Original Amount
        payer_info:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Payer Info
        permanent_address_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Set only on deposit invoices auto-created from a permanent address.
          title: Permanent Address Id
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Set only on deposit invoices auto-created from a permanent address
            (copied from the address).
          title: User Id
        received_amount:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: Cumulative crypto amount actually received on-chain.
          title: Received Amount
        txid:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Hash of the (last) transaction that contributed to this invoice. Set
            after a successful on-chain payment.
          title: Txid
        payment_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Payment Url
        webhook_format:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Webhook Format
        created_at:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          description: Unix timestamp (seconds).
          title: Created At
        processed_at:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          description: >-
            Unix timestamp when the invoice transitioned to a paid status
            (success / partially_paid / paid_over).
          title: Processed At
      required:
        - order_id
      title: Invoice
      type: object
    SimulatedInvoiceEnvelope.d4a12ff.WebhookProbe:
      example:
        delivered: true
        error: null
        status_code: 200
        url: https://shop.example.com/webhook/paw
      properties:
        url:
          title: Url
          type: string
        status_code:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          title: Status Code
        delivered:
          default: false
          title: Delivered
          type: boolean
        error:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Exception class name if delivery failed.
          title: Error
      required:
        - url
      title: WebhookProbe
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header

````