Indirect Sale via Partners

In the indirect sale scenario, the partner operates a platform that enables other companies to offer gift cards to their respective customers or employees. A typical example is an HR benefits platform where multiple employers provide gift cards as part of an employee benefits program.

Since the partner is not the direct seller to the end customer, each order must be associated with a client partner — the company on whose behalf the gift card is purchased. This requires client partner tracking.

Relevant Endpoints

Endpoint	Purpose
GET /balances	Check your available balance periodically
GET /products	List available products and import them into your system
POST /client_partners	Register new client partners (e.g. employer companies)
GET /client_partners	List and manage your client partners
POST /orders	Create gift card orders with the client partner id
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

Client Partner Setup

Before placing orders, client partners must be registered via POST /client_partners. Each client partner needs to be approved by finperks before orders can be placed on their behalf. See Client Partners for details on the client partner lifecycle.

Order Creation

For this use case the client_partner field is required in every order creation request. It must reference an approved client partner previously created through the API or web UI. Omitting the field or referencing a client partner that has not been approved will result in an error.

The following example demonstrates a typical order creation request with a client partner:

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

{
  "product_code": "b713c564-9e18-4810-a9bb-7b2d86afc8cd",
  "customer": {
    "id": "employee-1337"
  },
  "client_partner": {
    "id": "128c674a-8a7d-48bb-902c-72ba2351bdc9"
  },
  "country": "DE",
  "face_value": {
    "currency": "EUR",
    "amount": "25.0"
  },
  "processing_mode": "sync",
  "delivery_method": {
    "type": "email",
    "data": {
      "email": "employee@company.com"
    }
  }
}

The client_partner.id field associates the order with the respective client partner. Note that passing this field is rejected if client partner tracking is not enabled for the account.

Typical Integration Flow

1. Register client partners — Create client partners via POST /client_partners and wait for approval by finperks.
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 before placing orders.
4. Create order — Place an order via POST /orders with the selected product, customer identifier, client partner id, and delivery method.
5. 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.
6. 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.