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.00Response: 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}
Request a Voucher API with Id Check
Requesting a Secure Digital Voucher from i-movo whereby the voucher displays the customer’s name, address and post code under the barcode such that the staff at the shop can check those details against the documentation presented by the customer.
The voucher number only can be returned, or a link to a web page hosted by i-movo displaying the barcode, voucher details, help and a storefinder. The voucher can be delivered automatically by the i-movo system if required, by SMS or email.
Request
POST https://core-uat-api.azurewebsites.net/VoucherRequest/RequestVoucherWithId
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)
DeliveryRecipient - Where PayPoint are delivering the voucher, this field is used to supply the email address or mobile number of the recipient (string / Optional)
VoucherValue - For cash and energy vouchers only, this parameter allows a client to set the value of the voucher being generated (up to an agreed maximum) (decimal / Optional)
CustomerName - The customer’s full name that will appear on vouchers for retailers to check the customer's ID( string / Required)
Address - The customers address that will appear on vouchers for retailers to check the customer's ID (string / Required)
PostCode - The customer’s post code that will appear on vouchers for retailers to check the customer's ID (string / Required)
{"CampaignCode":"CAMP01","VoucherValue": 1.00,"CustomerReference": "09283-765748","DeliveryRecipient": Johnsmith@email.com,"CustomerName": "John Smith","Address": "19 Test Street, Welwyn Garden City","Postcode": "AL1 0BS"}
Response: Successful
{
"voucherCode": "648924429737",
"balance": 1.00,
"expiryDate": "2024-08-09T23:59:59.999",
"message": "Here is your FREE £5 off voucher: voucher 648924429737 Expires on 09-Aug-24. See here for barcode, storefinder, T&Cs: imovo.org/?id=GC-QGhDENUu4",
"successfulRequest": true
}Response: Error Examples
{
"errorMessages": [
"InvalidCampaign"
],
"successfulRequest": false
}{"errorMessages": ["ClientWeeklyValueLimitReached"],"successfulRequest": false}
{
"errorMessages": [
"address is required",
"post code is required",
"customer name is required"
],
"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.
Request
POST https://core-uat-api.azurewebsites.net/Voucher/CancelVoucher
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:
voucherCode - The voucher code to be cancelled. (string / Required)
https://core-uat-api.azurewebsites.net/Voucher/CancelVoucher?voucherCode=2193785990Response: Successful
{"successfulRequest": true}
Response: Error (Not Found)
{"errorMessages": ["Voucher not found"],"successfulRequest": false}
Response: Error
{"errorMessages": ["Voucher is already cancelled or redeemed"],"successfulRequest": false}