Sandbox API Concepts

The Sandbox API lets you simulate card activity in non‑production environments so you can build and validate your integration without processing real transactions. It is available for testing and produces the same downstream effects a real transaction would — including firing the full webhook chain — so you can verify your authorization logic and webhook handlers end to end.

This guide explains the simulation model. For how the resulting events are delivered, see Webhook API Concepts.

Transaction Simulations

Single‑Message vs. Dual‑Message

mCards transactions follow one of two flows, and the Sandbox API can simulate both:

• Single‑message — authorization and clearing happen together in one step. A single‑message purchase or a single‑message refund (a clearing reversal) completes in one call.
• Dual‑message — a purchase is authorized first (placing a hold), then completed in a separate step (clearing or reversal).

Authorize

The authorize simulation initiates a simulated card transaction. It supports:

• single‑message purchases,
• dual‑message purchase authorizations (to be completed later), and
• single‑message refunds (clearing reversals).

Complete

The complete simulation finalizes a previously authorized dual‑message transaction. It supports both clearing (settling the held amount) and reversal (releasing the hold). Use it after an authorize call to drive the second half of a dual‑message flow.

Location Simulations

The simulate location endpoint generates a cardholder location event and triggers the location webhook pipeline. It supports several source types:

• mobile_device — a location reported by the cardholder's mobile device.
• terminal — a location derived from a point‑of‑sale terminal.
• ip_geolocation — a location inferred from an IP address.

This lets you exercise location‑driven behavior and the location webhooks your integration relies on.

Webhooks Fire End‑to‑End

Simulations are not inert: an authorize, complete, or location simulation drives the same webhook chain a real event would. This is the primary reason to use the Sandbox API — you can point webhooks at your test endpoints and confirm your handlers react correctly before going live.

Key Patterns

Non‑Production Only

The Sandbox API exists to simulate activity in test environments; it does not move real money or affect production data. See the Sandbox (UAT) entry in the Glossary.

Testing the Full Lifecycle

Combine the simulations to reproduce realistic scenarios: authorize a dual‑message purchase, complete it (clear or reverse), issue refunds, and inject location events — verifying the webhooks and authorization responses at each step.

Related Guides

• Webhook API Concepts — How simulated events are delivered
• Platform Integration Concepts — The transaction lifecycle
• API Authentication and Credentials — How to authenticate API requests
• Sandbox API Reference — Full endpoint documentation