How to Use the Voucher Module

The Voucher Module allows you to manage vouchers within your system. This module includes three endpoints: Validate Voucher, Redeem Voucher, and Refund Voucher. This guide explains each endpoint, its parameters, and how to use them. The Voucher Module offers three endpoints:

Validate Voucher
Redeem Voucher
Refund Voucher

Validate Voucher

The Validate Voucher endpoint checks whether a voucher code is valid and retrieves details about the voucher, such as the amount and expiration date. This is typically used before allowing a voucher to be redeemed for goods or services. Below, you can see an example of a request and response to this endpoint:

curl --request POST \
     --url https://merchantapi.testewallet.com/api/v1/vouchers/validate \
     --header 'Token: <YOUR_TOKEN>' \
     --header 'X-MerchantId: <YOUR_MERCHANT_ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --data '
      {
        "voucherCode": "123456789",
        "currencyCode": "USD"
      }
    '

{
  "isSuccess": true,
  "message": "Voucher is valid.",
  "statusCode": 200,
  "logIdentifier": "LOG123456789",
  "data": {
    "amount": 30,
    "currencyCode": "USD",
    "isPendingToRedeem": true,
    "fxRates": [
      {
        "fxAmount": 30,
        "fxCurrencyCode": "USD"
      }
    ]
  }
}

Redeem Voucher

The Redeem Voucher endpoint allows you to redeem a voucher, partially or fully. If a voucher is redeemed partially, the remaining balance is returned to the sender. Below, you can see an example of a request and response to this endpoint:

curl --request POST \
     --url https://merchantapi.testewallet.com/api/v1/vouchers/redeem \
     --header 'Token: <YOUR_TOKEN>' \
     --header 'X-MerchantId: <YOUR_MERCHANT_ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --data '
      {
        "voucherCode": "123456789",
        "amount": 30,
        "currencyCode": "USD",
        "merchantReferenceId": "ref123",
        "comments": "Example transaction",
        "redeemUserName": "user_account"
      }
    '

{
  "isSuccess": true,
  "message": "Voucher redeemed successfully.",
  "statusCode": 200,
  "logIdentifier": "LOG987654321",
  "data": {
    "transactionIdentifer": 1234567890
  }
}

Refund Voucher

The Refund Voucher endpoint processes a refund for a voucher. This is typically used when a product or service is returned after purchase, and the value of the voucher needs to be restored to the original sender. Below, you can see an example of a request and response to this endpoint:

curl --request POST \
     --url https://merchantapi.testewallet.com/api/v1/vouchers/refund \
     --header 'Token: <YOUR_TOKEN>' \
     --header 'X-MerchantId: <YOUR_MERCHANT_ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --data '
      {
        "redeemMerchantReferenceId": "ref123",
        "refundAmount": 30,
        "refundCurrencyCode": "USD"
      }
    '

{
  "isSuccess": true,
  "message": "Voucher refunded successfully.",
  "statusCode": 200,
  "logIdentifier": "LOG1122334455",
  "data": {
    "transactionIdentifer": 9876543210
  }
}