Vouchereto API · v1

Environments & test credentials

Build and test everything in the sandbox, then switch keys. This page lists every test credential and test value you need.

Sandbox and live

There is one API host, https://api.vouchereto.com/v1. The key you send selects the mode, and every object is stamped with livemode. Test and live data are completely separate: a test key never sees live vouchers, redemptions, sessions or webhooks, and the other way round.

Sandbox versus live
	Sandbox	Live
API key	`vch_test_…`	`vch_live_…`
Money	None. Vouchers are created with POST /v1/sandbox/vouchers	Real vouchers bought by real customers
Webhooks	Endpoints you add in test mode	Endpoints you add in live mode
Settlements	Always empty (`GET /v1/settlements` returns `data: []`)	Weekly payouts
Available when	Your merchant account is in sandbox, uat or live	Your merchant account is live

Account lifecycle

Merchant statuses
Status	What works	How you move on
`onboarding`	Portal only (company verification, KYB)	We approve your business details
`sandbox`	Test keys, test webhooks, sandbox vouchers	You build and tell us you are ready for acceptance tests
`uat`	Same as sandbox; we run the go-live tests with you	Go-live checklist
`live`	Test and live keys	—
`suspended`	Nothing: every key returns `403 MERCHANT_NOT_ACTIVE`	Contact support

Your credentials

Credentials
Credential	Format	Where to get it	Used for
API key (test)	`vch_test_<12>_<32>`	Portal → test mode → Developers → API keys	Bearer token. Its last `_` segment is the signing secret.
API key (live)	`vch_live_<12>_<32>`	Same page in live mode, once your account is live	Real money
Webhook secret	`whsec_…`	Portal → Developers → Webhooks, one per endpoint	Verifying our webhook signatures

Keys and webhook secrets are shown once. We store only a hash of the key (and an encrypted copy of the secret used to check signatures). Lost it? Create a new one and revoke the old one.
You can have several active keys per mode: create the new key, deploy it, then revoke the old one (zero-downtime rotation).
Up to 5 active webhook endpoints per mode. URLs must be public https:// addresses; private and internal addresses are rejected.
Never put a key in a browser, mobile app or repository. All API calls come from your server.

We do not publish a shared demo key: each merchant gets its own test key, so your sandbox data and webhooks are yours only. Request sandbox access.

Test vouchers

Create vouchers in any state with POST /v1/sandbox/vouchers (test keys only) or with the form on the portal's Developers page in test mode. Each call returns a fresh, valid code tied to your merchant. Codes are 16 characters, shown in groups of 4; dashes and spaces are ignored when you send them back.

Sandbox voucher states
state	Reserve it and you get	Use it to test
`active`	`201 reserved`	The happy path: reserve → capture / cancel / let it expire
`reserved`	`409 VOUCHER_RESERVED`	A code already locked by another redemption (locked for 30 min)
`redeemed`	`409 VOUCHER_ALREADY_REDEEMED`	A code that was already used
`expired`	`422 VOUCHER_EXPIRED`	An expired code
`risk_hold`	`404 VOUCHER_INVALID`	A voucher held for fraud review (not usable until released)
`void`	`404 VOUCHER_INVALID`	A refunded or cancelled voucher

Any code that does not exist returns 404 VOUCHER_INVALID, for example AAAA-BBBB-CCCC-DDDD. Repeated invalid codes trigger 429 TOO_MANY_INVALID_ATTEMPTS for that customer: use a different customer_ref to keep testing.

Fields: amount_minor 100–10,000,000 (default 5000), currency one of your account's currencies (default USD).

Test cards

In the hosted checkout's test card processor, any future expiry date and any CVC work. The card number decides the outcome:

Test cards
Card number	Result
`4242 4242 4242 4242`	Approved
`4000 0027 6000 3184`	Approved after a 3D Secure challenge
`4000 0056 0000 0008`	Approved from a foreign card: the voucher is placed on a risk hold
`4000 0000 0000 0002`	Declined
`4000 0000 0000 9995`	Declined: insufficient funds

Never use a real card in the sandbox, and never use these numbers in live mode.

Local stack

Our full platform runs on your machine for offline development and CI (Postgres + the four apps). In the repository:

Copy scripts/local/vp.test.env.example to scripts/local/vp.test.env, apply the migrations to a local Postgres, then start everything with scripts/local/start-all.sh (API on http://localhost:3003, hosted pages on http://localhost:3000/pay).
Create a demo sandbox merchant, a test key and (optionally) a webhook endpoint. The credentials are printed once:

shell

DATABASE_URL=postgres://… API_SECRET_KEY=… \
  npx tsx scripts/sandbox/seed-demo-merchant.ts --webhook-url https://your-tunnel.example.com/hooks

Demo sandbox merchant ready (shown once, store it now):
  merchant_id     00000000-0000-4000-8000-00000000de30  (status sandbox, USD, checkout 5.00–500.00)
  api_key         vch_test_VAQ7bNGvAs8q_…
  webhook_url     https://your-tunnel.example.com/hooks
  webhook_secret  whsec_…

Point your client at http://localhost:3003/v1. Locally, return_url and cancel_url may use http://localhost.

Postman

Import the collection and the Sandbox or Local environment, paste your test key into api_key and run the Quickstart folder. Requests are signed automatically.