Reserve Voucher

Reserve a voucher within a payment context — returns a 6-digit voucher code.

POST /api/v1/vouchers/reserve-voucher

The payee reserves a voucher using the context code the payer shared with them. The response includes a 6-digit voucher code and a voucher ID. The voucher starts in RESERVED status.

This endpoint accepts both API key authentication and registered user tokens.

Parameters

Body

Name	Type	Required	Description
code	string	Yes	The context code shared by the payer. 6 characters.

Request example

curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/reserve-voucher' \
  --header 'Authorization: Bearer <payee_token>' \
  --header 'Content-Type: application/json' \
  --data '{ "code": "A1B2C3" }'

Response

Response schema

Field	Type	Description
id	string	Unique voucher identifier
code	string	6-digit voucher code
status	string	Voucher status — RESERVED
expiresAt	string	ISO 8601 expiry timestamp

Example response

{
  "id": "vch_482916",
  "code": "482916",
  "status": "RESERVED",
  "expiresAt": "2026-06-09T12:02:00.000Z"
}

Error responses

Status	Code	Description
400	invalid_code	The context code is invalid or expired
401	unauthorized	Missing or invalid bearer token
404	not_found	Context not found