How to Integrate Digital Gift Card APIs With Topupmate

Digital gift cards have become one of the fastest-growing revenue channels for fintech platforms, digital banks, and retail portals. Whether your users want to buy an Apple Gift Card, fund a Steam wallet, or purchase Amazon vouchers across the US, UK, Europe, or Nigeria, integrating a reliable gift card engine requires more than just firing a purchase request.

You need to know how to query dynamic product catalogs, build intuitive UI forms based on fixed vs. flexible denominations, calculate exchange fees, and securely present redemption codes and claim instructions.

This guide walks you through the end-to-end integration lifecycle using the Topupmate Gift Card API.

The Integration Lifecycle at a Glance

The gift card purchase lifecycle operates across three primary stages:

[ Catalog Discovery ] ──> [ Dynamic UI & Pricing ] ──> [ Order & Code Retrieval ]
   GET /giftcard/available      Fixed vs. Range Input       POST /giftcard/
                                Fee & FX Computation        GET /giftcard/redeem/

1. Catalog & Product Discovery

Before allowing a user to buy a card, your application needs to query available products and their regional metadata.

The Endpoint

GET [https://connect.topupmate.com/api/giftcard/available/]

Query Parameters

• countryCode (Optional): ISO-2 country code (e.g., US, GB, NG, CA).

• productName (Optional): Search term for specific brands (e.g., Amazon, Steam, Apple).

• productId (Optional): Target a single gift card product ID.

Example Request

curl -X GET "https://connect.topupmate.com/api/giftcard/available/?countryCode=US" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json"

Understanding the Catalog Response

The returned catalog contains configuration metadata that dictates how your frontend form should render:

{
  "status": "success",
  "msg": [
    {
      "productId": 1042,
      "productName": "Amazon US",
      "countryCode": "US",
      "denominationType": "FIXED",
      "recipientCurrencyCode": "USD",
      "senderCurrencyCode": "USD",
      "fixedRecipientDenominations": [10, 25, 50, 100],
      "minRecipientDenomination": null,
      "maxRecipientDenomination": null,
      "senderFee": 0.50,
      "senderFeePercentage": 1.5,
      "redeemInstruction": {
        "concise": "Apply code at amazon.com/gc/redeem",
        "verbose": "1. Visit amazon.com/gc/redeem. 2. Log in to your account. 3. Enter claim code and click Apply to Your Balance."
      }
    }
  ]
}

2. Rendering Dynamic UI: Fixed vs. Flexible Denominations

A common mistake in gift card UIs is hardcoding input fields. Gift card providers issue products with two distinct pricing models. Your frontend should evaluate denominationType dynamically:

Case A: denominationType == "FIXED"

• UI Behavior: Render a dropdown selector or a grid of pill buttons.

• Values: Populate options using the array in fixedRecipientDenominations (e.g., $10, $25, $50, $100).

• Validation: Block custom manual inputs; only allow values present in the array.

Case B: denominationType == "RANGE" (Flexible)

• UI Behavior: Render an editable numeric input field.

• Constraints: Bind the input's minimum and maximum values to minRecipientDenomination and maxRecipientDenomination (e.g., min: $5, max: $500).

3. How Pricing & Settlement Work

When users select an amount, the backend determines the settlement cost. While the Topupmate API calculates and debits your wallet automatically upon purchase, understanding the calculation flow helps you display accurate live estimates to your users:

[ Denomination (Foreign Currency) ]
                │
                ▼ (Recipient-to-Sender FX Conversion)
       [ Base USD Amount ]
                │
                ▼ (+ Provider Fixed & Percentage Fees)
    [ Gross USD Invoice Cost ]
                │
                ▼ (Platform Local FX Rate, e.g., NGN/USD)
   [ Final Wallet Debit (Local Currency) ]

1. Base Conversion: The selected face value (amount) is converted to USD using the currency exchange rate.

2. Provider Margin: Fixed (senderFee) and percentage-based (senderFeePercentage) processing costs are applied.

3. Local Settlement: The gross USD total is converted into your local wallet currency (e.g., NGN) alongside your internal merchant markup.

4. Purchasing a Gift Card

Once the user selects a product, specifies an amount, and inputs the recipient information, execute the purchase order.

The Endpoint

POST [https://connect.topupmate.com/api/giftcard/]

Request Payload Parameters

• product (integer, required): The productId obtained during catalog discovery.

• amount (numeric, required): The selected face value denomination.

• email (string, required): Delivery email address for transaction records.

• sender (string, required): Name or brand identifier of the purchaser.

• units (integer, required): Quantity of cards to issue (typically 1).

• ref (string, required): A unique merchant transaction reference for idempotency.

Example Request

curl -X POST "https://connect.topupmate.com/api/giftcard/" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": 1042,
    "amount": 50,
    "email": "customer@example.com",
    "sender": "John Doe",
    "units": 1,
    "ref": "TXN_GC_88392019482"
  }'

Success Response

{
  "status": "success",
  "message": "Gift card order processed successfully",
  "data": {
    "reference": "TXN_GC_88392019482",
    "redeemId": "VOUCH-994821",
    "productName": "Amazon US $50",
    "redeem": "AQ92-K82XPL-9921L",
    "redeem_details": "Visit amazon.com/gc/redeem, log in, enter the code above, and click Apply to Balance.",
    "amount_charged": 78500.00,
    "currency": "NGN"
  }
}

5. Delivering Redemption Codes & Display Guidelines

Unlike airtime or utility bill payments that settle silently in the background, gift card fulfillment requires clear user interaction.

1. The Code / Claim Token (redeem)

Present the voucher claim code in a high-contrast box with a 1-Click Copy action and a clear disclaimer reminding users not to share their code with unverified third parties.

2. The Instructions (redeem_details)

Always display the complete redemption instructions provided in the API response. For digital cards like Razer Gold, Apple, or Google Play, users often need regional account settings or direct URL entry to redeem vouchers successfully.

6. Retrieving Voucher Details Later

Users frequently misplace voucher codes or close their browser before copying the details. You can retrieve redemption data at any time using your initial transaction reference.

The Endpoint

GET [https://connect.topupmate.com/api/giftcard/redeem/?ref=YOUR_TRANSACTION_REF]

curl -X GET "https://connect.topupmate.com/api/giftcard/redeem/?ref=TXN_GC_88392019482" \
  -H "Authorization: Token YOUR_API_KEY"

This returns the historical transaction state, voucher PIN/link, and usage instructions so you can re-display them in customer order histories or email receipts.

Integration Best Practices & Error Handling

• Enforce Idempotency: Always supply unique ref strings per checkout attempt to prevent double-billing on transient network drops.

• Pre-Purchase Disclaimers: Display the product’s redeemInstruction.verbose text on the checkout modal so users confirm their account region matches the card's country code before purchasing.

• Handle Insufficient Balance Gracefully: Monitor your 400/422 response exceptions (Insufficient wallet balance) to alert operations teams before end-user requests fail.