Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

RaaS API Overview and Best Practices

326 views

Published on

The Rewards as a Service (RaaS) API is a robust digital gift card API built to power rewards and incentives in today’s apps and platforms.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

RaaS API Overview and Best Practices

  1. 1. Rewards as a Service (RaaS®) API Overview and Best Practices 1
  2. 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. 3. Intro 3
  4. 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. 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. 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. 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. 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. 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. 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. 11. API Methods[see Test Console for details] 11
  12. 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. 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. 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. 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. 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. 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. 18. Implementation Best Practices 18
  19. 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. 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. 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. 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. 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. 24. Design Best Practices 24
  25. 25. Best Practices for Catalog Setup Available Balance Reward category options Crisp, current brand images Progress to earning rewards 25
  26. 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. 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. 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. 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. 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. 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. 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. 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. 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. 35. Best Practices for Funding – Fund Account (3/3) Include: - Current balance - Specific Account selected - List of available credit cards 35
  36. 36. Best Practices for Reporting - Simple Include: - Date select - Choose or give permission for Platform, Customer, Account level reporting - Spreadsheet download 36

×