Pular para o conteúdo principal
Payment Element é a integração recomendada no navegador para novos checkouts com cartão.

​
Quando usar

  • Você está construindo um novo checkout com cartão.
  • Você quer campos hospedados em vez de coletar dados brutos do cartão.
  • Você precisa de 3D Secure no mesmo fluxo do navegador.
  • Seu back-end deve continuar dono da criação da transação e da liberação do pedido.
Responsabilidades do navegador:
  • carregar o script da Pagou
  • montar o campo de cartão
  • enviar por elements.submit(...)
  • continuar o fluxo de challenge no navegador quando necessário
Responsabilidades do back-end:
  • autenticar com credenciais secretas
  • criar POST /v2/transactions
  • persistir external_ref, ID da transação e requestId
  • liberar o pedido apenas a partir de webhook ou reconciliação

​
Exemplo de requisição do back-end

{
  "external_ref": "order_2001",
  "amount": 2490,
  "currency": "BRL",
  "method": "credit_card",
  "token": "pgct_token_from_browser",
  "installments": 1
}

​
Exemplo de resposta do back-end

{
  "success": true,
  "requestId": "req_4001",
  "data": {
    "id": "tr_2001",
    "status": "three_ds_required",
    "method": "credit_card",
    "next_action": {
      "type": "three_ds_challenge",
      "challenge_session_id": "3ds_1001",
      "client_secret": "sec_1001",
      "expires_at": "2026-03-16T14:20:00.000Z"
    }
  }
}

​
Erro comum

{
  "type": "https://api.pagou.ai/problems/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request contains invalid data.",
  "errors": [
    {
      "field": "token",
      "message": "Token is required for credit card payments",
      "code": "invalid_type"
    }
  ]
}

​
Comece por aqui