Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt

Use this file to discover all available pages before exploring further.

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": "req_4001",
  "data": {
    "id": "tr_2001",
    "status": "three_ds_required",
    "method": "credit_card",
    "next_action": {
      "type": "three_ds_challenge",
      "challenge_session_id": "3ds_1001",
      "client_secret": "sec_1001",
      "expires_at": "2026-03-16T14:20:00.000Z"
    }
  }
}

​
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 here