# Tango API > Rewards and incentives platform API for integrating digital and physical gift cards, prepaid cards, and other rewards into your application. **Quick Links:** [Tango Website](https://www.tangocard.com/) | [Developer Center](https://developers.tangocard.com/) | [Sandbox Signup](https://portal.sandbox.tangocard.com/#/signup) | [API Reference](https://developers.tangocard.com/reference/setup) ## Overview The Tango API is a RESTful API that enables businesses to integrate a global reward and incentive program into their applications. It provides access to thousands of digital and physical gift cards, prepaid cards, and other reward options that can be delivered via email, SMS, physical mail, or embedded directly into your application. **About Tango:** Tango Card, a division of Blackhawk Network (BHN), is a leading global rewards and incentives platform. We power reward programs for businesses of all sizes, from startups to Fortune 500 companies, delivering digital and physical rewards to millions of recipients worldwide. - **Tango Website:** https://www.tangocard.com/ - **Developer Center:** https://developers.tangocard.com/ - **Blackhawk Network (Parent Company):** https://blackhawknetwork.com/ **Key Capabilities:** - Browse and search a catalog of thousands of digital and physical rewards from top brands worldwide - Create and manage customer accounts with multi-currency support - Place orders for rewards with multiple delivery methods (email, SMS, physical mail, embedded) - Manage order lifecycle including freeze, cancel, and reissue operations - Set up webhooks for real-time order status notifications - Create custom email and digital templates for branded reward delivery - Support for both synchronous and asynchronous order processing **New to Tango?** Start with the [Getting Started](#getting-started) section below to sign up for a free sandbox account and begin testing within minutes. ## Getting Started ### Self-Service Signup Tango offers free self-service signup for both US and international users. You can start testing immediately and move to production after completing verification. #### Signup Options **1. US Production Signup** - URL: https://tango-portal.tangocard.com/vue/#/signup - For US-based businesses ready to use Tango in production - Requires business verification (KYB process) **2. Sandbox/Testing Signup** (Recommended for Development) - URL: https://tango-portal.sandbox.tangocard.com/vue/#/signup - Free testing environment with test gift cards - No business verification required - Perfect for integration development and testing **3. International Signup** - URL: https://www.tangocard.com/intnl-form - For businesses outside the United States - Requires business verification #### Signup Process 1. **Complete Registration Form** - Enter your name, work email, and company name - Describe how you plan to use Tango - Submit the form 2. **Account Activation** - You'll receive an invitation to the Tango Portal - Set up your password and log in - For production accounts: KYB (Know Your Business) verification may take up to 48 hours 3. **Access API Credentials** - Log in to the [Tango Portal](https://portal.tangocard.com) - Navigate to **Team Settings > API Credentials** - **Important:** API Credentials may not be immediately available due to KYB verification - If you don't see API Credentials after 48 hours, contact: - Your Customer Success Manager (CSM), or - Email: devsupport@tangocard.com 4. **Create OAuth Credentials** (See Authentication section below) - Create OAuth Client Credentials - Create OAuth Service Account - Use these to acquire API tokens #### Testing Options **Public Test Console:** - URL: https://developers.tangocard.com/reference/setup - Uses default credentials for quick testing - Do not enter proprietary or confidential information (publicly accessible) - Great for exploring the API before signup **Your Own Sandbox:** - Create your own sandbox platform for private testing - Full API access with test data - Safe environment for integration development - Recommended path before production #### Moving to Production Once you've completed testing in sandbox: 1. Complete UI review if using custom email templates 2. Get brand approvals if required 3. Sign up for production account (if using sandbox) 4. Receive production API credentials 5. Update your integration to use production endpoints **Support:** - **Developer Support:** devsupport@tangocard.com - **Developer Center:** https://developers.tangocard.com - **Tango Website:** https://www.tangocard.com/ - **Help Center:** https://help.rewardsgenius.com ## Base URLs Tango provides two complete environments for development and production use: ### Environments Overview **Sandbox Environment (Testing)** - **Purpose:** Safe environment for development, testing, and integration - **API Base:** `https://integration-api.tangocard.com/raas/v2` - **Auth Endpoint:** `https://sandbox-auth.tangocard.com/oauth/token` - **OpenAPI Spec:** `https://integration-api.tangocard.com/raas/v2/api-docs/swagger.json` - **Portal:** https://portal.sandbox.tangocard.com - **Signup:** https://portal.sandbox.tangocard.com/#/signup - **Features:** - Pre-funded test accounts (no real money required) - Test gift cards and rewards - Full API functionality matching production - No business verification required for signup - Safe for testing error scenarios and edge cases - Test webhooks with real-time notifications - **Use Cases:** - Initial integration development - Testing new features before production deployment - Training and demonstrations - Automated testing and CI/CD pipelines **Production Environment (Live)** - **Purpose:** Live environment for real customer transactions - **API Base:** `https://api.tangocard.com/raas/v2` - **Auth Endpoint:** `https://auth.tangocard.com/oauth/token` - **OpenAPI Spec:** `https://api.tangocard.com/raas/v2/api-docs/swagger.json` - **Portal:** https://portal.tangocard.com - **Signup:** - US: https://manage.rewardsgenius.com/#/signup - International: https://www.tangocard.com/intnl-form - **Features:** - Real gift cards and rewards - Real money transactions - Production-grade SLAs - Business verification (KYB) required - Full compliance and audit trail - **Requirements:** - Completed sandbox testing - UI review (if using custom templates) - Brand approvals (if required) - Active business account ### Environment Comparison | Feature | Sandbox | Production | |---------|---------|------------| | Real gift cards | No (test cards) | Yes | | Cost | Free | Paid | | Signup process | Instant | Up to 48 hours (KYB) | | Pre-funded | Yes | No (must fund) | | Data persistence | Test data only | Permanent | | API functionality | Full | Full | | OpenAPI specs | Available | Available | | Rate limits | Same as production | Standard | | Support | Developer support | Full support + CSM | ### Moving Between Environments **Key Differences to Note:** 1. **Credentials are separate** - Sandbox and production use different OAuth credentials 2. **Data does not transfer** - Customers, accounts, and orders are environment-specific 3. **URLs are different** - Update all endpoints when moving to production 4. **Catalog may differ** - Some test brands/items may not be available in production **Migration Checklist:** - [ ] Complete all testing in sandbox - [ ] Sign up for production account - [ ] Create production OAuth credentials - [ ] Update base URLs in your code - [ ] Update auth endpoint URLs - [ ] Recreate customers and accounts in production - [ ] Fund production accounts - [ ] Update webhook URLs to production endpoints - [ ] Test with small transactions first ### Important Environment Notes **Sandbox Environment:** - **Uptime:** Historically operates over 99.9% uptime (no published SLA) - **Data Persistence:** Tango may delete accounts or data at its discretion - **Troubleshooting:** If encountering issues, test the same operation in the [Sandbox Test Console](https://developers.tangocard.com/reference/setup) to determine if it's your code or the API - **Not a Replacement:** Sandbox testing does NOT replace production testing - always test in production with small transactions before full launch **Production Environment:** - **Terms Required:** You must agree to [Tango Terms of Service](https://www.tangocard.com/etos/#ETOS) before receiving production credentials - **SLA:** Production environment includes service level agreements - **System Alerts:** Subscribe to [Tango Status](https://status.tangocard.com) for system alerts, maintenance notifications, and item outages **Note:** Authentication endpoints are separate from API endpoints. First acquire a token from the auth endpoint, then use that token when calling the API endpoints. ## OpenAPI Specification Tango provides complete OpenAPI (formerly Swagger) specifications for the API in both environments. These machine-readable API definitions can be used to: - Import into API testing tools (Postman, Insomnia, etc.) - Generate client SDKs in multiple programming languages - Create automated tests - Generate interactive API documentation - Validate requests and responses ### Specification URLs **Sandbox:** ``` https://integration-api.tangocard.com/raas/v2/api-docs/swagger.json ``` **Production:** ``` https://api.tangocard.com/raas/v2/api-docs/swagger.json ``` ### Using OpenAPI Specifications **Import into Postman:** 1. Open Postman 2. Click Import 3. Enter the OpenAPI URL 4. Postman will generate a full collection of API requests **Generate Client SDK:** Use tools like OpenAPI Generator to create client libraries: ```bash # Example: Generate Python SDK openapi-generator-cli generate \ -i https://integration-api.tangocard.com/raas/v2/api-docs/swagger.json \ -g python \ -o ./tango-client ``` **Interactive Documentation:** The OpenAPI spec is also used to power the interactive [API Reference](https://developers.tangocard.com/reference/setup) and test console on the Tango developer portal. **Specification Format:** - Format: JSON - Version: OpenAPI 3.x compatible - Updated automatically with API changes - Includes all endpoints, parameters, request/response schemas, and authentication requirements ## Authentication The Tango API supports two authentication methods: ### 1. Bearer Token (OAuth 2.0 - Recommended) OAuth 2.0 using the **password grant type** with four required credentials created in the Tango Portal. **Prerequisites:** Before acquiring a token, you must create these credentials in the Tango Portal (Team Settings > API Credentials): 1. **OAuth Client Credentials:** - Client ID - Client Secret 2. **OAuth Service Account:** - Username - Password (only visible at creation - save immediately!) **Token Endpoints:** - **Production:** `POST https://auth.tangocard.com/oauth/token` - **Sandbox:** `POST https://sandbox-auth.tangocard.com/oauth/token` **Request (application/x-www-form-urlencoded):** ``` curl --request POST \ --url https://sandbox-auth.tangocard.com/oauth/token \ --header 'Accept: application/json' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data client_id=your_client_id \ --data client_secret=your_client_secret \ --data username=your_service_account_username \ --data password=your_service_account_password \ --data scope=raas.all \ --data audience=https://api.tangocard.com/ \ --data grant_type=password ``` **Required Parameters:** | Parameter | Value | Description | |-----------|-------|-------------| | client_id | string | Client ID from OAuth Client Credentials | | client_secret | string | Client Secret from OAuth Client Credentials | | username | string | Service Account Username | | password | string | Service Account Password | | scope | raas.all | Static value (always `raas.all`) | | audience | https://api.tangocard.com/ | Static value | | grant_type | password | Static value (always `password`) | **Response:** ```json { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "scope": "raas.all", "expires_in": 86400, "token_type": "Bearer" } ``` **Token Usage:** ``` Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... ``` **Important Notes:** - Tokens expire in **24 hours** (86400 seconds) - Fetch a new token at least once every 24 hours - Client credentials and service accounts never expire but should be rotated: - Rotate client credentials once a year - Rotate service accounts when credentials are compromised or when creating new client credentials - Service account passwords are only shown once at creation - save immediately - You can have up to 2 active client credentials at once for rotation purposes - Unlimited tokens can be generated **Setup Guide:** 1. Log in to [Tango Portal](https://portal.tangocard.com) 2. Go to **Team Settings > API Credentials** 3. Create **OAuth Client Credentials** (save Client ID and Client Secret) 4. Create **OAuth Service Account** (save Username and Password immediately!) 5. Use all four credentials to request a token 6. Use the token in API calls for 24 hours 7. Request a new token before expiration ### 2. Basic Authentication Legacy method using platform name and key. **Usage:** ``` Authorization: Basic base64(platformName:platformKey) ``` **Note:** OAuth 2.0 Bearer tokens are recommended for enhanced security and credential rotation capabilities. ## Core Concepts ### Hierarchy ``` Platform └── Customer (customerIdentifier) └── Account (accountIdentifier, accountNumber) └── Order (referenceOrderID) └── Line Item (referenceLineItemID) ``` ### Customers A Customer represents a business unit or client within your platform. Each customer can have multiple accounts. **Customer Identifier:** User-defined string (5-100 characters, alphanumeric and hyphens) ### Accounts An Account holds funds and is used to place orders. Each account has a specific currency and belongs to exactly one customer. **Account Identifier:** User-defined string (5-100 characters, alphanumeric and hyphens) **Account Number:** System-generated unique identifier (starts with 'A') ### Orders & Line Items - **Order:** A transaction containing one or more rewards - **Line Item:** Individual reward within an order (each has unique credentials) - **Reference Order ID:** System-generated order identifier - **Reference Line Item ID:** System-generated line item identifier - **External Reference ID:** Optional client-provided idempotency key ### UTIDs **UTID (Unique Tango Identifier):** A unique identifier for each reward product in the catalog (format: `U######`). Each UTID represents a specific reward with: - Fixed or variable denomination - Specific currency - Delivery method requirements - Geographic availability ### Delivery Methods - **EMAIL:** Sends reward via email to recipient (digital only) - **PHONE:** Sends reward via SMS to recipient's mobile number (digital only) - **EMBEDDED:** Returns reward credentials in API response for custom delivery (digital only) - **ADDRESS:** Physical delivery via postal mail (for physical gift cards and prepaid cards) - Requires full recipient address (street, city, state/province, postal code, country) - Available for select catalog items with `fulfillmentType: "PHYSICAL"` - Includes shipping time (varies by destination) - **NONE:** Stores order without delivery (credentials available via API, digital only) ## Main Endpoints ### Catalogs **GET /catalogs** Get all items in the platform's catalog with optional filtering. **Key Parameters:** - `verbose=true` - Include full brand details, images, and redemption instructions - `brandKey` - Filter by specific brand ID - `brandName` - Filter by brand name - `utid` - Get details for specific reward - `rewardName` - Search by reward name - `status` - Filter by status (active, test, inactive, deleted) - `currencyCode` - Filter by currency (USD, EUR, GBP, etc.) - `country` - Filter by country code (US, CA, GB, etc.) - `fulfillmentType` - Filter by delivery type: `["DIGITAL"]` or `["PHYSICAL"]` - `itemAttribute` - Filter by delivery method (EMAIL, PHONE, ADDRESS, EMBEDDED) - `categoryIds` - Filter by brand categories (UUIDs) **Response Structure:** ```json { "catalogName": "Platform Catalog", "brands": [ { "brandKey": "B123456", "brandName": "Example Brand", "status": "active", "items": [ { "utid": "U123456", "rewardName": "Example Gift Card $25", "currencyCode": "USD", "status": "active", "valueType": "FIXED_VALUE", "faceValue": 25.00, "minValue": null, "maxValue": null, "fulfillmentType": "DIGITAL", "attributes": ["EMAIL", "EMBEDDED"], "countries": ["US"], "credentialTypes": ["cardNumber", "pin"] } ] } ] } ``` **Fulfillment Types:** - `DIGITAL` - Electronic delivery (email, SMS, embedded) - `PHYSICAL` - Physical cards shipped via postal mail - Requires `deliveryMethod: "ADDRESS"` - Requires full recipient address - Subject to shipping times and availability **Value Types:** - `FIXED_VALUE` - Exact denomination specified by faceValue - `VARIABLE_VALUE` - Amount between minValue and maxValue - `FIXED_VARIABLE_VALUE` - Multiple fixed denominations available ### Customers **GET /customers** List all customers on the platform. **Parameters:** - `displayName` - Filter by customer display name - `accountIdentifier` - Filter customers by associated account - `status` - Filter by status **POST /customers** Create a new customer. **Request:** ```json { "customerIdentifier": "customer-123", "displayName": "Acme Corp Rewards" } ``` **GET /customers/{customerIdentifier}** Get details for a specific customer. ### Accounts **GET /customers/{customerIdentifier}/accounts** List all accounts for a customer. **POST /customers/{customerIdentifier}/accounts** Create a new account under a customer. **Request:** ```json { "accountIdentifier": "acct-123", "displayName": "North America Account", "contactEmail": "finance@example.com", "currencyCode": "USD" } ``` **GET /accounts** List all accounts on the platform (with filtering options). **GET /accounts/{accountIdentifier}** Get details for a specific account including current balance. ### Orders **POST /orders** Create a new order (synchronous processing). **Required Fields:** - `customerIdentifier` - Customer owning the account - `accountIdentifier` - Account to deduct funds from - `utid` - Reward to order - `amount` - Face value of reward - `deliveryMethod` - How to deliver (EMAIL, PHONE, EMBEDDED, etc.) **Conditional Fields:** - `recipient.email` - Required if deliveryMethod is EMAIL - `recipient.firstName` - Required if deliveryMethod is EMAIL, PHONE, or ADDRESS - `recipient.lastName` - Required if deliveryMethod is ADDRESS - `recipient.mobileNumber` - Required if deliveryMethod is PHONE - `recipient.address` - Required if deliveryMethod is ADDRESS **Optional Fields:** - `externalRefID` - Idempotency key (max 100 characters) - `sender` - Sender details (firstName, lastName, email) - `emailSubject` - Custom email subject line - `message` - Gift message to recipient - `etid` - Email template ID for branded emails - `campaign` - Campaign identifier for reporting (max 1024 characters) - `purchaseOrderNumber` - PO reference - `notes` - Internal notes (max 150 characters) **Request Example (Digital Delivery):** ```json { "externalRefID": "order-2025-001", "customerIdentifier": "customer-123", "accountIdentifier": "acct-123", "utid": "U123456", "amount": 25.00, "deliveryMethod": "EMAIL", "recipient": { "email": "recipient@example.com", "firstName": "Jane", "lastName": "Doe" }, "sender": { "firstName": "Acme", "lastName": "Rewards", "email": "rewards@acme.com" }, "emailSubject": "You've received a reward!", "message": "Thank you for your outstanding work!", "campaign": "Q4-Employee-Recognition" } ``` **Request Example (Physical Delivery):** ```json { "externalRefID": "order-2025-002", "customerIdentifier": "customer-123", "accountIdentifier": "acct-123", "utid": "U789012", "amount": 50.00, "deliveryMethod": "ADDRESS", "recipient": { "firstName": "John", "lastName": "Smith", "email": "john.smith@example.com", "address": { "streetLine1": "123 Main Street", "streetLine2": "Apt 4B", "city": "Denver", "stateOrProvince": "CO", "postalCode": "80202", "country": "US" } }, "campaign": "Holiday-Gifts-2025" } ``` **Note:** Physical delivery is only available for rewards with `fulfillmentType: "PHYSICAL"` in the catalog. Filter catalog by `fulfillmentType=["PHYSICAL"]` to find eligible items. **Response:** ```json { "referenceOrderID": "RA240112-123-456", "referenceLineItemID": "RA240112-123-456-1", "externalRefID": "order-2025-001", "status": "COMPLETE", "utid": "U123456", "rewardName": "Example Gift Card $25", "amountCharged": { "value": 25.00, "currencyCode": "USD", "total": 25.00 }, "reward": { "credentials": { "Card Number": "1234567890123456", "PIN": "1234" }, "redemptionInstructions": "Use this card online or in-store..." }, "recipient": { "email": "recipient@example.com", "firstName": "Jane", "lastName": "Doe" }, "deliveryMethod": "EMAIL", "createdAt": "2025-01-22T10:30:00Z" } ``` **GET /orders** List orders with filtering and pagination. **Parameters:** - `accountIdentifier` - Filter by account - `customerIdentifier` - Filter by customer - `externalRefID` - Find order by your reference ID - `startDate` - Filter by date range (YYYY-MM-DD) - `endDate` - Filter by date range - `elementsPerBlock` - Page size (default: 10, max: 100) - `page` - Page number **GET /orders/{referenceOrderID}** Get details for a specific order. **POST /orders/{referenceOrderID}/resends** Resend an order to the recipient. ### Async Orders For high-volume ordering with deferred processing. **POST /asyncOrders** Create an asynchronous order. **Request:** ```json { "externalRefID": "async-order-001", "customerIdentifier": "customer-123", "accountIdentifier": "acct-123", "lineItems": [ { "externalLineItemRefID": "item-001", "utid": "U123456", "amount": 25.00, "deliveryMethod": "EMAIL", "recipient": { "email": "recipient1@example.com", "firstName": "Jane", "lastName": "Doe" } }, { "externalLineItemRefID": "item-002", "utid": "U123456", "amount": 25.00, "deliveryMethod": "EMAIL", "recipient": { "email": "recipient2@example.com", "firstName": "John", "lastName": "Smith" } } ] } ``` **GET /asyncOrders** List async orders. **GET /asyncOrders/customers/{customerIdentifier}/accounts/{accountIdentifier}/{externalRefID}** Get async order by external reference ID. **PATCH /asyncOrders/customers/{customerIdentifier}/accounts/{accountIdentifier}/{externalRefID}** Update an async order (add/modify line items). ### Line Items Individual rewards within orders. **GET /lineItems** List line items with filtering. **GET /lineItems/{referenceLineItemID}** Get details for a specific line item. **PATCH /lineItems/{referenceLineItemID}** Update a line item (limited fields). **POST /lineItems/{referenceLineItemID}/freeze** Freeze a line item (prevent redemption). **POST /lineItems/{referenceLineItemID}/unfreeze** Unfreeze a previously frozen line item. **POST /lineItems/{referenceLineItemID}/cancel** Cancel a line item with a reason code. **Request:** ```json { "reasonCode": "CUSTOMER_REQUEST" } ``` **POST /lineItems/{referenceLineItemID}/reissue** Reissue a line item (create replacement). **Request:** ```json { "reasonCode": "CUSTOMER_REQUEST", "recipient": { "email": "newemail@example.com" } } ``` **POST /lineItems/{referenceLineItemID}/resends** Resend a line item to the recipient. **GET /lineItems/{referenceLineItemID}/embeddedUrl** Get embeddable URL for web component delivery. **GET /lineItems/reasonCodes** Get all valid reason codes for cancel/reissue operations. ### Choice Products Pre-configured collections of rewards that let recipients choose their preferred brand. **GET /choiceProducts** List all available choice products. **Parameters:** - `rewardName` - Filter by name - `currencyCode` - Filter by currency - `countries` - Filter by country availability **GET /choiceProducts/{choiceProductUtid}** Get details for a specific choice product. **GET /choiceProducts/{choiceProductUtid}/catalog** Get the full catalog of brands/items within a choice product. ### Webhooks Real-time notifications for order events. **GET /webhooks** List all webhook subscriptions. **POST /webhooks** Create a new webhook subscription. **Request:** ```json { "url": "https://your-app.com/webhooks/tango", "eventTypes": ["ORDER_CREATED", "ORDER_DELIVERED", "ORDER_FAILED"], "secret": "your-webhook-secret" } ``` **GET /webhooks/eventtypes** List all available event types. **Common Event Types:** - `ORDER_CREATED` - New order placed - `ORDER_DELIVERED` - Reward delivered successfully - `ORDER_FAILED` - Order processing failed - `LINE_ITEM_FROZEN` - Line item frozen - `LINE_ITEM_CANCELLED` - Line item cancelled - `LINE_ITEM_REISSUED` - Line item reissued **GET /webhooks/{webhookId}** Get webhook subscription details. **PATCH /webhooks/{webhookId}** Update webhook subscription. **DELETE /webhooks/{webhookId}** Delete webhook subscription. **POST /webhooks/{webhookId}/renew** Renew webhook subscription secret. **POST /webhooks/{webhookId}/replay** Replay failed webhook events. **POST /webhooks/{webhookId}/tests** Test webhook with sample events. ### Digital Templates Customizable email templates for branded reward delivery. **GET /digitalTemplates** List all digital templates. **POST /digitalTemplates** Create a new digital template. **GET /digitalTemplates/{etid}** Get details for a specific template. **PATCH /digitalTemplates/{etid}** Update a digital template. **DELETE /digitalTemplates/{etid}** Delete a digital template. ### Exchange Rates **GET /exchangerates** Get current exchange rates for cross-currency transactions. ### Credit Cards For funding accounts via credit card (if enabled). **GET /creditCards** List registered credit cards. **POST /creditCards** Register a new credit card. **POST /creditCardDeposits** Fund an account with a credit card. **POST /creditCardUnregisters** Unregister a credit card. ## Common Workflows ### 1. First-Time Setup (Complete Flow from Signup to First Order) ``` 1. Sign up for Tango account: a. Sandbox (testing): https://portal.sandbox.tangocard.com/#/signup b. Production (US): https://manage.rewardsgenius.com/#/signup c. Production (International): https://www.tangocard.com/intnl-form 2. Wait for account activation (up to 48 hours for production accounts) - Check email for Tango Portal invitation - Log in and set password 3. Create OAuth credentials in Tango Portal (Team Settings > API Credentials): a. Create OAuth Client Credentials (save Client ID and Client Secret) b. Create OAuth Service Account (save Username and Password immediately!) 4. Acquire Bearer Token (POST to auth endpoint) - Sandbox: https://sandbox-auth.tangocard.com/oauth/token - Production: https://auth.tangocard.com/oauth/token - Use all four credentials from step 3 - Token valid for 24 hours 5. Create Customer (POST /customers with Bearer token) 6. Create Account (POST /customers/{customerIdentifier}/accounts) 7. Fund Account: - Production: Wire transfer or credit card - Sandbox: Account comes pre-funded for testing 8. You're ready to place orders! ``` ### 2. Browse Catalog and Place Order **For Digital Rewards:** ``` 1. Search Catalog (GET /catalogs?currencyCode=USD&country=US&fulfillmentType=DIGITAL&itemAttribute=EMAIL) 2. Select UTID from results 3. Create Order (POST /orders) - Set deliveryMethod to EMAIL, PHONE, or EMBEDDED - Include recipient details (email, firstName, etc.) - Include externalRefID for idempotency 4. Receive order details with credentials in response (instant) ``` **For Physical Rewards:** ``` 1. Search Catalog (GET /catalogs?currencyCode=USD&country=US&fulfillmentType=PHYSICAL) 2. Select UTID from results 3. Create Order (POST /orders) - Set deliveryMethod to ADDRESS - Include full recipient address - Include externalRefID for idempotency 4. Receive order confirmation (physical card ships to recipient) ``` ### 3. Check Order Status ``` 1. Get Order Details (GET /orders/{referenceOrderID}) 2. Or search by externalRefID (GET /orders?externalRefID=your-ref-id) ``` ### 4. Cancel and Reissue Flow ``` 1. Freeze Line Item (POST /lineItems/{referenceLineItemID}/freeze) 2. Cancel Line Item (POST /lineItems/{referenceLineItemID}/cancel) 3. Reissue Line Item (POST /lineItems/{referenceLineItemID}/reissue) - Optionally update recipient details - Creates new line item with new credentials ``` ### 5. Webhook Setup ``` 1. Create Webhook (POST /webhooks) 2. Verify webhook with test events (POST /webhooks/{webhookId}/tests) 3. Handle webhook callbacks at your endpoint 4. Verify webhook signature using shared secret ``` ## Best Practices ### Idempotency Always use `externalRefID` when creating orders to prevent duplicate orders if the request is retried. ### Error Handling The API uses standard HTTP status codes: - `200/201` - Success - `400` - Bad Request (validation error) - `401` - Unauthorized (invalid credentials) - `402` - Payment Required (insufficient funds) - `403` - Forbidden (access denied) - `404` - Not Found - `409` - Conflict (duplicate externalRefID) - `422` - Unprocessable Entity - `429` - Rate Limited - `500/503` - Server Error (retry with exponential backoff) ### Rate Limiting - Default: 100 requests per second - Monitor `X-RateLimit-*` headers in responses - Implement exponential backoff for 429 responses ### Testing - **Always start with Sandbox**: Sign up at https://portal.sandbox.tangocard.com/#/signup - Sandbox accounts are pre-funded with test currency - Test UTIDs are available (status: "test") for integration testing - Verify all workflows including webhook handling before moving to production - Never use production credentials in test/development environments ### Security - Store credentials securely - Rotate Service Account secrets regularly - Use HTTPS for all API calls - Validate webhook signatures - Never log sensitive credential data ### Pagination For large result sets: - Use `elementsPerBlock` parameter (max 100) - Implement pagination with `page` parameter - Consider async orders for bulk operations ### Multi-Currency - Each account has one base currency - Cross-currency orders use current exchange rates - Check exchange rates before ordering (GET /exchangerates) ### Delivery Methods - **EMAIL**: Best for digital rewards, handled by Tango - **EMBEDDED**: For custom UI, credentials in API response (digital only) - **PHONE**: SMS delivery (international format required: +1234567890, digital only) - **ADDRESS**: Physical gift cards shipped via postal mail - Requires full recipient address - Only available for items with `fulfillmentType: "PHYSICAL"` - Subject to shipping times - **NONE**: Store credentials without delivery (retrieve via API, digital only) ## Support ### Documentation & Resources - **Tango Website:** https://www.tangocard.com/ - **Developer Portal:** https://developers.tangocard.com - **API Reference (Interactive):** https://developers.tangocard.com/reference/setup - **OpenAPI Specifications:** - Sandbox: https://integration-api.tangocard.com/raas/v2/api-docs/swagger.json - Production: https://api.tangocard.com/raas/v2/api-docs/swagger.json - **Help Center:** https://help.rewardsgenius.com - **MCP Server Documentation:** https://developers.tangocard.com/docs/tango-api-mcp ### Environments - **Sandbox Portal:** https://portal.sandbox.tangocard.com - **Production Portal:** https://portal.tangocard.com - **Sandbox Signup:** https://portal.sandbox.tangocard.com/#/signup ### Support Channels - **Developer Support Email:** devsupport@tangocard.com - **General Support Email:** support@tangocard.com - **System Status & Alerts:** https://status.tangocard.com ### Company - **Tango Card:** https://www.tangocard.com/ - **Blackhawk Network (Parent Company):** https://blackhawknetwork.com/ ### Terms & Legal - **Terms of Service:** https://www.tangocard.com/etos/#ETOS ## Recent Updates - **Async Orders:** Support for bulk order processing with deferred fulfillment - **Webhooks:** Real-time event notifications with signature verification - **Line Item Management:** Enhanced freeze, cancel, and reissue operations - **Choice Products:** Let recipients choose their preferred reward brand - **Mobile Delivery:** Enhanced SMS delivery with international support ## API Versioning Current version: **v2** Base path includes version: `/raas/v2` Breaking changes will result in a new version. Minor updates and additions are made to the current version without breaking existing integrations.