Charges

A charge is an authorized checkout that you capture. Capture moves money, posts fees and cashback, and is idempotent.

Capture

curl -s -X POST https://api.fluense.social/charges/$AUTH/capture \
  -H "x-api-key: $KEY"

{
  "journal_id": "019a…",
  "mdr_fee": 154,
  "buyer_amount": 0,
  "deferred_buyer_amount": 225,
  "recommender_amount": 75,
  "recommender_id": "019a…",
  "recommenders": [ { "user_id": "019a…", "amount": 75 } ]
}

Field	Meaning
mdr_fee	Merchant discount rate: (total - tax - cashback) x mdr_bps / 10000. Default 200 bps (2%), overridable per merchant
recommender_amount	Cashback earned by the recommender at capture (0 when the purchase did not come from a recommendation)
buyer_amount	Always 0 at capture — the buyer's share is deferred
deferred_buyer_amount	The buyer's cashback share, earned when they recommend the product they bought

Capture is idempotent on the charge id: retrying returns the same transaction reference and cashback, and never charges twice. Capture works with an API key or the owning consumer session; live capture requires an approved KYB for the org.

When a line's product matches an active buy-list entry, the recommender earns their share automatically. See Cashback.

Void

POST /charges/{id}/void cancels an AUTHORIZED charge and releases the hold. Only AUTHORIZED charges can be voided.

{ "ok": true }

Return (refund)

POST /charges/{id}/return refunds a captured charge. Omit items for a full refund, or pass quantities for a partial one.

curl -s -X POST https://api.fluense.social/charges/$AUTH/return \
  -H "x-api-key: $KEY" \
  -H 'content-type: application/json' \
  -d '{"reason":"damaged on arrival","items":[{"product_id":"sku-1","qty":1}]}'

{
  "return_id": "019a…",
  "refund": 9700,
  "buyer_cut": 225,
  "rec_cut": 75,
  "award_adjusted": true
}

Field	Meaning
refund	Principal returned: goods + pro-rata shipping and tax
buyer_cut / rec_cut	Cashback shares removed from the return
award_adjusted	True when this return reduced or voided pending cashback

Rules:

• Refund quantity is validated against captured quantity minus previous returns — over-returning is a 400.
• Pending cashback shrinks with the return; cashback that has already landed is never clawed back.
• Returns are not idempotent: retry only if the previous attempt produced no response.