/subscriptions

Cria uma subscription e o primeiro checkout dela. Envie o cliente para a redirect_url; ativação, renovações e cancelamento chegam como webhooks. replaces cancela uma subscription mais antiga do mesmo cliente quando esta fica ativa (troca de plano).

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

POST/subscriptions

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

amountstringobrigatório

Preço por intervalo, ex.: "29.90".

currencystringobrigatório

Um de BRL, USD, EUR

intervalstringobrigatório

Um de month, year

descriptionstringopcional

Aparece no checkout e nas invoices.

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

Formato uri

gatewaystringopcional

Fixa uma configuração de gateway que suporta subscriptions.

Formato uuid

replacesstringopcional

Uma subscription do mesmo cliente a cancelar quando esta ficar ativa.

Formato uuid

metadataobjectopcional

customerobjectobrigatório

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

201Subscription criada, aguardando o primeiro pagamento.application/json

idstringopcional

Formato uuid

statusstringopcional

pending: esperando o primeiro pagamento; active: dá acesso (também com um cancelamento agendado); past_due: uma renovação falhou e o gateway está tentando de novo; canceled: encerrada.

Um de pending, active, past_due, canceled

amountstringopcional

Preço por intervalo, decimal com ponto.

currencystringopcional

intervalstringopcional

Um de month, year

descriptionstring | nullopcional

gatewayobjectopcional

A configuração que processa o pagamento.

idstringopcional

Formato uuid

namestringopcional

providerstringopcional

Um de stripe, asaas, abacatepay, pagarme, cielo

sandboxbooleanopcional

customerobject | nullopcional

idstringopcional

Formato uuid

external_refstringopcional

O seu próprio id para o cliente, como mandado no /connect.

emailstring | nullopcional

namestring | nullopcional

documentstring | nullopcional

phonestring | nullopcional

address_line1string | nullopcional

address_line2string | nullopcional

address_numberstring | nullopcional

neighborhoodstring | nullopcional

citystring | nullopcional

statestring | nullopcional

zipcodestring | nullopcional

countrystring | nullopcional

metadataobjectopcional

O que o produto mandou com o checkout, devolvido na subscription e em cada ciclo de renovação.

current_period_endstring | nullopcional

Fim do período pago, quando a próxima renovação é cobrada. Pode vir null em subscription.activated; a data chega depois em subscription.updated.

Formato date-time

cancel_at_period_endbooleanopcional

true quando um cancelamento está agendado para o fim do período.

cancel_requested_atstring | nullopcional

Quando o cancelamento foi pedido.

Formato date-time

cancel_atstring | nullopcional

Quando um cancelamento agendado a encerra.

Formato date-time

replacesstring | nullopcional

A subscription que esta substituiu (troca de plano).

Formato uuid

canceled_atstring | nullopcional

Quando ela terminou.

Formato date-time

created_atstringopcional

Formato date-time

linksobjectopcional

selfstringopcional

Formato uri

session_idstringopcional

A session do primeiro pagamento.

Formato uuid

redirect_urlstringopcional

Envie o cliente para cá para assinar.

Formato uri

duplicatebooleanopcional

200Mesma Idempotency-Key de uma chamada anterior; a primeira subscription volta com `duplicate: true`.application/json

idstringopcional

Formato uuid

statusstringopcional

pending: esperando o primeiro pagamento; active: dá acesso (também com um cancelamento agendado); past_due: uma renovação falhou e o gateway está tentando de novo; canceled: encerrada.

Um de pending, active, past_due, canceled

amountstringopcional

Preço por intervalo, decimal com ponto.

currencystringopcional

intervalstringopcional

Um de month, year

descriptionstring | nullopcional

gatewayobjectopcional

A configuração que processa o pagamento.

idstringopcional

Formato uuid

namestringopcional

providerstringopcional

Um de stripe, asaas, abacatepay, pagarme, cielo

sandboxbooleanopcional

customerobject | nullopcional

idstringopcional

Formato uuid

external_refstringopcional

O seu próprio id para o cliente, como mandado no /connect.

emailstring | nullopcional

namestring | nullopcional

documentstring | nullopcional

phonestring | nullopcional

address_line1string | nullopcional

address_line2string | nullopcional

address_numberstring | nullopcional

neighborhoodstring | nullopcional

citystring | nullopcional

statestring | nullopcional

zipcodestring | nullopcional

countrystring | nullopcional

metadataobjectopcional

O que o produto mandou com o checkout, devolvido na subscription e em cada ciclo de renovação.

current_period_endstring | nullopcional

Fim do período pago, quando a próxima renovação é cobrada. Pode vir null em subscription.activated; a data chega depois em subscription.updated.

Formato date-time

cancel_at_period_endbooleanopcional

true quando um cancelamento está agendado para o fim do período.

cancel_requested_atstring | nullopcional

Quando o cancelamento foi pedido.

Formato date-time

cancel_atstring | nullopcional

Quando um cancelamento agendado a encerra.

Formato date-time

replacesstring | nullopcional

A subscription que esta substituiu (troca de plano).

Formato uuid

canceled_atstring | nullopcional

Quando ela terminou.

Formato date-time

created_atstringopcional

Formato date-time

linksobjectopcional

selfstringopcional

Formato uri

session_idstringopcional

A session do primeiro pagamento.

Formato uuid

redirect_urlstringopcional

Envie o cliente para cá para assinar.

Formato uri

duplicatebooleanopcional

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

errorstringopcional

O que deu errado.

422Idempotency-Key ausente, nenhum gateway com subscriptions para a moeda, amount inválido, `replaces` 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/api/v1/subscriptions" \
  -H "Authorization: Bearer $PAY_SECRET_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "29.90",
  "currency": "BRL",
  "interval": "month",
  "description": "Blackevin Pro",
  "return_to": "https://yourapp.com/billing/callback",
  "customer": {
    "external_ref": "user_42",
    "email": "[email protected]"
  }
}'

application/json

{
  "id": "5d6e7f80-91a2-4b3c-8d4e-5f60718293a4",
  "status": "pending",
  "amount": "29.9",
  "currency": "BRL",
  "interval": "month",
  "description": "Blackevin Pro",
  "gateway": {
    "id": "9424c381-a90d-4921-97e9-5175d91058fb",
    "name": "stripe-br",
    "provider": "stripe",
    "sandbox": true
  },
  "customer": {
    "id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
    "external_ref": "user_42",
    "email": "[email protected]",
    "name": null,
    "document": null,
    "phone": null,
    "address_line1": null,
    "address_line2": null,
    "address_number": null,
    "neighborhood": null,
    "city": null,
    "state": null,
    "zipcode": null,
    "country": "BR"
  },
  "metadata": {},
  "current_period_end": null,
  "cancel_at_period_end": false,
  "cancel_requested_at": null,
  "cancel_at": null,
  "replaces": null,
  "canceled_at": null,
  "created_at": "2026-09-25T12:00:00Z",
  "links": {
    "self": "https://pay.example.com/api/v1/subscriptions/5d6e7f80-91a2-4b3c-8d4e-5f60718293a4"
  },
  "session_id": "8e9fa0b1-c2d3-4e5f-8a6b-7c8d9e0f1a2b",
  "redirect_url": "https://checkout.stripe.com/c/pay/cs_test_d4e5f6",
  "duplicate": false
}

application/json

{
  "id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12",
  "status": "active",
  "amount": "49.90",
  "currency": "BRL",
  "interval": "month",
  "description": "Pro plan",
  "gateway": {
    "id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12",
    "name": "stripe-br",
    "provider": "stripe",
    "sandbox": true
  },
  "customer": {
    "id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12",
    "external_ref": "user_42",
    "email": "[email protected]",
    "name": "Ana Souza",
    "document": "123.456.789-09",
    "phone": "+55 11 99999-0000",
    "address_line1": "Av. Paulista",
    "address_line2": null,
    "address_number": "1000",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01310-100",
    "country": "BR"
  },
  "metadata": {
    "plan": "pro",
    "account_id": "acc_42"
  },
  "current_period_end": "2026-09-25T12:00:00Z",
  "cancel_at_period_end": true,
  "cancel_requested_at": "2026-09-25T12:00:00Z",
  "cancel_at": "2026-09-25T12:00:00Z",
  "replaces": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12",
  "canceled_at": "2026-09-25T12:00:00Z",
  "created_at": "2026-09-25T12:00:00Z",
  "links": {
    "self": "https://example.com"
  },
  "session_id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12",
  "redirect_url": "https://example.com",
  "duplicate": true
}

application/json

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

application/json

{
  "errors": {
    "replaces": "Subscription 5d6e7f80-91a2-4b3c-8d4e-5f60718293a4 is already canceled"
  }
}

application/json

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

/subscriptions

Autorização

Parâmetros

Request body

Response body

Tem certeza?

Atalhos de teclado