Transactions

Capture an authorization

Captures funds previously held by an authorization. Send amount_cents for a partial capture; omit it to capture the full authorized amount. Creates a capture transaction linked to the authorization via parent_transaction_id and returns it with 201; read the capture outcome from data.status. Pass an Idempotency-Key header to make retries safe. Returns 404 when the authorization is not found — including authorizations that were not created through this API — 409 on an in-flight duplicate key, and 422 when the authorization cannot be captured. On success, API-key-authenticated requests emit a payment.captured webhook.

POST

api

payment

v2026-04

transactions

{id}

capture

curl --request POST \
  --url https://api.fluid.app/api/payment/v2026-04/transactions/{id}/capture \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "data": {
    "id": "fpi_01hxyzghi789",
    "gateway_id": "stripe-usd",
    "payment_method_id": "018f2c1a-9c4b-7e6d-9f10-3b4c5d6e7f80",
    "card_network": "visa",
    "parent_transaction_id": "fpi_01hxyzabc123",
    "action": "capture",
    "status": "success",
    "amount_cents": 4999,
    "currency_code": "USD",
    "payment_source": "CreditCard",
    "gateway_transaction_id": "ch_3PQr7s2eZvKYlo2C",
    "reference_token": null,
    "description": null,
    "processing_fee_cents": 175,
    "platform_fee_cents": 130,
    "credited_amount_cents": 0,
    "retain_on_success": false,
    "metadata": {},
    "created_at": "2026-04-02T09:30:00Z",
    "updated_at": "2026-04-02T09:30:00Z"
  },
  "meta": {
    "request_id": "018f2c1a-8b3a-7e6d-9f10-2a3b4c5d6e7f",
    "timestamp": "2026-04-02T09:30:00Z"
  }
}

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

Transaction slug (authorization to capture)

Body

application/json

transaction

object

Show child attributes

Response

Capture 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/transactions/{id}/capture \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "data": {
    "id": "fpi_01hxyzghi789",
    "gateway_id": "stripe-usd",
    "payment_method_id": "018f2c1a-9c4b-7e6d-9f10-3b4c5d6e7f80",
    "card_network": "visa",
    "parent_transaction_id": "fpi_01hxyzabc123",
    "action": "capture",
    "status": "success",
    "amount_cents": 4999,
    "currency_code": "USD",
    "payment_source": "CreditCard",
    "gateway_transaction_id": "ch_3PQr7s2eZvKYlo2C",
    "reference_token": null,
    "description": null,
    "processing_fee_cents": 175,
    "platform_fee_cents": 130,
    "credited_amount_cents": 0,
    "retain_on_success": false,
    "metadata": {},
    "created_at": "2026-04-02T09:30:00Z",
    "updated_at": "2026-04-02T09:30:00Z"
  },
  "meta": {
    "request_id": "018f2c1a-8b3a-7e6d-9f10-2a3b4c5d6e7f",
    "timestamp": "2026-04-02T09:30:00Z"
  }
}

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

Capture an authorization

Authorizations

Headers

Path Parameters

Body

Response