/connect

Cria um pagamento avulso ou uma subscription para o app que chama, no gateway que as rotas dele escolhem (com fallback automático), e devolve para onde enviar o cliente.

A configuração Cobranças do app decide o que é criado:

um app de pagamentos cria um pagamento avulso;
um app de subscriptions cria uma subscription, e amount, currency e interval são obrigatórios.

Duas formas de chamar:

Do backend do produto (recomendado): JSON com Authorization: Bearer. A resposta traz a redirect_url.
Do navegador do cliente (apps no fluxo API + signed forms): um form assinado, application/x-www-form-urlencoded, com a public key do app, a cobrança, expires e signature, sem header Authorization. O broker responde 303 para o checkout.

Quando recusa um signed form, o cliente vê uma página HTML com um caminho de volta:

400: expires ausente ou inválido;
403: signature ou app errado;
410: expirado;
422: return_to não permitido.

A signature é o HMAC-SHA256 em hex minúsculo, com a secret key do app, de todos os outros campos:

achatados como customer[email];
ordenados pela key, byte a byte;
com percent-encoding RFC 3986 (espaço como %20);
unidos como key=value com &.

Ela também é a idempotency key. Veja o guide Signed checkout forms.

Server URLhttps://pay.contagorda.com

POST/connect

Autorização

Bearer token: a key de um app, em Apps (sk_app_live_… ou sk_app_test_…), ou a tenant key, em Settings (sk_live_… ou sk_test_…). A key define o modo: uma key live só vê dados live, uma key test só dados de sandbox.

Parâmetros

Idempotency-Keystring · headerobrigatório

Qualquer string única por operação (um id de pedido serve). A mesma key devolve o primeiro resultado em vez de criar outro.

Request body

application/json, obrigatório

amountstringopcional

Decimal com ponto.

currencystringopcional

Um de BRL, USD, EURPadrão BRL

methodstringopcional

Só para pagamentos avulsos. Sem ele, cartão, ou o método do gateway quando ele não tem cartão (PIX na AbacatePay).

Um de card, pix, boleto

intervalstringopcional

Só para subscriptions (obrigatório nelas).

Um de month, year

descriptionstringopcional

Só para subscriptions; aparece no checkout.

localestringopcional

Idioma da página de pagamento e do checkout do gateway. Também aceita pt, en-US e parecidos. Sem ele, vale o Idioma do checkout do app; se não houver, o navegador do cliente.

Um de en, pt-BR

return_tostringobrigatório

Precisa ser um return host permitido do app (qualquer host, se a lista estiver vazia).

Formato uri

replacesstringopcional

Só para subscriptions; a subscription em andamento do cliente a cancelar quando esta ficar ativa.

Formato uuid

metadataobjectopcional

customerobjectopcional

Encontrado pelo external_ref, criado quando é novo; os campos de contato são mantidos atualizados.

external_refstringobrigatório

O id do usuário no seu sistema.

emailstringopcional

Formato email

namestringopcional

documentstringopcional

CPF, CNPJ ou tax id.

phonestringopcional

address_line1stringopcional

address_line2stringopcional

address_numberstringopcional

neighborhoodstringopcional

citystringopcional

statestringopcional

Duas letras, ex.: SP.

zipcodestringopcional

countrystringopcional

Duas letras, ex.: BR.

Response body

303Só signed form. Redirect para o checkout do gateway; uma recusa responde uma página HTML com um caminho de volta.sem body

Sem body.

201Pagamento ou subscription criado.application/json

idstringopcional

O id da session (pagamento) ou o id da subscription.

Formato uuid

kindstringopcional

Um de payment, subscription

statusstringopcional

redirect_urlstringopcional

Formato uri

linksobjectopcional

selfstringopcional

Formato uri

200Mesma Idempotency-Key de uma chamada anterior; o primeiro resultado volta.application/json

idstringopcional

O id da session (pagamento) ou o id da subscription.

Formato uuid

kindstringopcional

Um de payment, subscription

statusstringopcional

redirect_urlstringopcional

Formato uri

linksobjectopcional

selfstringopcional

Formato uri

401Secret key ausente ou inválida.application/json

errorstringopcional

O que deu errado.

403O app está pausado, o `app` pedido não existe, ou o endpoint exige a tenant key.application/json

errorstringopcional

O que deu errado.

422Idempotency-Key ausente, nenhuma rota para o método e a moeda, amount inválido ou registro inválido.application/json

errorsobjectopcional

Uma mensagem por campo (idempotency_key, gateway, amount, replaces, subscription ou record).

502O gateway recusou ou falhou a chamada.application/json

errorsobjectopcional

gatewaystringopcional

A mensagem do gateway.

providerstringopcional

O provider que falhou.

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]"
  }
}'

Sem 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

Autorização

Parâmetros

Request body

Response body

Tem certeza?

Atalhos de teclado