Vouchereto API · v1

Hosted checkout

Add a “Pay with voucher” button to your top-up page. The customer buys a voucher by card on pay.vouchereto.com (3D Secure) and comes back with the amount already applied to your merchant.

Flow

Your server creates a session with the amount and where to send the customer back.
Redirect the customer to url. They enter their email and card on our page, in their language.
With auto_redeem: true (default) we issue the voucher, reserve and capture it for you: the session becomes completed with a redemption_id. The customer also gets the voucher by email as a receipt.
We redirect to return_url?vouchereto_session=<id>&status=<status>. If they give up, the back link goes to cancel_url.
Credit the customer on the checkout.completed webhook (or after GET /v1/checkout-sessions/{id} shows completed). Never trust the query string alone.

create a session

POST /v1/checkout-sessions
Idempotency-Key: topup-3141

{
  "amount_minor": 5000,
  "currency": "USD",
  "customer_ref": "user_8842",
  "customer_email": "ana@example.com",
  "country": "US",
  "locale": "en",
  "return_url": "https://shop.example.com/topup/done",
  "cancel_url": "https://shop.example.com/topup",
  "auto_redeem": true,
  "metadata": { "topup_id": "3141" }
}

201 Created
{
  "id": "132d93fe-5f19-4b22-b34b-4d22f2f20881",
  "object": "checkout_session",
  "url": "https://pay.vouchereto.com/c/132d93fe-5f19-4b22-b34b-4d22f2f20881",
  "status": "open",
  "amount_minor": 5000,
  "currency": "USD",
  "customer_ref": "user_8842",
  "locale": "en",
  "auto_redeem": true,
  "livemode": false,
  "redemption_id": null,
  "metadata": { "topup_id": "3141" },
  "expires_at": "2026-10-22T18:22:57.010Z"
}

Fields

Checkout session fields
Field	Required	Notes
`amount_minor`	yes	Within the minimum and maximum configured for your account
`currency`	yes	One of your account currencies
`customer_ref`	yes	Your customer id, returned in webhooks
`return_url`	yes	`https://` (`http://localhost` works on the local stack)
`cancel_url`	yes	Where the back link goes
`customer_email`	no	Prefills the email field
`country`	no	ISO 3166-1 alpha-2. Some categories cannot sell in some countries (`COUNTRY_NOT_ALLOWED`)
`locale`	no	`en` (default), `es`, `ja`, `ko`, `pt`, `it`, `de`
`auto_redeem`	no	`false` = the customer just gets the voucher by email and redeems it later
`metadata`	no	Up to 20 string values (500 chars each), echoed in webhooks

Statuses

Checkout statuses
status	Meaning
`open`	Waiting for the customer. Expires after 60 minutes.
`paid`	Card payment approved, voucher being issued. A voucher placed on a fraud review stays here until released, then completes.
`completed`	Done. With `auto_redeem`, `redemption_id` is the captured redemption.
`expired`	Not paid in time.
`failed`	Payment failed.
`cancelled`	Cancelled.

Testing

Create the session with a vch_test_ key and pay with the test cards (4242 4242 4242 4242 approves). Test sessions create test vouchers only.
Try the decline cards and the 3D Secure card, and let a session expire to see checkout.expired.

Keep amounts identical to what you show the customer. The fee (if any) is shown on our page before they pay; you receive the full amount_minor minus your agreed commission in the weekly settlement.