This document is intended for use by Tillo partners that wish to connect to the Tillo RESTful Application Program Interface v1 (the API) and exercise the functionality that the API provides. The most common uses of the API are for the purchase and issuance of digital gift codes to customers.

Please note that [Tillo API v2](https://tillo.tech/) is now available and for new integrations v2 should be used over v1. For existing partners, v1 will continue to be supported.

The API is provided as a web service using REST that is accessible only over HTTPS and only from IP addresses that have been added to the Tillo whitelist. In addition, the client system must have been provided credentials for authenticating the initial REST request.

Before beginning the integration development, we recommend contacting your Tillo account manager or via our Service Desk ([https://help.tillo.tech/](https://help.tillo.tech/) or [servicedesk@tillo.io](mailto:servicedesk@tillo.io)) with the IP address(es) that you will be using for development, and also in production, and requesting account set-up. Please provide an email address for your API user - this should be a shared/team address rather than tied to an individual e.g. tillo@yourcompany.com.

Different credentials and REST endpoints will be issued for development and for production.

If you have any technical questions about the API integration, please direct them to [techteam@tillo.io](mailto:techteam@tillo.io). ## Getting Started ### API URLs We have two URLs that you will need to be aware of, one for live and one for sandbox (integration testing). These sites are hosted separately and no data/users are shared between them. * Sandbox/test: [https://sandbox.tillo.dev/api](https://sandbox.tillo.dev/api) * Live: [https://app.tillo.io/api](https://app.tillo.io/api) ### Whitelisting IP Access to the sandbox and production API is restricted to authorised IP addresses only. Please contact and provide the public IP address(es) that your API calls will orginate from. You can have a separate set of IP addresses for the sandbox and live environments. ### Connecting Connecting to the API requires a POST request with the email address and password associated with the API account. An apiToken is returned that will be valid for up to 24 hours, and is needed to be send with other requests.

Note that an apiToken may be invalidated before its expiry date so any subsequent request e.g. to 'createGC' may return error code 060, which should trigger your system to issue another 'connect' request.

A user (email address) can only have one apiToken live at a time. Each time a user issues a 'connect' request their previous apiToken is disgarded - **Please do not issue a 'connect' for every sale**. It is expected that partners integrating to the API will hold this apiToken in a central data store (redis/memcache/database) and share across load-balanced web servers. #### Example Request ``` curl --data-urlencode email=someone@someplace.com --data password=12345678 https://sandbox.tillo.dev/api/connect ``` #### Example Response ```json { "status": "success", "code": "000", "apiToken": "601535d6c05a5b8bb4ff70fa273d819c59a116", "apiTokenExpires": "2016-07-09 05:57:08" } ``` You will be assigned a separate password for your live API account. ### Getting Available Brands To retrieve the brands that have been switched on for the integration partner, a POST request is sent with the apiToken to /api/brands.

Note: Brands that are only available in the GC Pool will have the "denominations" populated with a list of all the supported values. For the rest of the brands the attribute will be empty. #### Example Request ``` curl --data apiToken=601535d6c05a5b8bb4ff70fa273d819c59a116 https://sandbox.tillo.dev/api/brands ``` #### Example Response ```json { "status": "success", "code": "000", "brands": [ { "slug": "amazon", "name": "Amazon", "status": "ENABLED", "currency": "GBP", "discount": "3.00", "transactionTypes": [ "cancelled_digital_issuance", "digital_issuance" ], "deliveryMethods": [ "code", "url" ], "attributes": { "cardImage": "https:\/\/rewardcloud-production.s3.amazonaws.com\/assets\/images\/brands\/vouchers\/330x214\/amazon.jpg", "brandLogoImage": "https:\/\/rewardcloud-production.s3.amazonaws.com\/assets\/images\/brands\/logos\/180x180\/amazon.jpg", "website": "http://www.amazon.co.uk", "brandAbout": "Blurb about brand", "popularBrand": "", "openValueUpper": "1000.00", "openValueLower": "1.00" }, "flashSales": { "live": [], "upcoming": [] } }, { "slug": "laithwaites", "name": "Laithwaite's Wine", "status": "ENABLED", "discount": "10.00", "transactionTypes": [ "digital_issuance" ], "deliveryMethods": [ "code", "url" ], "attributes": { "cardImage": "https:\/\/rewardcloud-sandbox.s3.amazonaws.com\/assets\/images\/brands\/vouchers\/330x214\/laithwaites.jpg", "brandLogoImage": "https:\/\/rewardcloud-sandbox.s3.amazonaws.com\/assets\/images\/brands\/logos\/180x180\/laithwaites.jpg", "brandAbout": "Wine always makes a lovely gift! And who better to choose from than Laithwaite's, the UK's no.1 home delivery wine merchant. Ever since founder Tony Laithwaite drove a van to Bordeaux in 1969, this family-owned firm have been going direct to find those delicious gems you won't find on the big retailers' shelves. Over nearly 50 years, they've built up an award-winning range of 1,400 different wines, beers, spirits and Champagne. Every bottle comes with a 100% money back guarantee \u2013 and their customer service is second to none, with higher scores than any other wine merchant, even beating Amazon and John Lewis too.", "website": "https:\/\/www.laithwaites.co.uk\/" }, "similarBrands": [], "denominations": ["10.00","25.00","50.00"], "flashSales": { "live": [], "upcoming": [] } } ] } ``` #### Transaction Types The transactionTypes in the response determine what transaction(s) the Brand support. ``` +-------------------------------+------------------+ | Transaction Type | API Endpoint | +-------------------------------+------------------+ | digital_issuance | createGC | | cancelled_digital_issuance | cancelGC | | physical_activation | activateGC | | cancelled_physical_activation | cancelActivateGC | | physical_top_up | topupGC | | cancelled_physical_top_up | cancelTopupGC | +-------------------------------+------------------+ ``` #### Error response when calling a transaction type that is not available for the requested brand ```json { "status": "error", "code": "720", "message": "The transaction type is not available for the requested brand" } ``` #### Delivery Methods There are two ways we can deliver gift cards to you. The deliveryMethods in the response determine what format(s) the Brand support. ``` +-----------------+-------------------------------------------------------------------------+ | deliveryMethods | Description | +-----------------+-------------------------------------------------------------------------+ | code | The plain code is returned in the API response | | url | A hosted URL is returned in the API response | +-----------------+-------------------------------------------------------------------------+ ``` #### Error response when requesting a delivery method that is not available for the brand ```json { "status": "error", "code": "713", "message": "You cannot deliver codes via this method for this brand" } ``` #### Redemption Methods The redemptionMethods in the response determine the methods of redemption that a Brand supports. ``` +-------------------+-----------------------------------------------------------------------+ | redemptionMethods | Description | +-------------------+-----------------------------------------------------------------------+ | online | The card can be redeemed online | | instore | The card can be redeemed in-store | | phone | The card can be redeemed over the phone | +-------------------+-----------------------------------------------------------------------+ ``` #### Sales When Tillo has an up-coming or live Flash Sale for a brand (time-limited promotion/increased discount) the details of the Sale will be returned within the 'brands' API response. ### Creating Gift Code Creating a gift code requires a POST request with the original apiToken that is passed back in the connect call to be sent in the response. Also a unique clientRequestID is sent, this is unique for each request and is generated by the integration partners implementation.

Note: All parameters should be submitted as separate POST fields and not placed in the HTTP body. The API does not support passing the parameters as a JSON block. ##### Example Request ``` curl --data apiToken=601535d6c05a5b8bb4ff70fa273d819c59a116 --data brand=amazon --data currency=GBP --data value=10.00 --data clientRequestID=3423423f --data-urlencode additionalParams={} https://sandbox.tillo.dev/api/createGC ``` ##### Example Response ```json { "status": "success", "code": "000", "amount": 10.00, "currencyCode": "GBP", "clientRequestID": "3423423f", "gcClaimCode": "xderfg56G", "gcExpirationDate": "2019-01-05T11:49:41+00:00", "pin": "1234" } ``` #### Serial number and security code Creating gift codes for certain brands will return the default response but also contain a security code and a serial number. The security code is used for redemption purposes while the serial number is needed when performing topups. ##### Example response containing serial number and security code ```json { "status": "success", "code": "000", "amount": 10.00, "currencyCode": "GBP", "clientRequestID": "3423423f", "gcClaimCode": "xderfg56G", "gcExpirationDate": "2019-01-05T11:49:41+00:00", "pin": "5463", "securityCode": "248", "serialNumber": "2040053083" } ``` #### Client Request ID The clientRequestID parameter must be unique as it is used as a primary key to identify sales. Recommended format: * Allowable characters: A-Z, a-z, 0-9, hyphen and underscore. * Minimum length: 8 characters * Maximum length: 32 #### Delivery Method The deliveryMethod parameter determines what you will get back in our API response. It is optional and you may request either **code** or **url**. If you do not supply a delivery method then **code** will be assumed (where it is available) and we will return the raw data in our API response (see examples above). Please note that some brands only supply URLs, these are: * Argos If you request a deliveryMethod of **url** then we shall return a URL in our response. The URL is hosted by Tillo on https://revealyourgift.com. ##### Example Request selecting **url** as the deliveryMethod ``` curl --data apiToken=3987f73d09735943d9bec5e9f6615b9fe23660 --data brand=amazon --data currency=GBP --data value=10.00 --data clientRequestID=64325663 --data deliveryMethod=url --data-urlencode additionalParams={} https://sandbox.tillo.dev/api/createGC ``` ##### Example response containing a URL hosted by Tillo ```json { "status": "success", "code": "000", "amount": 10.00, "currencyCode": "GBP", "clientRequestID": "64325663", "gcURL": "https://sandbox.revealyourgift.com/b7583aa8-5144-4cb9-9ee0-c858ccf46a9b/6d68b125-2e52-48dc-b1ae-faa5c4ef9433" } ``` #### Additional Parameters Additional parameters are required when Tillo are issuing a code to a recipient by email rather than being delivered to them by the Partner. This service is available for an additional charge.

Each brand has a different email template that has been signed off by the brand.

The different templates support a subset of the fields listed below e.g. Brand A may not require a message. For this reason, it is recommended that you pass through all of the parameters regardless of the brand if Reward Cloud are sending the email. ```json { "orderSender": "Sarah Smith", "orderConfirmation": "davidsmith@email.com", "toName": "David Smith", "fromName": "Sarah Smith", "message": "Happy Birthday David, enjoy your gift card", "subject": "Here is your e-gift card", "headerImage": "", "headerUrl": "", "supportText": "", "supportUrl": "", "emailFromAddress": "noreply@reply.cloud", "emailFromName": "Your Organisation" } ``` Note: If you wish to use a 'from' address other than you must advise so that we can enable your domain on our mail service. You will need to update your mail server with DKIM and SPF DNS records to authorise our mail server to send on your behalf. ### Canceling Gift Code To cancel, a POST request is sent. #### Example Request ``` curl --data apiToken=601535d6c05a5b8bb4ff70fa273d819c59a116 --data clientRequestID=njad98 --data originalClientRequestID=3423423f --data brand=amazon --data gcClaimCode=xderfg56G https://sandbox.tillo.dev/api/cancelGC ``` #### Example Response ```json { "status": "success", "code": "000" } ``` Note: Cancellations for some SVS brands also requires the pin to be passed in as gcPin. ### Reversing a Transaction You can attempt to reverse a transaction within a short period of time after creating a code, 30 minutes (15 minutes for Amazon). You do not need to know the gcClaimCode or gcPIN but you do need to pass through the original parameters using a new clientRequestID. Only brands that support cancellations support reversing a transaction. #### Example Request ``` curl --data apiToken=601535d6c05a5b8bb4ff70fa273d819c59a116 --data clientRequestID=rev1234 --data originalClientRequestID=orig1234 --data brand=amazon --data value=5.00 --currency=GBP https://sandbox.tillo.dev/api/reverseGC ``` #### Example Response ```json { "status": "success", "code": "000" } ``` ### Checking available denominations While the 'brands' API response will return a list of denominations generally available for each fixed-denomination brand, for those brands in the GC Pool you are also able to check live stock levels with the 'checkStockGC' call. This applies to the following brands: * Adventure Card by Geronigo * asos * Cineworld Adult (2D) * Cineworld Adult (Premium) * Cineworld Child (2D) * Cornerstone * Currys PC World * Fabyouless * Feelunique * Global Hotel Card * Jack Wills * Just Eat * Laithwaite's Wine * M&S * National Express * NOW TV Entertainment * NOW TV Kids * NOW TV Sky Cinema * NOW TV Sky Sports * Odeon Adult (Inside M25) * Odeon Adult (Outside M25) * Odeon Child (Inside M25) * Odeon Child (Outside M25) * Racingbreaks.com * Spabreaks.com * thriva * TodayTix * TripGift * wagamama #### Example Response ```json { "status": "success", "code": "000", "brand": "string", "denominations": [ { "denomination": "10.00", "total_quantity_codes": "GOOD" }, { "denomination": "50.00", "total_quantity_codes": "OUT" } ] } ``` The total_quantity_codes will return an indicator based on our re-order levels. The valid values that could be returned for each denomination are GOOD or OUT.

### Status Codes A successful request will have a status code 000 send back in response. Anything other than 000 will mean there has been some form of error, this could be an authentication error (for example). The API will also attempt to send the correct HTTP Response Code, so for example - a successfull request will have be a 200.

Tillo Error Code	HTTP response code	Description	Example Error Message
000	200	Success
060	400 or 401	Invalid API Token	API token [%s] not valid or expired from IP [%s]
070	400	Missing Parameters	Missing API token from [%s]
071	400	Missing Additional Parameters
072	400	Invalid Brand - The brand slug is incorrect, or has not been enabled on your account. Check the /brands API request, or log in to the Partner Hub and navigate to Partner overview to see what has been enabled.	Partner [%s] does not have permission to access the brand [%s]
100	422	Data	Unable to locate the issued card
210	401	Connection from an IP address that has not been put on our white list.	Illegal attempt to access Restful API for user [%s] from [%s]
433	403	Validation Errors
434	403	Access Denied
435	401	Unauthorised
600	500	Internal	Internal error
601	401	Credentials	Authentication failed for email [%s]
602	503	System unavailable due to maintenance	Tillo is currently being upgraded.
603	500	External – Issue communicating with the Processor
610	403	Insufficient Balance	Insufficient balance on account
701	503	Partner not API	Partner does not have access to API
702	400	Partner not configured correctly
703	400	Invalid currency requested	Invalid currency. The provided currency is invalid.
704	400	Invalid value requested
705	400	Value requested is outside of min/max limits
706	400	Brand disabled or unavailable	The brand xxxxx is inactive.
707	400	Invalid JSON
708	500	Request cannot be replayed	The original request failed. Please re-submit with a new clientRequestID
709	404	Partner Brand Relationship not configured correctly	We couldn't find a record for a relationship between yourself and brand
710	400	Cancel GC Not Found
711	400	Cancel GC Not Active	Card no longer active
712	404	Incorrect Delivery Method	The requested delivery method was not found
713	400	Unavailable Delivery Method	You cannot deliver codes via this method for this brand
714	400	Missing Delivery Method	You did not supply a deliveryMethod and we were unable to fallback to the default of code
715	503	URL Hosting Service is unavailable	The URL hosting service is currently unavailable
716	400	Template Not Found	The requested template was not found
719	422	Unsupported Transaction Type by partner	The transaction type is not supported by the partner
720	422	Unsupported Transaction Type for brand	The transaction type is not available for the requested brand
721	422	Currency Not Found	The requested currency was not found
722	400	Currency Not Supplied	You did not supply a currency
723	422	Currency Not Supported	The requested currency is not supported by this brand
724	422	Sale Not Found	The sale could not be found
725	500	Denomination not in stock	Denomination 5.00 is currently not in stock for Brand [brand]
434	429	Too Many Attempts	Too many attempts

### Maintenance Mode System maintenance is normally performed between 4am and 6am. You will receive a notification ahead of planned maintenance/upgrades.

During a system upgrade the API will respond to all requests with a status code of 602 (HTTP response code 503). #### Response when in maintenance mode ```json { "status": "error", "code": 602, "message": "Tillo is currently being upgraded." } ```

200Successful response

401Authentication failure

503Service unavailable