Best practices
Idempotent external reference ID
External Ref ID externalRefID
is an optional idempotent field. We allow one unique order per External Reference ID. Subsequent requests using the same External Reference ID does not create a new order, but returns the original Order information even if the original order is for a different item.
- IDs have a maximum of 100 alphanumeric characters.
- If an
externalRefID
is not provided, theX-REQUEST-ID
included in the response header for the transaction is used as a reference when you contact Tango support on the status of an order. - Idempotency is enforced at the account level. We do not check for ID uniqueness in other accounts even if they are under the same platform or customer.
- If you wish to use a non-idempotent field for notes, we recommend you use the optional Notes field.
- Order requests receiving a 5XX error may occasionally process after a network connection is lost. We strongly recommend you make use of the External Reference ID idempotent parameter to ensures duplicate orders are not created when you retry a failed order.
Note:
Tango does not support idempotency after 90 days from the original order.
Handle reward types
Tango 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 | Credential Type | Integration example |
---|---|---|---|
text | Plain Text | cardNumber, PIN, securityCode, claimCode, etc. | Wrap in a <span> tag |
url | URL to a reward landing page | redemptionUrl, securityUrl | Wrap in an <a> tag |
barcode | URL for a barcode image | barcode | Add an <img> tag |
date | ISO datetime | expirationDate | Display in localized date format based on locale of reward according to RFC 3339, i.e. "2016-01-01T00:00:00Z". |
Use credential type
Use credentialType
key in credentialList
in the Order response for better parsing and display of reward data.
- A list of available credential types can be found with a
GET {URI}/credentialtypes
call. - We have also updated
GET {URI}/catalogs
to provide the credential types information for each item in the catalog.
Note:
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.
The categorization of credentialType(s) is based on internal factors of the Tango system. Many of the definitions found in the
GET {URI}/credentialtypes
call have similar or identical definitions.
Avoid browser-based API calls
We do not allow browsers to POST calls. Attempts to do so, will result in an authorization error (403.001).
For best practices, we recommend you to use non-browser tools for all API calls.
Design for change in your catalog
API users that create their own in-app Catalog should keep 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. Use the UTID and Brand Key as your primary identifier for programmatic decisions.
Avoid HTML input in POST operations
Tango provides HTML-formatted brand and reward information in our method responses with the aim of minimizing integration design time. For security concerns, we escape any HTML input in POST operations.
About responses
- JSON is currently the only supported content type for inputs or outputs. It is not required that the requests contain an Accept header, but if they do, it must 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.
- Tango can add fields in the Tango API response objects at any time. What you use to unmarshal the JSON responses into native data types must handle unknown fields without failing.
Updated about 1 month ago