Pagamentos

Assinaturas

Cobre um cliente todo mês ou todo ano a partir de um preço recorrente. Comece assinaturas por um link de pagamento ou pela API e acompanhe renovações, falhas, pausas e cancelamentos pelos eventos.

Nesta página

Uma assinatura liga um cliente a um preço recorrente. A cada período, a KrokoPay cria uma cobrança no valor do preço; quando ela é paga, a assinatura avança para o período seguinte. Tudo o que você vende, recorrente ou não, começa no catálogo: produtos e seus preços.

Produtos e preços

Um produto é o que você vende (um curso, um plano, um serviço). Um preço diz quanto e com que frequência: um produto pode ter vários preços, como um plano mensal e um anual.

`type`	`interval`	Quando usar
`one_time`	`null`	Pagamentos únicos: um curso, um pacote de templates, um serviço avulso. Cobrado uma vez por uma cobrança ou link de pagamento.
`recurring`	`month` ou `year`	Assinaturas. Pagar esse preço inicia uma assinatura que renova a cada intervalo.

POST/v1/products

Parâmetros do corpo

namestringObrigatório: Nome do produto, exibido no checkout.
descriptionstringOpcional: Descrição curta.
activebooleanOpcional: O padrão é true. Produtos inativos não podem ser comprados.

Criar um produto

curl -X POST https://api.krokopay.app/v1/products \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Content-Type: application/json" \  -d '{    "name": "Curso Identidade Visual do Zero",    "description": "Curso online em 32 aulas, com exercícios práticos e arquivos de apoio."  }'

POST/v1/prices

Parâmetros do corpo

product_idstringObrigatório: O produto ao qual o preço pertence (prod_…).
nicknamestringObrigatório: Nome do plano ou variação, por exemplo Mensal ou Acesso vitalício.
amountintegerObrigatório: Valor de cada pagamento, em centavos.
currencystringObrigatório: BRL.
typestringObrigatório: one_time ou recurring.
intervalstringOpcional: Obrigatório para recurring: month ou year.

Um preço único

curl -X POST https://api.krokopay.app/v1/prices \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Content-Type: application/json" \  -d '{    "product_id": "prod_3Vb7QpK9sWd2Ee",    "nickname": "Acesso vitalício",    "amount": 49700,    "currency": "BRL",    "type": "one_time"  }'

Um preço mensal

curl -X POST https://api.krokopay.app/v1/prices \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Content-Type: application/json" \  -d '{    "product_id": "prod_6Rj8YdF3nQs5Kv",    "nickname": "Mensal",    "amount": 4900,    "currency": "BRL",    "type": "recurring",    "interval": "month"  }'

Informação: Arquive em vez de alterar valores

Para mudar o que os novos assinantes pagam, crie um novo preço e defina active: false no antigo com POST /v1/prices/{id}. Links de pagamento que usam um preço arquivado mostram o estado indisponível no checkout.

Como uma assinatura começa

Passo 1: Por um link de pagamento
Crie um link de pagamento para um preço recorrente e compartilhe. Quando o comprador paga, a KrokoPay cria o cliente (se necessário), a primeira cobrança e a assinatura. Você recebe charge.paid e subscription.created.
Passo 2: Pela API
Chame POST /v1/subscriptions para um cliente e um preço recorrente que já existem. A assinatura começa na hora e o primeiro período é cobrado imediatamente.

Um link que inicia assinaturas

curl -X POST https://api.krokopay.app/v1/payment_links \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Content-Type: application/json" \  -d '{    "name": "Clube Jacarandá — Mensal",    "price_id": "price_9Tm4BxW2gLp7Zc",    "methods": [      "card"    ]  }'

Criar uma assinatura

POST/v1/subscriptions

Parâmetros do corpo

customer_idstringObrigatório: O cliente que paga.
price_idstringObrigatório: Um preço recurring. Preços únicos são rejeitados.
methodstringObrigatório: card ou pix, usado em todas as renovações.

Criar uma assinatura

curl -X POST https://api.krokopay.app/v1/subscriptions \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Idempotency-Key: signup_ana_souza_club" \  -H "Content-Type: application/json" \  -d '{    "customer_id": "cus_8Hq2LmZr4TxN1a",    "price_id": "price_9Tm4BxW2gLp7Zc",    "method": "card"  }'

Atenção: Coleta dos dados de pagamento

Como o comprador autoriza pagamentos recorrentes numa assinatura criada pela API ainda será definido na proposta. Hoje, o caminho completo é o link de pagamento: o comprador paga o primeiro período no checkout e a assinatura nasce desse pagamento.

O objeto subscription

Atributos

idstring: Identificador único, com o prefixo sub_.
objectstring: Sempre subscription.
customer_idstring: Quem paga.
product_idstring: O produto assinado.
price_idstring: O preço recorrente cobrado a cada período.
statusstring: trialing, active, past_due, paused ou canceled.
methodstring: card ou pix.
started_atstring: Quando a assinatura começou.
current_period_startstring: Início do período já pago.
current_period_endstring: Fim desse período; a próxima renovação acontece aqui.
canceled_atstring | null: Quando terminou, ou quando vai terminar se cancel_at_period_end for true.
cancel_at_period_endboolean: true quando a assinatura termina em current_period_end em vez de renovar.

Uma assinatura ativaJSON

{  "id": "sub_5Hn2RtK8wPz4Bq",  "object": "subscription",  "customer_id": "cus_8Hq2LmZr4TxN1a",  "product_id": "prod_6Rj8YdF3nQs5Kv",  "price_id": "price_9Tm4BxW2gLp7Zc",  "status": "active",  "method": "card",  "started_at": "2026-09-03T12:00:00.000Z",  "current_period_start": "2026-11-03T12:00:00.000Z",  "current_period_end": "2026-12-03T12:00:00.000Z",  "canceled_at": null,  "cancel_at_period_end": false}

GET/v1/subscriptions/{id}

Consultar uma assinatura

curl https://api.krokopay.app/v1/subscriptions/sub_5Hn2RtK8wPz4Bq \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b"

Status e transições

Status	Significado
`trialing`	Em período de teste, antes do primeiro período pago. A configuração de testes gratuitos ainda será definida.
`active`	O período atual está pago. Renova em `current_period_end`.
`past_due`	A última cobrança de renovação falhou. A decisão sobre o acesso é sua.
`paused`	Nenhuma renovação é cobrada até a assinatura ser retomada.
`canceled`	Encerrada. Uma assinatura cancelada não pode ser retomada; crie uma nova.

De	Para	Gatilho	Eventos
—	`active`	Primeiro período pago (link) ou assinatura criada (API).	`subscription.created`, `charge.created`, `charge.paid`
`active`	`active`	Uma cobrança de renovação é paga; começa um novo período.	`charge.created`, `charge.paid`, `subscription.renewed`
`active`	`past_due`	Uma cobrança de renovação falha.	`charge.failed`, `subscription.past_due`
`trialing` / `active` / `past_due`	`paused`	`POST /v1/subscriptions/{id}/pause`	`subscription.paused`
`paused`	`active`	`POST /v1/subscriptions/{id}/resume`	`subscription.resumed` (mais uma renovação, se o período já tiver acabado)
qualquer um, exceto `canceled`	`canceled`	`DELETE /v1/subscriptions/{id}`, ou o fim do período com `cancel_at_period_end`	`subscription.canceled`

Informação: Ainda a definir

A política de novas tentativas para uma renovação que falhou (quando e quantas vezes uma assinatura past_due é cobrada de novo) e a passagem de trialing para active ainda não foram definidas. Trate o subscription.past_due pedindo ao cliente que atualize o pagamento.

Pausar e retomar

POST/v1/subscriptions/{id}/pause

Interrompe as renovações. Permitido a partir de trialing, active e past_due.

Pausar

curl -X POST https://api.krokopay.app/v1/subscriptions/sub_5Hn2RtK8wPz4Bq/pause \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b"

POST/v1/subscriptions/{id}/resume

Só para assinaturas paused. Se o período pago ainda não terminou, a assinatura simplesmente volta a active. Se já terminou, um novo período começa agora e é cobrado na hora, emitindo subscription.renewed depois de subscription.resumed.

Retomar

curl -X POST https://api.krokopay.app/v1/subscriptions/sub_5Hn2RtK8wPz4Bq/resume \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b"

Cancelar

No fim do período

POST/v1/subscriptions/{id}

Defina cancel_at_period_end: true. O cliente mantém o que já pagou, o canceled_at mostra quando a assinatura termina e ela não renova. Nenhum evento é enviado no momento da requisição; o subscription.canceled chega quando o período acaba.

Cancelar no fim do período

curl -X POST https://api.krokopay.app/v1/subscriptions/sub_5Hn2RtK8wPz4Bq \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Content-Type: application/json" \  -d '{    "cancel_at_period_end": true  }'

Imediatamente

DELETE/v1/subscriptions/{id}

Encerra a assinatura agora e emite subscription.canceled. As cobranças já pagas não são reembolsadas automaticamente: faça o reembolso da última cobrança se a sua política prever isso.

Cancelar agora

curl -X DELETE https://api.krokopay.app/v1/subscriptions/sub_5Hn2RtK8wPz4Bq \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b"

Eventos

Inscreva o seu endpoint de webhook nos eventos de assinatura e nos charge.* (cada período é uma cobrança). O data.object do evento é a assinatura como a API a devolve.

subscription.renewedJSON

{  "id": "evt_5Ee6Ff7Gg8Hh9I",  "object": "event",  "type": "subscription.renewed",  "api_version": "2026-11-01",  "created_at": "2026-11-03T12:00:09.000Z",  "data": {    "object": {      "id": "sub_5Hn2RtK8wPz4Bq",      "object": "subscription",      "customer_id": "cus_8Hq2LmZr4TxN1a",      "product_id": "prod_6Rj8YdF3nQs5Kv",      "price_id": "price_9Tm4BxW2gLp7Zc",      "status": "active",      "method": "card",      "started_at": "2026-09-03T12:00:00.000Z",      "current_period_start": "2026-11-03T12:00:00.000Z",      "current_period_end": "2026-12-03T12:00:00.000Z",      "canceled_at": null,      "cancel_at_period_end": false    }  }}

subscription.created: libere o acesso.
subscription.renewed: estenda o acesso até o novo current_period_end.
subscription.past_due: avise o cliente e decida por quanto tempo manter o acesso.
subscription.paused / subscription.resumed: suspenda e restabeleça o acesso.
subscription.canceled: remova o acesso.