Skip to main content
Use customers when your checkout reuses buyer data across multiple payments.

​
Supported operations

  • POST /v2/customers
  • GET /v2/customers
  • GET /v2/customers/{id}

​
When to use this resource

  • You want a stable Pagou customer ID.
  • Your product stores reusable payer profiles.
  • You want to create the buyer once and reference it later.

​
Example request

curl --request POST \
  --url https://api.pagou.ai/v2/customers \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "document": {
      "type": "CPF",
      "number": "12345678901"
    },
    "externalRef": "customer_1001"
  }'

​
Example response

{
  "success": true,
  "requestId": "req_1101",
  "data": {
    "id": "cus_1001",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "externalRef": "customer_1001"
  }
}

​
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": "email",
      "message": "Invalid email format",
      "code": "invalid_string"
    }
  ]
}
Fix: send a valid email and keep the customer linked to your own internal ID. Customer creation does not replace transaction idempotency.

​
Next steps