Payment Element para pagamentos com cartão

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.
A autenticação do cartão é tratada dentro de elements.submit(...), sem campos extras a coletar.
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": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "id": "018f1f2e-7b43-7c9a-8d3e-1a2b3c4d5e70",
    "status": "three_ds_required",
    "method": "credit_card",
    "amount": 2490,
    "base_price": 2490,
    "currency": "BRL",
    "next_action": {
      "type": "three_ds_challenge"
    },
    "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.

Parcelado com juros pagos pelo comprador

Quando a sua conta está configurada para cobrar os juros do parcelamento do comprador, a transação é criada do mesmo jeito, com duas diferenças:

amount é o valor antes dos juros. A Pagou soma os juros da parcela escolhida e cobra o total. A resposta da criação e o webhook trazem amount como o total cobrado. Use base_amount, presente na resposta da criação, no GET /v2/transactions/{id} e no webhook, para o valor que você enviou. O GET /v2/transactions/{id} traz amount como o valor antes dos juros, igual ao base_amount; o total cobrado está na resposta da criação e no webhook.
A parcela precisa ser escolhida no campo de cartão (veja a opção installments do SDK). Envie o mesmo amount, installments e interest_free_installments que o campo de cartão mostrou.

Campo opcional:

Campo	Descrição
`interest_free_installments`	Maior número de parcelas cujos juros você absorve, de 1 a 12. O padrão é `1`. Envie só pelo seu servidor.

interest_rate enviado na requisição é ignorado nessas vendas; a taxa cobrada é sempre a calculada pela Pagou.

Status	Quando
`422`	Parcelado com juros sem a escolha feita no campo de cartão, com cartão salvo, ou quando o total com juros passa do valor máximo da transação.
`409`	A requisição difere do que o comprador viu: `amount`, `installments`, `interest_free_installments`, ou o total da parcela mudou nesse meio-tempo. Mostre as opções de novo e tente outra vez.

Nos dois casos nada é cobrado e nenhuma transação é criada. base_amount também vem nas vendas comuns: é o valor que você enviou, na moeda da transação.

Regra de decisão

Use Payment Element nos fluxos de cartão no navegador.

Pagamentos

Checkout Links

Pix

Vouchers

Cartão

Payment Element para pagamentos com cartão

Por que a Pagou recomenda

Requisição do back-end

Exemplo de resposta

Erro comum

Parcelado com juros pagos pelo comprador

Regra de decisão

Continue com

​Por que a Pagou recomenda

​Requisição do back-end

​Exemplo de resposta

​Erro comum

​Parcelado com juros pagos pelo comprador

​Regra de decisão

​Continue com

Por que a Pagou recomenda

Requisição do back-end

Exemplo de resposta

Erro comum

Parcelado com juros pagos pelo comprador

Regra de decisão

Continue com