Vouchers XP API

Introduction

Edenred's Vouchers XP API has been purposed to use by POS Merchants/ e commerce merchants. This Powerful Mulesoft based REST API allows the Merchant to connect and immediately burn the consumer presented vouchers issued by Edenred.

Lifecycle

1. GetVoucher
2. Authorize and Capture Voucher (Redeem Voucher)
3. Refund a captured voucher
4. Authorization & Capture manual
5. Cancel authorization
6. Capture voucher (After Authorization)

1. GetVoucher(Query voucher details)

If Merchant wants to know the status of a Voucher or Balance of a Voucher, they can make this API call to get the voucher information.

URL format: {{your endpoint}}/vouchers/{{product_class}}-{{voucher_id}}
Example:
Singapore UAT URL : http://xp-voucher-stg-sg-v1.sg-s1.cloudhub.io/api/vouchers/ETX_001-OC570985876

URL parameters:

https://anypoint.mulesoft.com/exchange/portals/edenred-corporate/63c4959e-234c-4599-a53f-113f6da4b148/vouchers-xp-api/minor/2.0/console/method/%232682/

Sample URL:
Method Type: GET
http://xp-voucher-dev-sg-v1.sg-s1.cloudhub.io/api/vouchers/ETX_001-UG8248094446

Response Message

{
"data": {
  "product_code": "ProdPin12",
  "product_label": "PB-jibei",
  "remaining_value": 4,
  "expiration_date": "2020-02-29 23:59:59"
},
"meta": {
  "status": "succeeded"
},
"links": [
  {
"rel": "authorize",
        "href": "/transactions"
      }
    ]
  }

2. Authorize and Capture Voucher (Redeem Voucher)

Merchant should use this API call for Voucher redemptions at POS/WEB. If there is no pre-authorization required, then this API will use the “capture-mode” “auto” by default.

URL format: {{End point}}/transactions
Example: http://xp-voucher-stg-sg-v1.sg-s1.cloudhub.io/transactions

Singapore UAT URL: http://xp-voucher-stg-sg-v1.sg-s1.cloudhub.io/api/transactions?return_vouchers_info=true

Field “capture_mode” in the request body Indicates that how Merchant want to process the voucher redemption. Two values provided.

Default value: auto
auto: indicates transaction is sent for authorization, and if approved, automatically captured.

Manual: indicates transaction is sent for authorization only and there will be another "capture" call after this capture mode "Manual".

Below is the sample raw request with the capture mode “auto”.

Request Message

  {
    "capture_mode": "auto",
    "currency" : "SGD",
    "vouchers": [
        {
            "value":100,
            "product_class": "ETX_001",
            "ref": "OC4704835893"
        }
    ]
}

Below is a sample successful redemption response message. Voucher is successfully redeemed.

Response Message

    {
    "data": {
        "authorization_id": "0000100000000000013220201109002406111",
        "capture_id": "0000100000000000013220201109002406112",
        "mid": "000000000000132",
        "captured_amount": 100,
        "authorized_amount": 100,
        "vouchers": [
            {
                "product_label": "$10 FairPrice Voucher",
                "product_code": "FAIPDDMMYY00TEST03",
                "remaining_value": 900,
                "expiration_date": "2021-06-30 23:59:59"
            }
        ]
    },
    "meta": {
        "status": "succeeded"
    },
    "links": [
        {
            "rel": "refund",
            "href": "/api/transactions/edr-0000100000000000013220201109002406112/actions/refund"
        }
    ]
}

3. Refund a captured voucher

After performing a capture transaction, if Merchant wants to reverse the capture, use this Refund API call.

URL format: {{End point}}/transactions/{{transaction_ref}}/actions/refund
Example:
Singapore UAT URL:
http://xp-voucher-stg-sg-v1.sg-s1.cloudhub.io/api/transactions/edr-0000100000000000013220201109002406112/actions/refund

Request Message

    {
    "vouchers": [
        {
            "product_class": "ETX_001",
            "ref": "OC4704835893"
        }
    ]
}

Response Message

    {
    "data": {
        "refund_id": "0000100000000000013220201109002406113",
        "mid": "000000000000132",
        "refunded_amount": 1
    },
    "meta": {
        "status": "succeeded"
    }
}

4. Authorization & Capture manual

This API can be used to pre authorize any vouchers in TX. Merchant should pass the “capture mode” value as “manual”. To complete the transaction
This section explains how to raise a pre authorization request.

URL format: {{End point}}/transactions
Example: http:xp-voucher-stg-sg-v1.sg-s1.cloudhub.io/transactions

Singapore UAT URL:http://xp-voucher-stg-sg-v1.sg-s1.cloudhub.io/api/transactions?return_vouchers_info=true

Capture Mode: Manual, indicates that the transaction has been initiated for authorization only, and will be captured with another "Capture" API call.

Use “manual” as the input value of “capture_mode” to raise an authorization request.

All Authorized transactions should be followed with a capture call for the redemption transaction completion. If authorization expires, then Merchant needs to repeat a new Authorization call followed with a Capture call.

Authorization Capture Mode: Manual
Request Message

    {
    "capture_mode": "manual",
    "currency" : "SGD",
    "vouchers": [
        {
            "value":200,
            "product_class": "ETX_001",
            "ref": "OC4704835893"
        }
    ]
}

Response Message

    {
    "data": {
        "authorization_id": "0000100000000000013220201109002406114",
        "mid": "000000000000132",
        "authorized_amount": 200,
        "vouchers": [
            {
                "product_label": "$10 FairPrice Voucher",
                "product_code": "FAIPDDMMYY00TEST03",
                "remaining_value": "701",
                "expiration_date": "2021-06-30 23:59:59"
            }
        ]
    },
    "meta": {
        "status": "succeeded"
    },
    "links": [
        {
            "rel": "cancel",
            "href": "/api/transactions/edr-0000100000000000013220201109002406114/actions/cancel"
        },
        {
            "rel": "capture",
            "href": "/api/transactions/edr-0000100000000000013220201109002406114/actions/capture"
        }
    ]
}

5. Cancel authorization

After making an authorization success call, if Merchant decides to cancel the authorization, then make this call to Ticketxpress.

URL format: {{End point}}/transactions/{{transaction_ref}}/actions/cancel

Example:
Singapore UAT URL:
http://xp-voucher-stg-sg-v1.sg-s1.cloudhub.io/api/transactions/edr-0000100000000000013220201109002406114/actions/cancel?return_vouchers_info=true

Request Message

{
    "vouchers": [
        {
            "product_class": "ETX_001",
            "ref": "OC4704835893"
        }
    ]
}

Response Message

    {
    "data": {
      "cancellation_id": "0000100000000000000920191128002230851",
      "mid": "000000000000009"
    },
    "meta": {
      "status": "succeeded"
    }
  }

6.Capture voucher (After Authorization)

Capture a voucher after authorization. Only for available Product_class. Only lists of 1 voucher are implemented in this version.

Note: Use the Capture Transaction URL received in the Authorization (capture mode: "manual") response - e.g "/api/transactions/edr-0000100000000000013520200703001875452/actions/capture"

URL format: {{End point}}/transactions/{{transaction_ref}}/actions/capture
Example:
Singapore UAT URL: http://xp-voucher-stg-sg-v1.sg-s1.cloudhub.io/api/transactions/edr-0000100000000000013220201109002406114/actions/capture?return_vouchers_info=True

Request Message

  {
    "vouchers": [
        {
            "value":200,
            "product_class": "ETX_001",
            "ref": "OC4704835893"
        }
    ]
}

Response Message

{
    "data": {
        "capture_id": "0000100000000000013220201109002406116",
        "mid": "000000000000132",
        "captured_amount": 200,
        "vouchers": [
            {
                "product_label": "$10 FairPrice Voucher",
                "product_code": "FAIPDDMMYY00TEST03",
                "remaining_value": 701,
                "expiration_date": "2021-06-30 23:59:59"
            }
        ]
    },
    "meta": {
        "status": "succeeded"
    },
    "links": {
        "rel": "refund",
        "href": "/api/transactions/edr-0000100000000000013220201109002406116/actions/refund"
    }
}