/sessions

Creates a payment session on the best gateway for the method and currency (or the one pinned with gateway) and returns where to send the customer.

Server URLhttps://pay.contagorda.com/api/v1

POST/sessions

Authorization

Bearer token: an app key from Apps (sk_app_live_… or sk_app_test_…), or the tenant key from Settings (sk_live_… or sk_test_…). The key picks the mode: a live key only sees live data, a test key only sandbox data.

Parameters

Idempotency-Keystring · headerrequired

Any unique string per operation (an order id works). The same key returns the first result instead of creating another.

Request Body

application/json, required

amountstringrequired

Positive, at most 2 decimal places, e.g. "49.90".

currencystringrequired

One of BRL, USD, EUR

methodstringrequired

One of card, pix, boleto

localestringoptional

Language of the payment page and the gateway checkout. Also takes pt, en-US and similar. Without it the app's Checkout language applies, else the customer's browser.

One of en, pt-BR

return_tostringrequired

Where the customer comes back, with session_id and a signed pay_token.

Format uri

gatewaystringoptional

Pins one gateway configuration; without it the router picks by method and currency.

Format uuid

metadataobjectoptional

Your own keys, returned as sent.

customerobjectoptional

Found by external_ref, created when new; the contact fields are kept up to date.

external_refstringrequired

Your own user id.

emailstringoptional

Format email

namestringoptional

documentstringoptional

CPF, CNPJ or tax id.

phonestringoptional

address_line1stringoptional

address_line2stringoptional

address_numberstringoptional

neighborhoodstringoptional

citystringoptional

statestringoptional

Two letters, e.g. SP.

zipcodestringoptional

countrystringoptional

Two letters, e.g. BR.

Response Body

201Session created.application/json

idstringoptional

Format uuid

statusstringoptional

One of pending, processing, paid, failed, expired, refunded

amountstringoptional

currencystringoptional

methodstringoptional

gatewayobjectoptional

The configuration that handles the payment.

idstringoptional

Format uuid

namestringoptional

providerstringoptional

One of stripe, asaas, abacatepay, pagarme, cielo

sandboxbooleanoptional

redirect_urlstringoptional

Send the customer here to pay.

Format uri

duplicatebooleanoptional

true when the Idempotency-Key was already used.

created_atstringoptional

Format date-time

200Same Idempotency-Key as an earlier call; the first session comes back with `duplicate: true`.application/json

idstringoptional

Format uuid

statusstringoptional

One of pending, processing, paid, failed, expired, refunded

amountstringoptional

currencystringoptional

methodstringoptional

gatewayobjectoptional

The configuration that handles the payment.

idstringoptional

Format uuid

namestringoptional

providerstringoptional

One of stripe, asaas, abacatepay, pagarme, cielo

sandboxbooleanoptional

redirect_urlstringoptional

Send the customer here to pay.

Format uri

duplicatebooleanoptional

true when the Idempotency-Key was already used.

created_atstringoptional

Format date-time

401Missing or invalid secret key.application/json

errorstringoptional

What went wrong.

422Missing Idempotency-Key, no gateway for the method and currency, an invalid amount or an invalid record.application/json

errorsobjectoptional

One message per field (idempotency_key, gateway, amount, replaces, subscription or record).

502The gateway refused or failed the call.application/json

errorsobjectoptional

gatewaystringoptional

The gateway's message.

providerstringoptional

The provider that failed.

cURL

curl -X POST "https://pay.contagorda.com/api/v1/sessions" \
  -H "Authorization: Bearer $PAY_SECRET_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "49.90",
  "currency": "BRL",
  "method": "card",
  "gateway": "9424c381-a90d-4921-97e9-5175d91058fb",
  "return_to": "https://yourapp.com/billing/callback",
  "metadata": {
    "order_id": "1042"
  },
  "customer": {
    "external_ref": "user_42",
    "email": "[email protected]",
    "name": "Ana Costa"
  }
}'

application/json

{
  "id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12",
  "status": "pending",
  "amount": "49.9",
  "currency": "BRL",
  "method": "card",
  "gateway": {
    "id": "9424c381-a90d-4921-97e9-5175d91058fb",
    "name": "stripe-br",
    "provider": "stripe",
    "sandbox": true
  },
  "redirect_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3",
  "duplicate": false,
  "created_at": "2026-09-25T12:00:00Z"
}

application/json

{
  "id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12",
  "status": "pending",
  "amount": "49.9",
  "currency": "BRL",
  "method": "card",
  "gateway": {
    "id": "9424c381-a90d-4921-97e9-5175d91058fb",
    "name": "stripe-br",
    "provider": "stripe",
    "sandbox": true
  },
  "redirect_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3",
  "duplicate": true,
  "created_at": "2026-09-25T12:00:00Z"
}

application/json

{
  "error": "Invalid or missing API key"
}

application/json

{
  "errors": {
    "gateway": "No active gateway supports card in BRL"
  }
}

application/json

{
  "errors": {
    "gateway": "Your card was declined.",
    "provider": "stripe"
  }
}

/sessions

Authorization

Parameters

Request Body

Response Body

Are you sure?

Keyboard shortcuts