Sandbox

The sandbox is a separate environment of the Buckaroo API in which no money moves. It has the same endpoints, request and response formats, statuses and webhooks as live. Only the base URL and the credentials differ.

Environment

	Sandbox	Live
Base URL	`https://sandbox-api.buckaroo.io/v1/`	`https://api.buckaroo.io/v1/`
API keys	Sandbox keys only	Live keys only

Sandbox and live credentials are not interchangeable: a live API key is rejected by the sandbox and a sandbox key is rejected by live. Sandbox API keys are created with POST /v1/apikeys against the sandbox base URL. See API Keys.

Authentication is the same as in live, with the key in the Buck-Api-Key header. GET /v1/merchant returns 200 with the merchant details when the key and the base URL match.

Sales, transactions, API keys and webhook configurations created in the sandbox stay in the sandbox. Nothing is migrated to live.

Behaviour

The sandbox never contacts a bank, card scheme or wallet. Supported payment methods are simulated by Buckaroo.
There is no consumer interaction. Where a live payment redirects the consumer to a bank or wallet, the sandbox redirects straight to the sale's returnUrl.
Webhooks are sent for the same sale and transaction events as in live. See Webhooks.
Sale and transaction statuses are the same as in live. See Sale Lifetime.

Sandbox scenarios

A sandbox scenario selects the outcome that is simulated for an operation. It is set with the optional sandboxScenario field. The accepted values depend on the operation:

Operation	Endpoint	Field	Values
Create sale	`POST /v1/sales`	`paymentMethodOptions.sandboxScenario`	`Success`, `Cancelled`, `Expired`, `Failed`
Cancel sale	`POST /v1/sales/{saleId}/cancel`	`sandboxScenario`	`Success`, `Failed`
Capture sale	`POST /v1/sales/{saleId}/capture`	`sandboxScenario`	`Success`, `Failed`
Capture authorization	`POST /v1/sales/authorizations/{authorizationId}/capture`	`sandboxScenario`	`Success`, `Failed`
Release authorization	`POST /v1/sales/authorizations/{authorizationId}/release`	`sandboxScenario`	`Success`, `Failed`

Without a scenario, an operation is simulated as Success.
A value outside the listed ones is rejected with 400 and the allowed values.
The scenario of a sale applies to every transaction of that sale, including refunds. A capture uses its own scenario and falls back to the scenario of the sale.
Every transaction shows the scenario that was simulated in details.sandboxScenario. Authorizations do not carry a scenario.

A sandbox scenario is only available in the sandbox. In live, a sale with a scenario creates a transaction that fails with error code VP06, and cancel, capture and release requests with a scenario are rejected. See Transaction Error Codes.

Example of a sale that simulates an expired payment:

POST /v1/sales
{
  "reference": "test-0001",
  "currency": "EUR",
  "totalAmount": "25.00",
  "sequenceType": "OneOff",
  "intentType": "Pay",
  "paymentMethods": ["Wero"],
  "paymentMethodOptions": {
    "sandboxScenario": "Expired"
  },
  "returnUrl": "https://example.com/return"
}

Supported scenarios per payment method

Payment method	Create sale	Cancel sale	Capture sale	Capture authorization	Release authorization
Wero	`Success`, `Cancelled`, `Expired`, `Failed`	`Success`, `Failed`	–	–	–

–: the operation is not available for the payment method.