Overview

Payment Element is the recommended browser integration for new card checkouts.

When to use it

You are building a new card checkout.
You want hosted card fields instead of collecting raw card data.
You need 3D Secure in the same browser flow.
Your backend should remain the owner of transaction creation and fulfillment state.

Browser vs backend

Browser responsibilities:

load the Pagou script
mount the card field
submit through elements.submit(...)
continue browser-side challenge flow when required

Backend responsibilities:

authenticate with secret credentials
create POST /v2/transactions
persist external_ref, transaction ID, and requestId
fulfill only from webhook or reconciliation state

Backend request example

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

Backend response example

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

Return this payload to the browser unchanged. next_action is opaque — elements.submit(...) reads it and completes card authentication for you.

Common error

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

Start with Payment Element

Build a Card Checkout

Launch and Migrate

When to use it

Browser vs backend

Backend request example

Backend response example

Common error

Start here

​When to use it

​Browser vs backend

​Backend request example

​Backend response example

​Common error

​Start here

When to use it

Browser vs backend

Backend request example

Backend response example

Common error

Start here