Sandbox

The sandbox is a separate copy of the Buckaroo API where no money moves. You use the same endpoints, the same request and response formats and the same webhooks as in live. Only the credentials and the base URL differ.

Use it to build and test your integration before you accept real payments.

1. Get sandbox credentials

Sandbox credentials are separate from live credentials. A live API key does not work in the sandbox and a sandbox key does not work in live.

Create a sandbox API key the same way you create a live one, through POST /v1/apikeys against the sandbox base URL. See API Keys for the request.

2. Point your integration at the sandbox

Send every request to the sandbox base URL:

https://sandbox-api.buckaroo.io/v1/

Authentication does not change. Include your sandbox API key in the Buck-Api-Key header:

Buck-Api-Key: apk_your_sandbox_key

Check the connection with GET /v1/merchant. A 200 response with your merchant details means the key and the URL are correct.

3. Create a test sale

Create a sale exactly as you would in live. The sandbox never contacts a bank, a card scheme or a wallet. Instead it decides the outcome from the request itself, based on the payment method and the amount.

curl -X POST {{SANDBOX_BASE_URL}}/v1/sales \
  -H "Buck-Api-Key: apk_your_sandbox_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "test-0001",
    "currency": "EUR",
    "totalAmount": "47.01",
    "sequenceType": "OneOff",
    "intentType": "Pay",
    "paymentMethods": ["Wero"],
    "returnUrl": "https://example.com/return"
  }'

Each payment method has its own test data. The section for that payment method on this page tells you which amounts or values trigger which outcome. Any other value is rejected with a 400 response that names the accepted values.

4. Receive the result

The sandbox completes most payments within a few seconds. There is no consumer interaction. Where a live payment would redirect the consumer to a bank or wallet, the sandbox redirects straight to your returnUrl.

Handle the outcome the same way you will in live:

Subscribe a webhook to sale and transaction events. The sandbox sends the same events as live. See Webhooks.
Or poll GET /v1/sales/{saleId} and read status and the transactions.

Do not rely on the redirect to your returnUrl as the source of truth. In live, consumers close the browser before the redirect. Test that your webhook handling works without it.

Statuses are the same as in live. A sale is Open, Paid, Cancelled, Expired or Failed. A transaction is Pending, Successful, Cancelled, Expired or Failed. See Sale Lifetime.

5. Test the full flow

Test more than the happy path. Before you go live, confirm that your integration handles:

A payment that is declined or fails.
A payment that stays pending longer than you expect.
A refund that is rejected.
An authorization that cannot be captured or cancelled.

The test data per payment method:

Wero

6. Go live

To switch to live:

Replace the sandbox base URL with https://api.buckaroo.io/v1/.
Replace the sandbox API key with a live API key.
Remove any test amounts or test values from your code. In live they are ordinary amounts.
Register your live webhook URL. Webhook configurations are not copied from the sandbox.

Sandbox data is not migrated to live. Sales, transactions and webhook configurations created in the sandbox stay in the sandbox.