Giftly API V2 Documentation

In this document, you can find all the requirements for Giftly API V2 to access product catalogs and issue an order for digital gift card types. Customers with the proper credentials can access Giftly API endpoints using an access token (see Authentication).

Note: Use HTTPS protocol for all requests.

AUTHENTICATION

API endpoints are only accessible to customers who have credentials (a client ID and a secret key) provided by Giftly. Approved customers can access various endpoint resources using an access token. This access token grants access to the API for a specified amount of time. You pass the access token in the Authorization header of any subsequent request to API endpoints.

Note: Use retrieved token in header: Authorization: Bearer {token}

Expected Behavior

The following are the expected results to common requests to the API list (see Status Codes and Error Messages for more information).

Error code explanation

While using Giftly API you may face a HTTP 400 error which has a code inside JSON response. Following table could help you figure out the problem programmatically.

Base URL

All of the URLs referenced in this API documentation have the following base:

Production : https://#/vendors/v2/

SandBox: https://#/vendors/v2/

These REST APIs are served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

API Endpoints

you can find endpoints as below.

Generate Token

An access token provides access to Giftly API for a specified amount of time. When the access token expires, clients must obtain another one.

POST /auth/token/

Sample Response
{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfaWQiOj",
  "expire": 1579799052
}
        

Request Format

Get Account Balance

Returns account balance of various currencies.

GET /balance/

Sample Response
[
  {
    "currency": {
      "currency": "Dollars",
      "symbol": "$",
      "code": "USD"
    },
    "balance": 673.67
  },
  {
    "currency": {
      "currency": "Dollars",
      "symbol": "CAD$",
      "code": "CAD"
    },
    "balance": 49.5
  },
  {
    "currency": {
      "currency": "Euro",
      "symbol": "€",
      "code": "EUR"
    },
    "balance": 4.71
  },
  {
    "currency": {
      "currency": "Pounds",
    "symbol": "£",
    "code": "GBP"
    },
    "balance": 459.0
  },
  {
    "currency": {
      "currency": "TestService",
      "symbol": "GY",
      "code": "GY"
    },
    "balance": 9090.74
  }
]
      

Request Format

Catalog List

Gets a list of all fixed price and range-priced product catalogs.
Some gift cards have fixed prices and some do not. If the “min” and “max” of a product are the same, it means the price of that product is FIXED. For instance, iTunes gift cards are available in amount of $5 to $500. Whereas, PlayStation gift cards prices are fixed and available ONLY in amount of $25, $100, $500.

GET /catalogs/

Sample Response
 {
   "count": 3,
   "results": [
     {
       "sku": 562,
       "upc": 659245724761,
       "title": "2,400 CALL OF DUTY: MODERN WARFARE POINTS",
        "min_price": 19.99,
        "max_price": 19.99,
        "pre_order": false,
        "activation_fee": 0.0,
        "percentage_of_buying_price": 20.0,
        "currency": {
          "currency": "Dollars",
          "symbol": "$",
          "code": "USD"
        },
        "categories": [
          {
            "name": "CALL OF DUTY"
          },
          {
            "name": "CALL OF DUTY"
          }
        ],
        "regions": [
          {
            "name": "Global",
            "code": "GLC"
          }
        ],
           "image":
 "http://gy-api.vercel.app/image/media/products/images/2020/08/2400_CALL_OF_DUTY.jpg
 ",
           "description": "",
           "showing_price": {
             "price": 35.0,
             "showing_currency": {
               "currency": "Lira",
               "symbol": "TL",
               "code": "TRY"
             }
           }
         },
         {
           "sku": 1152,
           "upc": 659245710948,
           "title": "amazon Canada",
           "min_price": 5.0,
           "max_price": 500.0,
           "pre_order": false,
           "activation_fee": 0.0,
           "percentage_of_buying_price": 10.0,
           "currency": {
             "currency": "Dollars",
             "symbol": "CAD$",
             "code": "CAD"
            },
            "categories": [
              {
                "name": "amazon Canada"
              }
            ],
            "regions": [ 
               {
                "name": "Canada",
                "code": "CA"
               }
            ],
            "image":
 "http://gy-api.vercel.app/image/media/products/images/2020/09/amazon.jpg",
            "description": "",
            "showing_price": null
         },
         {
            "sku": 1159,
            "upc": 659245799523,
            "title": "Amazon DE",
            "min_price": 10.0,
            "max_price": 100.0,
            "pre_order": true,
            "activation_fee": 3.0942,
            "percentage_of_buying_price": 0,
            "currency": {
              "currency": "Euro",
              "symbol": "€",
              "code": "EUR"
            },
            "categories": [
              {
                "name": "amazon Germany"
              }
            ],
            "regions": [
               {
                "name": "Germany",
                "code": "DE"
               }
            ],
            "image":
 "http://gy-api.vercel.app/image/media/products/images/2019/11/Image7_g0lgIVb.jpg",
            "description": "{\"content\":[],\"barcode\":null}",
            "showing_price": null
          }
]
}

        

Request Format

Catalog Availability

Checks if enough cards are available for a specific product

GET /catalogs/{product_sku}/availability/

Sample Response
{
  "availability": true,
  "detail": "This catalog is available."
}
      

Request Format

Digital Card Order Create

You must include a valid access token in the Authorization header and a valid catalog SKU in the body of the POST request. A successful POST returns the Order ID and creation time. When pre-order is true, you can create order if the product is out of stock. When pre-order flag is false, you can order digital cards for immediate use at the point of sale. An immediate order is limited to a total of five digital cards.

Pre order (How does pre order works?) To determine whether you want to pre-order your request or not. The product must support pre-order mood. If you pass true your cards will get ready in the future. (Please use the “Pre-order” option when the product is not available at GY PIN panel or the delivery time is not important for you. The product will be delivered when it is ready, which usually takes within one to two business days.) If you would like to receive and deliver the product to your customers instantly, please use “False” option.

POST /orders/

 Sample Response
 {
   "order_id": 156734,
   "delivery_type": 3,
   "destination": "18004441234",
   "status": 1,
   "status_text": "accept",
   "created_time": "2021-09-19T12:46:19.577169",
   "terminal_id": 97,
   "reference_code": "bb715b4e-6792-45ca-9ca5-2d708f41a6e0",
   "product": {
     "sku": 1148,
     "title": "App Store & iTunes US"
   },
   "count": 1,
   "total_face_value": 3.0,
   "total_fees": 0,
   "total_discounts": 0.42,
   "total_customer_cost": 3.42,
   "is_completed": true,
   "share_link": "gyapilink/redeem/01c79b97-8ab4-423c-a11d-225897f2135a"
 }
status list: pending(0) , accept(1) , reject(-1)
    

      

Request Format

Digital Card Order Details by Reference Code

A successful GET returns information about the order
Order Status: Reject or Pending or Success

GET /orders/{reference_code}/

 Sample Response
  {
    "order_id": 156734,
    "delivery_type": 3,
    "destination": "18004441234",
    "status": 1,
    "status_text": "accept",
    "created_time": "2021-09-19T12:46:19.577169",
    "terminal_id": 97,
    "product": {
    "sku": 1148,
    "title": "App Store & iTunes US"
    },
    "count": 1,
    "total_face_value": 3.0,
    "total_fees": 0,
    "total_discounts": 0.42,
    "total_customer_cost": 3.42,
    "is_completed": true,
    "share_link": "gyapilink/redeem/01c79b97-8ab4-423c-a11d-225897f2135a"
  }
status list: pending(0) , accept(1) , reject(-1)

      

Request Format

Digital Card Order Cards Information

lets you retrieve a list of cards in an order using the Reference Code. A successful GET returns information about the cards in the order.

GET /orders/{reference_code}/cards/

Sample Response
{
  "results": [
    {
      "card_number": "ZNNPZRRYP49VT9UK",
      "pin_code": "393145478240831916",
      "claim_url": "gyapilink/redeem/9853476c-3b05-4871-a56f-9bb7eb33891d",
      "expire_date": ""
    },
    {
      "card_number": "NWUJ7LAR3KGTU77X",
      "pin_code": "930854294202589407",
      "claim_url": "gyapilink/redeem/db095ef3-7d21-4307-8cdc-3b1c0fa300c3",
      "expire_date": ""
    }
  ]   
}

      

Request Format

Digital Card Order History

lets you retrieve your list of orders. A successful GET returns information about the orders history.

GET /orders/

Sample Response
{
  "count": 66,
  "next":
"https://gy-api.vercel.app/orders/?end_date=2021-09-19&limit=4&offset=1&
start_date=2021-09-01",
  "previous": null,
  "results": [
    {
    "order_id": 156609,
    "delivery_type": 2,
    "destination": "18885051234",
    "status": 1,
    "status_text": "accept",
    "created_time": "2021-09-09T06:28:55.467051",
    "terminal_id": null,
    "reference_code": "3d497a5e-64bd-4b95-a5db-61f42b6c70d5",
    "product": {
      "sku": 21,
      "title": "Test Amazon"
    },
    "count": 1,
    "total_face_value": 10.0,
    "total_fees": 0,
    "total_discounts": 0.1,
    "total_customer_cost": 10.1,
    "is_completed": true,
    "share_link": "gyapilink/redeem/01c79b97-8ab4-423c-a11d-225897f2135b"
  },
  {
    "order_id": 156610,
    "delivery_type": 1,
    "destination": "example@example.com",
    "status": 0,
    "status_text": "pending",
    "created_time": "2021-09-09T09:08:23.167070",
    "terminal_id": null,
    "reference_code": "88813f11-5ba2-4ea2-b34a-e2ea4998892c",
    "product": {
    "sku": 1159,
    "title": "Amazon DE"
    },
    "count": 1,
    "total_face_value": 10.0,
    "total_fees": 3.09,
    "total_discounts": 0,
    "total_customer_cost": 13.09,
    "is_completed": false,
    "share_link": "gyapilink/redeem/01c79b97-8ab4-423c-a11d-225897f2123f"
  },
  {
    "order_id": 156613,
    "delivery_type": 1,
    "destination": "example@example.com",
    "status": 1,
    "status_text": "accept",
    "created_time": "2021-09-09T10:49:08.501976",
    "terminal_id": null,
    "reference_code": "8f1453f0-96cd-4dbf-89c4-cb44b293241d",
    "product": {
      "sku": 1148,
      "title": "App Store & iTunes US"
    },
    "count": 1,
    "total_face_value": 3.0,
    "total_fees": 0,
    "total_discounts": -0.06,
    "total_customer_cost": 2.94,
    "is_completed": true,
    "share_link": "gyapilink/redeem/01c79b97-8ab4-423c-a11d-225897f2110d"
  },
  {
    "order_id": 156614,
    "delivery_type": 0,
    "destination": null,
    "status": 1,
    "status_text": "accept",
    "created_time": "2021-09-09T11:09:37.059887",
    "terminal_id": null,
    "reference_code": "7956fd9a-b2ee-4dfa-a1b2-e7224c2516a0",
    "product": {
      "sku": 1148,
      "title": "App Store & iTunes US"
    },
    "count": 1,
    "total_face_value": 3.0,
    "total_fees": 0,
    "total_discounts": -0.06,
    "total_customer_cost": 2.94,
    "is_completed": true,
    "share_link": "gyapilink/redeem/01c79b97-8ab4-423c-a11d-225897f2129e"
  }
 ]
}
    

      

Request Format

Exchange Rates

When you order a product with a currency from which you don’t have enough balance, an exchange happens from one currency you have enough from, to the required one, provided that a rate exists in GY PIN for this exchange. Calling this API, you will receive all the available exchange rates.

GET /exchange_rates/

Sample Response
{
  "count": 3,
  "results": [
      {
          "from_currency": {
              "currency": "Dollars",
              "symbol": "$",
              "code": "USD"
          },
          "to_currency": {
              "currency": "Pounds",
              "symbol": "£",
              "code": "GBP"
          },
          "rate": 0.75
      },
      {
          "from_currency": {
              "currency": "Dollars",
              "symbol": "$",
              "code": "USD"
          },
          "to_currency": {
              "currency": "Dollars",
              "symbol": "CAD$",
              "code": "CAD"
          },
          "rate": 1.32
      },
      {
          "from_currency": {
              "currency": "Dollars",
              "symbol": "$",
              "code": "USD"
          },
          "to_currency": {
              "currency": "Euro",
              "symbol": "€",
              "code": "EUR"
          },
          "rate": 0.83
      }
  ]
}



      

Request Format

Physical Card Check

Client can check physical card status using VAN16 barcode number on the back of the physical card.

GET /cards/check/

Sample Response
{
  "barcode": "888462551206058120006239903648",
  "product": "iTunes US",
  "sku": 299,
  "status_text": "Activated",
  "status": 1,
  "min_price": 10.0,
  "max_price": 200.0,
  "activate_price": 10.0,
  "activate_time": "2019-11-20T13:24:26.862624",
  "currency": "USD"
 }
status list: Pending(-1) , Activated(1) , Inactive(0)
    

      

Request Format

Physical Card Activate

Client can activate physical card using VAN16 barcode number on the back of the physical card. sku and price must be retrieved from check API first. request will be processed within maximum 40 seconds and the result will be returned to the client.

POST /cards/activate/

Sample Response
{
  "transaction_id": 8350,
  "barcode": "190199890346058120024981343201",
  "product": "App Store & iTunes US physical 2020",
  "status": -1,
  "status_text": "Pending",
  "total_face_value": 25.0,
  "total_fees": 0,
  "total_discounts": 0.25,
  "total_customer_cost": 25.25,
  "terminal_id":97,
  "currency": "USD",
  "created_time": "2021-09-20T07:58:27.328676",
  "reference_code": "bb715b4e-6792-45ca-9ca5-2d708f41a6a4"
}
status list: pending(-1) , activate(1) , failed(-2)

      

Request Format

Physical Card Activation Status

Client can check physical card activation status using the Reference Code of the activation process.

GET /cards/{reference_code}/

Sample Response
  {
    "transaction_id": 8350,
    "barcode": "190199890346058120024981343201",
    "product": "App Store & iTunes US physical 2020",
    "status": -1,
    "status_text": "Pending",
    "total_face_value": 25.0,
    "total_fees": 0,
    "total_discounts": 0.25,
    "total_customer_cost": 25.25,
    "terminal_id":97,
    "currency": "USD",
    "created_time": "2021-09-20T07:58:27.328676"
  }
status list: pending(-1) , activate(1) , failed(-2)

      

Request Format

Notification Config

Adjust this api if you want to be notified after the digital order has been accepted or rejected.

POST /notification_config/

Sample Response
{
  "detail": "API setting added successfully.",
  "code": 801
}

          

Request Format

{
"type_code": 1,
"type_text": "digital",
"order_id": 1572156,
"status": 1,
"confidential_key": "ikasd7823q4lmk132jk"
}
status list: accept(1) , reject(-1)
                  

Get Notification Configs

A successful GET returns information about your notification settings.

Get /notification_config/

Sample Response
{
  "endpoint": "https://example.com/",
  "confidential_key": "ikasd7823q4lmk132jk"
}
          

Request Format