Skip to content
Docs

Get started

Sandbox testing

Use a wgp_test_… key to run real checkout flows with synthetic cards, or simulate outcomes without a device. No money moves in sandbox.

Test cards

Create a payment with a sandbox key, open its checkout, and choose Pay by card. The checkout shows a sandbox notice; only use these cards when you see it.

ScenarioCard numberWhat happens
Successful payment4242 4242 4242 4242No customer challenge. The payment becomes paid.
3D Secure challenge4000 0025 0000 3155Complete the challenge in the browser, then verify the payment.
Successful payment (alternative)4111 1111 1111 1111No customer challenge.

For every card, use card holder TEST TEST, any future expiry such as 12/2030, and CVV 123. Use a new payment for each scenario.

Never mix test and real data

Never use test cards with a live key, and never enter a real card in sandbox. For declines and failed challenges, ask Wegopay for approved fixtures; do not invent card numbers.

Verify the result

After checkout, read the payment and confirm status: "paid", environment: "sandbox", and the expected amount, currency and reference. Check that your webhook endpoint received and accepted the signed event.

Device-free simulations

Simulations let you test your webhook handling and order states without a card, wallet device or provider. Run them in Dashboard → Test checkout → Device-free sandbox scenarios, or from your server:

POST/v1/sandbox/simulations
API reference →

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

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"
  }
}

Scenarios are paid, declined, requiresAction and expired, for card or wallet. Finish a requiresAction simulation with POST /v1/sandbox/simulations/{id}/complete and {"outcome":"paid"} or {"outcome":"declined"}. Live keys cannot use simulations.

Simulations are not payments

A simulation is its own resource with simulation: true. Its webhooks use sandbox.simulation.* event types. It never changes real payments or totals. Never fulfill an order from a simulated event.

What sandbox does not prove

Sandbox cannot show production approval rates, issuer or risk decisions, real-device wallet behaviour, production 3D Secure, or settlement. There is no API to force a real payment’s status. To test checkout expiry, leave a sandbox checkout unused until its expiresAt. This tests session expiry, not a decline.

Acceptance checks before going live

Run these against the deployed sandbox and record payment IDs, event IDs and results. Do not record secrets or card data. Wegopay signs off this list with you before issuing a live key.

ScenarioExpected result
Hosted checkout, with and without 3D SecureVerified paid payment, signed event accepted, order fulfilled once
Decline, abandonment, expiryNo premature fulfillment; the pending order is reconciled
Same create request retried, or sent twice at onceOne payment ID; no second charge
Wrong environment on create, cross-environment readRequest rejected; a sandbox key cannot read live payments
Tampered or stale webhook, wrong environment secretYour receiver rejects it, with no side effects
Duplicate or out-of-order webhooksDeduplicated by event ID; current state read; fulfilled once
Your receiver returns 500, then recoversDelivery retries and is accepted
Signing secret rotation, API key revocationOld secret accepted while draining; revoked key rejected

Next: configure hosted checkout.