Criar uma payment session
Uma session é uma tentativa de pagamento: um valor, um método e um cliente, com um checkout para onde enviá-lo.
Request
POST https://pay.contagorda.com/connect
{ "amount": "49.90", "currency": "BRL", "method": "card", "return_to": "https://yourapp.com/billing/callback", "metadata": { "order_id": "1042" }, "customer": { "external_ref": "user_42", "email": "[email protected]", "name": "Ana", "document": "123.456.789-09" } }
- 1Headers: Authorization: Bearer <app key> e Idempotency-Key (obrigatório). Repetir com a mesma key devolve a mesma session (200 em vez de 201).
- 2amount é uma string com ponto; currency é BRL, USD ou EUR; method é card, pix ou boleto (o gateway precisa suportar).
- 3return_to precisa ser um host permitido nos Return hosts permitidos do app (ou qualquer host, se a lista estiver vazia).
- 4customer é opcional, mas recomendado: é criado uma vez por external_ref e cadastrado no gateway.
Response
201 Created
{ "id": "7f3a9c1e-…", "kind": "payment", "status": "processing", "redirect_url": "https://checkout.stripe.com/c/pay/…", "links": { "self": "https://pay.example.com/api/v1/sessions/7f3a9c1e-…" } }
Envie o navegador para a redirect_url. Leia a session quando quiser em links.self (GET /api/v1/sessions/:id), que devolve todos os campos.
Escolha do gateway
As rotas do app decidem: a primeira rota dentro da janela cujo gateway suporta o método e a moeda. Se esse gateway não consegue abrir o checkout, o próximo é tentado. Um app sem rotas usa todos os gateways ativos, por prioridade. POST /api/v1/sessions também aceita "gateway" para fixar um explicitamente (ele precisa estar nas rotas do app).