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

Authentication

Runa Base URL

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

X-Api-Key: XXxxq8Vl.5fx~8r_dS7LGJ*HdEeGd^P9pQwi4cV_7

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 all orders
Create Order	`GET /v2/order`	`GET /v2/order`	Create a new gift card order (processed as a background operation)
Get Balance (All Accounts)	`GET /v2/balance`	`GET /v2/balance`	Get balance for all currencies
Get Balance (Single Currency)	`GET /v2/balance?currency=USD`	`GET /v2/balance?currency=USD`	Get balance for a specific currency

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"
}

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
- Good for testing scenarios but may experience timeouts for complex purchases
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 to avoid timeouts

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

Idempotency Support

Both the original Runa API and Fluz's implementation support idempotency keys to prevent duplicate operations:

Header: X-Idempotency-Key: your-unique-key

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>" \
  -H "X-Idempotency-Key: 123"

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 for All Currencies

# Get Balance for all currencies 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 for USD Currency

# Get Balance for USD currency with Runa via Fluz API Adapter
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" \
  -H "X-Idempotency-Key: unique-key-123456" \
  -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" \
  -H "X-Idempotency-Key: unique-key-789012" \
  -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"
  }'