Caixa — Recarga

Endpoint	O que faz
POST /v1/events/{eventId}/cashier/topups	Recarrega a wallet do participante. Sempre imediata — não existe confirmação externa de pagamento nesta fase, o caixa só declara como o dinheiro entrou.

paymentMethod é texto livre, não uma lista fechada — "cash", "credit_card", "pix", ou qualquer categoria que a organização usar. Exige o header Idempotency-Key: repetir a mesma chave devolve o mesmo resultado, sem recreditar — mesmo que as duas chamadas cheguem ao mesmo tempo, nunca executam a recarga em paralelo. Se uma segunda chamada com a mesma chave chegar enquanto a primeira ainda está em andamento, ela é rejeitada com 409 IDEMPOTENCY_KEY_IN_PROGRESS (em vez de esperar) — tente de novo em seguida, não é um erro definitivo.

Resposta

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

replayed diz se essa resposta é de uma recarga nova ou a repetição de uma chamada anterior com a mesma Idempotency-Key — false quando a recarga aconteceu agora, true quando é a mesma resposta de antes, sem crédito novo algum. Reusar a mesma chave com um corpo diferente (outro amountMinor, userId, etc.) não devolve o resultado antigo por engano — vira 409 IDEMPOTENCY_KEY_BODY_MISMATCH: gere uma chave nova pra cada operação logicamente diferente.

curl

curl -X POST http://127.0.0.1:8787/v1/events/{eventId}/cashier/topups \
  -H "Authorization: Bearer <accessToken do caixa>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid gerado pelo cliente>" \
  -d '{ "userId": "<userId do participante>", "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()