Pular para o conteúdo principal
Use Payment Element quando estiver construindo ou reconstruindo o checkout.

​
Por que a Pagou recomenda

  • Campos hospedados reduzem exposição PCI.
  • A tokenização acontece no navegador sem o seu back-end tocar dados brutos do cartão.
  • O handoff de 3D Secure usa next_action no mesmo fluxo.
  • O contrato do back-end fica simples: criar uma transaction com o token devolvido pelo navegador.

​
Requisição do back-end

curl --request POST \
  --url https://api.pagou.ai/v2/transactions \
  --header "Authorization: Bearer SEU_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "external_ref": "order_2001",
    "amount": 2490,
    "currency": "BRL",
    "method": "credit_card",
    "token": "pgct_token_from_browser",
    "installments": 1,
    "buyer": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "document": {
        "type": "CPF",
        "number": "12345678901"
      }
    },
    "products": [
      {
        "name": "Plan upgrade",
        "price": 2490,
        "quantity": 1
      }
    ]
  }'

​
Exemplo de resposta

{
  "success": true,
  "requestId": "req_1301",
  "data": {
    "id": "tr_2001",
    "status": "three_ds_required",
    "method": "credit_card",
    "amount": 2490,
    "base_price": 2490,
    "currency": "BRL",
    "next_action": {
      "type": "three_ds_challenge",
      "challenge_session_id": "3ds_1001",
      "client_secret": "sec_1001",
      "expires_at": "2026-03-16T14:20:00.000Z"
    },
    "created_at": "2026-03-16T14:00:00.000Z",
    "updated_at": "2026-03-16T14:00:00.000Z",
    "paid_at": null
  }
}

​
Erro comum

Status 422 
{
  "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"
    }
  ]
}
Como corrigir: crie o token no Payment Element antes. Não colete os dados brutos do cartão no seu próprio formulário e envie direto para a API.

​
Regra de decisão

  • Use Payment Element em novos fluxos de cartão no navegador.
  • Mantenha tokenização antiga apenas quando você estiver sustentando um fluxo legado e ainda não puder migrar.

​
Continue com