Campaigns

Settle a creator payment

Triggers a real Stripe transfer + wallet debit when reward_type='cash'. reward_type='custom' records the settlement only — no money moves. Idempotency-Key is REQUIRED and the inner PaymentService.settle runs claim/release semantics so a retry with the same key can never double-pay. Every successful settlement emits an audit.campaigns.settle log line for on-call reconciliation. X-Dry-Run: true skips the Stripe call entirely.

post/campaigns/payments/settle

Headers

Idempotency-Keystring nullable

X-Dry-Runstring nullable

Request body

creator_idinteger required

campaign_idinteger required

amountnumber required

Settlement amount in the campaign's currency. Capped at $100,000 per call as a sanity guard.

currencystring required

ISO 4217 currency code (e.g. 'USD'). Informational — the shop's persisted wallet currency takes precedence at settlement time. If the wallet currency differs from this value, the transfer executes in the wallet currency without rejection. The response's currency field confirms the currency actually used for the transfer.

reward_typestring required

'cash' triggers a Stripe transfer + wallet debit; 'custom' records the settlement only (no money moves).

campaign_creator_mapping_idinteger required

REQUIRED. The campaign-creator mapping id that the settlement is being recorded against. The portal surfaces this id on every creator row in GET /campaigns/{id}/detail and in the response to the accept endpoint, so callers always have it. Required because the underlying PaymentService.settle only runs its double-payment guard (claim_for_settlement_sync) when a mapping id is present — omitting it would leave the money-moving path with idempotency-only protection (a different Idempotency-Key per call could debit the wallet repeatedly with no DB-level guard).

metadataobject nullable

Free-form metadata stored alongside the settlement (e.g. agent annotation, internal reference).

Response

Successful Response

successboolean required

transfer_idstring nullable

Stripe transfer id for cash settlements. Null for custom-reward settlements (no Stripe call).

amountnumber nullable

currencystring nullable

paid_atstring nullable

wallet_balancenumber nullable

Remaining wallet balance after the settlement.

Changes

No recorded changes to this endpoint across all 2 revisions of this API.