/connect

Creates a one-off payment or a subscription for the calling app, on the gateway its routes pick (with automatic fallback), and returns where to send the customer.

The app's Charges setting decides what is created:

a payments app creates a one-off payment;
a subscriptions app creates a subscription, and amount, currency and interval are required.

Two ways to call it:

From the product's backend (recommended): JSON with Authorization: Bearer. The answer carries redirect_url.
From the customer's browser (apps on the API + signed forms flow): a signed form, application/x-www-form-urlencoded, with the app's public key, the charge, expires and signature, and no Authorization header. The broker answers 303 to the checkout.

When it refuses a signed form, the customer sees an HTML page with a way back:

400: expires missing or invalid;
403: wrong signature or app;
410: expired;
422: return_to not allowed.

The signature is the lowercase hex HMAC-SHA256, keyed with the app's secret key, of every other field:

flattened as customer[email];
sorted by key, byte by byte;
percent-encoded per RFC 3986 (space as %20);
joined as key=value with &.

It is also the idempotency key. See the Signed checkout forms guide.

Server URLhttps://pay.contagorda.com

POST/connect

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

amountstringoptional

Decimal with a dot.

currencystringoptional

One of BRL, USD, EURDefault BRL

methodstringoptional

One-off payments only. Without it, card, or the gateway's method when it has no card (PIX on AbacatePay).

One of card, pix, boleto

intervalstringoptional

Subscriptions only (required there).

One of month, year

descriptionstringoptional

Subscriptions only, shown on the checkout.

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

Must be an allowed return host of the app (any host while the list is empty).

Format uri

replacesstringoptional

Subscriptions only; the customer's running subscription to cancel once this one is active.

Format uuid

metadataobjectoptional

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

303Signed form only. Redirect to the gateway's checkout; a refusal answers an HTML page with a way back.no body

No body.

201Payment or subscription created.application/json

idstringoptional

The session id (payment) or the subscription id.

Format uuid

kindstringoptional

One of payment, subscription

statusstringoptional

redirect_urlstringoptional

Format uri

linksobjectoptional

selfstringoptional

Format uri

200Same Idempotency-Key as an earlier call; the first result comes back.application/json

idstringoptional

The session id (payment) or the subscription id.

Format uuid

kindstringoptional

One of payment, subscription

statusstringoptional

redirect_urlstringoptional

Format uri

linksobjectoptional

selfstringoptional

Format uri

401Missing or invalid secret key.application/json

errorstringoptional

What went wrong.

403The app is paused, the `app` asked for does not exist, or the endpoint needs the tenant key.application/json

errorstringoptional

What went wrong.

422Missing Idempotency-Key, a field of the other kind of charge (interval or replaces on a payments app, method on a subscriptions app), no route 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/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]"
  }
}'

No body.

application/json

{
  "id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12",
  "kind": "payment",
  "status": "processing",
  "redirect_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3",
  "links": {
    "self": "https://pay.example.com/api/v1/sessions/7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12"
  }
}

application/json

{
  "id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12",
  "kind": "payment",
  "status": "processing",
  "redirect_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3",
  "links": {
    "self": "https://pay.example.com/api/v1/sessions/7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12"
  }
}

application/json

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

application/json

{
  "error": "App blackevin-prod is inactive"
}

application/json

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

application/json

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

/connect

Authorization

Parameters

Request Body

Response Body

Are you sure?

Keyboard shortcuts