API Functionality

๐Ÿ“˜

  • The RaaS v2 API is a RESTful JSON API
  • Authentication is handled via HTTP Basic Auth

Primary Functions

Catalog

Calls that allow you to view the items in your catalog, along with the details you will need for ordering items and displaying item information.

UTID: Unique Tango ID {{utid}} - the item being ordered (Gift Card/NPO Donation)

{
  "brands": [
    {
      "brandKey": "{{brandKey}}",
      "brandName": "{{brandName}}",
      "items": [
        {
          "countries": [
            "{{countries}}"
          ],
          "credentialTypes": [
            "{{credentialTypes}}"
          ],
          "currencyCode": "{{currencyCode}}",
          "exchangeRateRule": "{{exchangeRateRule}}",
          "faceValue": 0,
          },
          "isWholeAmountValueRequired": boolean,
          "maxValue": 0,
          "minValue": 0,
          "redemptionInstructions": "{{redemptionInstructions}}",
          "rewardName": "{{rewardName}}",
          "rewardType": "{{rewardType}}",
          "utid": "{{utid}}",
        }
      ],
    }
  ],
  "catalogName": "{{catalogName}}"
}

Catalog Endpoint Filters

๐Ÿ“˜

Use Endpoint Filters to call details for specific items or groupings

Use the specific values from your GET /catalogs response

GET /catalogs?utid={{utid}}

  • return the details for a specific item (utid)

GET /catalogs?brandKey={{brandKey}}

  • return all the items and details for a specific brand

GET /catalogs?currencyCode=*{{currencyCode}}

  • return items of a specific currency

GET /catalogs?country=((2-digit country code))

  • return items from a specific country; the value can be found in the 'countries' collection

Customers

Calls pertaining to the creation and viewing of Customers (Groups) on the platform. Includes details for all Customers and Accounts under a platform but does not include balance and contact information for the Accounts.

GET https://integration-api.tangocard.com/raas/v2/customers/{{customerIdentifier}}

Accounts

Calls that allow you to get detailed information, such as balance, for the Accounts in your platform.

Funding

Calls pertaining to the registering, funding and un-registering of credit cards.

Orders

Calls pertaining to creating, viewing and resending orders.

๐Ÿ“˜

Displaying and Delivering Rewards to Recipients

When "sendEmail" is set to "false" placing orders, Tango Card does NOT deliver a reward email.

  • It is our clients' responsibility to deliver rewards when "sendEmail=false".
  • Note: For the best data mapping experience, inspect the 'credentialList' array under the 'reward' block.
  • 'credentials' is a legacy parameter with no data mapping key/value pairs
  • 'credentialList' contains 'type', 'label', and 'value', stable parameters that allow our clients to display rewards within an application or by email.
"reward": {
    "credentialList": [
      {
        "credentialType": "{credentialType}",
        "label": "{lable}",
        "type": "{type}",
        "value": "{value}"
      }
    ],
    "credentials": {},
    "redemptionInstructions": "{redemptionInstructions}"
  },
  "rewardName": "{rewardName}",
  "sendEmail": false,

Line Items

Orders consist of one or more line items. Each line item represents a single gift card, reward, disbursement, or promotional link and has its unique reference number, customer's first name, last name, email address, dollar amount, etc. Each line item can be managed separately when a request fails due to an undeliverable email or a misspelled recipient's name, for example.

You can use these endpoints to page through or filter a list of line items, including their non-sensitive details and reward status. You can also view details for a specific line item, including sensitive details, reward history, redemption history, or resend a specific line item.

EndpointsDescription
GET /lineItemsGet a paged list of line items
GET /lineItems/{referenceLineItemId}Get details for a specific line item
POST /lineItems/{referenceLineItemId}/resendsResend a specific line item

Refer to Sample API lineItems for detailed information

Email Templates

Calls pertaining to creating, viewing, updating and deleting email templates for reward delivery.

Additional Functions

Exchange Rates

Provides a list of exchange rates currently set in the Tango Card system. Can be used for calculating the cost of international rewards.

Health Check

The '/pulse' endpoint is available to determine whether the system is healthy, confirmed by a 200 OK response.