Physical Store (Retail)

In the physical store scenario, the partner operates retail locations where gift cards are sold at the point of sale. This integration pattern uses a dedicated set of retail order endpoints and follows a two-step order flow: the order is first created to perform preliminary checks, and then confirmed after payment has been successfully collected from the customer.

Unlike the digital order flow, retail orders identify the transaction context through store, terminal, and receipt identifiers rather than a customer object. The gift card information is delivered as formatted receipt lines in the API response. For Print on Receipt (POR) that includes the gift card code. For Point of Sale Activation (POSA) it contains support information.

Relevant Endpoints

Endpoint	Purpose
GET /balances	Check your available balance
GET /products	List available products for your stores and import them into your system
POST /stores	Register your retail store locations
GET /stores	List and manage your stores
POST /retail_orders	Create a retail order (preliminary check)
GET /retail_orders/{id}	Retrieve retail order details, e.g. to check the state
POST /retail_orders/{id}/actions/confirm	Confirm the order after payment is collected
POST /retail_orders/{id}/actions/invalidate	Invalidate an order if needed
GET /settlements	(Optional) Retrieve settlement information
Webhooks	(Optional) Receive real-time updates for orders and products

Store Setup

Before placing retail orders, the retail store locations must be registered via POST /stores. The store information is required in order to execute checks to prevent fraud or money laundering. Each store is identified by a unique store identifier that is used when creating retail orders. It uses the identifier from the partner system to simplify integration on the individual point of sale terminal.

Order Creation

Retail orders require store_id, terminal_id, and receipt_id to identify the transaction context. Additionally, the receipt_printing object specifies the formatting parameters for the receipt output.

The following example demonstrates a typical retail order creation request:

POST /v1/retail_orders
Idempotency-Key: unique-key-789

{
  "product_code": "4001232232332",
  "store_id": "A1234",
  "terminal_id": "T01",
  "receipt_id": "R1234567890",
  "country": "DE",
  "face_value": {
    "currency": "EUR",
    "amount": "100.0"
  },
  "receipt_printing": {
    "characters_per_line": 40,
    "locale": "de-DE"
  }
}

Order Confirmation

Once payment has been collected from the customer, the order must be confirmed to trigger the activation of the gift card. The confirmation request optionally includes the payment method and the total receipt value. This information is also used to apply checks to prevent fraud or money laundering and therefore recommended to be passed.

POST /v1/retail_orders/{id}/actions/confirm

{
  "payment_method": "cash",
  "receipt_value": {
    "currency": "EUR",
    "amount": "100.0"
  }
}

The confirmation response includes receipt_printing.lines, which contains the formatted lines to be printed on the customer receipt.

Typical Integration Flow

1. Register stores — Register the retail store locations via POST /stores.
2. List products — Retrieve and cache the available products via GET /products. It is recommended to refresh the product list periodically or to use webhooks for real-time product updates.
3. Check balance — Verify the available balance via GET /balances.
4. Create retail order — When a customer selects a gift card at the point of sale, create a retail order via POST /retail_orders. This performs preliminary checks but does not trigger the purchase yet.
5. Collect payment — Process the payment at the terminal.
6. Confirm order — After successful payment, confirm the order via POST /retail_orders/{id}/actions/confirm to activate the gift card.
7. Print receipt — Print the receipt using the lines returned in the confirmation response.
8. Handle technical issues — In case of technical issues where it is uncertain whether a transaction succeeded, invalidate the order via POST /retail_orders/{id}/actions/invalidate as soon as possible.