Vouchers

🎟️ Voucher Purchase Flow

This flow allows the purchase of digital vouchers (e.g., gift cards, prepaid codes, supermarket coupons, etc.), and also other kinds of vouchers such us raffle tickets.

🔍 Description

In most cases, voucher products are predefined and do not require product discovery. The client can go directly to the purchase step. Only in specific cases (e.g., raffles, dynamic pricing) is it necessary to query available products or check the final result of a voucher.

✅ Standard Flow (Most Common)

1. Purchase Voucher

Endpoint: POST /vouchers/purchase/{terminalId}/{operatorId}/{localReference}

Executes the voucher purchase using:

productId

amountToSendX100

The response includes the voucherCode and, optionally, a flag hasAdditionalData: true if further information is available.

2. Get Voucher Additional Data (if applicable)

Endpoint: GET /vouchers/additional-data/{terminalId}/{operatorId}/{localReference}

If the purchase response includes hasAdditionalData: true, this endpoint must be called to retrieve:

Redemption instructions

PDF download links

Barcodes or QR codes

Any other metadata required to deliver or display the voucher

🧠 Notes

This is the default flow for most voucher operators.

In these cases, calling the Get Products will return a 404 Not Found, meaning there are no dynamic vouchers for that operatorID.

Always check the additionalData field in the response to determine if extra user input is required (e.g., receiverEmail, documentNumber, etc.).

Additionally, if the "hasAdditionalData" field is TRUE, you must call the Voucher Additional Data query to retrieve the pending redemption information. This is only necessary when the provider takes longer times to process the transaction.

🧩 Extended Flow (Only for Dynamic or Complex Vouchers)

Use this flow only :

when the operator supports dynamic product selection,

when the voucher may represent an entry into a draw and the final result — win/loss or prize — will be resolved later.

1. Get Voucher Products

Endpoint: GET /vouchers/products/{terminalId}/{operatorId}

Returns a list of available voucher products for the operator.

Only applicable if the operator supports dynamic product discovery

If not supported, this endpoint returns 404 Not Found

2. Purchase Voucher

Endpoint: POST /vouchers/purchase/{terminalId}/{operatorId}/{localReference}

Executes the voucher purchase using:

Selected productId

amountToSendX100

Any required additionalData (if applicable)

The response includes voucherCode and may contain hasAdditionalData: true.

3. Get Voucher Additional Data (if applicable)

Endpoint: GET /vouchers/additional-data/{terminalId}/{operatorId}/{localReference}

If the purchase response includes hasAdditionalData: true, use this endpoint to retrieve:

Redemption metadata

Printable/downloadable assets (PDF, barcode, QR code)

Instructions for the user

4. Deferred - Get Finished Vouchers (e.g. Raffles)

Endpoint: GET /vouchers/finished/{terminalId}/{operatorId}/{localReference}

Retrieves the final outcome of a voucher in scenarios such as raffle ticket resolution. This is a deferred call, intended to be triggered only after the raffle has concluded. As such, it is not part of the dynamic transaction flow.

🧠 Notes

Steps 1 and 4 apply only in specific business cases (e.g. dynamic pricing, raffles, etc.).

Always check hasAdditionalData to determine whether step 3 is required after purchase.

🧠 Summary

Scenario	Flow to Use
Standard voucher (predefined)	➡️ Direct `purchase`
Complex or deferred response	➡️ `purchase` + `additionalData`
Dynamic product selection needed	➡️ `get products` → `purchase`
Raffle or delayed result	➡️ `purchase` → `get finished`

🎟️ Voucher Purchase Flow#

🔍 Description#

✅ Standard Flow (Most Common)#

🧠 Notes#

🧩 Extended Flow (Only for Dynamic or Complex Vouchers)#

🧠 Notes#

🧠 Summary#

🎟️ Voucher Purchase Flow

🔍 Description

✅ Standard Flow (Most Common)

🧠 Notes

🧩 Extended Flow (Only for Dynamic or Complex Vouchers)

🧠 Notes

🧠 Summary