1. Rewards as a Service (RaaS®) API
Overview and Best Practices
1

2. Contents
Intro (3)
- Tango Card and RaaS API Intro (4)
- RaaS API Test Console (5)
- Rewards Genius Dashboard Overview (6)
- RaaS API Structure Definitions (7)
- RaaS API Structure Use (8)
- RaaS API Structure – 1 to 1 Account (9)
- RaaS API Structure – Multi Account (10)
API Methods (11)
- Customer Methods (12)
- Account Methods (13)
- Fund Methods (14)
- Catalog Method (15)
- Order Methods (16)
- Email Methods (17)
Implementation Best Practices (18)
- International Programs (19)
- Security and Authentication (20)
- Handling Responses (21)
- Behind the Scenes Best Practices (22)
- Getting Started & Brand Approvals (23)
Design Best Practices (24)
- Catalog Setup (25)
- Reward Checkout (26)
- Reward Delivery – Tango Card Sends Email (29)
- Reward Delivery – Present in app (30)
- Reward Delivery – Customer Sends Email (32)
- Funding (33)
- Reporting (36)
2

3. Intro
3

4. Tango Card and RaaS API Intro
Tango Card
Mission: To make rewards easy to send and awesome to receive.
Our Focus: Help our partners achieve meaningful business results.
Key Areas of Differentiation: Reward Catalog, Delivery Technology, Expert Support
Use the Rewards as a Service API to create a modern and engaging reward program in your app or platform.
Platform Support. The RaaS API allows you to organize your integration to support a single program or multiple
programs for multiple customers on your platform.
Catalog as a Service. Access our catalog of e-gift cards, prepaid cards, donations and more! Additionally, our verbose
catalog contains descriptions, disclaimers, reward images, and other necessary brand details—everything you need to
integrate a full catalog into your app or platform.
Automate and Deliver Rewards. Real time reward ordering and delivery on branded email templates or delivery of
reward codes for presentation in your UX.
4

5. RaaS API Test Console
Our API Test Console is an excellent tool for viewing all calls, planning, and testing your
integration with the RaaS API.
Available at https://integration-www.tangocard.com/raas_api_console/v2/
5

6. Rewards Genius™ Overview
Rewards Genius is our self-serve reward ordering and account management dashboard.
You can manage several aspects of your integration via Rewards Genius:
• Create and manage groups (customers) and accounts
• Create and manage email templates
• Fund accounts and view funding history
• View order history and email tracking
• Generate order history reports
• Resend rewards
6

7. RaaS API Platform Structure – Definitions
The RaaS API has three organizational levels–Platform, Customer, and Account.
Platform: This is the entity that has the direct relationship with Tango Card and is
performing the integration. In all instances there is only one platform.
Authentication requires Platform Name and Platform Key.
Customer (Group): The customer or group level is used to differentiate between
different customers on one platform. This allows customers to manage their own
accounts, funds, reward catalogs, email templates, etc.
The term “customer” is interchangeable with “group”. We refer to customer in the RaaS
API and group in the Rewards Genius dashboard.
Account: The account level is specifically used to hold the funds that reward orders will
draw from. You can create multiple accounts per customer to differentiate budgets.
7

8. RaaS API Platform Structure – Use
These levels are meant to support different integration use cases. There are two primary distinctions between how
RaaS API customers leverage the organizational levels:
• 1 to 1 Account (1 platform, 1 customer, 1 account): We see two main single customer use cases:
1. The 1 to 1 account will be using the API to build their own rewards program.
2. The 1 to 1 account is managing funding for multiple users.
• Multi Account (1 platform, multiple customers, multiple accounts): The main use of multi account implementations
is to give your users the ability to manage their own rewards program through your UX.
8

9. RaaS API Platform Structure – 1 to 1
If you are the sole customer for this integration or if you are planning on managing your
customers’ money, than the 1 to 1 structure is for you.
9

10. RaaS API Platform Structure – Multi Account
If you are planning on multiple customers leveraging your integration, then you’ll need
to set up multiple customers.
If you’re planning on differentiating between budgets, then you can have multiple
accounts per customer.
10

11. API
Methods[see Test Console for details]
11

12. Customer Methods
Customer Methods. The customer or group level is used to differentiate between different customers on one
platform. This allows customers to manage their own accounts, funds, reward catalogs, email templates, etc.
With the Customer Methods you can:
- (Post) Create new Customers on your Platform
- (Post) Create Accounts for Customers on your Platform
- (Get) Get a list of all Customers on your Platform
- (Get) Get details for a specific customer on your Platform
- (Get) Get a list of all Accounts for a Customer on your Platform
Notes:
- A Customer/Group is a way of organizing Accounts.
- If you will have only one Account you will only need to create one Customer.
- If you have multiple Accounts you may want to create multiple Customers under which you can group like
Accounts.
- Note! In our Rewards Genius Portal "Customer" has been renamed to "Group“ – and these terms are
interchangeable.
- Our API endpoints still refer to this level as "Customer".
12

13. Account Methods
Account Methods. The account level is specifically used to hold the funds that reward orders will draw from. You can
create multiple accounts per customer to differentiate budgets.
With the Account Methods of the RaaS API you can:
- (Get) Get a list of Accounts on your Platform
- (Get) Get details for a specific Account on your Platform
Notes:
- We'll set up your platform and provide you with the access credentials.
- Once you have your credentials, you can use the API to create Customers and Accounts according to your
desired platform configuration.
- An Account must be associated with a Customer.
13

14. Fund Methods
Fund Methods. Use the Funds Methods of the RaaS API to allow your users to register credit cards and fund
accounts. Credit Cards come with a 3.5% fee – discuss with your BD/CSM team.
With the Fund Methods of the RaaS API you can:
- (Post) Register a new credit card on an Account
- (Post) Unregister a credit card from an Account
- (Get) Get a list of registered credit cards on your Platform
- (Get) Get details for a specific credit card on your Platform
- (Get) Get details for all credit cards on your Platform
- (Get) Fund an account. Create a deposit to and Account from a registered credit card
14

15. Catalog Method
Catalog Method. The Catalog Method of the RaaS API are meant to give you the ability to integrate a reward catalog
into your UX.
With the Catalog Method of the RaaS API you can:
(Get) Get all of the reward items in your Platform's catalog—contains details you’ll need for displaying your catalog
and ordering from your catalog.
Reward items contain:
- Brand Name, Images, Descriptions, and Disclaimers
- Available denominations
- Countries and Currency
- Item ID (UTID) for ordering
Notes:
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.
15

16. Order Methods
Order Methods. Use the order methods of the Raas API to place orders from your catalog, resend previously placed
orders, and get order history.
With the Order Methods of the RaaS API you can:
- (Post) Place an Order from an Account
- (Post) Resend an Order previously placed from an Account (*Idempotentcy available)
- (Get) Get a list of Orders placed on your Platform
- (Get) Get details for a specific Order on your Platform
Notes:
Field definitions - minimums for placing an order:
accountIdentifier - specify the account this order will be deducted from
amount - specify the face value of the reward. Always required.
customerIdentifier - specify customer (group) associated with the accountIdentifier
sendEmail - should Tango Card send the email to the recipient?
recipient - email - required if sendEmail is true
recipient - firstName - required if sendEmail is true
utid - the unique identifier for the reward you are sending as provided in the Get Catalog call
etid - Optional. The unique identifier for the email template you would like to use. Only applicable if sendEmail is true. If you don’t have a custom
template defined we will return our default template ID: E000000.
*Idempotentcy available to avoid reordering duplicate rewards. Use externalRefId field. 16

17. Email Methods
Email Methods. Use the emal methods of the Raas API to configure email templates and maintain branding for your
UX or maintain your customers’ branding throughout the reward experience.
With the Email Methods of the RaaS API you can:
- (Get) Get a list of all Email Templates on this Platform
- (Post) Create a new email template
- (Delete) Delete a specific Email Template on this Platform
- (Get) Get details for a specific Email Template on this Platform
- (Patch) Update details for a specific Email Template on this Platform
Notes:
17

18. Implementation
Best Practices
18

19. Best Practices International Reward Programs
- Expiration Dates
- For international items (load value other than USD), 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日.
- Exchange Rates
- Use the GET .../catalogs Call to determine the applicable faceValue of non-USD currencyCode items.
- Use the GET .../exchangerates method to find the corresponding exchange rate currently loaded for that
item.
- Calculate the cost of the item using the reward face value and baseFx
- Countries and Currencies
- ‘currencyCode’ is a parameter in the GET /catalogs response, represents the currency to the end recipient
- ‘countries’ is a parameter in the GET /catalogs response, represents the countries in which the code may be
redeemed
- Order Response
- "amountCharged“ will contain "value“ (face value in local currency), "currencyCode“ (the local currency for
the end recipient, "exchangeRate“ (the baseFx) and "total” (the amount charged to you in USD)
19

20. - 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. We recommend you add the Certificate
Authorities (CA’s) cert to your system’s trusted list.
- Certificate Authority
- 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.
- Cross-site Scripting (XSS) and Malicious Behavior
- Tango Card may reject requests based on content or behavior that could be exploitative in nature.
This includes requests containing insecure characters or not consistent with OWASP Top 10
guidelines.
- Protect your platform keys
- NEVER transmit your platform keys via email or any other unsecured method. Design your system
to allow for routine key changes. Change your keys immediately when employees who had access
to the keys leave. If you suspect any suspicious activity on your platform, change your keys.
Best Practices for Security and Authentication
20

21. Handling RaaS API Response Status Codes
Response Handling recommendations:
2xx - Successful
3xx - Log response, report To Tango Card
4xx errors - Log response, fix the request and manually retry
5xx errors - Log response, implement an automated retry mechanism that is
capped at 5 requests.
Note that error class responses will also include descriptive text further
explaining the nature of the error.
Refer to our documentation for additional info on response.
21

22. Protect your platform keys – NEVER transmit your platform keys via email or any other unsecured method.
Design your system to allow for routine key changes. Change your keys immediately when employees who
had access to the keys leave. If you suspect any suspicious activity on your platform, change your keys.
Incremental retry - Network vagaries, infrastructure and supplier factors mean occasional network errors
are inevitable and must be planned for. For this reason, we strongly 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. FIND A LINK
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.
Parsing – Please take note of our Versioning and build your implementation accordingly. When possible,
we will add additional functionality to the current version of the API in order to better serve existing
customers.
Recommended Behind the Scenes Best Practices
22

23. Getting Started & Brand Approvals
Components to Launching with the RaaS API:
- Meet and Discuss Integration Plan (Both)
- Receive Sandbox Credentials (Tango Card sends)
- API integration (You complete)
- *Brand Approval/UI review/Email Templates Creation (Tango Card completes)
- Sandbox Testing (Both)
- Receive Production Credentials (Tango Card sends)
- Production Testing (Both)
- Customer support planning – who is first tier, proper contact info (Discuss)
- Finance planning – account funding/invoicing/reporting – funding in app/platform? (Discuss)
*Brand Approval is very important:
- Our brand partners are very protective of their brands (Amazon.com, iTunes, The Home Depot, etc.)
- There are certain brands that will need extra approval of:
- Your use case
- Your UI/UX
- Your CSM will facilitate all approvals.
23

24. Design
Best Practices
24

25. Best Practices for Catalog Setup
Available Balance
Reward category options
Crisp, current brand images
Progress to earning rewards
25

26. Best Practices for Reward Checkout (1/3)
Display:
- Brand name
- Image
- Description
- Available denoms
- Disclaimer
Employ cart
functionality if
enabling multiple
reward redemptions
in one transaction
26

27. Best Practices for Reward Checkout (2/3)
Provide a clear order review
step. Include:
- Card(s) chosen
- Total value to be redeemed
- Name of intended recipient
- Email of intended recipient
- Acknowledgment of next
steps
27

28. Best Practices for Reward Checkout (3/3)
Provide a clear order
confirmation step.
Include:
- Returned Reference Order #
- Clear next steps
- If applicable: contact info for
Tango Card Customer Service
28

29. Best Practices for Standard Reward Delivery
In most cases best practice will be to
have Tango Card deliver the reward.
Rewards are delivered on a branded
email template as soon as an Order call is
placed.
You can also configure email templates
via the RaaS API. All information
requirements can be found in the test
console:
https://integration-
www.tangocard.com/raas_api_console/v2
/
Email Templates > POST /emailTemplates
- Name the template
1) Header Image & Accent
- 300dpi, 1200x279px
- JPEG, PNG
- Alt text
- Accent HEX Code
2) Messaging:
- From name
- Subject
- Body Message
- Closing Message
- Customer Service Info
29

30. Best Practices for In App Reward Delivery – Details (1/2)
Reward Image, name, and
amount
Reward number or URL
Links and instructions to spend
reward
Contact info for assistance
Proper brand disclaimers
30

31. Best Practices for In App Reward Delivery – History (2/2)
Total Redeemed
Reward image and amount
Reward ID, Date and link to
details
General disclaimers
31

32. Best Practices for Reward Delivery – Customer Emails
Brand the template to maintain
user experience
Reward image, amount and
number
Links and instructions to spend
reward
Contact info for assistance
Proper brand disclaimers
From: Your Brand
Subject: Your [reward brand] card from [your brand] has arrived
32

33. Notes on Funding with Credit Card (1/3)
Credit Card Funding costs a 3.5% convenience fee.
Best Practice is ACH and we have simple methods outside of the API for adding funds.
[Link to/share funding document]
33

34. Best Practices for Fund Method – Register Card (2/3)
Include:
- Language of what to expect
- Specific Account selected
- 24 hour registration notice
34

35. Best Practices for Funding – Fund Account (3/3)
Include:
- Current balance
- Specific Account selected
- List of available credit cards
35

36. Best Practices for Reporting - Simple
Include:
- Date select
- Choose or give permission
for Platform, Customer,
Account level reporting
- Spreadsheet download
36