Payment Element for Cards

Use Payment Element when you are building or rebuilding checkout.

Why Pagou recommends it

Hosted card fields reduce PCI exposure.
Tokenization happens in the browser without your backend touching raw card data.
Card authentication is handled inside elements.submit(...), with no extra fields to collect.
Your backend contract stays simple: create a transaction with the token returned by the browser.

Backend request

curl --request POST \
  --url https://api.pagou.ai/v2/transactions \
  --header "Authorization: Bearer YOUR_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
      }
    ]
  }'

Example response

{
  "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
  }
}

Common error

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"
    }
  ]
}

Fix: create the token in Payment Element first. Do not collect raw card data in your own form and send it directly to the API.

Installments with interest paid by the buyer

When your account is set up to charge installment interest to the buyer, the transaction is created the same way, with two differences:

amount is the amount before interest. Pagou adds the interest of the chosen installment and charges the total. The creation response and the webhook return amount as the total charged. Use base_amount, present on the creation response, on GET /v2/transactions/{id} and on the webhook, for the amount you sent. GET /v2/transactions/{id} returns amount as the amount before interest, the same as base_amount; the total charged is in the creation response and in the webhook.
The installment must be chosen in the card field (see the installments option of the SDK). Send the same amount, installments and interest_free_installments the card field showed.

Optional field:

Field	Description
`interest_free_installments`	Highest installment count whose interest you absorb, from 1 to 12. Defaults to `1`. Only send it from your server.

interest_rate sent in the request is ignored for these sales; the rate charged is always the one Pagou calculated.

Status	When
`422`	Installments with interest without a choice made in the card field, with a saved card, or when the total with interest exceeds the maximum transaction amount.
`409`	The request differs from what the buyer saw: `amount`, `installments`, `interest_free_installments`, or the installment total changed in the meantime. Show the options again and retry.

In both cases nothing is charged and no transaction is created. base_amount is also returned for regular sales: it is the amount you sent, in the transaction currency.

Decision rule

Use Payment Element for browser card flows.

Payments

Checkout Links

Pix

Vouchers

Cards

Why Pagou recommends it

Backend request

Example response

Common error

Installments with interest paid by the buyer

Decision rule

Continue with

​Why Pagou recommends it

​Backend request

​Example response

​Common error

​Installments with interest paid by the buyer

​Decision rule

​Continue with

Why Pagou recommends it

Backend request

Example response

Common error

Installments with interest paid by the buyer

Decision rule

Continue with