Skip to content
Docs

API reference

Sandbox simulations

Device-free test scenarios for sandbox keys. Simulations are separate resources: they never change real payments or financial totals.

Create a simulation

POST/v1/sandbox/simulations

Creates an isolated simulated payment with the outcome you choose and sends its signed sandbox.simulation.* webhook. Sandbox keys only; simulations never change real payments.

Auth Secret API key as Authorization: Bearer. Call from your server only.

Headers

  • Idempotency-Keyrequiredstring16–128 chars

Request body application/json

  • scenariorequiredstring

    One ofpaiddeclinedrequiresActionexpired

  • referencerequiredstring1–255 chars
  • amountCentsrequiredinteger500–100000000
  • currencyrequiredstring

    AlwaysUSD

  • methodstring

    One ofcardwallet

    Default"wallet"

Responses

Isolated simulation resource; do not use for real fulfillment.

  • dataobject
    • idstring <uuid>
    • environmentstring

      Alwayssandbox

    • simulationboolean

      Alwaystrue

    • statusstring

      One ofpaidfailedrequiresActionexpired

    • scenariostring

      One ofpaiddeclinedrequiresActionexpired

    • methodstring

      One ofcardwallet

    • referencestring
    • amountCentsinteger
    • currencystring

      AlwaysUSD

    • createdAtstring <date-time>
    • expiresAtstring <date-time>
    • failureCodestringcan be null
    • failureMessagestringcan be null
    • webhookStatusstring

      One ofpendingprocessingdelivereddead

See errors and idempotency for how to handle each error code.

Request
curl -X POST "https://api.wegopay.tech/v1/sandbox/simulations" \
  -H "Authorization: Bearer $WEGOPAY_API_KEY" \
  -H "Idempotency-Key: order-1042-create" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "requiresAction",
    "method": "wallet",
    "amountCents": 500,
    "currency": "USD",
    "reference": "SIM-order-1"
  }'
Response
{
  "data": {
    "id": "7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55",
    "environment": "sandbox",
    "simulation": true,
    "status": "paid",
    "scenario": "paid",
    "method": "card",
    "reference": "order-1042",
    "amountCents": 1500,
    "currency": "USD",
    "createdAt": "2026-10-11T12:00:00Z",
    "expiresAt": "2026-10-11T12:00:00Z",
    "failureCode": "string",
    "failureMessage": "string",
    "webhookStatus": "pending"
  }
}

Retrieve a simulation

GET/v1/sandbox/simulations/{id}

Retrieves a simulation and the delivery status of its webhook.

Auth Secret API key as Authorization: Bearer. Call from your server only.

Path parameters

  • idrequiredstring <uuid>

Responses

Isolated simulation resource; do not use for real fulfillment.

  • dataobject
    • idstring <uuid>
    • environmentstring

      Alwayssandbox

    • simulationboolean

      Alwaystrue

    • statusstring

      One ofpaidfailedrequiresActionexpired

    • scenariostring

      One ofpaiddeclinedrequiresActionexpired

    • methodstring

      One ofcardwallet

    • referencestring
    • amountCentsinteger
    • currencystring

      AlwaysUSD

    • createdAtstring <date-time>
    • expiresAtstring <date-time>
    • failureCodestringcan be null
    • failureMessagestringcan be null
    • webhookStatusstring

      One ofpendingprocessingdelivereddead

See errors and idempotency for how to handle each error code.

Request
curl "https://api.wegopay.tech/v1/sandbox/simulations/7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55" \
  -H "Authorization: Bearer $WEGOPAY_API_KEY"
Response
{
  "data": {
    "id": "7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55",
    "environment": "sandbox",
    "simulation": true,
    "status": "paid",
    "scenario": "paid",
    "method": "card",
    "reference": "order-1042",
    "amountCents": 1500,
    "currency": "USD",
    "createdAt": "2026-10-11T12:00:00Z",
    "expiresAt": "2026-10-11T12:00:00Z",
    "failureCode": "string",
    "failureMessage": "string",
    "webhookStatus": "pending"
  }
}

Complete a simulation

POST/v1/sandbox/simulations/{id}/complete

Completes a requiresAction simulation as paid or declined.

Auth Secret API key as Authorization: Bearer. Call from your server only.

Path parameters

  • idrequiredstring <uuid>

Headers

  • Idempotency-Keyrequiredstring16–128 chars

Request body application/json

  • outcomerequiredstring

    One ofpaiddeclined

Responses

Isolated simulation resource; do not use for real fulfillment.

  • dataobject
    • idstring <uuid>
    • environmentstring

      Alwayssandbox

    • simulationboolean

      Alwaystrue

    • statusstring

      One ofpaidfailedrequiresActionexpired

    • scenariostring

      One ofpaiddeclinedrequiresActionexpired

    • methodstring

      One ofcardwallet

    • referencestring
    • amountCentsinteger
    • currencystring

      AlwaysUSD

    • createdAtstring <date-time>
    • expiresAtstring <date-time>
    • failureCodestringcan be null
    • failureMessagestringcan be null
    • webhookStatusstring

      One ofpendingprocessingdelivereddead

See errors and idempotency for how to handle each error code.

Request
curl -X POST "https://api.wegopay.tech/v1/sandbox/simulations/7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55/complete" \
  -H "Authorization: Bearer $WEGOPAY_API_KEY" \
  -H "Idempotency-Key: order-1042-create" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "paid"
  }'
Response
{
  "data": {
    "id": "7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55",
    "environment": "sandbox",
    "simulation": true,
    "status": "paid",
    "scenario": "paid",
    "method": "card",
    "reference": "order-1042",
    "amountCents": 1500,
    "currency": "USD",
    "createdAt": "2026-10-11T12:00:00Z",
    "expiresAt": "2026-10-11T12:00:00Z",
    "failureCode": "string",
    "failureMessage": "string",
    "webhookStatus": "pending"
  }
}