Accessing Pre-Purchased Gift Cards

Overview

Learn how to retrieve unaccessed gift cards from bulk purchases made through the webapp or async orders. This method is ideal for inventory-based systems with deferred access.

Key Concepts

• Product Skew: Unique combination of product + currency + denomination
• Unaccessed Payout: Gift card never retrieved through API
• Idempotent Access: First retrieval marks payout as accessed permanently

Prerequisites

1. Existing purchases for target product skew
2. Valid API key in Authorization header

Step-by-Step Guide

1. Check Available Inventory

   • Use GET /orders/products to verify available quantities

2. Retrieve Latest Unaccessed Payout

   • Call GET /orders/products/{productId}/payout/latest
   • Specify exact currency and denomination as query parameters

3. Handle Response

   • Success: Returns payout details with first-time access URL
   • 404 Error: No unaccessed payouts available
   • Auto-marked as accessed after first retrieval

4. Subsequent Calls

   • Will return next unaccessed payout (if available)
   • Maintain first-come-first-served access order

When to Use

• Bulk purchase fulfillment
• Delayed gift card distribution
• Inventory management systems
• Fraud-sensitive workflows requiring access control

Best Practices

• Always check product availability first
• Implement error handling for 404 responses
• Store retrieved payout URLs securely
• Monitor payout expiration dates