TCB.Admin Home
  1. Home
  2. The Coupon Bureau Getting Started Guide

Manufacturer Getting Started Guide

Manufacturer APIs allow a manufacturer to deposit their own offers into TCB through their own internal systems. APIs are NOT required for a Manufacturer to connect to The Coupon Bureau, these APIs are designed specifically for partners who are looking to integrate these functions into your own system.

API functions include Master Offer File deposits, Authorized Partner authorization by account for Master Offer File management, and Provider authorization by Master Offer File or account for distribution.

Step #1 : Get Access Token


curl -X POST '{{API_SERVER}}/access_token' \
-H 'Content-Type: application/json' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'

The Access Token will be valid for 24 hours. You should cache it and use the same access token for next 59 mins to call any other manufacturer APIs.

Step #2 : Create Master Offer File 

curl -X POST '{{API_SERVER}}/manufacturer/base_gs1' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{
    "data":{
        "base_gs1":"8112010031493140188",
        "brand_id":"XYZ",
        "description":"50% off ",
        "campaign_start_time":"04/21/2020",
        "campaign_end_time":"04/30/2020",
        "redemption_start_time":"04/22/2020",
        "redemption_end_time":"04/30/2020",
        "total_circulation":"100",
        "primary_purchase_save_value":"1",
        "primary_purchase_requirements":"1",
        "primary_purchase_req_code":"1",
        "primary_purchase_gtins":[
            "294239749273","2390843209"
            ],
        "primary_purchase_family_code":"",
        "additional_purchase_rules_code":"",
        "second_purchase_requirements":"",
        "second_purchase_gs1_company_prefix":"",
        "second_purchase_req_code":"",
        "second_purchase_gtins":[
            ""
            ],
        "second_purchase_family_code":"",
        "third_purchase_requirements":"",
        "third_purchase_gs1_company_prefix":"",
        "third_purchase_req_code":"",
        "third_purchase_gtins":[
            ""
            ],
        "third_purchase_family_code":"",
        "gln":"",
        "save_value_code":"1",
        "applies_to_which_item":"",
        "store_coupon":"1",
        "donot_multiply_flag":""
    }
}'

Once the master offer file is created, you can use the below API call to manage the master offer files.
      Assign / Unassign provider for master offer file
      Delete master offer file

 To get master offer file(s) created by you
      My master offer files
      Master offer file detail

 Master offer file needs to be locked before a provider deposits a serialized data string. If the master offer file is editable (not locked), no one will be able to deposit a serialized data string under that master offer file.
      My master offer files
      Master offer file detail

Step #3.1 : Get all Providers connected to TCB 

curl -X GET '{{API_SERVER}}/providers' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN'

This API response can be cached so that you can skip this step. Once you get the list of providers, you can select the desired providers (email_domain of the provider) from this list to authorize. Once the provider is authorized to distribute a master offer file, they can deposit the serialized GS1 of that master offer file.

Step #3.2 : Authorize provider(s) to allow master offer file distribution

curl -X POST '{{API_SERVER}}/manufacturer/base_gs1/<BASE_GS1>/toggle_provider' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"email_domain":"qples.com"}'

You can call this API multiple times to authorize multiple providers. Once the provider is authorized, you can get the list of all authorized providers of a master offer file

      Get assigned providers of master offer file

Step #4.1 : Authorize a Authorized Partner

curl -X PUT '{{API_SERVER}}/manufacturer/toggle/manufacturer_agent' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"email_domain":"qples.com"}'

You can call this API multiple times to authorize multiple Authorized Partners.
   To unauthorize a Authorized Partner use
      Call the same toggle api (/manufacturer/toggle/manufacturer_agent)

 You can also get the list of all authorized Authorized Partners
      Get connected Authorized Partners

Step #4.2 : Give Brand Access to a Authorized Partner to create / manage master offer files and receive redemption data

curl -X PUT '{{API_SERVER}}/manufacturer/manufacturer_agents/:manufacturer_agent_email_domain/toggle_brand/:brand_internal_id' \
-H 'Content-Type: application/json' 
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"access_type":"campaign_set"}'

You can call this API to authorize your brand to a manufacturer agent with proper access_type. access_type attribute value should be one of the below

  • view_only: can view all the master offer files of the brand.
  • campaign_set: can edit campaign detail of the master offer file of the brand.
  • full_set: can edit complete master offer file of the brand.
  • full_set_with_lock: can edit complete master offer and of the brand and can lock it to stop future update. Once the master offer file is locked, only campaign data (following attributes) can be edited.
    • description
    • campaign_start_time
    • campaign_end_time
    • redemption_start_time
    • redemption_end_time
    • total_circulation
    • primary_purchase_gtins
    • second_purchase_gtins
    • third_purchase_gtins

Authorized Partner Getting Started Guide

Authorized Partner APIs allow the ability to connect to the TCB from your internal systems so that you can directly deposit and manage an 8112 offer into a manufacturer’s TCB account and retrieve redemption data. APIs are NOT required for a Authorized Partner to perform your functions as they relate to The Coupon Bureau, these APIs are designed specifically for partners who are looking to integrate these functions into your own system.

Step #1 : Get Access Token


curl -X POST '{{API_SERVER}}/access_token' \
-H 'Content-Type: application/json' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'

The Access Token will be valid for 24 hours. You should cache it and use the same access token for next 59 mins to call any other manufacturer APIs.

Step #2 : Get Connected Manufacturers


Required in step #3 where you will create master offer file on behalf of one manufacturer.

curl -X GET '{{API_SERVER}}/manufacturer_agent/manufacturers' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN'

You can cache the response of this API call as there will be no change in response until and unless another manufacturer authorizes the same Authorized Partner. Once you cache it, you can skip step #2 while creating a master offer file.

Step #3 : Create Master Offer File for a Manufacturer 

curl -X POST '{{API_SERVER}}/manufacturer/base_gs1?email_domain=<MANUFACTURER_EMAIL_DOMAIN>' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{
    "data":{
        "base_gs1":"8112010031493140188",
        "brand_id":"XYZ",
        "description":"50% off ",
        "campaign_start_time":"04/21/2020",
        "campaign_end_time":"04/30/2020",
        "redemption_start_time":"04/22/2020",
        "redemption_end_time":"04/30/2020",
        "total_circulation":"100",
        "primary_purchase_save_value":"1",
        "primary_purchase_requirements":"1",
        "primary_purchase_req_code":"1",
        "primary_purchase_gtins":[
            "294239749273","2390843209"
            ],
        "primary_purchase_family_code":"",
        "additional_purchase_rules_code":"",
        "second_purchase_requirements":"",
        "second_purchase_gs1_company_prefix":"",
        "second_purchase_req_code":"",
        "second_purchase_gtins":[
            ""
            ],
        "second_purchase_family_code":"",
        "third_purchase_requirements":"",
        "third_purchase_gs1_company_prefix":"",
        "third_purchase_req_code":"",
        "third_purchase_gtins":[
            ""
            ],
        "third_purchase_family_code":"",
        "gln":"",
        "save_value_code":"1",
        "applies_to_which_item":"",
        "store_coupon":"1",
        "donot_multiply_flag":""
    }
}'

Once the master offer file is created, you can use the below API call to manage the master offer files.
To activate / deactivate / update a specific master offer file
      Activate / Deactive master offer file
      Assign / Unassign provider for master offer file
      Delete master offer file

 To get master offer file(s) created by you
      My master offer files
      Master offer file detail

Step #4.1 : Get all Providers connected to TCB

curl -X GET '{{API_SERVER}}/providers' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN'

This API response can be cached so that you can skip this step. Once you get the list of providers, you can select the desired providers (email_domain of the provider) from this list to authorize. Once the provider is authorized to distribute a master offer file, they can deposit the serialized data string of that master offer file.

Step #4.2 : Authorize provider(s) to allow master offer file distribution

curl -X POST '{{API_SERVER}}/manufacturer/base_gs1/<BASE_GS1>/toggle_provider' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"email_domain":"qples.com"}'


This API response can be cached so that you can skip this step. Once you get the list of providers, you can select the desired providers from this list to authorize. Once the provider is authorized to distribute a master offer file, they can deposit the serialized data string of that master offer file.

Step #4.3 : Authorize provider(s) to allow master offer file distribution

curl -X PUT '{{API_SERVER}}/manufacturer/toggle/manufacturer_agent' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"email_domain":"qples.com"}'

You can call this API multiple times to authorize multiple Authorized Partners.
   To unauthorize a Authorized Partner use
      Call the same toggle api (/manufacturer/toggle/manufacturer_agent)

 You can also get the list of all authorized Authorized Partners
      Get connected Authorized Partners

Provider Getting Started Guide

Provider APIs allow a coupon provider to deposit/ delete a serialized data string (the serialized data string distributed to a consumer) at the time of distribution into a manufacturer’s TCB account. These APIs are required for a provider to participate with TCB. Note: A provider will only be able to deposit serialized data strings into Master Offer Files of those manufacturers who have authorized them.

Step #1 : Get Access Token


curl -X POST '{{API_SERVER}}/access_token' \
-H 'Content-Type: application/json' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'

The Access Token will be valid for 24 hours. You should cache it and use the same access token for next 59 mins to call any other manufacturer APIs.

Step #2 : Get authorized master offer files.


Manufacturers / Manufacturer Agents will authorize provider to distribute master offer files. To get the list of all authorized master offer files, use My master offer files API 

curl -X GET '{{API_SERVER}}/provider/base_gs1s' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN'



Step #3 : Deposit a serialized data string 


curl -X POST '{{API_SERVER}}/provider/deposit' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"gs1s":"<Comma Seperated GS1s>"}'

Retailer Getting Started Guide

When an AI (8112) serialized data string is scanned at the POS, the POS makes an API request to POF with that serialized data string. The POF will then return the serialized data string with a status of “success” or “Failure” – if “success,” it will also send offer details. The POS then uses offer details from the API response to validate offer against basket data and apply the discount or send a rollback response if the discount cannot be applied.

There are two main components to consider:

Redeem:
 This is the primary API endpoint for TCB Positive Offer File functionality. The retailer sends scanned data string(s) to POF, and POF responds with one or more data strings with "success" or "failure" for each.

      "success" means the serialized data string is available for redemption.
      "failure" means the data string was already redeemed or was in some other way invalid.

Whenever the API returns any "success" response, it is also marking the relevant data string as "redeemed", meaning the same data string cannot be used more than once.

      On "success", the data string will be accompanied with offer details
      On "failure", the failure reason will be returned per data string

Data strings will be use in the "rollback" scenario described below.

Rollback:
It may be necessary to "rollback" a data string in the event that purchase requirements are not met or a failed payment.

Example Flows
Retailer calls the TCB "redeem" API as they scan GS1s during the checkout process.

  • In this flow, if a customer has 5 GS1s to scan, the retailer makes 5 calls to the TCB API during the checkout process. TCB will respond with applicable complete GS1s and "success" (valid) or "failure" (invalid) for each serialized GS1.
  • Before payment is processed, the retailer must determine which valid complete GS1s are applicable to the customer's basket, and apply discounts appropriately.
  • If any returned redeemed serialized GS1s are *not* applicable to the customer's basket, the TCB "rollback" API should be called for those un-applied serialized GS1s.
  • If the payment fails for any reason and the transaction itself is rolled back, the TCB "rollback" API should be called for all serialized GS1s previously returned by the TCB "redeem" API, whether or not they were applied to the basket.
Retailer scans GS1s during the checkout process, but waits to call the TCB "redeem" API until all items have been scanned.
  • In this flow, if a customer has 5 GS1s to scan, the retailer would scan GS1s during or at the end of the checkout process, and then make one single TCB "redeem" API call just before payment is processed. TCB will respond with a list of complete GS1s with "success" (valid) or "failure" (invalid) for each complete GS1.
  • After the "redeem" API call is made, the retailer should determine which redeemed serialized GS1s are applicable to the customer's basket and apply the discounts.
  • If any returned redeemed serialized GS1s are *not* applicable to the customer's basket, the TCB "rollback" API should be called for those un-applied complete GS1s.
  • If the payment fails for any reason and the transaction itself is rolled back, the TCB "rollback" API should be called for all serialized GS1s previously returned by the TCB "redeem" API, whether or not they were applied to the basket.

Step #1 : Get Access Token


curl -X POST '{{API_SERVER}}/access_token' \
-H 'Content-Type: application/json' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'

The Access Token will be valid for 24 hours. You should cache it and use the same access token for next 59 mins to call any other manufacturer APIs.



Step #2.1 : Redeem a Coupon

curl -X POST '{{API_SERVER}}/retailer/redeem' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{
    "gs1s":"<Comma seperated GS1s>",
    "selected_store":"<Store ID>"
  }'

How to handle "redeem" API responses

"redeem" API responses will be returned in a JSON array, with each item corresponding to a GS1 from the "gs1s" request array.
Response fields (per GS1 item): 

  status -> "success" or "failure"
  newly_redeemed -> List of GS1s redeemed successfully
          {
            gs1: <GS1 redeemed>,
            master_offer_file: <Master offer file (base gs1) data string> Refer to master_offer_files mapping to get the purchase requirements
          }
  master_offer_files -> Master offer file purchase details


Example response for redeem

{
  "status": "success",
  "total_gs1s_processed": 3,
  "already_redeemed": [
      "811201777777754545412323432"
  ],
  "not_yet_live": [
      "8112013333333676767223234543"
  ],
  "newly_redeemed": [
      {
          "gs1": "811201777777754545412323433",
          "master_offer_file": "8112017777777545454"
      }
  ],
  "master_offer_files": {
      "8112017777777545454": {
          "primary_purchase_gtins": [
              "678987654323",
              " 876789876543"
          ],
          "second_purchase_gtins": [],
          "third_purchase_gtins": [],
          "primary_purchase_save_value": 100,
          "primary_purchase_requirements": 1,
          "primary_purchase_req_code": 0
      }
  },
  "message": "Added 1 gs1(s) as available to redeem",
  "execution_id": "9fc7f4db-c5ca-41c7-8a65-65be4bcd8e76",
  "execution_time_in_ms": 2405,
  "execution_start_time": 1587495466023
}



Step #2.2 : Rollback a Coupon

curl -X DELETE '{{API_SERVER}}/retailer/rollback/<GS1 to Rollback> \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN'

Authorize Accelerator to manage redeem / rollback



Retailer can authorize the Accelerators to call redeem / rollback API on their behalf. An accelerator is an entity that has a connection to the retailer POS and has the ability perform these API functions in or on behalf of the POS. They are responsible to change the point of sale software to redeem / rollback 8112 barcode. To do that, first get the list of accelerators connected to The Coupon Bureau®

All Accelerators

 If you find the vendor who is managing your point of sale system software, you can allow them to implement redeem / rollback on your behalf. You can use the below API calls to assign / unassign accelerator.

Assign/Unassign Accelerators

Authorize Clearinghouse to manage settlement


Retailer can authorize one clearinghouse to do the final settlement with the coupon manufacturer. Once they authorize a clearinghouse, the clearinghouse will be able to see the real time redemption and do the final settlement. To authorize a clearinghouse, retailer can call get_clearinghouses API to get the list of clearinghouses connected to The Coupon Bureau®

All clearinghouses

 Retailer can assign / unassign clearinghouse using the below API calls

Assign / Unassign clearinghouse

Clearinghouse Getting Started Guide

Retailer clearinghouse will be able to view the redemption report of authorized retailers. Retailers connected to The Coupon Bureau® will authorize a clearinghouse to do the final settlement with the manufacturer. Once the clearinghouse is authorized, they will be able to view the redemption data in realtime.

Step #1 : Get Access Token


curl -X POST '{{API_SERVER}}/access_token' \
-H 'Content-Type: application/json' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'

The Access Token will be valid for 24 hours. You should cache it and use the same access token for next 59 mins to call any other manufacturer APIs.

Step #2 : Get Authorized Retailers 

curl -X GET '{{API_SERVER}}/clearinghouse/retailers' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN'

Step #3 : Get Authorized Retailer Redemption Info 

curl -X GET '{{API_SERVER}}/clearinghouse/data/fetch?report_from_date=<Data (YYYY-MM-DD)>&report_to_date=<Data (YYYY-MM-DD)>&retailer_email_dmain=<E.g. qples.com>&pageNo=<Page No (E.g. 0,1,2...)>' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN'

Accelerator Getting Started Guide

Accelerators will facilitate retailer connectivity to The Coupon Bureau Positive Offer File. The Coupon Bureau will authorize an Accelerator to execute coupon redemption/ rollback on behalf of multiple retailers. Retailers will use this accelerator connectivity as their connection to The Coupon Bureau Positive Offer File (POF).

When an AI (8112) serialized data string is scanned at the POS, the POS makes an API request to POF with that serialized data string. The POF will then return the serialized data string with a status of “success” or “Failure” – if “success,” it will also send additional purchase requirement data. The POS then uses the additional purchase requirement data from the API response to validate offer against basket data and apply the discount or send a rollback response if the discount cannot be applied.

There are three main components to consider:

Get Connected Retailers:
 Retailer will allow the accelerator to perform operation on their behalf. In this step, accelerator will pull the list of authorized retailers so that they can use the appropriate retailer_client_id while making the API calls

Redeem:
 This is the primary API endpoint for TCB Positive Offer File functionality. The accelerator (on behalf of a retailer) sends scanned serialized data string(s) to POF, and POF responds with one or more serialized data strings. with "success" or "failure" for each.
   "success" means the serialized data string is available for redemption
   "failure" means the serialized data string was already redeemed or was in some other way invalid.

Whenever the API returns any "success" response, it is also marking the relevant complete serialized data string as "redeemed", meaning the same complete serialized data string cannot be used more than once.
   On "success", ", the serialized data string will be accompanied with offer details.
   On "failure", the failure reason will be returned per data string.

Data strings will be use in the "rollback" scenario described below.

Rollback:
 Depending on the point of sale implementation, it may be necessary to "rollback" relevant data string redemptions. For example, if "redeem" is called before the point of sale confirms payment, and payment is rejected, any complete data strings previously "redeemed" during the checkout process must be rolled back.

Step #1 : Get Access Token


curl -X POST '{{API_SERVER}}/access_token' \
-H 'Content-Type: application/json' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'

The Access Token will be valid for 24 hours. You should cache it and use the same access token for next 59 mins to call any other manufacturer APIs.

Step #2 : Get connected retailers.


Accelerator can perform operation (redeem / rollback) on behalf of an authorized retailer. Retailer connected to The Coupon Bureau® will authorize an Accelerator to do the work on their behalf. 

curl -X GET '{{API_SERVER}}/accelerator/retailers' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN'


Step #3.1 : Redeem a Coupon 

curl -X POST '{{API_SERVER}}/retailer/redeem' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{
    "gs1s":"<Comma seperated GS1s>",
    "selected_store":"<Retailer Store ID>",
    "retailer_email_domain":"<Retailer email domain>"
  }'

How to handle "redeem" API responses

"redeem" API responses will be returned in a JSON array, with each item corresponding to a GS1 from the "gs1s" request array.
Response fields (per data string item): 

  status -> "success" or "failure"
  newly_redeemed -> List of data strings redeemed successfully
          {
            gs1: <data string redeemed>,
            master_offer_file: <Master offer file (base gs1) data string> Refer to master_offer_files mapping to get the purchase requirements
          }
  master_offer_files -> Master offer file purchase details


Example response for redeem

{
  "status": "success",
  "total_gs1s_processed": 3,
  "already_redeemed": [
      "811201777777754545412323432"
  ],
  "not_yet_live": [
      "8112013333333676767223234543"
  ],
  "newly_redeemed": [
      {
          "gs1": "811201777777754545412323433",
          "master_offer_file": "8112017777777545454"
      }
  ],
  "master_offer_files": {
      "8112017777777545454": {
          "primary_purchase_gtins": [
              "678987654323",
              " 876789876543"
          ],
          "second_purchase_gtins": [],
          "third_purchase_gtins": [],
          "primary_purchase_save_value": 100,
          "primary_purchase_requirements": 1,
          "primary_purchase_req_code": 0
      }
  },
  "message": "Added 1 gs1(s) as available to redeem",
  "execution_id": "9fc7f4db-c5ca-41c7-8a65-65be4bcd8e76",
  "execution_time_in_ms": 2405,
  "execution_start_time": 1587495466023
}


Step #3.2 : Rollback a Coupon 

curl -X DELETE '{{API_SERVER}}/accelerator/rollback/<GS1>' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN'

3rd Party Data Access

There are scenarios wherein you will need to fetch data from TheCouponBureau® to integrate and enhance your own SAAS platform. Imagine, your client #1 is managing their coupons inside your SAAS platform. Now, your client #1 is also subscribed to TCB as a Manufacturer Agent. You are a SAAS provider and subscribed to TCB as Authorized partner. Your client #1 wants to manage coupons, view redemption report in your platform and the data is available in TCB database. To access data from TCB platform for your client #1,



Step #1 : Ask your client #1 to login to TCB from your portal

Construct TCB Access URL and redirect your client #1 to that URL. Your client #1 will login to TCB, on successful login, TCB will generate a temporary token and redirect to the URL you will specify while constructing the TCB Access URL. To construct the TCB Access URL, you need the followings

  • access_key You will get it from developer access page
  • secret_key: You will get it from developer access page
  • redirectURL: the URL which TCB will use to redirect on successful login. This URL will receive temp_token as GET parameter.
  • timestamp: Epoch timestamp. Click here to get the current epoch timestamp
TCB Access URL also needs a signature parameter to autheticate you. Use the below mentioned formula to calculate the signature value which you can append to the URL. 
md5(access_key + redirectURL + timestamp + secret_key)
Then you construct the TCB Access URL by sending access_key, redirectURL and signature as GET parameters. 
{{API_SERVER}}/oauth_access?
  access_key=ACCESS_KEY&
  redirectURL=REDIRECT_URL&
  timestamp=TIMESTAMP&
  signature=CALCULATED_SIGNATURE

TCB will then open a login window for your client #1 to login. It will also mention that, once you login, your data will be accessed by the SAAS provider.



On successful login, TCB will send a temp_token to the redirectURL.
redirectURL?temp_token=TEMPORARY_TOKEN
use the temp_token to acquire the access_token which will be valid for 24 hours. To get the access_token, construct TCB Access Token URL by passing the temp_token and signature. You can calculate signature by using the following formula. 
md5(temp_token + secret_key)

Send a GET request to TCB Access Token URL to acquire access_token for your client #1 
{{ API_SERVER }}/oauth_token?temp_token=TEMPORARY_TOKEN&signature=CALCULATED_SIGNATURE

You should cache the access_token against your client #1 in your system to continue using it to make various API calls on your client's behalf. Client Access Token will be valid for 180 days. You should ask your client to relogin once the access_token had expired.

Near-realtime Webhook

If you need to receive realtime updates about the coupons (serialized data strings), you can register your webhook url and TCB will keep sending events in realtime. TheCouponBureau® backend will generate events on the below actions. If you are authorized to receive the event, TCB will send push message to your configured webhook so that you can process it as per your need.



Step #1 : Save Webhook

Go to your homepage, click on Enterprise Setting, enter the webhook url and click save button. Your webhook url should be active. TCB backend will check the webhook by sending a HTTP POST request with JSON body 

{
  "TCBVERIFIER": "..."
}
Your webook endpoint should return HTTP Status Code: 200. If it fails to do that, you will get an error message while saving the webhook.



Step #2 : Verify Domain Ownership

TCB will verify the ownership of the webhook domain just to make sure you own the domain. There are three verification methods

  • using DNS Add a TXT record to verify that you own the domain
  • using hosted file: host a file in your server to verify the ownership of the domain
  • using hosted endpoint: create an endpoint in your server to prove the domain ownership
Once you verify the domain ownership, TCB will connect your webhook to data fabric and this process might take few hours. You will receive and email notification when your webhook is active.



Step #3 : Process Incomming Request

A TCB push request looks like this example below. Note that the message.data field is base64-encoded. 

{
  "message": {
    "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGV...........",
    "messageId": "136969346945"
  },
  ...
}
Your webhook needs to handle incoming messages and return an HTTP status code to indicate success or failure. A success response is equivalent to acknowledging a message. The status codes interpreted as message acknowledgements by the TCB backend system are: 200, 201, 202, 204. A success response might look like this: 
204 No Content

If your webhook does not return a success code, TCB retries delivery for 7 days before it will expire. Once you decode the message.data, you will get the below message 
{
  gs1: 'GS1 data string (coupon)', 
  action: 'deposited',
  primary_signature: '...',
  secondary_signature: '...'
}

Primary / Secondary signature will help you validate that the message is originated at TheCouponBureau® server and it is intended for you. As soon as your callback is approved (Enterprise Setting page), you will see two secret keys (primary and secondary) associated with your callback.

TheCouponBureau® backend will sign the message before pushing to your webhook using both primary and secondary keys and send those to your webhook as primary_signature / secondary_signature. Webhook implementation should recalculate the signatures and proceed execution if any one of the signatures matches.

  • primary_signature will be calculated using Primary Callback Secret
  • secondary_signature will be calculated using Secondary Callback Secret
Follow the below process to calculate the signature value 

primary_signature = md5 ( concat(gs1 + action + primary callback secret) )

secondary_signature = md5 ( concat(gs1 + action + secondary callback secret) )

Two secret keys concept will enable you rotate the key in case you want to change your keys. Here if the process you can use to safely rotate two keys.

  • Regenerate primary secret
  • Key change will take some time to reflect across TCB backend cluster
  • In the meantime, your backend will keep matching secondary_signature value
  • Once the key change is reflected across TCB cluster, which will take atleast 300 seconds, your primary_signature will start matching
  • You can now safely regenerate secondary secret
  • Your backend will keep matching primary_signature for sometime till secondary key will get stabilised in TCB cluster

Your webhook should calculate both signatures and continue if any one of the signatures matches.

Action will be any of the followings

  • deposited: new data string is deposited by provider
  • deleted: data string is deleted by provider
  • redeemed: deposited data string is redeemed by retailer / accelerator
  • rollback: redeemed data string is rollbacked by retailer / accelerator