SopagueDocs
v3

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 id retornado no campo planId.
  • Cliente (Opcional): Caso o pagador já possua cadastro no seu sistema, informe o id cadastrado em Criar Cliente no campo customerId. Se omitido, o formulário público solicitará nome, e-mail, documento e endereço diretamente ao comprador.

Cabeçalhos (Headers)

CabeçalhoValorObrigatórioDescrição
AuthorizationBearer <token>SimToken JWT Bearer autenticado do lojista
Content-Typeapplication/jsonSimTipo de mídia
Idempotency-Key<guid_ou_string>NãoChave 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 checkoutUrl ou 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.