Create a payment session
A session is one payment attempt: an amount, a method and a customer, with a checkout to send them to.
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> and Idempotency-Key (required). Retrying with the same key returns the same session (200 instead of 201).
- 2amount is a string with a dot; currency is BRL, USD or EUR; method is card, pix or boleto (the gateway must support it).
- 3return_to must be a host allowed in the app's Allowed return hosts (or any host while the list is empty).
- 4customer is optional but recommended: it is created once per external_ref and registered on the 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-…" } }
Send the browser to redirect_url. Read the session any time at links.self (GET /api/v1/sessions/:id), which returns every field.
Choosing the gateway
The app's routes decide: the first route inside its window whose gateway supports the method and currency. If that gateway fails to open the checkout, the next one is tried. An app without routes uses every active gateway by priority. POST /api/v1/sessions also takes "gateway" to pin one explicitly (it must be routed for the app).