Suward
Simulate
GUIDES

Simulate

Simulate a test payment without a wallet or an on-chain transfer. Use it to test valid status transitions, polling and webhooks. Simulated payments never credit your project balance — for that, pay a real transfer with test tokens.

Driving a payment

Create a test payment, then POST each step to its /simulate endpoint. A payment moves one edge at a time, so reaching success takes two calls: accepted first, then success carrying the same subStatus. Jumping a fresh payment straight to success is rejected.

terminal
# 1. Accept the deposit: pending/awaitingPayment → accepted/completed.
curl -X POST https://api.suward.com/v1/payments/$PAYMENT_ID/simulate \
-H "X-Api-Key: $SUWARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "accepted", "subStatus": "completed" }'
# 2. Finalize it: accepted/completed → success/completed.
curl -X POST https://api.suward.com/v1/payments/$PAYMENT_ID/simulate \
-H "X-Api-Key: $SUWARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "success", "subStatus": "completed" }'

Only overpaid and underpaid accept an amount — an integer string in the asset’s smallest unit, like every amount in the API. Overpaid must exceed the payment amount, underpaid must fall below it; any other target rejects an amount outright.

Targets the simulator accepts

Every call must be a valid edge out of the payment’s current status/subStatus pair. These are the only targets the simulator takes — created, awaitingPayment and partiallyPaid are not among them.

  • pending
    activated

    from pending/created, and only when the payment has an activation flow

  • pending
    confirming

    from pending/awaitingPayment, or back from any accepted pair

  • accepted
    completedoverpaidunderpaid

    from pending/awaitingPayment, pending/confirming, or another accepted pair

  • success
    completedoverpaidunderpaid

    from the accepted pair carrying the same subStatus

  • failed
    expired

    from any pending pair

  • failed
    cancelled

    from pending/created, pending/activated or pending/awaitingPayment

Static wallets

Static wallets are a separate endpoint with a different shape. POST /v1/static-wallets/{id}/simulate takes an asset, an amount and a deposit status — detected, accepted, confirmed or invalidated — not a payment status/subStatus pair. The amount is required and must be positive; txHash is generated for you when omitted. It credits no balance either.