Gyft Developer Docs

The Gyft API and SDK empowers website and mobile app developers to use digital gift cards to reward employees, create incentivization, and increase loyalty and sales. Using the Gyft API and SDK, you can easily create and offer your own end-to-end digital gift card program.

img-docs-header2@2x

Getting Started

Enroll and Create Your Application

Register a Gyft Developer account on Gyft Corporate.

In the Developer Portal, create your application. Provide the details required to register your application and issue Gyft API credentials, including:

  • The Application Name for which Sandbox (and later Production) credentials will be issued.
  • A brief Description of your application, and the planned digital gift card experience within your application.

On submission of these details, you will be issued Gyft API credentials for the Sandbox environment.

Test the Gyft API Using I/O Docs

Navigate through the Gyft API offering using I/O Docs.

Use your Gyft API Sandbox credentials to make API requests and see the responses.

Authentication

Request Authentication & Security

Each request requires your  “api_key” and a “sig” parameter to be submitted. These parameters are defined as follows:

  • The “api_key” parameter will be your Gyft API Key.
  • The “sig” parameter is built up from “api_key” + “api_secret” + “timestamp” that is SHA-256 encrypted and then Hex encoded.

REQUEST URL STRUCTURE

[Base URL][API Call]?api_key=[api_key]&sig=[Hex(SHA-256([api_key] + [api_secret] + [timestamp]))]

REQUEST PARAMETERS

  • Base URL (Sandbox) = https://apitest.gyft.com/mashery
  • Base URL (Production) = https://api.gyft.com/mashery
  • API Call = The specific API call you want to make, e.g. /v1/reseller/account or /v1/partner/purchase/gift_card_direct
  • api_key = Your Gyft API Sandbox or Production Key
  • api_secret = Your associated Gyft API Sandbox or Production Secret
  • timestamp = The difference, measured in seconds, between the current time and midnight on January 1, 1970 UTC

Request Signing

Java

The following code snippet provides an example of submitting a Gyft API request and printing the JSON response, using the Java programming language.

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.security.MessageDigest;

public class MasheryTestMain {
  public static void main(String... args) throws Exception {
    String apiKey = args[0];
    String apiSecret = args[1];
    String timestamp = Long.toString(
      Math.round(System.currentTimeMillis() / 1000.0)
    );
    String stringToSign = apiKey + apiSecret + timestamp;
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(stringToSign.getBytes("UTF-8"));
    String signature = hexEncode(hash);
    String fullURLString = String.format(
      "https://apitest.gyft.com/mashery/v1/reseller/account?api_key=%s&sig=%s",
      apiKey,
      signature
    );
    URL url = new URL(fullURLString);
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestProperty("x-sig-timestamp", timestamp);
    BufferedReader br = new BufferedReader(
      new InputStreamReader((conn.getInputStream()))
    );
    String output;
    while ((output = br.readLine()) != null) {
      System.out.println(output);
    }
    conn.disconnect();
  }
  private static String hexEncode(final byte[] bytes) {
    StringBuilder hexEncode = new StringBuilder();
    for (int i = 0; i < bytes.length; i++) {
      String hex = Integer.toHexString(0xFF & bytes[i]);
      if (hex.length() == 1) hexEncode.append('0');
      hexEncode.append(hex);
    }
    return hexEncode.toString();
  }
}

PHP

The following code snippet provides an example of submitting a Gyft API request and printing the JSON response, using the PHP programming language.

<?php
$apiKey = $argv[1];
$apiSecret = $argv[2];
$timestamp = time();
$stringToSign = $apiKey . $apiSecret . $timestamp;
$hash = hash('sha256', $stringToSign, true);
$signature = bin2hex($hash);
$fullURLString = sprintf(
  'https://apitest.gyft.com/mashery/v1/reseller/account?api_key=%s&sig=%s',
$apiKey,
$signature
);
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $fullURLString);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('x-sig-timestamp: '.$timestamp));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
echo curl_exec($curl)."\n";
?>

Python

The following code snippet provides an example of submitting a Gyft API request and printing the JSON response, using the Python programming language.

import sys, httplib, hashlib, time

apiKey = sys.argv[1]
apiSecret = sys.argv[2]
timestamp = str(long(round(time.time())))
stringToSign = apiKey + apiSecret + timestamp
signature =  hashlib.sha256(stringToSign).hexdigest()
host = "apitest.gyft.com"
path = "/mashery/v1/reseller/account?api_key=%s&sig=%s" % (apiKey, signature)
conn = httplib.HTTPSConnection(host)
conn.putrequest("GET", path)
conn.putheader("x-sig-timestamp", timestamp)
conn.endheaders()
response = conn.getresponse()
data = response.read()
print data
conn.close()

Ruby

The following code snippet provides an example of submitting a Gyft API request and printing the JSON response, using the Ruby programming language.

require 'digest'
require 'net/http'

apiKey = ARGV[0]
apiSecret = ARGV[1]
timestamp = Time.now.getutc.to_i.to_s
stringToSign = apiKey + apiSecret + timestamp
sha256 = Digest::SHA256.new
signature = sha256.hexdigest(stringToSign)
fullURLString = "https://apitest.gyft.com/mashery/v1/reseller/account?api_key=%s&sig=%s" % [apiKey, signature]
uri = URI(fullURLString)
req = Net::HTTP::Get.new(uri)
req['x-sig-timestamp'] = timestamp
res = Net::HTTP.start(uri.hostname, uri.port) {|http|
  http.request(req)
}
puts res.body

Node.js

The following code snippet provides an example of submitting a Gyft API request and printing the JSON response, using the Node.js programming language.

var apiKey = process.argv[2];
var apiSecret = process.argv[3];
var timeStamp = Math.round(new Date().getTime() / 1000).toString();
var stringToSign = apiKey + apiSecret + timeStamp;
var sha256 = require('crypto').createHash('sha256');
var signature = sha256.update(stringToSign).digest('hex');
var http = require('http');
http.get(
  {
    hostname: 'apitest.gyft.com', 
    port: 443, 
    method: 'GET',
    path: '/mashery/v1/reseller/account?api_key=' + apiKey + '&sig=' + signature, 
    headers: {'x-sig-timestamp': timeStamp}
  },
  function(res) {
    res.on('data',
      function(chunk) {
        console.log(chunk.toString());
      }
    )
  }
);

C#

The following code snippet provides an example of submitting a Gyft API request and printing the JSON response, using the C# programming language.

using System;
using System.IO;
using System.Net;
using System.Text;
using System.Security.Cryptography;

namespace MasheryTestMain
{
  class MainClass
  {
    public static void Main(string[] args)
    {
      string apiKey = args[0];
      string apiSecret = args[1];
      TimeSpan timeStan = DateTime.UtcNow - new DateTime(1970, 1, 1);
      string timestamp = ((int)timeStan.TotalSeconds).ToString();
      string stringToSign = apiKey + apiSecret + timestamp;
      SHA256 sha256 = SHA256Managed.Create();
      byte[] messageBytes = Encoding.UTF8.GetBytes(stringToSign);
      byte[] hash = sha256.ComputeHash(messageBytes);
      string signature = HexEncode(hash);
      string fullURLString = String.Format(
        "https://apitest.gyft.com/mashery/v1/reseller/account?api_key={0}&sig={1}",
        apiKey,
        signature
      );
      HttpWebRequest req = WebRequest.Create(fullURLString) as HttpWebRequest;
      req.Headers.Add("x-sig-timestamp", timestamp);
      string output = null;
      using (HttpWebResponse res = req.GetResponse() as HttpWebResponse)
      {
        StreamReader reader = new StreamReader(res.GetResponseStream());
        output = reader.ReadToEnd();
      }
      Console.WriteLine(output);
    }
    private static string HexEncode(byte[] bytes)
    {
      StringBuilder hexEncode = new StringBuilder();
      for (int i = 0; i < bytes.Length; i++)
        hexEncode.Append(bytes[i].ToString("X2"));
      return hexEncode.ToString().ToLower();
    }
  }
}

Endpoints

Health Check

The Health Check API returns a 200 OK response code if the Gyft API is available.

GET /v1/health/check

Expected Response Status

200 OK

My Account Details

The My Account Details API returns details of your Gyft API application, including Application Name and the current balance of the application.

GET /reseller/account

Request Parameters

None. This API Call only requires that an authenticated request be submitted.

Response Parameters

  • id: Your Gyft API application ID.
  • status: The status of your application, including:
    • 0 = Active
    • 1 = Inactive
    • 2 = Blocked
    • 3 = Requested
  • application_name: The Application Name that you submitted when you created your application.
  • usd_exchange_rate: This will always be USD and will therefore always return 1.
  • balance: The current pre-funded balance remaining in your application’s account.
  • balance_updated_when: Timestamp in UTC of the last update to your application’s balance.

Request URL

https://apitest.gyft.com/mashery/v1/reseller/account

Sample Response

{
    "id": "29849-2323-2312-31",
    "status": 0,
    "application_name": "My Test App",
    "usd_exchange_rate": "1.0",
    "balance": "200.00",
    "balance_updated_when": "89899091"
}

List Merchants

The List Merchants API returns a list of all merchants (i.e. retailers, brands) that are available in Gyft’s catalog.

You can manage the scope of merchant content to display in your application using the merchant-specific IDs returned in this response.

Certain merchants require that your application’s user experience be submitted for review and approval prior to including their content in your application. Gyft’s Biz Team will work with you to coordinate this process once you are ready to move your integration into Production.

GET /reseller/merchants

Request Parameters

None. This API Call only requires that an authenticated request be submitted.

Response Parameters

  • id: The unique id of the merchant.
  • name: The display name of the merchant.
  • card_name: The display name the merchant’s gift card, optionally specified by the merchant. When the card_name is set by the merchant, then this should be used as the display name in your application from the point of choosing a gift card denomination onwards.
  • description: A short description of the merchant.
  • long_description: A long description of the merchant. This will be returned in HTML format.
  • country_code: The country in which the merchant is available for sale. This will always be US for the Gyft API.
  • homepage_label: A label that can be applied as a mask of the merchant’s website URL, if desired.
  • homepage_url: The merchant’s website URL.
  • min_card_value: The lowest denomination available for purchase for the merchant.
  • max_card_value: The highest denomination available for purchase for the merchant.
  • icon_url: The URL for the merchant’s logo image. The highest resolution to expect for this image is 150×150 pixels.
  • cover_image_url_hd: The URL for the merchant’s card cover image. The highest resolution to expect for this image is 564×370 pixels.
  • legal_disclaimer_html: The merchant’s terms and conditions, which must be displayed leading up to purchase of the gift card.
  • shop_cards: All of the denominations available for purchase for the merchant.
  • categories: The categories that the merchant is included in.

Request URL

https://apitest.gyft.com/mashery/v1/reseller/merchants

Sample Response

{
    "id": "22",
    "name": "Test Merchant", 
    "card_name": "Test Merchant Gift Card",
    "description": "A short description about Test Merchant.",
    "long_description": "<p>A long description about Test Merchant. The 
            very best merchant for all shopping. This description is returned 
            in HTML format.</p>",
    "country_code": "US",
    "homepage_label": "Go to Test Merchant website",
    "homepage_url": "https://testmerchantwebsite.com",
    "min_card_value": 25,
    "max_card_value": 50,
    "icon_url": "http://....png"
    "cover_image_url_hd": "http://....png",
    "legal_disclaimer_html":"Merchant terms and conditions"
}

List Shop Cards

The List Shop Cards API returns a list of all merchant denominations that are available for purchase via the Gyft API.

You can manage the range of denominations available for purchase in your application using the Shop Card IDs returned in this response.

GET /reseller/shop_cards

Request Parameters

None. This API Call only requires that an authenticated request be submitted.

Response Parameters

  • id: The unique id of the shop card, which is a required parameter for the Purchase Gift Card API Call.
  • merchant_id: The id of the merchant to which the shop card belongs (e.g. Test Merchant will be associated to shop cards for each available denomination – $5, 10, 15, 20. There will therefore be 4 Shop Card IDs associated to Merchant ID = 22.).
  • name: The display name of the merchant.
  • long_description: A long description of the merchant. This will be returned in HTML format.
  • card_currency_code: The currency of the opening balance. This will always be USD for the Gyft API.
  • opening_balance: The USD value of the gift card denomination when purchased.
  • merchant_icon_image_url: The URL for the merchant’s logo image. The highest resolution to expect for this image is 150×150 pixels.
  • cover_image_url_hd: The URL for the merchant’s card cover image. The highest resolution to expect for this image is 564×370 pixels.

Request URL

https://apitest.gyft.com/mashery/v1/reseller/shop_cards

Sample Response

{
    "id": "220",
    "merchant_id": "22",
    "merchant_name": "Test Merchant", 
    "long_description": "<p>A long description about Test Merchant. The 
            very best merchant for all shopping. This description is returned 
            in HTML format.</p>",
    "card_currency_code": "USD", 
    "opening_balance": 10,
    "merchant_card_template_id": 22, 
    "cover_image_url_hd": "http://....png", 
    "merchant_icon_image_url_hd": "http://....png"
}

List Categories

The List Categories API returns a list of all categories that are available in Gyft’s catalog.

Merchants can be grouped by category in your application, if desired. The categories associated to each merchant are detailed in the List Merchants API response.

GET /reseller/categories

Request Parameters

None. This API Call only requires that an authenticated request be submitted.

Response Parameters

  • id: The unique id of the category.
  • name: The display name of the category.

Request URL

https://apitest.gyft.com/mashery/v1/reseller/categories

Sample Response

{
    "id": "3",
    "name": "Department Stores", 
}

List All Transactions

The List All Transactions API returns a list of all transactions generated from your application’s Gyft API integration. The following API Calls will generate transactions for your application:

  • Purchase Gift Card
  • Refund Specific Transaction

Adding balance to your application’s account will also generate a transaction that will be returned in this response.

GET /reseller/transactions

Request Parameters

None. This API Call only requires that an authenticated request be submitted.

Response Parameters

  • id: The unique id for a specific transaction. This ID is the required parameter for the View Specific Transaction and Refund Specific Transaction API Calls. This ID would also be required to handle customer support issues.
  • type: The type of transaction, including:
    • 0 = Account Balance Top Up
    • 1 = Purchase Gift Card
    • 2 = Refund Transaction
  • amountThe USD value of the transaction.
  • transaction_reference: Your unique reference for the transaction. This is often used to enable easy search for a particular transaction in your back office or by your support teams.
  • created_when: Timestamp in UTC of when this transaction was generated.

Request URL

https://apitest.gyft.com/mashery/v1/reseller/transactions

Sample Response

{
    "id": 22000,
    "type": 1,
    "amount": -10.00,
    "transaction_reference": "29849-2323-2312-31",
    "notes": "Test purchase using the Gyft API!",
    "created_when": 1428356249000
 }

List Recent Transactions

The List Recent Transactions API returns a limited list of the most recent set of transactions generated by your application’s Gyft API integration.

GET /reseller/transactions/last/:number_of_records

Request Parameters

  • number_of_records:  The number (int) of transactions to return starting backwards from the last transaction.

Response Parameters

  • id: The unique id for a specific transaction.
  • type: The type of transaction, including:
    • 0 = Account Balance Top Up
    • 1 = Purchase Gift Card
    • 2 = Refund Transaction
  • amountThe USD value of the transaction.
  • created_when: Timestamp in UTC of when this transaction was generated.

Request URL

https://apitest.gyft.com/mashery/v1/reseller/transactions/last/2

Sample Response

{
    "id": 22011,
    "type": 1,
    "amount": -10.00,
    "created_when": 1428356249001
 },{
    "id": 22010,
    "type": 1,
    "amount": -5.00,
    "created_when": 1428356249000
 }

List Initial Transactions

The List Initial Transactions API returns a limited list of the initial set of transactions generated by your application’s Gyft API integration.

GET /reseller/transactions/first/:number_of_records

Request Parameters

  • number_of_records:  The number (int) of transactions to return starting from the first transaction.

Response Parameters

  • id: The unique id for a specific transaction.
  • type: The type of transaction, including:
    • 0 = Account Balance Top Up
    • 1 = Purchase Gift Card
    • 2 = Refund Transaction
  • amountThe USD value of the transaction.
  • created_when: Timestamp in UTC of when this transaction was generated.

Request URL

https://apitest.gyft.com/mashery/v1/reseller/transactions/first/2

Sample Response

{
    "id": 22000,
    "type": 0,
    "amount": 100.00,
    "created_when": 1428356249000
 },{
    "id": 22001,
    "type": 1,
    "amount": -5.00,
    "created_when": 1428356249001
 }

View Specific Transaction

The View Specific Transaction API returns the all relevant details for a specific transaction generated by your application’s Gyft API integration.

GET /reseller/transaction/:id

Request Parameters

  • id: The unique id for the specific transaction for which the full details are required.

Response Parameters

  • id: The unique id for the requested transaction.
  • transaction_notes: An optional field that may have been populated with by the partner to associate extra information to the transaction.
  • merchant_name: The display name of the associated merchant.
  • amount: The USD value of the requested transaction.
  • delivered_to: The recipient email address associated to the requested transaction.
  • auto_delivered: This will always be “Y”.
  • revealed: This indicates whether or not the recipient has viewed the gift card details.
  • gift_status: Indicates the delivery and recipient usage status of the gift card, including:
    • 0 = Pending
    • 1 = Sent
    • 2 = Received
    • 3 = Spent (added manual transaction through Gyft app and balance > $0)
    • 4 = Depleted (current_balance = $0)
    • 5 = Incomplete (order origination status, precedes Pending)
    • 6 = Void
    • 7 = ClickedLink (not applicable)
    • 8 = PartialError (error encountered on text/email delivery)
    • 9 = Error (all other errors outside of delivery)
  • card_status: Indicates the status of the gift card itself, including:
    • 0 = Active
    • 1 = Gifted
    • 2 = Expired
    • 3 = Depleted
    • 4 = Archived
    • 5 = Refunded
  • opening_balance: The USD value of the gift card denomination when purchased.
  • current_balance: The USD value of the balance currently remaining on the gift card.
  • transaction_created: Timestamp in UTC of when this transaction was generated.
  • user_created: Timestamp in UTC of when the associated recipient’s Gyft user account was created.

Request URL

https://apitest.gyft.com/mashery/v1/reseller/transaction/22010

Sample Response

{
    "id": 22010,
    "transaction_notes": "Test purchase using the Gyft API!",
    "merchant_name": "Test Merchant",
    "amount": -5.00,
    "delivered_to": "testrecipient@gyft.com",
    "auto_delivered": "Y",
    "revealed": "N",
    "gift_status": 0,
    "card_status": 5,
    "opening_balance": 5.00,
    "current_balance": 5.00,
    "transaction_created": 1428356249000,
    "user_created": 1428929607000
}

Refund Specific Transaction

The Refund Specific Transaction API refunds a Purchase Gift Card transaction, assuming that transaction is in Pending or Sent gift status.

POST /v1/reseller/transaction/refund/:id

Request Parameters

  • id: The unique id for a the specific transaction that should be refunded.

Response Parameters

  • id: Full id of the reseller card associated to this transaction.
  • status: Status of the account, including:
    • 0 = Pending
    • 1 = Error
    • 2 = Received
    • 3 = Refunded
  • gf_reseller_transaction_id: The unique id for this transaction.
  • email: The recipient email address associated to this transaction.

Request URL

https://apitest.gyft.com/mashery/v1/reseller/transaction/refund/22010

Sample Response

{
    "id": "xDGJxz0987zr4357b2453",
    "status": 0,
    "gf_reseller_transaction_id": 22010,
    "email": testrecipient@gyft.com
}
Note:The Refund API response will only be successful when the gift_status of the transaction submitted is Pending (0) or Sent (1).

Purchase Gift Card

The Purchase Gift Card API purchases a single gift card and returns a direct link to the redemption experience.

This process depletes the USD value of the gift card purchased from the current pre-funded balance remaining in your application’s account.

The response confirms the purchase and returns the redemption URL for the gift card purchased. This Redemption URL can be delivered to the end user via the partner’s reward delivery process (email, in app, etc). The end user, upon clicking the Redemption URL, will call a Gyft-managed web page that presents the gift card details.

POST /partner/purchase/gift_card_direct

Request Parameters

  • shop_card_id:  The unique id of the shop card the end user is purchasing.
  • reseller_reference (optional):  An optional reference code that might be relevant to the partner. For example, the partner’s order_id of the specific purchase could be linked with this parameter.
  • notes (optional):  An optional additional field that allows the partner to associate some relevant information to the transaction (255 characters).

Response Parameters

  • id: The unique id for the purchase transaction.
  • url: The redemption URL, which will navigate the end  user to a Gyft-managed web page that presents the gift card details in a merchant-approved redemption experience.

Request URL

https://apitest.gyft.com/mashery/v1/partner/purchase/gift_card_direct

Sample Response

{
    "id": 23010,
    "url": "https://staging.gyft.com/..."
}

Coming Soon!

The Gyft SDK will be available soon, watch this space!

Success!

Thanks for your interest. We’ll be in touch soon.

Cool. Got it.