Quick start

1. Keep your app key on the server

Each app in Apps has its own secret key (the Default app's starts with sk_app_live_…). Store it as PAY_SECRET_KEY in your backend; never ship it to a browser or a mobile app.

2. Start the checkout

POST /connect from your backend. Send the amount, the customer and where to come back. The key says which app is calling; the app decides whether it is a payment or a subscription and which gateway takes it, so this request never changes when you switch gateways.

curl -X POST https://pay.contagorda.com/connect \
  -H "Authorization: Bearer $PAY_SECRET_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "BRL",
    "return_to": "https://yourapp.com/billing/callback",
    "customer": { "external_ref": "user_42", "email": "[email protected]" }
  }'

The answer carries redirect_url, the gateway's checkout:

{
  "id": "7f3a9c1e-…",
  "kind": "payment",
  "status": "processing",
  "redirect_url": "https://checkout.stripe.com/c/pay/…",
  "links": { "self": "https://pay.example.com/api/v1/sessions/7f3a9c1e-…" }
}

Want the broker to redirect the customer for you, with no API call? Render a signed checkout form instead (the app's Checkout flow set to API + signed forms).

3. Send the customer and trust the result

1. 1Redirect the browser to redirect_url.
2. 2After paying, the customer comes back to return_to with ?session_id=…&pay_token=… — verify the token on your server before granting anything.
3. 3Also listen to the session.paid webhook: it arrives even if the customer closes the tab.

Next: Apps & routing · Handle the result · Outbound events