Criar Sessão de Checkout
POST/v2/recurrences/checkout-sessions
Gera uma sessão de checkout para link externo de pagamento recorrente. O lojista envia o link gerado para o cliente final efetuar a adesão.
Pré-requisitos para Implementação
Antes de gerar uma sessão de checkout:
- Plano Cadastrado: Crie previamente o plano em Criar Plano e utilize o
idretornado no campoplanId. - Cliente (Opcional): Caso o pagador já possua cadastro no seu sistema, informe o
idcadastrado em Criar Cliente no campocustomerId. Se omitido, o formulário público solicitará nome, e-mail, documento e endereço diretamente ao comprador.
Cabeçalhos (Headers)
| Cabeçalho | Valor | Obrigatório | Descrição |
|---|---|---|---|
Authorization | Bearer <token> | Sim | Token JWT Bearer autenticado do lojista |
Content-Type | application/json | Sim | Tipo de mídia |
Idempotency-Key | <guid_ou_string> | Não | Chave de idempotência |
Parâmetros
Exemplo de requisição
{
"planId": "9fa85f64-5717-4562-b3fc-2c963f66afa6",
"customerId": "1a46ad42-78f0-4aaa-9831-612c1359c315",
"externalId": "PEDIDO-EXTERNO-1234",
"returnUrl": "https://minhaloja.com.br/assinatura/obrigado",
"expiresInMinutes": 1440,
"allowedUseCount": 1
}Resposta (201 Created)
Exemplo de resposta
{
"id": "e30c4ef1-0d32-4752-bf1c-5d15a51a8dae",
"status": "Pending",
"planId": "9fa85f64-5717-4562-b3fc-2c963f66afa6",
"customerId": "1a46ad42-78f0-4aaa-9831-612c1359c315",
"externalId": "PEDIDO-EXTERNO-1234",
"checkoutUrl": "https://api.enoqpay.com/v2/recurrences/checkout-sessions/e30c4ef1-0d32-4752-bf1c-5d15a51a8dae",
"returnUrl": "https://minhaloja.com.br/assinatura/obrigado",
"expiresOn": "2026-09-18T14:30:00Z",
"createdOn": "2026-09-17T14:30:00Z"
}Próximos Passos
- Compartilhar o Link: Redirecione seu cliente para a URL retornada em
checkoutUrlou incorpore em um botão de contratação. - Carregar Dados no Checkout: A interface web pública carrega os dados do plano via Consultar Sessão de Checkout sem exigir autenticação.
- Processar Pagamento e Assinatura: O comprador insere os dados do cartão e conclui a operação em Pagar Sessão de Checkout.
Erros
As respostas de erro conhecidas estão abaixo. Os retornos observados em homologação estão identificados separadamente dos exemplos documentados; as respostas podem variar conforme o ambiente e a configuração.
Ver validações observadas em homologação
Requisição com corpo JSON vazio ou identificador sintético. O retorno abaixo mostra a validação realizada em homologação.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"Idempotency-Key": [
"The idempotencyKey field is required."
]
},
"traceId": "00-dcb87ad675affb46d3d01de801b396d2-7ef79d7e77fe03c9-00"
}Observado em homologação
Requisição com o header Idempotency-Key e corpo JSON vazio; os identificadores na rota são sintéticos.
[
{
"tag": "RecurrencePlanId",
"description": "O RecurrencePlanId é obrigatório."
}
]Campos da resposta de erro
A tabela reúne os campos presentes nos exemplos acima. Uma resposta HTTP sem corpo não inclui esses campos.
