Payouts

A payout sends the cash value of a prize award to the player who won it. The money moves from your Stripe Connect Standard account to the player's connected Stripe account, as a Stripe transfer made on your account's behalf. Tanitar never holds, pools or forwards the funds: it decides when a payout is due, submits it once, and records what Stripe reports.

Before you startCopy Anchor Link

Payout configuration is done in the dashboard by an administrator of your organization, not with an API key. See Payouts in the dashboard. There you:

1. Connect your Stripe account (or create one) and complete Stripe's onboarding.
2. Choose the currencies you allow for payouts. A payout is made only in your account's default currency, and only if it is on that list.
3. Register each winning player's connected Stripe account (acct_…) as a payout recipient. A recipient must be eligible to be paid.

Then, on the API side:

• Check that payouts are available: GET /v1/payouts/capabilities returns { "providers": ["stripe"] } when the deployment's Stripe preflight passed, and { "providers": [] } otherwise.
• Create a prize award definition with a payout of currency (three lowercase letters, such as eur) and amountMinor (an integer in the currency's minor unit), bound to a tournament and a rank. See Award kinds and awards.

When the tournament completes, the winner receives the prize award automatically.

Request a payoutCopy Anchor Link

POST /v1/awards/:awardId/payouts with scope rewards:mutate and no body.

curl -X POST "$REWARD_API_URL/v1/awards/awd_91c2/payouts" \
  -H "Authorization: Bearer $TANITAR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

There is exactly one payout per award. Requesting it again, with any key, returns the same record.

The request is checked before anything reaches Stripe:

If the request is admissible but your configuration does not allow it, the payout is recorded as rejected with a failureCode, and Stripe is never called:

Otherwise the payout is claimed and Tanitar submits it in the background.

StatusesCopy Anchor Link

A payout is attempted up to six times, on a fixed ladder: immediately, then after 30 seconds, 2 minutes, 10 minutes, 30 minutes and 2 hours. Each attempt reuses a key stored before the call, so Stripe never executes the same attempt twice, and an attempt whose answer was lost is checked with Stripe before any new one is made.

Read and reconcileCopy Anchor Link

Neither list is paginated or filtered. Each payout reads as:

{
  "payoutId": "pay_5d0e…",
  "awardId": "awd_91c2",
  "status": "settled",
  "currency": "eur",
  "amountMinor": 5000,
  "transferId": "tr_1Q…",
  "settledAt": "2026-09-30T12:40:03.000Z",
  "playerId": "player-7f3a",
  "failureCode": null,
  "amountReversed": 0,
  "attemptCount": 1
}

Reconcile reads the transfer from Stripe and records it: a transfer found settles the payout (or marks it reversed), and a transfer proven absent lets the next attempt proceed. If Stripe cannot be reached, reconcile answers 503 PAYOUT_PROVIDER_UNAVAILABLE and changes nothing. A rejected payout is returned unchanged.

No response contains a Stripe account id, an idempotency key or a credential.

What your players seeCopy Anchor Link

A player reads their own payouts with GET /player/v1/payouts: the award, status, currency, amount, Stripe transfer id and settlement time, without failure details.

When a payout settles, fails or is reversed, reward.payout-settled is published and can be delivered to your webhook endpoint. See the event catalog.