i-movo Voucher APIs

The following API details describe how you can generate or cancel a Secure Digital Voucher from the i-movo Voucher Service. The documentation contain details about the API request POST parameters and the possible responses from the i-movo Voucher Service endpoints.

Request a Voucher API

To request a Secure Digital Voucher from the i-movo Voucher Service a POST request is required containing: campaignCode , customerReference, and the value of the voucher you would like to generate.

Upon successful submission of the request the API response will contain the voucher number or a link to an i-movo web voucher with barcode, help and a storefinder. The voucher can also be delivered automatically by the i-movo Voucher Service, if your voucher campaign is set up to do so.

Request

POST https://core-uat-api.azurewebsites.net/VoucherRequest/Request

Request Header

X-API-KEY - Your API Subscription Key must be specified in the header for all requests. This key will be supplied to you securely by PGP once we receive a public PGP key from you. (string / Required)

Request Body

The request body must contain:

campaignCode - The campaign from which the voucher is being requested. The code will have been issued by i-movo. (string / Required)
customerReference - Your customer reference for this request. Where i-movo is delivering the voucher, this needs to contain e.g. the customer’s mobile or email address. (string / Required)
value - For cash vouchers only, this parameter allows a client to set the value of the voucher being generated up to an agreed maximum. (decimal / Optional)

https://core-uat-api.azurewebsites.net/VoucherRequest/Request?campaignCode=THINK&customerReference=07123456789&value=20.00

Response: Successful

{
   "voucherCode": "3721902693",
   "balance": 20.00,
   "expiryDate": 2020-06-23T23:59:59.9999999,
   "message": "£20.00 CashOut voucher valid at any PayPoint to 23-Jun: http://imovo.org/3721902693TY OR shop: use CASHOUT > I-MOVO > 3721902693 > ENTER Help? 0800 310 0000",
   "successfulRequest": true
}

Response: Error

{
   "errorMessages": 
   [
      "Unable to create voucher: the campaign code submitted does not exist"
   ],
   "successfulRequest": false
}

Response: Validation Error

{
   "errorMessages": 
   [
      "Unable to create voucher: the value entered is invalid"
   ],
   "successfulRequest": false
}

Cancel a Voucher API

To instantly cancel a Secure Digital Voucher generated by the i-movo Voucher Service, a simple POST request is required containing the voucher code that you wish to cancel.

A synchronous response containing the result of the request is returned and if successful the Secure Digital Voucher will be flagged as cancelled.