This document provides specific details for using the Fluz Gift Card Vendor API Connector with Runa as the vendor.

Original Runa API vs Fluz API Adapter

Base URL

Original Runa API: https://playground.runa.io
Fluz API Adapter:
- Staging: https://api-adapter.staging.fluzapp.com/runa
- Production: https://api-adapter.fluzapp.com/runa

Authentication

Runa Base URL

Uses API Key Authentication with the header X-Api-Key

X-Api-Key: <RUNA-API-KEY>

Fluz API Adapter

Uses Basic Authentication with the Authorization header (same as all vendor integrations).

Authorization: Basic <FLUZ-API-Key>

API Endpoint Comparison

Operation	Runa Endpoint	Fluz Endpoint	Notes
Get Order	`GET /v2/order/:id`	`GET /v2/order/:id`	Retrieve details for a specific order
Get All Orders	`GET /v2/order`	`GET /v2/order`	Retrieve the 100 most recent orders
Create Order	`POST /v2/order`	`POST /v2/order`	Create a new gift card order
Get Balance	`GET /v2/balance`	`GET /v2/balance`	Get your account balance. Returns an array of one
Get Balance (single object)	`GET /v2/balance?currency=USD`	`GET /v2/balance?currency=USD`	The same balance, returned as a single object rather than an array. Balances are USD

Request Examples

Create Order

Original Runa Request:

{
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "USD"
  },
  "items": [
    {
      "distribution_method": {
        "type": "PAYOUT_LINK"
      },
      "products": {
        "type": "SINGLE",
        "value": "1800FL-US"
      },
      "face_value": 10
    }
  ],
  "description": "string"
}

Fluz API Adapter Request:

{
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "USD"
  },
  "items": [
    {
      "distribution_method": {
        "type": "PAYOUT_LINK"
      },
      "products": {
        "type": "SINGLE",
        "value": "1800FL-US"
      },
      "face_value": 10
    }
  ],
  "description": "d8e118ab-732b-4884-8e8a-70746b5f359e"
}

The request shape is unchanged from Runa’s. Only the brand code in products.value has to change, because it is resolved against the Fluz catalog. Correlate an order using the id from the response.

Background Processing for Runa Orders

All purchase operations through the Runa integration are processed as background operations. The Fluz API Adapter provides two response modes for Runa:

Synchronous vs Asynchronous Processing Modes

Synchronous Mode:
- Add header X-Execution-Mode: sync to wait for the background operation to complete
- The API call will wait until the background purchase operation completes
- Full operation results are returned in the response
- Best for testing and low-volume flows, since the call stays open for the length of the purchase
Asynchronous Mode (Default):
- Returns immediately with an operation reference ID
- The purchase continues processing in the background
- Check the status later by querying the order endpoint with the reference ID
- Recommended for production, since your call returns immediately regardless of how long the purchase takes

Both modes rely on background processing, but they differ in how the API responds to the client.

An order is readable once its purchase has completed. Reading a reference ID before then returns an error rather than a pending status, so treat an error on a freshly created order as still processing and read again shortly. Order status values are Fluz’s: PENDING, IN_PROGRESS, COMPLETED, FAILED, CANCELED. See Connector behaviour for status values, error responses, limits, and request constraints.

Example Usage with cURL

Example 1: Get a Specific Order

# Get a specific order with Runa via Fluz API Adapter
curl -X GET "https://api-adapter.staging.fluzapp.com/runa/v2/order/df263170-1c87-4e53-baf5-96258c3dd6b9" \
  -H "Authorization: Basic <FLUZ-API-Key>"

Example 2: Get All Orders

# Get all orders with Runa via Fluz API Adapter
curl -X GET "https://api-adapter.staging.fluzapp.com/runa/v2/order" \
  -H "Authorization: Basic <FLUZ-API-Key>"

Example 3: Get Balance

# Get your account balance with Runa via Fluz API Adapter
curl -X GET "https://api-adapter.staging.fluzapp.com/runa/v2/balance" \
  -H "Authorization: Basic <FLUZ-API-Key>"

Example 4: Get Balance as a Single Object

# Same balance as Example 3, returned as an object rather than an array
curl -X GET "https://api-adapter.staging.fluzapp.com/runa/v2/balance?currency=USD" \
  -H "Authorization: Basic <FLUZ-API-Key>"

Example 5: Create Order with Runa (Asynchronous Mode - Default)

# Create Order with Runa via Fluz API Adapter (Asynchronous mode - default)
# This will return quickly with a reference ID while processing continues in the background
curl -X POST "https://api-adapter.staging.fluzapp.com/runa/v2/order" \
  -H "Authorization: Basic <FLUZ-API-Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": {
      "type": "ACCOUNT_BALANCE",
      "currency": "USD"
    },
    "items": [
      {
        "distribution_method": {
          "type": "PAYOUT_LINK"
        },
        "products": {
          "type": "SINGLE",
          "value": "1800FL-US"
        },
        "face_value": 10
      }
    ],
    "description": "d8e118ab-732b-4884-8e8a-70746b5f359e"
  }'

Example 6: Create Order with Runa (Synchronous Mode)

# Create Order with Runa via Fluz API Adapter (Synchronous mode)
# This will wait for the background process to complete before responding
curl -X POST "https://api-adapter.staging.fluzapp.com/runa/v2/order" \
  -H "Authorization: Basic <FLUZ-API-Key>" \
  -H "Content-Type: application/json" \
  -H "X-Execution-Mode: sync" \
  -d '{
    "payment_method": {
      "type": "ACCOUNT_BALANCE",
      "currency": "USD"
    },
    "items": [
      {
        "distribution_method": {
          "type": "PAYOUT_LINK"
        },
        "products": {
          "type": "SINGLE",
          "value": "1800FL-US"
        },
        "face_value": 10
      }
    ],
    "description": "d8e118ab-732b-4884-8e8a-70746b5f359e"
  }'

Developers

Recipes

Runa

Original Runa API vs Fluz API Adapter

Base URL

Authentication

Fluz API Adapter

API Endpoint Comparison

Request Examples

Create Order

Original Runa Request:

Fluz API Adapter Request:

Background Processing for Runa Orders

Synchronous vs Asynchronous Processing Modes

Example Usage with cURL

Example 1: Get a Specific Order

Example 2: Get All Orders

Example 3: Get Balance

Example 4: Get Balance as a Single Object

Example 5: Create Order with Runa (Asynchronous Mode - Default)

Example 6: Create Order with Runa (Synchronous Mode)

​Original Runa API vs Fluz API Adapter

​Base URL

​Authentication

​Fluz API Adapter

​API Endpoint Comparison

​Request Examples

​Create Order

​Original Runa Request:

​Fluz API Adapter Request:

​Background Processing for Runa Orders

​Synchronous vs Asynchronous Processing Modes

​Example Usage with cURL

​Example 1: Get a Specific Order

​Example 2: Get All Orders

​Example 3: Get Balance

​Example 4: Get Balance as a Single Object

​Example 5: Create Order with Runa (Asynchronous Mode - Default)

​Example 6: Create Order with Runa (Synchronous Mode)

Original Runa API vs Fluz API Adapter

Base URL

Authentication

Fluz API Adapter

API Endpoint Comparison

Request Examples

Create Order

Original Runa Request:

Fluz API Adapter Request:

Background Processing for Runa Orders

Synchronous vs Asynchronous Processing Modes

Example Usage with cURL

Example 1: Get a Specific Order

Example 2: Get All Orders

Example 3: Get Balance

Example 4: Get Balance as a Single Object

Example 5: Create Order with Runa (Asynchronous Mode - Default)

Example 6: Create Order with Runa (Synchronous Mode)