SopagueDocs
v3

Pagar Sessão de Checkout

POST/v2/recurrences/checkout-sessions/{sessionId}/pay

Processa os dados de pagamento informados na tela de checkout público, tokeniza o cartão no cofre seguro, cadastra o cliente (se necessário), ativa a assinatura e conclui a sessão.

Este endpoint é público ([AllowAnonymous]) e não exige token Bearer de autenticação.

Cabeçalhos (Headers)

CabeçalhoValorObrigatórioDescrição
Content-Typeapplication/jsonSimTipo de mídia
Idempotency-Key<guid_ou_string>NãoChave de idempotência

Parâmetros

Exemplo de requisição
{
  "cardNumber": "4012001037141112",
  "holderName": "CARLOS EDUARDO",
  "expirationDate": "12/28",
  "securityCode": "123",
  "customer": {
    "name": "Carlos Eduardo",
    "email": "[email protected]",
    "document": "12345678909",
    "phone": "11987654321"
  }
}

Resposta (200 OK)

Exemplo de resposta
{
  "success": true,
  "sessionId": "e30c4ef1-0d32-4752-bf1c-5d15a51a8dae",
  "subscriptionId": "a82f3b9c-4819-482f-b4a1-30ef478b86d1",
  "customerId": "1a46ad42-78f0-4aaa-9831-612c1359c315",
  "status": "Active",
  "billingId": "d54f8e6c-7f5e-4c8d-96a3-2f08a95b8d14",
  "paymentId": "5849842a-9e12-4217-a128-9d4cb71c4c81",
  "paymentStatus": "Succeeded",
  "message": "Assinatura criada com sucesso via checkout.",
  "returnUrl": "https://minhaloja.com.br/assinatura/obrigado"
}

Próximos Passos

Após a confirmação do pagamento:

  • Redirecionamento: Redirecione o usuário para a URL informada em returnUrl exibindo a tela de confirmação/sucesso.
  • Gerenciar a Assinatura Criada: Utilize o subscriptionId para acompanhar o ciclo de cobrança em Consultar Assinatura.
  • Consultar Cliente: O pagador foi registrado e pode ser consultado via customerId em Consultar Cliente.
  • Histórico Financeiro: Acompanhe o status das faturas geradas em Listar Faturas do Cliente.

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-13aa54004fcc57d0cd389bbbc4181380-bf7125aee7332efd-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": "CardNumber",
    "description": "O número do cartão é obrigatório."
  },
  {
    "tag": "ExpiryDate",
    "description": "A data de validade é obrigatória."
  }
]

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.