Gateways

Create an authorization

Authorizes (holds funds on) the payment method for amount_cents without capturing. Creates an authorize transaction and returns it with 201; capture it later via the transaction capture endpoint or release it with void. A 201 means the request was processed — read the outcome from data.status (success, declined, or error). Pass an Idempotency-Key header to make retries safe. Returns 404 when the gateway is not found, or a referenced payment_method_id is unknown or owned by a different merchant, 409 on an in-flight duplicate key, and 422 when the request fails validation. On success, API-key-authenticated requests emit a payment.completed webhook.

POST

api

payment

v2026-04

gateways

{id}

authorize

curl --request POST \
  --url https://api.fluid.app/api/payment/v2026-04/gateways/{id}/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transaction": {
    "amount_cents": 4999,
    "currency_code": "USD",
    "payment_method_id": "pm_9f8e7d6c"
  }
}
'

{
  "data": {
    "id": "<string>",
    "action": "purchase",
    "status": "success",
    "amount_cents": 123,
    "currency_code": "<string>",
    "processing_fee_cents": 123,
    "platform_fee_cents": 123,
    "credited_amount_cents": 123,
    "retain_on_success": true,
    "metadata": {},
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "gateway_id": "<string>",
    "payment_method_id": "<string>",
    "card_network": "<string>",
    "parent_transaction_id": "<string>",
    "payment_source": "<string>",
    "gateway_transaction_id": "<string>",
    "reference_token": "<string>",
    "description": "<string>"
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

{
  "message": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  },
  "status": "<string>"
}

{
  "message": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

{
  "status": "error",
  "message": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  },
  "errors": "<string>"
}

{
  "status": "error",
  "message": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  },
  "errors": "<string>"
}

{
  "status": "error",
  "message": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  },
  "errors": "<string>"
}

Authorizations

Authorization

string

header

required

Merchant API key (fp_live_* for live, fp_test_* for sandbox) or an admin-tier JWT (company admin or root admin). Non-admin JWTs are rejected with 403; live API keys additionally require the merchant's API access to be enabled.

Headers

Idempotency-Key

string

Optional client-generated key (UUID recommended) used to deduplicate retries. The first request with a given key executes normally; a retry with the same key replays that first response with X-Idempotent-Replayed: true for up to 24 hours. A concurrent retry while the first request is still in flight returns 409.

The response cache is keyed on the authenticated merchant and this key ONLY — not on the operation, path, or request body. Use a fresh, unique key per logical request: reusing one key across different operations (for example a purchase and then a capture) replays the first operation's cached status and body instead of performing the second.

Idempotency applies to API-key-authenticated requests only. On JWT-authenticated requests the header is accepted but ignored — no deduplication, no 409, no replay. The cache stores whatever the first execution returned, including error responses such as 404 or 422. Keys longer than 255 characters are rejected with an unhandled 500.

Maximum string length: 255

Path Parameters

string

required

Gateway slug

Body

application/json

transaction

object

required

Show child attributes

Response

Authorization created

data

object

required

Show child attributes

meta

object

required

Show child attributes

curl --request POST \
  --url https://api.fluid.app/api/payment/v2026-04/gateways/{id}/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transaction": {
    "amount_cents": 4999,
    "currency_code": "USD",
    "payment_method_id": "pm_9f8e7d6c"
  }
}
'

{
  "data": {
    "id": "<string>",
    "action": "purchase",
    "status": "success",
    "amount_cents": 123,
    "currency_code": "<string>",
    "processing_fee_cents": 123,
    "platform_fee_cents": 123,
    "credited_amount_cents": 123,
    "retain_on_success": true,
    "metadata": {},
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "gateway_id": "<string>",
    "payment_method_id": "<string>",
    "card_network": "<string>",
    "parent_transaction_id": "<string>",
    "payment_source": "<string>",
    "gateway_transaction_id": "<string>",
    "reference_token": "<string>",
    "description": "<string>"
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

{
  "message": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  },
  "status": "<string>"
}

{
  "message": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

{
  "status": "error",
  "message": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  },
  "errors": "<string>"
}

{
  "status": "error",
  "message": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  },
  "errors": "<string>"
}

{
  "status": "error",
  "message": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  },
  "errors": "<string>"
}

Overview

Task guides

Portal & Widgets

Endpoints

Auth endpoints

Checkout endpoints

Public SDK endpoints

Member endpoints

Payment gateway endpoints

Cart payment endpoints

Commerce endpoints

Webhooks endpoints

Company admin endpoints (v0)

Analytics

Create an authorization

Authorizations

Headers

Path Parameters

Body

Response