Vouchers Management XP API

Introduction

The Vouchers Management API allows clients to request vouchers and manage the status of the vouchers. It's an HTTPS-based API that apps can use programmatically request vouchers, check voucher status, and ask to trash vouchers.

Endpoints

The API service for the environment:

• Staging: http://xp-voucher-mgt-stg-sg-v1.sg-s1.cloudhub.io
• Production:

Authentication

Before integrating with the Vouchers Management XP API, need to define the following actors to perform specific operations and to interact to create a secure authorization framework:

• Who is the Frontend application provider?
• Who is in charge of authorizing the end-user to access and perform certain operations?
• What kind of end-user? Customer or client?

After defining the authorization model you will implement, see the Authorization to know the authorization workflow for each business model.

To know the Identity System provided by Edenred, please refer to Edenred Connect for the integration guide.

Basic

The basic of vouchers management composed:

• catalog_ref - basically indicate the voucher service provider

Request Vouchers

URL format: {End point}/catalogs/{catalog_ref}/product_assets/{product_asset_ref}/products/{product_ref}/vouchers/actions/request

Be able to request vouchers, the following parameters for specifying particular catalogs:

• product_asset_ref - provided by Edenred for the request products asset reference
• product_ref - provided by Edenred for the request products reference

Field “distribution_mode” in the request body indicates that does Client need TX to directly manage the distribution.

If manual, TX will not do any distribution.

If auto, TX will do the distribution by provided email address/phone number.

The structure of the response vouchers mainly contains:

• voucher_ref: the redeemed code for the redemption side
• voucher_settlement_ref: it's unique for each voucher for settlement between Edenred and Client
• expiration_date: each voucher will have its own expiration date
• edenred_url + view_code: provided smart voucher link and the view code for the end-user to open the link

2. Trash Vouchers

URL format: {End point}/catalogs/{catalog_ref}/vouchers/actions/trash

Be able to trash by the voucher settlement ref, and support multiple vouchers in one request.

If any one of the vouchers got failed, the rest actions will be rollback.

After the voucher has been trashed the life cycle ends, which means that the voucher cannot be processed anymore.

3. Check Vouchers

URL format: {End point}/catalogs/{catalog_ref}/vouchers/actions/check

Be able to check a list of vouchers' current status and remaining value by the voucher settlement ref.