> ## Documentation Index
> Fetch the complete documentation index at: https://docs-consumer.voucher.allride.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get a sandbox API key, list your catalog, redeem a voucher, replay the request safely and receive a signed webhook.

This quickstart runs entirely in the **sandbox**. It takes about 15 minutes and uses `curl` and `jq`. Every request here is a real request against `https://api.voucher-staging.allride.io`; nothing you do affects production.

**1. Get sandbox access and an API key**

1. **Get a sandbox account.** If you have no sandbox sign-in yet, send your AllRide account manager (or AllRide through the **Support** link at the top of this site) your company name and the email address of your first user. AllRide creates your consumer partner in the sandbox and sends that user an invitation.
2. Sign in to the [sandbox developer dashboard](https://consumer-developers.voucher-staging.allride.io/go/api-access) and request API access for your consumer partner. AllRide activates it; you get an email when it is active.
3. Open [API keys](https://consumer-developers.voucher-staging.allride.io/go/api-keys) and create a key with these scopes:
   * `view-consumer-catalog`
   * `create-consumer-redemptions`
   * `view-consumer-redemptions`
   * `manage-webhooks`
4. Copy the key now: it starts with `vk_test_` and is shown only once.

Export the base URL and the key in your shell:

```bash theme={null}
export VOUCHER_API_BASE_URL="https://api.voucher-staging.allride.io"
export VOUCHER_API_KEY="<paste your vk_test_ key here>"
```

Check that the key works and has the scopes you expect:

```bash theme={null}
curl -s "$VOUCHER_API_BASE_URL/partner/v1/principal" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" | jq '.data | {partnerSlug, environment, effectivePermissions}'
```

`environment` is `test` in the sandbox. A `401` with `errorCode` `api-key-invalid` means the key is mistyped or belongs to production; a `403` with `api-access-inactive` means API access is not active yet.

**2. List your catalog**

Ask for the voucher sets that are active and switched on for your channels:

```bash theme={null}
curl -s -G "$VOUCHER_API_BASE_URL/consumer/v1/catalog/voucher-sets" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  --data-urlencode "filter[availability]=active" \
  --data-urlencode "filter[providerToggle]=true" \
  --data-urlencode "filter[voucherSetToggle]=true" \
  --data-urlencode "search=Sandbox ride credit" \
  | jq '.data.data[] | {id, name: .live.name.en, provider: .provider.slug, stockStatus, priceAcceptance}'
```

The sandbox seeds the provider `sandbox-scooters` with the voucher set **Sandbox ride credit** and switches that provider on for every new consumer. Note the set's `id`:

```bash theme={null}
export VOUCHER_SET_ID=<the id from the response>
```

Each entry carries `priceAcceptance.status`. A set is redeemable only after a user of your partner accepted its Price Terms. The sandbox sets show `priceAcceptance.status: acceptance-required`: they carry a €0 sandbox price that is never billed. Open **Prices** in the sandbox consumer dashboard and accept it once before you redeem ([Prices and price acceptance](https://docs-consumer.voucher.allride.io/consumer/prices.md)).

**3. Redeem a voucher**

Redeem one voucher for a customer of yours. The inline `redemptionEntity` creates (or reuses) a [redemption entity](https://docs-consumer.voucher.allride.io/consumer/redemption-entities.md) with your own reference, and the `Idempotency-Key` makes the request safe to retry:

```bash theme={null}
export IDEMPOTENCY_KEY=$(uuidgen)

curl -s -i -X POST "$VOUCHER_API_BASE_URL/consumer/v1/redemptions" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d "{\"voucherSetId\": $VOUCHER_SET_ID, \"redemptionEntity\": {\"refId\": \"customer:42\"}}"
```

The response is `201 Created` with the issued voucher in `issued`:

```json theme={null}
{
  "data": {
    "id": 6017,
    "resource": "redemption",
    "status": "completed",
    "channel": "api",
    "voucherSetId": 2030,
    "issued": { "kind": "code", "code": "SANDBOX-7KQ2-M9XA", "link": null },
    "validFrom": null,
    "validUntil": "2026-12-31T22:59:59Z",
    "redemptionEntity": {
      "id": 9017,
      "resource": "redemption-entity",
      "refId": "customer:42",
      "_links": { "self": { "href": "https://api.voucher-staging.allride.io/consumer/v1/redemption-entities/9017", "type": "application/json" } }
    },
    "redeemedAt": "2026-10-26T09:15:00.120Z",
    "_links": { "self": { "href": "https://api.voucher-staging.allride.io/consumer/v1/redemptions/6017", "type": "application/json" } }
  }
}
```

The example is shortened; [Create a redemption](https://docs-consumer.voucher.allride.io/api-reference/consumer-redemptions-create.md) shows every field. The issued code is a secret for your customer: show it only to the customer it was issued to.

A `409` [`price-acceptance-required`](https://docs-consumer.voucher.allride.io/errors/catalog#price-acceptance-required) here means the previous step was skipped: accept the sandbox price in **Prices**, then send the request again with a new `Idempotency-Key`.

**4. Repeat the identical request**

Send exactly the same request again, with the same `Idempotency-Key`:

```bash theme={null}
curl -s -i -X POST "$VOUCHER_API_BASE_URL/consumer/v1/redemptions" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d "{\"voucherSetId\": $VOUCHER_SET_ID, \"redemptionEntity\": {\"refId\": \"customer:42\"}}"
```

You get the same `201` body, including the same `issued` code, and the header `Idempotent-Replayed: true`. No second voucher was redeemed. This is how you retry after a timeout or a network error without redeeming twice ([Idempotency](https://docs-consumer.voucher.allride.io/guides/idempotency.md)).

**5. Receive and verify a webhook**

Register a publicly reachable HTTPS endpoint you control (port 443 or 8443) for `redemption-created`:

```bash theme={null}
export WEBHOOK_URL="https://hooks.example-transit.example.com/allride-voucher"
```

```bash theme={null}
curl -s -X POST "$VOUCHER_API_BASE_URL/partner/v1/webhook-endpoints" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"url\": \"$WEBHOOK_URL\", \"eventTypes\": [\"redemption-created\"]}" \
  | jq '.data | {id, firstSecret, secondSecret}'
```

Store `firstSecret` and `secondSecret` in your secret manager: they are shown only in this response. Then send a test event to the endpoint:

```bash theme={null}
export WEBHOOK_ENDPOINT_ID=<the id from the response>

curl -s -X POST "$VOUCHER_API_BASE_URL/partner/v1/webhook-endpoints/$WEBHOOK_ENDPOINT_ID:send-test-event" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
```

Your endpoint receives a `webhook-endpoint-test` event with the header `x-signing-signature: t=…,s1=…,s2=…`. Verify it as described in [Verifying signatures](https://docs-consumer.voucher.allride.io/webhooks/verify-signatures.md) and answer with any `2xx` status within 15 seconds. From now on, every redemption of your partner also sends a signed [`redemption-created`](https://docs-consumer.voucher.allride.io/webhooks/events/redemption-created) event to this endpoint.

**6. Next steps**

* Hand out vouchers without building a UI: [Redemption links](https://docs-consumer.voucher.allride.io/consumer/redemption-links.md).
* Model your customers or accounts and set per-customer limits: [Redemption entities](https://docs-consumer.voucher.allride.io/consumer/redemption-entities.md).
* Make your integration production-ready: [Going-live checklist](https://docs-consumer.voucher.allride.io/guides/going-live.md).

## Related

* [Authentication](https://docs-consumer.voucher.allride.io/guides/authentication.md)
* [Redeeming vouchers](https://docs-consumer.voucher.allride.io/consumer/redeeming.md)
* [Webhooks](https://docs-consumer.voucher.allride.io/webhooks/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.