Technical Contact Email:
sdk@tangocard.com
examples

Introduction

Production endpoint:

https://api.tangocard.com/raas/v1.1

Sandbox endpoint:

https://sandbox.tangocard.com/raas/v1.1

With our RESTful RaaS API you can integrate a global reward or incentive program into your platform.

Our API is made to support multiple account structures. Following Platform Setup and Authentication, the following methods are available:

Create an Account

Versatility to create multiple account structures to support many use cases

Get Account information

Call up information about accounts in your platform

Register a Credit Card

Securely save up to 10 credit cards to accounts with our third-party payment partner

Fund an Account

Call up your saved credit card(s) and use them to fund accounts

Delete a Credit Card

Remove saved credit cards for good

Get the Catalog

Call up our catalog of e-gift cards, donations, prepaid visas, and bitcoin e-gift cards

Place an Order

Place an order for a reward. Choose whether Tango Card delivers the reward via email

Resend a Reward E-mail

Simply resend a reward e-mail for an order that has already been placed

Get Order information

Call up order information about an individual order

Get Order history

Call up a list of orders for an account

Changes

Version 1.1 URL (current):

https://api.tangocard.com/raas/v1.1

Version 1.0 URL (deprecated):

https://api.tangocard.com/raas/v1

The goal of the RaaS API v1.1 is to support global reward and incentive programs in localized currencies and languages.

Summary of Key Changes

Get Reward Catalog Method Changes

Order Response Changes

Order Details & Order History Changes

API Methods with no changes between v1.0 and v1.1

Note: v1.1 order details and order history responses will include transactions placed on v1.0. For Order History, the “denomination” value will appear as null for orders placed in v1.0.

Platform Setup

Platform Configurations

The RaaS API is capable of supporting rewards and incentives for multiple platform structures.

If you are a company sending all the rewards for your platform from one rewards account then this 1 to 1 structure is for you:

alt text

If you are hosting multiple companies on your platform and you want them to be able to hold their own reward accounts then this multi-company and account structure will be what you’re looking for:

alt text

Sandbox credentials

Please email sdk@tangocard.com to receive your own credentials for the RaaS API Sandbox environment. The endpoint for the RESTful interface on the Sandbox environment is https://sandbox.tangocard.com/raas/v1.1/.

You may also use these general credentials to get started - they are the same credentials that are pre-loaded in the RaaS API Test Console.

Example Platform Credentials

Platform Name: TangoTest
Platform Key: 5xItr3dMDlEWAa9S4s7vYh7kQ01d5SFePPUoZZiK/vMfbo3A5BvJLAmD4tI=
Platform Authorization: Basic VGFuZ29UZXN0OjV4SXRyM2RNRGxFV0FhOVM0czd2WWg3a1EwMWQ1U0ZlUFBVb1paaUsvdk1mYm8zQTVCdkpMQW1ENHRJPQ==

An important note about Test Codes: Rewards delivered from Tango Card’s Sandbox environment contain sample codes and have no monetary or redeemable value. Additionally, please note that some Amazon.com denominations, like $20, may fail in the Sandbox environment. This is intentional behavior for the purpose of simulating an API error. If you encounter an error when testing an Amazon.com code, please try another denomination. Be assured that Amazon.com orders work consistently in the production environment.

When you have completed your development and are ready for production testing / launch you can request production credentials.

Production credentials

Once you are ready to move to production, you need to agree to the RaaS API Terms & Conditions. Once you agree to the Terms & Conditions, we will create credentials on the Production environment and follow up with you. The endpoint for the RESTful interface on the Production environment is https://api.tangocard.com/raas/v1.1/

RaaS API credentials versus TangoCard.com user credentials

Our now-deprecated legacy SDKs used username and password credentials (like those used for user accounts on our website). If you are upgrading to the RaaS API from one of our legacy SDKs, please note that our RaaS API uses a Platform Name and Platform Key that need to be created for your RaaS API account and you can not mix the credentials for TangoCard.com site with the credentials for the RaaS API.

System Notes

RaaS Best Practices

Retries - Network vagaries, infrastructure and supplier factors mean occasional network errors are inevitable and must be planned for. For this reason we recommend that you build an “exponential back off” or similar retry algorithm in which the timeout value for retry increases after each unsuccessful attempt. Exponential retries are well-documented elsewhere and beyond the scope of this document.

Balance Alerts - The RaaS API allows you to check an account balance at any time with the Get Account resource, but it does not have low balance alerts at this time. We recommend building in a balance check and alert system if you anticipate the need to re-fund accounts on a regular basis.

SSL/TLS

All communication with Tango Card’s RaaS API is handled over SSL, a commonly-used protocol for managing secured message transmissions on the Internet. As a result, clients of the RaaS API need to ensure that you have the chain (intermediate) certificate in place on your server. This is important as not having the chain certificate in place will (at best) disallow communication or (at worst) expose you to the potential for man-in-the-middle attacks. To accomplish this, we recommend you add the CA’s cert to your system’s trusted list. If that’s not possible, an alternative is to include the certificate in your application. Major CAs deliver a ‘bundled’ file containing the complete certificate chain providing a single installation method for the certificate.

The Certificate Authority that issued our server certificates is DigiCert, and we have one of their DigiCert SHA2 Secure Server CA certs. You can get DigiCert’s root and intermediate certificates from https://www.digicert.com/digicert-root-certificates.htm. If you choose to reference the certificate chain from your application’s code, the details on how to do this are highly specific to the library being used to make the connection, but here are a few examples to demonstrate the idea:

Ruby SSL example:

https = Net::HTTP.new('integration-api.tangocard.com', 443)
https.use_ssl = true
https.verify_mode = OpenSSL::SSL::VERIFY_PEER
https.ca_file = File.join(File.dirname(__FILE__), "../ca_certs/digicert_chain.pem")
https.request_get('/fake/example')

PHP SSL example:

$curl = curl_init('https://integration-api.tangocard.com/fake/example');
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($curl, CURLOPT_CAINFO, __DIR__ . "../ca_certs/digicert_chain.pem");
curl_exec($curl);

Python SSL example:

import requests
from requests.auth import HTTPBasicAuth
# SSL verify-peer is used by default.
requests.get('https://integration-api.tangocard.com/fake/example', auth=HTTPBasicAuth(username, password))

One thing to take note of in both examples is that OpenSSL is being instructed to “VERIFY PEER”. This setting is essential as without it you will know that your communication is encrypted, but you won’t know who it is you’re talking to.

Note: We use a wild-card certificate from DigiCert and hence the certificate chain is the same for both Sandbox and Production environments.

Console

You can test drive the RaaS API without writing a single line of code!

Using the RaaS API Test Console, you can easily go through each method supported in our API and see the requests and the responses for each of these resources. When you are comfortable with the concepts you can begin coding by requesting Sandbox credentials for our test site. Then, if you run into problems during the coding phase you can come back to our console and compare your JSON to our requests and responses.

Authentication

Example request:

POST /raas/v1.1/accounts HTTP/1.1
Authorization: Basic VGFuF29UZXN0OjV4SXRyM2RNRGxFV0FhOHM0czd2WWg3a1EwMWQ1U0ZlUFCVb1paaUsvdk1mYm8zQSVCdkpMQW1ENHRJPP==
Host: integration-api.tangocard.com

All calls require the platform’s authentication credentials. Authentication credentials are sent using HTTP Basic auth with the platform name as the username and the platform access key as the password. These will be assigned by Tango Card.

Versioning

Example Request

GET /raas/v1.1/rewards HTTP/1.1
Host: api.tangocard.com

All API calls specify the version in the endpoint URL.

The following changes are introduced without producing a new API version:

Responses

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "success": true,
  "data": {
    "name": "abc",
    "date": "2015-09-17T16:49:39+00:00"
  },
  "system_message": "Hello developers!"
}

Errors

The generic errors can be triggered by any calls. Error responses use HTTP status codes to indicate the type of error.

Status Code Description
400 - Bad Request HTTP entity provided does not match the content type.
401 - Unauthorized Authentication credentials were not supplied, but are required.
403 - Forbidden The request credentials or payload is invalid.
404 - Not Found The requested resource was not found.
409 - Conflict The resource to be created already exists.
500 - Server Error Something went wrong on our end.

The JSON response body will contain an error code and a description of the error. Many errors will have a field called “error_message” which can be used to give more information as to why it failed (for debugging, not displaying to end-users).

Please ensure that the response body is read to get more information on an error condition. Some HTTP client libraries may choose to not read the response body in case of any errors (4xx or 5xx).

Authentication Needed

Example missing authentication response:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="api.tangocard.com"
Content-Type: application/json; charset=utf-8

{
  "success": false,
  "error_message": "Use of this API endpoint requires authentication."
}

Authentication credentials were not supplied, but they’re required.

Bad Authentication

Example bad authentication response:

HTTP/1.1 403 Forbidden
X-Status-Reason: Authentication failed
Content-Type: application/json; charset=utf-8

{
  "success": false,
  "error_message": "Authentication failed."
}

The supplied authentication was invalid.

Input Validation Failed

Example validation response:

HTTP/1.1 403 Forbidden
X-Status-Reason: Validation failed
Content-Type: application/json; charset=utf-8

{
  "success": false,
  "error_message": "The supplied input entity was invalid.",
  "invalid_inputs": [
    {
      "field": "identifier",
      "error": "does not match the regex pattern ^[\\+\\w-]{5,96}$"
    },
    {
      "field": "identifier",
      "error": "must be at least 5 characters long"
    },
    {
      "field": "email",
      "error": "does not match the regex pattern ^\\S+@\\S+$"
    }
  ]
}

The input object was invalid for the reasons explained below.

Not Found

The requested resource was not found.

System Error

This is a fatal error that can not be recovered from. Please contact Tango Card engineering with the error code for assistance.

Resource Exists

The resource that was to be created already exists.

Invalid Resource Entity

The entity provided does not match the content type.

Invalid Accept Content-type

The Accept header did not contain content-types that we could fulfill.

RAAS OC 1003

RAAS OC

RaaS OC errors are catch-all errors that occur during the order process. These may or may not be followed by additional text that further clarifies the nature of the error. Here are some examples:

If you encounter a RAAS:OC:xxxx error and would like additional details, please contact sdk@tangocard.com and include your request and response JSON.

Account

The following is a section of methods related to the platform’s accounts.

Account Resource

Example account resource (scroll down for example request and response):

{
  "identifier":"Account1",
  "customer": "CompanyA",
  "email": "email@companya.com",
  "available_balance": 0
}

Attribute Description
identifier
string
The identifier that will be used to uniquely identify this account.
email
string
The email address for the account.
customer
string
The platform’s customer. A customer is a mechanism for denoting a company, department, etc…, an account belongs to.
available_balance
integer
The available balance for the account.

Create Account

Endpoint:

POST /raas/v1.1/accounts

Example request:

POST /raas/v1.1/accounts HTTP/1.1
Authorization: Basic VGFuF29UZXN0OjV4SXRyM2RNRGxFV0FhOHM0czd2WWg3a1EwMWQ1U0ZlUFCVb1paaUsvdk1mYm8zQSVCdkpMQW1ENHRJPP==
Host: sandbox.tangocard.com
Content-Type: application/json

{
  "customer":"CompanyA",
  "identifier":"Account1",
  "email":"email@companya.com"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: https://sandbox.tangocard.com/raas/v1.1/accounts/123456

{
  "success": true,
  "account": {
    "identifier": "Account1",
    "customer": "CompanyA",
    "email": "email@companya.com",
    "available_balance": 0
  }
}

Create a new platform account.

Arguments

Attribute Description
identifier
string
The identifier that will be used to uniquely identify this account going forward.

These must be unique to the platform, but not globally… for instance: ABC123 could exist for PlatformX and PlatformY without conflicting.

The identifier an be whatever is convenient for the platform as long as it adheres to the following rules:

  • Between 5 and 96 characters in length (inclusive).
  • Must be made up exclusively of: alphanumeric (A-Z, a-z, 0-9), underscore (_), dash (-), or plus (+).
  • Must NOT contain characters invalid in a URI. Examples include, but are not limited to: . , ! &.
  • Spaces are not allowed either. A full account of character rules can be found here.
  • Must be unique to the company.

email
string
The email address for the account.
customer
string
The platform’s customer.

Returns

Returns the created account if successful. Returns an error if something went wrong.

Get Account

Endpoint:

GET /raas/v1.1/accounts/{customer}/{identifier}

Example request:

GET /raas/v1.1/accounts/CompanyA/Account1 HTTP/1.1
Authorization: Basic VGFuF29UZXN0OjV4SXRyM2RNRGxFV0FhOHM0czd2WWg3a1EwMWQ1U0ZlUFCVb1paaUsvdk1mYm8zQSVCdkpMQW1ENHRJPP==
Host: sandbox.tangocard.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "success": true,
  "account": {
    "customer": "CompanyA",
    "identifier": "Account1",
    "email": "email@companya.com",
    "available_balance": 0
  }
}

Get account and balance information.

Arguments

Attribute Description
customer
string
The platform’s customer.
identifier
string
The account identifier.

Returns

Returns an account if successful. Returns an error if something went wrong.

CC Registration

The following is a section of methods related to the platform’s credit card registrations.

Credit card transactions to fund an account will be subject to a 3.5% convenience fee. Fundings via ACH, wire transfer, or check carry no fees.

CC Registration Resource

Example credit card registration resource (scroll down for example request and response):

{
    "cc_token": "33465088",
    "active_date": 1442434992
}

Attribute Description
cc_token
string
Represents your credit card registration. DO NOT LOSE IT, there is currently no way to list registrations.
active_date
timestamp
The unix timestamp representing when this card completes the approval stage.

You can use EpochConverter to decode the timestamp.

Create CC Registration

Endpoint:

POST /raas/v1.1/cc_register

Example request:

POST /raas/v1.1/cc_register HTTP/1.1
Authorization: Basic ...
Host: sandbox.tangocard.com
Accept: */*
Content-Type: application/json

{
  "customer": "CompanyA",
  "account_identifier": "Account1",
  "client_ip": "127.0.0.1",
  "credit_card": {
    "number": "4111111111111111",
    "security_code": "123",
    "expiration": "2016-01",
    "billing_address": {
      "f_name": "FName",
      "l_name": "LName",
      "address": "Address",
      "city": "Seattle",
      "state": "WA",
      "zip": "98116",
      "country": "USA",
      "email": "test@example.com"
    }
  }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "cc_token": "33465088",
    "active_date": 1442434992
}

Create a new credit card registration for a platform user’s account. Save up to 10 credit cards to a each account with our third-party payment partner.

In the sandbox environment the credit card registration delay is set to 5 minutes. The registration delay will be longer in the production environment. In both cases, the duration of the delay will be reflected in active_date.

For Sandbox testing you MUST use the test credit card number 4111111111111111, as reflected in the example. Other fake credit card numbers and valid credit card numbers are not supported in the Sandbox environment.

Arguments

Attribute Description
customer
string
The platform’s customer.
account_identifier
string
The identifier for the platform account to fund.
client_ip
string
The IP address of the person making the purchase.
credit_card
CreditCard
Details of the credit card being used to fund the account.

CreditCard Object

Attribute Description
number
string
The credit card number, preferably numbers only.
expiration
string
The expiration date of the credit card in YYYY-MM format.
security_code
string
The 3 or 4-digit card security code (CVV2, CVC2, or CID).
billing_address
Address
The billing address associated with the credit card.

Address Object

Attribute Description
f_name
string
The first name associated with the customer’s billing address.
l_name
string
The last name associated with the customer’s billing address.
address
string
The billing address. For multi-line addresses append subsequent lines to the first.
city
string
The city of the customer’s billing address.
state
string
The state of the customer’s billing address. Up to 40 characters (no symbols) or a FIPS state alpha code (e.g. AL, WA, etc).
country
string
The country of the customer’s billing address.
email
string
The customer’s email address.

Returns

Returns the credit card registration if successful. Returns an error if something went wrong.

CC Un-Registration

The following is a section of methods related to the platform’s credit card un-registration events.

CC Un-Registration Resource

Example credit card un-registration resource (scroll down for example request and response):

{
    "message": "This card is no longer present in the system."
}

Attribute Description
message
string
Message about un-registration.

Create CC Un-Registration

Endpoint:

POST /raas/v1.1/cc_unregister

Example request:

POST /raas/v1.1/cc_unregister HTTP/1.1
Host: sandbox.tangocard.com
Authorization: Basic ...
Accept: */*
Content-Type: application/json

{
  "customer": "CompanyA",
  "account_identifier": "Account1",
  "cc_token": "33465088"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "message": "This card is no longer present in the system."
}

Un-registering a credit card deletes it from the platform. The card will no longer be available to place orders through the API.

Arguments

Attribute Description
customer
string
The platform’s customer.
account_identifier
string
The identifier for the platform account to fund.
cc_token
string
The payment token issued at registration time.

Returns

Returns the credit card un-registration if successful. Returns an error if something went wrong.

CC Fund

The following is a section of methods related to the platform’s fund events.

Credit card transactions to fund an account will be subject to a 3.5% convenience fee. Fundings via ACH, wire transfer, or check carry no fees.

CC Fund Resource

Example credit card fund resource (scroll down for example request and response):

{
    "fund_id": "115-0934-16",
    "amount": 1000
}

Attribute Description
fund_id
string
The unique ID of the funding event. There is currently no way to list fundings, but the ID may be used when contacting customer support.
amount
integer
The amount in USD cents for the funding event

Create CC Fund

Endpoint:

POST /raas/v1.1/cc_fund

Example request:

POST /raas/v1.1/cc_fund HTTP/1.1
Host: sandbox.tangocard.com
Authorization: Basic ...
Accept: */*
Content-Type: application/json

{
  "customer": "CompanyA",
  "account_identifier": "Account1",
  "amount": 1000,
  "client_ip": "127.0.0.1",
  "cc_token": "33465088",
  "security_code": "123"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "success": true,
  "fund_id": "115-0934-16",
  "amount": 1000
}

Example funding error response:

HTTP/1.1 400 Bad Request
X-Status-Reason: Credit card authorization failure.
Content-Type: application/json; charset=utf-8

{
    "success": false,
    "denial_code": "CC_DECLINED",
    "denial_message": "Credit card declined."
}

Add funds to a platform account.

Arguments

Attribute Description
customer
string
The platform’s customer.
account_identifier
string
The identifier for the platform account to fund.
amount
integer
The amount to add to the account (and thus, charge the credit card), in cents.
client_ip
string
The IP address of the person making the purchase.
cc_token
string
The payment token issued at registration time.
security_code
string
The 3 or 4-digit card security code (CVV2, CVC2, or CID).

Returns

Returns the credit card fund event if successful. Returns an error if something went wrong.

Payment Error (Credit Card)

There was an error processing the credit card.

Attribute Description
denial_code
string
Will be one of the following:
CC_DECLINED: The credit card was declined.
CC_REVIEW: The credit card is being held for review.
CC_ERROR: There was a server error from processor side.
CC_UNKNOWN: There was a system error on the processor side.
CC_DECLINED: There was an error authorizing the credit card.
RAAS:CCFND: Attempting to fund with a card / token combination that is not registered to the specified account or has been cancelled by Tango Card.
CC_DUPEREGISTER: This payment method has already been registered, it can not be added again.
CC_APPROVAL: This card has not finished the approval process and cannot be used yet.
denial_message
string
An error message that CAN be displayed to end-users.

Reward Catalog

The following is a section of methods related to the platform’s reward catalog.

Reward Catalog Resource

Example reward catalog resource (scroll down for example request and response):

{
  "rewards": [
    {
      "description": "Tango Card",
      "image_url": "https://d54ks1x7dxslx.cloudfront.net/graphics/item-images/tango-card-gift-card.png",
      "rewards": [
        {
          "type": "reward",
          "description": "Tango Card E-Custom",
          "sku": "TNGO-E-V-STD",
          "is_variable": true,
          "min_price": 1,
          "max_price": 100000,
          "currency_code": "USD",
          "available": true,
          "countries": ["US"]
        }
      ]
    },
    {
      "description": "Chipotle",
      "image_url": "https://d54ks1x7dxslx.cloudfront.net/graphics/item-images/chipotle-gift-card.png",
      "rewards": [
        {
          "type": "reward",
          "description": "Chipotle Gift Card $5",
          "sku": "CHIP-E-500-STD",
          "is_variable": false,
          "denomination": "500",
          "currency_code": "USD",
          "available": true,
          "countries": ["US"]
        },
      ]
    },
    {
      "description": "iTunes Australia",
      "image_url": "https://d54ks1x7dxslx.cloudfront.net/graphics/item-images/itunes-australia-gift-card.png",
      "rewards": [
        {
          "type": "reward",
          "description": "iTunes Australia Gift Card AUD 10",
          "sku": "APAU-E-1000-STD",
          "is_variable": false,
          "denomination": "1000",
          "currency_code": "AUD",
          "available": true,
          "countries": ["AU"]
        },
      ]
    },
    {
      "description": "Amazon.ca*",
      "image_url": "https://d54ks1x7dxslx.cloudfront.net/graphics/item-images/amazon-ca-gift-card-custom.png",
      "rewards": [
        {
          "type": "reward",
          "description": "Amazon.ca Gift Certificate (Custom)",
          "sku": "AMZCA-E-V-STD",
          "is_variable": true,
          "min_price": 1,
          "max_price": 200000,
          "currency_code": "CAD",
          "available": true,
          "countries": ["CA"]
        }
      ]
    },
  ],
  "xrates": {
    "disclaimer": "Exchange rates are provided for estimation. Actual rates at time of order may vary… etc.",
    "timestamp": 1439402461,
    "rates": [
      {
        "AUD": 1.356359,
        "CAD": 1.30066,
        "CNY": 6.373144,
        "EUR": 0.895154,
        "GBP": 0.639733,
        "JPY": 124.246
      }
    ]
  }
}

Attribute Description
brands
Brand[]
List of Brands making up the catalog.
xrates
ExchangeRates
Object for current exchange rates.

Brand Sub-Resource

Attribute Description
description
string
The brand approved name of the reward (may change over time).
image_url
string
URL to brand image.
rewards
Reward[]
Array of Reward objects for the Brand.

Reward Sub-Resource

Attribute Description
type
string
Denotes whether the catalog item is reward (e-gift card or prepaid card) or a donation (non-profit donation).
description
string
The brand approved name of the reward (may change over time).
sku
string
The unique ID of the reward, used when placing an order.
is_variable
boolean
Denotes whether a brand has a variable range of values (true) or has fixed denominations to choose from (false).

A variable range of values means that a brand can be purchased for any denomination between a minimum value and a maximum value.

  • If a brand is variable, the range is defined, in cents, by min_price and max_price.
  • If a brand is fixed, the face value of the brand is defined, in cents, by denomination

min_price
optional integer
The minimum available value in cents. This property is present only when is_variable is true.
max_price
optional integer
The maximum available value in cents. This property is present only when is_variable is true.
denomination
optional integer
The face value of the reward, in cents. This property is present only when is_variable is false.
currency_code
string
Defines the ISO 4217 currency code for the type of currency used in min_price, max_price, and denomination.

This is not the unit type of value fields: all values are in the lowest fractional currency unit (i.e. cents, yen). For example, a reward with a denomination of 500 and currency_code of USD represents $5.00 in USD.

available
boolean
If the item is currently available. Note: Certain items may continue to show as available: true during periods of short-term supplier interruption where a return to service is expected within a couple hours. As mentioned elsewhere, we recommend an incremental retry method to handle these situations.
countries
string[]
List of 2-letter countries codes that the reward is available in. See ISO 3166-1. This list only contains countries that have a 2-letter ISO code.

ExchangeRates Sub-Resource

ExchangeRates contains international exchange rates to USD. Tango Card updates the exchange rates for non-US items at least once a day. As part of the Get Rewards Catalog method, the API returns the exchange rates currently loaded into our system.

Attribute Description
disclaimer
string
Disclaimer about changing rates.
timestamp
integer
The unix timestamp for when the rates were last updated.
rates
map<string,float>
A hash map of current exchange rates relative to USD indexed by ISO 4217 currency code.

Get Reward Catalog

Endpoint:

GET /raas/v1.1/rewards

Example request:

GET /raas/v1.1/rewards HTTP/1.1
Authorization: Basic VGFuF29UZXN0OjV4SXRyM2RNRGxFV0FhOHM0czd2WWg3a1EwMWQ1U0ZlUFCVb1paaUsvdk1mYm8zQSVCdkpMQW1ENHRJPP==
Host: sandbox.tangocard.com
Accept: */*

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "success": true,
  "brands": [
    {
      "description": "Tango Card",
      "image_url": "https://d54ks1x7dxslx.cloudfront.net/graphics/item-images/tango-card-gift-card.png",
      "rewards": [
        {
          "type": "reward",
          "description": "Tango Card E-Custom",
          "sku": "TNGO-E-V-STD",
          "is_variable": true,
          "min_price": 1,
          "max_price": 100000,
          "currency_code": "USD",
          "available": true,
          "countries": ["US"]
        }
      ]
    }
  ],
  "xrates": {
    "disclaimer": "Exchange rates are provided for estimation. Actual rates at time of order may vary… etc. ",
    "timestamp": 1439402461,
    "rates": [
      {
        "AUD": 1.356359,
        "CAD": 1.30066,
        "CNY": 6.373144,
        "EUR": 0.895154,
        "GBP": 0.639733,
        "JPY": 124.246
      }
    ]
  }
}

Get the current rewards catalog.

Returns

Returns a reward catalog if successful. Returns an error if something went wrong.

Order

The following is a section of methods related to the platform’s orders.

Order Resource

Example order resource (scroll down for example request and response):

{
    "order_id": "115-0992-17",
    "account_identifier": "Account1",
    "customer": "CompanyA",
    "sku": "TNGO-E-V-STD",
    "denomination": {
        "value": 1000,
        "currency_code": "USD"
    },
    "amount_charged": {
        "value": 1000,
        "currency_code": "USD"
    },
    "reward_message": "Way to go, John! Thanks!",
    "reward_subject": "Here is your reward!",
    "reward_from": "Joan From",
    "delivered_at": "2015-09-17T16:49:39+00:00",
    "recipient": {
        "name": "John To",
        "email": "johnto@email.com"
    },
    "reward": {
        "token": "55faef23ec33a2.36972978",
        "number": "7001004001338100213",
        "pin": "345038"
    },
    "external_id": "123456-XYZ"
}

Attribute Description
order_id
string
The id that the order can be referenced by in the future.
customer
string
The customer associated with this account.
account_identifier
string
The account used to place this order.
sku
string
The reward that was purchased.
denomination
Money
The face value of the reward that was purchased.
amount_charged
Money
The value of the reward that was charged for the purchase in USD cents.
reward_message
string
The message (to the recipient) that was associated with this order.
delivered_at
string
When the reward was delivered.
recipient
Recipient
The recipient of the rewards.
reward
optional Reward
A reward object containing reward properties. Only included if send_reward was false when order placed.
external_id
optional string
Optional field that can be used for client-side order cross reference. Will be returned in order response, order details and order history. Tango Card does not perform any validation on this field

Money Object

Attribute Description
value
integer
Amount given in the lowest fractional currency unit (i.e. cents, yen). For example, an amount value of 500 and currency_code of USD represents $5.00 in USD.
currency_code
string
Defines the ISO 4217 currency code for the type of currency that amount represents.

Recipient Object

Attribute Description
name
string
The name of the recipient.
email
string
The email address of the recipient.

Reward Object

Attribute Description
token
string
A token that can be used by Tango Card to look up the reward (will always be included).
number
optional string
The reward’s card number.
pin
optional string
The reward’s card pin.
redemption_url
optional string
The reward’s redemption URL.
event_number
optional string
The reward’s card event number.

Create Order

Endpoint:

POST /raas/v1.1/orders

Example request:

POST /raas/v1.1/orders HTTP/1.1
Authorization: Basic VGFuF29UZXN0OjV4SXRyM2RNRGxFV0FhOHM0czd2WWg3a1EwMWQ1U0ZlUFCVb1paaUsvdk1mYm8zQSVCdkpMQW1ENHRJPP==
Host: sandbox.tangocard.com
Accept: */*
Content-Type: application/json

{
  "customer": "CompanyA",
  "account_identifier": "Account1",
  "campaign": "emailtemplate1",
  "recipient": {
    "name": "John To",
    "email": "johnto@email.com"
  },
  "sku": "TNGO-E-V-STD",
  "amount": 1000,
  "reward_from": "Joan From",
  "reward_subject": "Here is your reward!",
  "reward_message": "Way to go, John! Thanks!",
  "send_reward": true,
  "external_id": "123456-XYZ"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: https://sandbox.tangocard.com/raas/v1.1/orders/115-0992-17

{
  "success": true,
  "order": {
    "order_id": "115-0992-17",
    "account_identifier": "Account1",
    "customer": "CompanyA",
    "sku": "TNGO-E-V-STD",
    "denomination": {
      "value": 1000,
      "currency_code": "USD"
    },
    "amount_charged": {
      "value": 1000,
      "currency_code": "USD"
    },
    "reward_message": "Way to go, John! Thanks!",
    "reward_subject": "Here is your reward!",
    "reward_from": "Joan From",
    "delivered_at": "2015-09-17T16:49:39+00:00",
    "recipient": {
      "name": "John To",
      "email": "johnto@email.com"
    },
    "reward": {
      "token": "55faef23ec33a2.36972978",
      "number": "7001004001338100213",
      "pin": "345038"
    },
    "external_id": "123456-XYZ"
  }
}

Example response for international variable SKU:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: https://integration-api.tangocard.com/raas/v1.1/orders/
Content-Length: 297

{
  "success": true,
  "order": {
    "order_id": "115-09104-17",
    "account_identifier": "Account2",
    "customer": "CompanyA",
    "sku": "AMZDE-E-V-STD",
    "denomination": {
      "value": 500,
      "currency_code": "EUR"
    },
    "amount_charged": {
      "value": 564,
      "currency_code": "USD"
    },
    "reward_message": "Way to go, John! Thank you!",
    "reward_subject": "Here is your reward!",
    "reward_from": "Jerry From",
    "delivered_at": "2015-09-17T23:51:08+00:00",
    "recipient": {
      "name": "Harry To",
      "email": "harryto@email.com"
    },
    "reward": {
      "token": "55fb51f14d3f85.97417356",
      "number": "8B5M-8P8BTG-U3HB",
      "expiration": "2025-09-18"
    },
    "external_id": "123456-XYZ"
  }
}

Example insufficient funds error:

HTTP/1.1 400 Bad Request
X-Status-Reason:  Funding Failed
Content-Type: application/json; charset=utf-8

{
    "success": false,
    "error_message": "Insufficient funds.",
    "available_balance": 0
}

Places a new order for a reward.

Arguments

Attribute Description
customer
string
The platform’s customer.
account_identifier
string
The identifier of the account for whom to place the order.
sku
string
The SKU identifying the reward to be purchased.
recipient
Recipient
The information for the person who is to receive this reward.
amount
optional integer
The desired amount (for variable-priced SKUs) of the reward. Must be present for variable-price SKUs, must not be present for static-price SKUs.

Amounts must be given in the lowest fractional currency unit (i.e. cents, yen, etc…) in the SKUs currency. For example, a reward with denomination of 500 and currency_code of USD represents $5.00 in USD, not $500.00.

The USD cent value is calculated using the following formula: usdCents = amount / (10 ^ currencyExponent) / rate * 100

Current exchange rates can be obtained through the Reward Catalog resource.

Example calculation:

The USD value for a given amount of 1000 in JPY currency (exponent = 0) with exchange rate 123.19 can be calculated as follows:

usdDollars = amount / (10 ^ currencyExponent) / rate
= 1000 / (10 ^ 0) / 123.19
= 8.12

reward_subject
optional string
An optional subject line for the reward email.
reward_message
optional string
The message (to the recipient) that was associated with this order.
reward_from
optional string
An optional ‘from name’ to display to the recipient.
send_reward
optional boolean
Whether Tango Card should send the reward. If this is false the returned object will contain the order details. Defaults to true.
campaign
optional string
E-mail template to use for reward e-mail.
external_id
optional string
Optional field that can be used for client-side order cross reference. Will be returned in order response, order details and order history. Tango Card does not perform any validation on this field

Returns

Returns the created order if successful. Returns an error if something went wrong.

For international variable SKUs, there will be an expiration date (“expiration”) in the successful response, if applicable. The format for expiration date is ISO6801 standard date format, example: 2016-06-19 (Year-Month-Day).

*Expiration dates in email templates will appear in localized format, for example: 2016-06-19 could be 2016年6月19日. We are using this PHP library to format international dates: http://php.net/manual/en/class.intldateformatter.php

Insufficient Funds Error

There were not enough funds available in the account to cover the cost of the order.

Attribute Description
error_message
string
A debug message (description of what was not found).
available_balance
integer
The currently available funds for the account.

Get Order

Endpoint:

GET /raas/v1.1/orders/{order_id}

Example request:

GET /raas/v1.1/orders/115-0992-17 HTTP/1.1
Authorization: Basic VGFuF29UZXN0OjV4SXRyM2RNRGxFV0FhOHM0czd2WWg3a1EwMWQ1U0ZlUFCVb1paaUsvdk1mYm8zQSVCdkpMQW1ENHRJPP==
Host: sandbox.tangocard.com
Accept: */*

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "success": true,
  "order": {
    "order_id": "115-0999-17",
    "account_identifier": "Account2",
    "customer": "CompanyA",
    "sku": "AMZN-E-V-STD",
    "denomination": {
      "value": 2500,
      "currency_code": "USD"
    },
    "amount_charged": {
      "value": 2500,
      "currency_code": "USD"
    },
    "reward_message": "You're awesome! Keep it up!",
    "reward_subject": "Here is your reward!",
    "reward_from": "Jane From",
    "delivered_at": "2015-09-17T17:19:31+00:00",
    "recipient": {
      "name": "Jake To",
      "email": "jaketo@email.com"
    },
    "reward": {
      "token": "55faf623e97603.25696715",
      "number": "AR3E-T74NRL-VVQQ"
    },
    "external_id": "123456-XYZ"
  }
}

Retrieves an existing order.

Arguments

Attribute Description
order_id
string
The order’s ID.

Returns

Returns an order if successful. Returns an error if something went wrong.

List Orders

Endpoint:

GET /raas/v1.1/orders?arguments

Example request:

GET /raas/v1.1/orders?customer=CompanyA&account_identifier=Account2&offset=0&limit=10&start_date=2015-09-01T00:00:00&end_date=2015-10-01T23:59:59 HTTP/1.1
Authorization: Basic VGFuF29UZXN0OjV4SXRyM2RNRGxFV0FhOHM0czd2WWg3a1EwMWQ1U0ZlUFCVb1paaUsvdk1mYm8zQSVCdkpMQW1ENHRJPP==
Host: sandbox.tangocard.com
Accept: */*

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "success": true,
  "offset": 0,
  "limit": 10,
  "start_date": "2015-09-01T00:00:00",
  "end_date": "2015-10-01T23:59:59",
  "result_count": 1,
  "total_count": 1,
  "orders": [
    {
      "order_id": "115-0999-17",
      "account_identifier": "Account2",
      "customer": "CompanyA",
      "sku": "AMZN-E-V-STD",
      "denomination": {
        "value": 2500,
        "currency_code": "USD"
      },
      "amount_charged": {
        "value": 2500,
        "currency_code": "USD"
      },
      "reward_message": "You're awesome! Keep it up!",
      "reward_subject": "Here is your reward!",
      "reward_from": "Jane From",
      "delivered_at": "2015-09-17T17:19:31+00:00",
      "recipient": {
        "name": "Jake To",
        "email": "jaketo@email.com"
      },
      "external_id": "123456-XYZ"
    }
  ]
}

List existing orders.

Arguments

Attribute Description
start_date
optional string
Start date (ISO 8601) of orders.
end_date
optional string
End date (ISO 8601) of orders.
offset
integer
How far into the result set to start.
limit
integer
How many to return (maximum of 100).
account_identifier
string
Filter to only a single platform account.
customer
string
Filter only to a single customer.

Returns

Returns a collection of orders matching criteria if successful. Returns an error if something went wrong.

Reward E-mail Resend

Endpoint:

POST /raas/v1.1/orders/{order_id}/resend

Example request:

POST /raas/v1.1/orders/123-12345678-12/resend HTTP/1.1
Authorization: Basic VGFuF29UZXN0OjV4SXRyM2RNRGxFV0FhOHM0czd2WWg3a1EwMWQ1U0ZlUFCVb1paaUsvdk1mYm8zQSVCdkpMQW1ENHRJPP==
Host: sandbox.tangocard.com
Accept: */*

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true
}

Example 24-hr limit error response:

HTTP/1.1 403 Forbidden
X-Status-Reason: Validation failed
Content-Type: application/json; charset=utf-8

{
    "success": false,
    "error_message": "Cannot send more than once every 24 hours (last send at 2015-02-18T20:17:31+00:00)"
}

Example unable to send reward error response:

HTTP/1.1 403 Forbidden
X-Status-Reason: Validation failed
Content-Type: application/json; charset=utf-8

{
    "success": false,
    "error_message": "Unable to resend requested reward."
}

The Resend functionality allows Tango Card RaaS API Platform partners to resend reward emails to the original recipient on demand. This may be useful if a recipient reports that they never received or cannot find a reward email.

Rules & Important Notes

  1. Resend is not supported for emails originally sent prior to February 18, 2015.

  2. The target order (to be resent) must have been sent with the send_reward property set to true (the default value). This means Tango Card sent the original email. If it was false we cannot resend the email because we never sent the original.

  3. Orders can be resent once every 24 hours. This is reflected in the error message timestamp if a second attempt is made less than 24 hours after the last send.

  4. Resend functionality does not have to be specific to a RaaS account. The Resend functionality occurs at the platform level of the RaaS integration.

  5. You will need the original order number in order to perform the resend. The Tango Card Order History call allows for a search of past orders and includes the order number for order result.

  6. Orders can only be resent to the original recipient. If an administrator needs to verify reward information for a given order, consider using the Get Order Information call instead of the Resend a Reward Email call.

  7. Resending an email does not guarantee delivery. If the recipient does not receive an email due to spam filter settings, corporate firewalls, etc. resending an email will not get them their reward. The underlying problem will need to be determined and resolved.

Arguments

Attribute Description
order_id
string
The order’s ID.

Returns

Returns an success if successful. Returns an error if something went wrong.

24-hr Limit Error

Cannot send more than once every 24 hours Resend functionality is limited to once every 24 hours per order. The 24 hour period starts at the last recorded sent time in UTC.

Unable To Send Reward Error

If Tango Card cannot resend the reward for a reason other than listed above we will provide a generic error. One example cause for this error would be if Tango Card was not configured to send the email in the original order (send_reward flag was set to false).