API reference

POST/v1/redemptions

Reserve a voucher (step 1 of 2). Locks the voucher's full value for ttl_seconds. Nothing is charged until you capture. If you neither capture nor cancel, the reservation expires and the voucher becomes usable again (redemption.expired webhook). Vouchers are single-use: the whole face value is redeemed. Invalid codes are rate limited per customer_ref, per customer IP and per merchant (5 failures / 15 min per customer, then exponential blocks). Send X-Customer-Ip so one abusive customer cannot block your server's IP.

Rate limit: 120 requests / minute / key.

Request body:

{
  "code": "K7QM-4XPD-9TRW-2WNZ",
  "currency": "USD",
  "customer_ref": "user_8842",
  "ttl_seconds": 900
}

Response 201:

Errors: 400, 401, 403, 404, 409, 422, 429 · codes

GET/v1/redemptions

List redemptions. Newest first. Cursor pagination.

Response 200:

Errors: 400, 401 · codes

GET/v1/redemptions/{id}

Retrieve a redemption.

Response 200:

Errors: 404 · codes

POST/v1/redemptions/{id}/capture

Capture a reservation (step 2 of 2). Credits your merchant balance with the voucher's value. Credit your customer only after a 200 here (or the redemption.captured webhook).

Response 200:

Errors: 404, 409 · codes

POST/v1/redemptions/{id}/cancel

Cancel a reservation. Releases the voucher so the customer can use it again. Only reservations can be cancelled; a captured redemption is final.

Response 200:

Errors: 404, 409 · codes

POST/v1/checkout-sessions

Create a hosted checkout session. Redirect your customer to url. They buy a voucher by card (3D Secure) on pay.vouchereto.com. With auto_redeem: true (default) the voucher is reserved and captured for you in the same step and the session becomes completed with a redemption_id. The customer is sent back to return_url?vouchereto_session=<id>&status=<status>. Trust the checkout.completed webhook or GET /checkout-sessions/{id}, never the query string alone. Sessions expire after 60 minutes.

Rate limit: 300 requests / minute / key.

Request body:

{
  "amount_minor": 5000,
  "currency": "USD",
  "customer_ref": "user_8842",
  "locale": "en",
  "return_url": "https://shop.example.com/topup/done",
  "cancel_url": "https://shop.example.com/topup",
  "metadata": {
    "cart": "3141"
  }
}

Response 201:

Errors: 400, 403, 422, 429 · codes

GET/v1/checkout-sessions/{id}

Retrieve a checkout session.

Response 200:

Errors: 404 · codes

POST/v1/redeem-sessions

Create a hosted redeem session. Redirect your customer to url; they type their code on pay.vouchereto.com. They return to return_url?vouchereto_redemption=<id>&status=<reserved|captured>. With auto_capture: false (default) you must capture or cancel the redemption yourself. Sessions expire after 30 minutes.

Request body:

{
  "currency": "USD",
  "customer_ref": "user_8842",
  "return_url": "https://shop.example.com/wallet",
  "auto_capture": false
}

Response 201:

Errors: 400, 422 · codes

POST/v1/sandbox/vouchers

Create a test voucher. Test keys only (a live key gets 403 LIVEMODE_NOT_ALLOWED). Returns a real, valid code in the state you ask for, tied to your merchant.

Request body:

{
  "state": "active",
  "amount_minor": 5000,
  "currency": "USD"
}

Response 201:

Errors: 403, 422 · codes

GET/v1/settlements

List settlements. Latest 100, newest first. Test keys always get an empty list (no money moves in the sandbox). The line-level CSV is in the merchant portal.

Response 200: