Quickstart

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.

Get sandbox access and an API key

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.
Sign in to the sandbox developer dashboard and request API access for your consumer partner. AllRide activates it; you get an email when it is active.
Open API keys and create a key with these scopes:
- view-consumer-catalog
- create-consumer-redemptions
- view-consumer-redemptions
- manage-webhooks
Copy the key now: it starts with vk_test_ and is shown only once.

Export the base URL and the key in your shell:

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:

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.

List your catalog

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

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:

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).

Redeem a voucher

Redeem one voucher for a customer of yours. The inline redemptionEntity creates (or reuses) a redemption entity with your own reference, and the Idempotency-Key makes the request safe to retry:

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:

{
  "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 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 here means the previous step was skipped: accept the sandbox price in Prices, then send the request again with a new Idempotency-Key.

Repeat the identical request

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

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).

Receive and verify a webhook

export WEBHOOK_URL="https://hooks.example-transit.example.com/allride-voucher"

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:

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 and answer with any 2xx status within 15 seconds. From now on, every redemption of your partner also sends a signed redemption-created event to this endpoint.

Next steps

Hand out vouchers without building a UI: Redemption links.
Model your customers or accounts and set per-customer limits: Redemption entities.
Make your integration production-ready: Going-live checklist.

Get started

Authentication and security

API conventions

Webhooks

Consumer guides

Workspace

​Related

Related