Direct Sale to Customers

In the direct sale scenario, the partner purchases gift cards and delivers them directly to end customers. This is the most common integration pattern and applies when the partner operates their own customer-facing platform, such as an online shop, a mobile application, or a loyalty rewards system.

Since the partner is the direct seller, no intermediary is involved and client partner tracking is not required.

Relevant Endpoints

Endpoint	Purpose
GET /balances	Check your available balance periodically
GET /products	List available products to display to your customers and import them into your system
POST /orders	Create gift card orders for your customers
GET /orders/{id}	Retrieve order status and delivery information
POST /orders/{id}/actions/invalidate	Invalidate an order if needed, e.g. due to technical issues
GET /settlements	(Optional) Retrieve settlement information
Webhooks	(Optional) Receive real-time updates for orders and products

Order Creation

The following example demonstrates a typical order creation request for a direct sale:

POST /v1/orders
Idempotency-Key: unique-key-123

{
  "product_code": "b713c564-9e18-4810-a9bb-7b2d86afc8cd",
  "customer": {
    "id": "customer-42"
  },
  "country": "DE",
  "face_value": {
    "currency": "EUR",
    "amount": "50.0"
  },
  "processing_mode": "sync",
  "delivery_method": {
    "type": "code"
  }
}

Typical Integration Flow

1. List products — Retrieve and cache the available products via GET /products. It is recommended to refresh the product list periodically (e.g. once a day) or to use webhooks for real-time product updates.
2. Check balance — Verify the available balance via GET /balances before placing orders.
3. Create order — Place an order via POST /orders with the selected product, customer identifier, and delivery method.
4. Deliver gift card — Present the gift card code, URL, or email confirmation to the end customer based on the chosen delivery method. See Order Presentation for guidance on how to deliver the gift card information.
5. Handle technical issues — In case of technical issues where it is uncertain whether a transaction succeeded, attempt invalidation via POST /orders/{id}/actions/invalidate as soon as possible.