Visão geral

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.

Navegador vs back-end

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": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "id": "018f1f2e-7b43-7c9a-8d3e-1a2b3c4d5e70",
    "status": "three_ds_required",
    "method": "credit_card",
    "next_action": {
      "type": "three_ds_challenge"
    }
  }
}

Retorne esse payload ao navegador sem alterações. next_action é opaco — elements.submit(...) o lê e conclui a autenticação do cartão para você.

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 com Payment Element

Construa o checkout de cartão

Lançamento e migração

Quando usar

Navegador vs back-end

Exemplo de requisição do back-end

Exemplo de resposta do back-end

Erro comum

Comece por aqui

​Quando usar

​Navegador vs back-end

​Exemplo de requisição do back-end

​Exemplo de resposta do back-end

​Erro comum

​Comece por aqui

Quando usar

Navegador vs back-end

Exemplo de requisição do back-end

Exemplo de resposta do back-end

Erro comum

Comece por aqui