@flowglad/fgp-openclaw

OpenClaw plugin for Flowglad Pay — gives AI agents the ability to purchase products, sign up for services, and manage jobs, credentials, payment methods, and shipping addresses.

Prerequisites

• An OpenClaw instance (self-hosted or cloud)
• A Flowglad Pay account with an API key
• Node.js >= 18

Getting Your API Key

1. Sign in to the Flowglad Pay dashboard
2. Navigate to Settings > API Keys
3. Create a new key — it will start with pk_
4. Copy it for the plugin configuration below

Installation

Install the plugin via npm:

npm install @flowglad/fgp-openclaw

Then add it to your OpenClaw configuration file (openclaw.json or equivalent). The array form registers the plugin with default settings, while the object form lets you provide configuration inline:

{
  "plugins": {
    "@flowglad/fgp-openclaw": {
      "apiKey": "pk_your_api_key_here"
    }
  }
}

Configuration

The plugin requires an API key and accepts an optional custom endpoint.

Via the OpenClaw Control UI

When configuring through the UI, the API Key field is marked as sensitive and will be masked. The API Endpoint field defaults to https://app.flowgladpay.com/api and only needs to be changed for self-hosted deployments.

Config reference

| Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | apiKey | string | Yes | — | Flowglad Pay API key (pk_...) | | endpoint | string | No | https://app.flowgladpay.com/api | API base URL. Override for self-hosted or local dev (http://localhost:3001/api). |

Agent Tools

Once installed, the following tools are available to any OpenClaw agent with access to this plugin.

Purchasing

flowglad_buy

Submit a purchase job to Flowglad Pay. An autonomous agent will visit the URL, add items to cart, and complete checkout using a virtual payment card. Streams events until the job completes (or returns immediately with noWait). For complex orders (signups, multi-item, fallback options), use flowglad_order instead.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | url | string | Yes | — | URL of the product to purchase | | maxSpend | number | No | 1500 | Maximum spend in cents ($15) | | paymentMethodId | string | No | default | Payment method to charge | | shippingAddressId | string | No | — | Shipping address for physical goods | | noWait | boolean | No | false | Return immediately after submission |

Example agent prompt: "Buy the Pro plan at https://example.com/pricing"

Returns (wait mode):

{
  "jobId": "job_abc123",
  "status": "completed",
  "result": {
    "success": true,
    "productObtained": "Pro Plan",
    "credentials": "cred_xyz"
  },
  "events": [
    { "type": "job_started", "message": "Agent navigating to vendor" },
    { "type": "done", "message": "Job completed" }
  ]
}

flowglad_order

Submit a structured BuyNode order to Flowglad Pay for complex purchases (multiple items, fallback options, signups).

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | order | object | Yes | — | BuyNode order tree (see below) | | maxSpend | number | No | 1500 | Maximum spend in cents | | paymentMethodId | string | No | default | Payment method to charge | | shippingAddressId | string | No | — | Shipping address | | noWait | boolean | No | false | Return immediately |

BuyNode types:

| Kind | Fields | Description | |------|--------|-------------| | item | url, label?, constraints? | Purchase a single product | | signup | url, label? | Sign up for a service | | goal | url, intent, label? | Achieve a freeform goal on a site | | one-of | options: BuyNode[] | Try options in order, use first success | | all-of | items: BuyNode[] | Complete all items |

Example order:

{
  "kind": "all-of",
  "items": [
    { "kind": "signup", "url": "https://example.com/signup" },
    { "kind": "item", "url": "https://example.com/pricing", "constraints": [{ "kind": "max-price", "cents": 2000 }] }
  ]
}

Job Management

flowglad_list_jobs

List recent purchase jobs. Returns job ID, status, vendor, and timestamps. Use status to filter. Default limit is 20.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | limit | number | No | Maximum number of jobs to return | | status | string | No | Filter: created, retry, active, completed, failed, cancelled |

flowglad_get_job

Get full details for a specific job including status, result, and agent steps. Check result.success and result.credentials (credential ID if account was created).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | jobId | string | Yes | Job ID to look up |

flowglad_get_job_events

Get high-level business events for a job (e.g. "navigated to checkout", "payment submitted"). Human-readable milestones. Useful for giving the user a progress summary.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | jobId | string | Yes | Job ID |

flowglad_cancel_job

Cancel a running job. Only works on jobs with status created, retry, or active.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | jobId | string | Yes | Job ID to cancel |

Credentials

flowglad_list_credentials

List all stored credentials (account logins created by the agent during signup jobs). Returns credential IDs and metadata. Use flowglad_get_credential to retrieve actual username/password.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | vendor | string | No | Filter by vendor name |

flowglad_get_credential

Retrieve a stored credential (username, password, etc.) created by the agent during a signup job. The credential ID is available in the completed job's result.credentials field.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | credentialId | string | Yes | Credential ID |

Payment Methods

flowglad_list_payment_methods

List the payment methods (virtual cards) registered on the account. Use the ID when submitting a job. No parameters.

flowglad_get_payment_method

Get details for a specific payment method by ID.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | paymentMethodId | string | Yes | Payment method ID |

Shipping Addresses

flowglad_list_shipping_addresses

List the shipping addresses registered on the account. Use the ID as shippingAddressId when submitting a job. No parameters.

flowglad_get_shipping_address

Get details for a specific shipping address by ID.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | shippingAddressId | string | Yes | Shipping address ID |

Agent Tool Access Control

To restrict which tools an agent can use, configure allowlists/denylists in your OpenClaw agent config:

{
  "agents": {
    "list": [
      {
        "name": "purchasing-agent",
        "tools": {
          "allow": ["flowglad_buy", "flowglad_list_jobs", "flowglad_get_job"]
        }
      }
    ]
  }
}

Error Handling

When the Flowglad Pay API returns an error, the response typically includes error and status fields:

{
  "error": "Job not found",
  "status": 404
}

Network errors or unexpected failures may surface as unstructured error messages. Common API error codes:

| Status | Meaning | |--------|---------| | 401 | Invalid or missing API key | | 404 | Resource not found | | 422 | Validation error (e.g. invalid URL, missing required field) | | 429 | Rate limited — retry after backoff |

Local Development

To test against a local Flowglad Pay instance:

{
  "plugins": {
    "@flowglad/fgp-openclaw": {
      "apiKey": "pk_devkey_local_testing_only_not_for_production",
      "endpoint": "http://localhost:3001/api"
    }
  }
}

See the Flowglad Pay docs for instructions on running the server locally.