Checkout hospedado de cartão internacional

A sessão de checkout é uma cobrança de cartão internacional de uso único que o comprador paga na página hospedada da Lezty Pay. Você não tokeniza cartão nem trata 3DS: cria a sessão no seu servidor, manda o comprador para a url e espera o webhook.

Vale para card em EUR, USD e GBP, com as mesmas regras de Cartão e carteiras internacionais: gates, limites, taxa, saldo internacional e webhook.

1. Crie a sessão

POST /v1/checkout-sessions com a sua chave de API (ou o token OAuth) com a permissão charges. O header Idempotency-Key é obrigatório: use o id do pedido no seu sistema.

curl https://api.leztypay.com/v1/checkout-sessions \
  -H "Authorization: Bearer $LEZTY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-A123" \
  -d '{
    "amount": 4990,
    "currency": "EUR",
    "description": "Plano anual",
    "payment_method": "card",
    "metadata": { "order_id": "A123" },
    "postback_url": "https://loja.exemplo.com.br/webhooks/lezty",
    "return_url": "https://loja.exemplo.com.br/obrigado",
    "expires_in_seconds": 3600
  }'

Resposta 201:

{
  "id": "cs_01j9x5k8p2q3r4s5t6u7v8w9xy",
  "object": "checkout_session",
  "url": "https://pay.leztypay.com/s/cs_01j9x5k8p2q3r4s5t6u7v8w9xy",
  "status": "open",
  "mode": "live",
  "payment_method": "card",
  "amount": 4990,
  "currency": "EUR",
  "description": "Plano anual",
  "metadata": { "order_id": "A123" },
  "postback_url": "https://loja.exemplo.com.br/webhooks/lezty",
  "return_url": "https://loja.exemplo.com.br/obrigado",
  "transaction_id": null,
  "expires_at": "2030-03-10T13:00:00.000Z",
  "created_at": "2030-03-10T12:00:00.000Z"
}

Os gates do cartão internacional e os limites por venda e por dia rodam na criação, então um 503 payment_method_unavailable ou 400 intl_ticket_above_limit aparece aqui, antes de o comprador abrir a página. Eles rodam de novo na hora do pagamento.

Repetir a mesma Idempotency-Key com o mesmo corpo devolve a mesma sessão, com Idempotent-Replayed: true e o corpo da criação (o status ali é o de quando ela nasceu; para o estado atual use o GET). Com corpo diferente, 409 idempotency_conflict.

2. Mande o comprador para a url

Na página, o comprador vê o valor, a descrição e o nome da sua loja, preenche nome, e-mail, telefone, documento e país e digita o cartão. O cartão vai direto para o adquirente; o 3DS, quando existe, acontece ali mesmo.

Uma sessão aceita no máximo um pagamento aprovado:

• cartão recusado: o comprador pode tentar outro cartão até expires_at;
• enquanto uma tentativa está sendo confirmada, a página não aceita outra;
• depois de paga, a sessão fica completed e recusa novas tentativas;
• depois de expires_at nenhuma tentativa nova começa, mas uma que já estava sendo confirmada (3DS, por exemplo) ainda pode ser paga: até ela resolver, a sessão continua open.

3. Confirme pelo webhook

A cobrança criada pela página leva o seu metadata e o seu postback_url, e dispara os eventos de sempre (transaction.created, transaction.paid e os seguintes) com a assinatura da chave que criou a sessão. Confirme o pedido só pelo transaction.paid.

4. Receba o comprador de volta

Depois do pagamento, a página leva o comprador para o return_url com session_id, transaction_id e status=paid na query. Esses parâmetros são só navegação: não confirme o pedido por eles. Consulte a sessão:

curl https://api.leztypay.com/v1/checkout-sessions/cs_01j9x5k8p2q3r4s5t6u7v8w9xy \
  -H "Authorization: Bearer $LEZTY_API_KEY"

transaction_id é a cobrança paga ou, antes disso, a última tentativa (null antes da primeira). O detalhe, com o metadata, está em GET /v1/transactions/{id}. Se uma tentativa antiga for paga depois de outra (raro, pagamento atrasado no banco), você recebe dois transaction.paid com o mesmo metadata: a Lezty Pay estorna um deles, e a sessão segue completed com a primeira paga.

Erros da criação

Referência: Cria uma sessão de checkout (cartão internacional hospedado) e Consulta uma sessão de checkout.