Cashier — Top-up

Endpoint	What it does
POST /v1/events/{eventId}/cashier/topups	Recharges the participant's wallet. Always immediate — there's no external payment confirmation in this phase, the cashier just declares how the money arrived.

paymentMethod is free text, not a fixed list — "cash", "credit_card", "pix", or whatever category the organization uses. Requires the Idempotency-Key header: repeating the same key returns the same result, without crediting twice — even if both calls arrive at the same time, they never run the recharge in parallel. If a second call with the same key arrives while the first is still in flight, it's rejected with 409 IDEMPOTENCY_KEY_IN_PROGRESS (rather than waiting) — retry shortly, it's not a permanent error.

Response

{
  "walletId": "018f26d7-...",
  "eventId": "018f26d7-...",
  "availableAmountMinor": 21750,
  "replayed": false
}

replayed says whether this response is a fresh recharge or a replay of an earlier call with the same Idempotency-Key — false when the recharge just happened, true when it's the same response as before, with no new credit at all. Reusing the same key with a different body (a different amountMinor, userId, etc.) doesn't return the old result by mistake — it becomes 409 IDEMPOTENCY_KEY_BODY_MISMATCH: generate a new key for each logically different operation.

curl

curl -X POST http://127.0.0.1:8787/v1/events/{eventId}/cashier/topups \
  -H "Authorization: Bearer <cashier accessToken>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <client-generated uuid>" \
  -d '{ "userId": "<participant userId>", "amountMinor": 5000, "paymentMethod": "cash" }'

JavaScript

const response = await fetch(`http://127.0.0.1:8787/v1/events/${eventId}/cashier/topups`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${cashierAccessToken}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ userId, amountMinor: 5000, paymentMethod: "cash" }),
});
const { availableAmountMinor } = await response.json();

Python

import requests
import uuid

response = requests.post(
    f"http://127.0.0.1:8787/v1/events/{event_id}/cashier/topups",
    headers={
        "Authorization": f"Bearer {cashier_access_token}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"userId": user_id, "amountMinor": 5000, "paymentMethod": "cash"},
)
result = response.json()