Implementation Notes

Idempotent External Reference ID

The External Reference ID (externalRefID) is an optional idempotent field, meaning we will allow one unique order per External Reference ID used. Subsequent requests using the same External Reference ID will not create a new order but will return the original order information, even if the original order was for a different item.

IDs may have a maximum of 100 alphanumeric characters.

If an externalRefID is not provided, the X-REQUEST-ID that is included in the response header for the transaction can be used as a reference should it be necessary to contact Tango Card for support on the status of an order.

Idempotency is enforced at the account level. We will not check for ID uniqueness in other accounts, even those under the same Platform or Customer.

🚧

Tango Card makes no claim of idempotency support after 90 days from the original order.

Customers wishing to use a non-idempotent field for notes are directed to use the optional 'notes' field.

Handling Reward Types

Tango Card returns the following types of reward credentials. If your integration requires displaying reward data in app or creating custom reward emails you may need to add logic to parse the returned reward data correctly.

Reward Type

Description

Integration Example

text

Plain Text

Wrap in a <span> tag

url

URL to a reward landing page

Wrap in an <a> tag

barcode

URL for a barcode image

Add an <img> tag

date

ISO datetime

Display in localized date format based on locale of reward according to RFC 3339, i.e. "2016-01-01T00:00:00Z".

credentialType New (July 2018)
To better assist our customers with parsing & display of reward data, we have added the credentialType key to the credentialList object in the order response.

  • A list of available credential types can be found with a GET .../raas/v2/credentialtypes call.
  • We have also updated GET .../raas/v2/catalogs to provide the credential types information for each item in the catalog.

Please note that the categorization of credentialType(s) is based on internal factors of the Tango Card system and many of the definitions found in the GET .../raas/v2/credentialtypes call will have similar or identical definitions.

📘

We are continuously expanding our catalog and it is likely that new reward types will arise over time. For this reason we recommend a fallback / default to handle unspecified types as text.

RESTful Practices

We strive to follow standard conventions whenever possible, but in a few select cases we have chosen to deviate from standard practice in order to provide better customer value. One example of this is that our Create Customer and Create Account calls will return back the created fields rather than just a 200 code. Standard RESTful practice would dictate we return only a 200, we have chosen to return the created information along with additional parameters like the created at time and the current balance (always $0 at time of account creation) because we believe these are are more helpful than strictly adhering to the RESTful rule. We welcome your feedback on these decisions.

POST calls / 403 Forbidden errors

We do not allow clients to use browsers to make POST calls. Instead, we recommend using non-browser tools for POST calls.

Designing for Change in your Catalog

Platforms creating a customer-facing catalog should bear in mind that reward parameters may change from time to time. Brands often update their images, description, terms, redemption instructions and sometimes even their names and available denominations. For this reason, please use the UTID and Brand Key as your primary identifier for programmatic decisions.

Email Delivery

Sending Emails

Use the sendEmail field to specify whether whether or not Tango Card should deliver a reward email to the recipient.

Custom Email Templates

Tango Card can create a customized email template at the Platform, Customer or Account level. Your Tango Card CSM can provide additional details.

Campaigns

In addition to supporting custom templates at the Platform / Customer / Account levels, Tango Card supports one-off email templates that can be called by the optional "campaign" field. Contact your Tango Card CSM for details.

HTML Use

Tango Card provides HTML-formatted brand and reward information in our method responses with the aim of minimizing integration design time. Please note that security concerns dictate that we escape any HTML input in POST operations.

Responses

JSON is the only currently-supported content type for inputs or outputs. It is not required that the requests contain an Accept header, but if they do it should contain application/json or /.

👍

All dates must be represented in a format that is compatible with ISO 8601 (for example:2013-02-21T20:37:07-07:00).

Fields in the RaaS API response objects may be added at any time. This means that whatever is used to unmarshal the JSON responses into native data types needs to be able to handle unknown fields without failing.

Versioning

All API calls specify the version in the endpoint URL.

The following changes are considered backward-compatible and may be introduced without producing a new API version:

  • Adding new API methods
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.