Understanding Orders

Overview

Orders are how you purchase and deliver gift cards to your end users. When you create an order, the system finds the best available provider, processes the payment from your balance, and returns redemption details (like codes, PINs, or links) that your users need to redeem their gift cards.

Before Creating Orders

You'll need:

1. Sufficient balance - Orders are charged against your company balance in the specified currency
2. Available products - Check the products catalog to see which brands, denominations, and countries are available
3. Unique reference - Generate a unique identifier for each order (used for idempotency)

Creating an Order

Specify:

• Brand - The brand slug (e.g., "adidas", "amazon")
• Currency - ISO currency code (e.g., "USD", "EUR")
• Face value - Must match one of the available denominations for that brand
• Country - 2-letter country code where the gift card will be valid
• Reference - Your unique identifier for this order (prevents duplicates)

Optionally:

• Payment currency - If you want to pay in a different currency than the product currency (cross-currency orders)

You'll receive an order_id in the response - save this to check the order status and retrieve redemption details.

Order Processing

Orders don't complete instantly. After creation, they go through:

1. Offer selection - System finds the best offer based on availability and pricing
2. Fulfillment - Provider processes the gift card order
3. Completion - Redemption details become available

This typically takes a few seconds but can be longer during peak times or if a source fails and the system needs to try another source.

Checking Order Status

Use the order_id to check status. Poll this endpoint regularly (e.g., every minute ) until the order reaches a final state:

• pending - Still processing, keep polling
• completed - Success! Redemption details are ready
• failed - Order failed, refund automatically initiated
• refunded - Order was refunded to your balance

Redemption Details

Once an order is completed, you'll receive redemption details. What you get depends on the brand:

• Code - The main redemption code
• PIN - PIN number (if required)
• Link - Direct redemption URL
• Link Challenge Code - A special code required to access the link (if present)
• Serial number - Card serial number
• Security code - Additional security code

Some brands provide all of these, others just provide a code or link. Present whatever details are available to your end users.

Cross-Currency Orders

If you have balance in EUR but need to order a USD gift card, specify EUR as the payment_currency. The system will:

1. Convert the order amount from USD to EUR using current exchange rates
2. Apply an FX conversion fee (1% of converted order value)
3. Charge your EUR balance

The response includes an fx_fee object showing the exchange rate, fee percentage, and total amount charged in your payment currency.

Important Details

Idempotency: If you retry a request with the same reference, you won't create duplicate orders. This is crucial for handling network errors or timeouts.

Discounts: Your pricing may include discounts (positive percentage) or fees (negative percentage).

The price field shows the final amount charged in returned currency.

Failed Orders: If an order fails, the system automatically refunds the amount to your balance. You don't need to do anything.

Listing Orders: You can retrieve all your historical orders with pagination to track order history, reconcile transactions, or debug issues.

Error Handling: If an order request fails (422 status), you'll get a request_id - save this if you need to contact support.