Capture payment over the processor rail

POST

/captures/via-rail

curl --request POST \
  --url https://quikstik-core.fly.dev/captures/via-rail \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "obligation_ref": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "offering_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "offering_variant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "demand_class": "example", "effective_year": 1, "effective_month": 1, "effective_day": 1, "credential_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "capture": "now", "capacity_pool": "example", "units": 1 }'

• Production

Authoritative money capture for a booking obligation. Commits the requested seats against the capacity pool before the rail is touched (reserve-then-pay — an oversell is rejected 409 with nothing charged), resolves net + tax + gross server-side from the governed catalog and tax configuration (the client never supplies a price), then charges the operator’s configured processor (Stripe or Finix) and records the result. Idempotent on the session’s idempotency key. Fail-closed: if the operator has not connected a processor (402) or capacity cannot hold the seats (409), nothing is charged.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

obligation_ref

required

The booking obligation this charge settles.

string format: uuid

offering_id

required

string format: uuid

offering_variant_id

required

string format: uuid

demand_class

required

Demand lane (channel / OTA / membership) the price resolves in. The net is derived server-side from the governed catalog; the client cannot supply a price.

string

effective_year

required

integer format: int32

effective_month

required

integer

>= 1 <= 12

effective_day

required

integer

>= 1 <= 31

credential_id

required

Operator processor credential (or, for “on_file”, the stored buyer instrument) to charge against.

string format: uuid

capture

required

“now” captures immediately; “on_file” charges off-session against a stored instrument.

string

Allowed values: now on_file

capacity_pool

required

Opaque capacity pool key (slot / departure leaf) the seats commit against.

string

units

required

Seats to commit before any charge. Zero is rejected 400 before the rail is touched.

integer

>= 1

Responses

200

Captured — the charge settled and the result was recorded

Media typeapplication/json

object

outbox_id

required

Transactional-outbox record id for the recorded capture.

string format: uuid

processor_ref

required

The processor’s reference for the charge (Stripe / Finix).

string

gross_minor

required

Total charged in integer minor units (net + tax), server-derived.

integer format: int64

net_minor

required

Tax-exclusive net in integer minor units, server-derived from the governed catalog.

integer format: int64

tax_minor

required

Tax in integer minor units, server-derived from the tax configuration.

integer format: int64

Example ^generated

{
  "outbox_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "processor_ref": "example",
  "gross_minor": 1,
  "net_minor": 1,
  "tax_minor": 1
}

400

Malformed request (missing idempotency key, invalid effective date, unsupported capture kind, or zero seats)

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}

401

Missing or invalid session bearer token

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}

402

The operator has not connected a processor for this tenant (fail-closed, nothing charged)

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}

403

The session’s effect authority does not cover this operation

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}

404

The referenced stored buyer instrument was not found

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}

409

The capacity pool cannot hold the requested seats (oversell guard; nothing charged)

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}

422

The processor rail refused the charge

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}

502

The operator’s stored credential could not be opened into a usable processor

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}