Testing

Before going live, exercise the full payment flow in a sandbox. Quidkey routes test payments to a sandbox provider so you can integrate, verify webhooks, and rehearse edge cases, with no real bank movement.

Route a Payment to the Sandbox

Pass test_transaction: true when you create a payment. Quidkey routes it to the sandbox provider instead of a live bank connection.

curl -X POST 'https://core.quidkey.com/api/v1/payment-requests:redirect' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1999,
    "currency": "GBP",
    "locale": "en-GB",
    "test_transaction": true
  }'

const response = await fetch(
  'https://core.quidkey.com/api/v1/payment-requests:redirect',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: 1999,
      currency: 'GBP',
      locale: 'en-GB',
      test_transaction: true,
    }),
  },
);

response = requests.post(
    'https://core.quidkey.com/api/v1/payment-requests:redirect',
    headers={
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': 1999,
        'currency': 'GBP',
        'locale': 'en-GB',
        'test_transaction': True,
    },
)

Body abbreviated. See the Redirect guide for the full required payload.

Always set test_transaction: true in development. A request without it is treated as live and may attempt a real bank movement.

Identifying Test Events

Webhooks for sandbox payments carry test markers, so your handler can tell sandbox traffic apart from production. The event payload includes a test flag (and sandbox indicators) on the payment object:

{
  "id": "evt_9f8b2c14-3d6a-4e21-bb02-7c1d9a4e5f60",
  "object": "event",
  "type": "quidkey.payment_request.succeeded",
  "data": {
    "object": {
      "id": "4a7b1e2c-9d83-4f10-a6b5-2e9c7d041f8a",
      "amount": "1999",
      "currency": "GBP",
      "status": "completed",
      "test": true,
      "metadata": { "order_id": "ORD-123", "payment_token": "ptok_..." }
    }
  }
}

Gate your fulfilment logic on data.object.test. In non-production environments, ignore live events; in production, ignore test events. This prevents a stray sandbox webhook from triggering real fulfilment.

Sandbox vs. Live

Aspect	Sandbox (`test_transaction: true`)	Live
Bank movement	None: simulated by the sandbox provider	Real funds move
Webhook events	Same shapes, with `test`/`sandbox` markers	Production events
Credentials	Use a separate set of credentials / webhook secret if you have them	Production credentials

If your account provides separate sandbox credentials and a separate webhook signing secret, use them for test traffic and keep them distinct from production. This keeps environments cleanly isolated.

A Typical Test Pass

Create a test payment

Create a payment request with test_transaction: true and complete it through the sandbox flow.

Confirm the webhook arrives

Verify your endpoint receives the event, the signature validates, and data.object.test is true. See Webhooks.

Exercise edge cases

Test failure and cancellation paths, and confirm your idempotency and error handling behave as expected.

Reconcile

Look up the payment via the status endpoint to confirm your records match Quidkey’s.

Next Steps

Webhooks

Verify signatures and handle test events

Accept a Payment (Redirect)

Create your first test payment

Amounts & Currencies

Send amounts correctly in tests

Errors

Test your error handling paths

Get started

Core concepts

Accept a payment

API reference

Route a Payment to the Sandbox

Identifying Test Events

Sandbox vs. Live

A Typical Test Pass

Next Steps

Webhooks

Accept a Payment (Redirect)

Amounts & Currencies

Errors

​Route a Payment to the Sandbox

​Identifying Test Events

​Sandbox vs. Live

​A Typical Test Pass

​Next Steps

Webhooks

Accept a Payment (Redirect)

Amounts & Currencies

Errors

Route a Payment to the Sandbox

Identifying Test Events

Sandbox vs. Live

A Typical Test Pass

Next Steps