Digital Gift Card API Integration Guide

Your app needs reward catalog access. Users should browse offerings, check point costs, redeem directly in your application. This requires API integration between your system and reward provider. Here's how it works technically.

Authentication and API Keys

First step: obtain API credentials from reward provider. Typically API key and secret enabling authenticated requests.

Store credentials securely. Never hardcode in client-side code or commit to version control. Use environment variables or secure credential management services.

Endpoints You'll Need

Catalog listing endpoint returning available rewards with metadata: name, description, point cost, availability status, images.

User balance endpoint showing current point balance for authenticated user.

Redemption endpoint processing reward requests, debiting points, initiating fulfillment.

Transaction history endpoint showing past redemptions and point earnings.

Request Authentication

Most reward APIs use OAuth 2.0 or API key authentication. Each request includes authorization header proving legitimacy.

Rate limiting typically applies. Respect documented limits to avoid throttling or blocking. Implement exponential backoff for retries on temporary failures.

Handling Catalog Data

Catalog endpoint might return hundreds of items. Implement pagination rather than requesting everything at once.

Cache catalog data appropriately. Availability and pricing can change, but names and descriptions stay stable. Balance freshness against API call efficiency.

User Balance Integration

Display user point balance prominently. Fetch on app launch and after any point-affecting actions.

Consider websocket connections for real-time balance updates versus polling. Depends on expected balance change frequency.

Redemption Flow

User selects reward. Your app calls redemption endpoint with reward ID and user credentials.

Handle response codes properly: success, insufficient points, item unavailable, technical error. Provide appropriate user feedback for each case.

Implement idempotency. If network fails after redemption but before receiving confirmation, retry shouldn't redeem twice. Unique request IDs prevent double redemption.

Webhook Event Handling

Some providers send webhooks when user earns points outside your app or redemptions fulfill. Set up endpoint receiving these notifications to keep your app state synchronized.

Verify webhook signatures proving they're from legitimate provider, not spoofing attempts.

Error Handling

Network failures happen. API downtime occurs. Handle gracefully with retries, fallbacks, clear error messages.

Log errors with sufficient context for debugging but avoid logging sensitive user data or API credentials.

Testing in Sandbox

Most providers offer sandbox/testing environments. Use these before production integration. Test edge cases: zero balance, non-existent items, expired credentials.

Offers and rewards are subject to availability, terms, and conditions. Stashfin reserves the right to modify or withdraw offers at any time.