P
pactualpay
API Reference v1
Criar Conta
Padrão Institucional RESTful

Referência da API PactualPay

A API PactualPay é construída sobre convenções REST padrão. Possui URLs com recursos previsíveis, aceita corpos de requisição codificados em JSON, retorna respostas JSON nos padrões RFC 9457 e utiliza códigos de status HTTP convencionais para indicar sucesso ou erro.

Autenticação Bearer

Header Authorization: Bearer pp_live_... em todas as requisições autenticadas.

Idempotência Nativa

Header x-idempotency-key em mutações para proteção absoluta contra duplo débito.

Webhooks Assinados

Assinatura HMAC SHA-256 no cabeçalho X-PactualPay-Signature para cada evento.

GET/health

Status & Liveness Check

Endpoint público de diagnóstico para verificar se a API Gateway da PactualPay está operacional e pronta para receber requisições.

Cabeçalhos HTTP (Headers)

Content-Type

application/json

Padrão
curl
curl -X GET https://api.pactualpay.com.br/health
Resposta da API200 OK
{
  "status": "ok",
  "service": "api",
  "uptime": 341829.41
}
POST/v1/public/checkout-sessions

Iniciar Sessão de Checkout

Inicia uma sessão temporária e segura de checkout para um visitante anônimo. Protegida contra scraping e abusos com mascaramento LGPD e hash criptográfico de IP.

Cabeçalhos HTTP (Headers)

Content-Type

application/json

Padrão

Corpo da Requisição (JSON Body)

publicTokenobrigatório
string

Token público do link de pagamento.

Exemplo: pl_xsMwcMDgJGArjkvFyRG5O6Px

utmSourceopcional
string

Origem de tráfego para analítica de vendas.

Exemplo: instagram

consentGivenopcional
boolean

Confirmação de aceite dos termos pelo comprador.

Exemplo: true

curl
curl -X POST https://api.pactualpay.com.br/v1/public/checkout-sessions \
  -H "Content-Type: application/json" \
  -d '{
    "publicToken": "pl_xsMwcMDgJGArjkvFyRG5O6Px",
    "utmSource": "instagram",
    "consentGiven": true
  }'
Resposta da API201 Created
{
  "sessionToken": "cs_8fa7d9b2c4e109f5a3b2c1d8",
  "status": "OPEN",
  "expiresAt": "2026-09-15T02:30:00.000Z"
}
POST/v1/public/checkout-sessions/:sessionToken/generate-pix

Submeter Dados e Gerar Pix Dinâmico

Submete os dados cadastrais do comprador (nome, CPF/CNPJ e e-mail) e gera imediatamente o QR Code Pix SVG e o payload EMVCo padrão BACEN Copia e Cola.

Cabeçalhos HTTP (Headers)

x-idempotency-key

Identificador único UUID v4

Obrigatório
Content-Type

application/json

Padrão

Parâmetros de Rota (Path)

sessionTokenstring

Token da sessão de checkout criada no passo anterior.

Corpo da Requisição (JSON Body)

payerNameobrigatório
string

Nome completo ou Razão Social do pagador.

Exemplo: Carlos Silva Oliveira

payerDocumentobrigatório
string

CPF (11 dígitos) ou CNPJ (14 dígitos) válido do comprador.

Exemplo: 123.456.789-00

payerEmailobrigatório
string (email)

E-mail do comprador para envio do comprovante.

Exemplo: carlos.silva@exemplo.com.br

payerPhoneopcional
string

Telefone celular do pagador com DDD.

Exemplo: (11) 98765-4321

idempotencyKeyobrigatório
string

Chave única para garantir que cliques duplos gerem a mesma cobrança Pix.

Exemplo: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

curl
curl -X POST https://api.pactualpay.com.br/v1/public/checkout-sessions/cs_8fa7d9b2c4e109f5a3b2c1d8/generate-pix \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: $(uuidgen)" \
  -d '{
    "payerName": "Carlos Silva Oliveira",
    "payerDocument": "123.456.789-00",
    "payerEmail": "carlos.silva@exemplo.com.br",
    "payerPhone": "(11) 98765-4321"
  }'
Resposta da API201 Created
{
  "attemptId": "pa_01H9A5Y2B1D7C3E8F4G",
  "useId": "plu_01H9A5Y2A0B1C2D3E4F",
  "txid": "PACTUALPAY00192837461928374",
  "amountBrl": "150.00",
  "copiaECola": "00020101021226840014br.gov.bcb.pix2562pix.pactualpay.com.br/qr/v1/9a8b7c6d5e5204000053039865406150.005802BR5915PactualPay S.A.6009Sao Paulo62070503***6304ABCD",
  "qrCodeSvgBase64": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmci...",
  "expiresAt": "2026-09-15T02:30:00.000Z",
  "remainingSeconds": 3600
}
GET/v1/public/checkout-sessions/:sessionToken/status

Consultar Status do Pagamento (Polling / Real-time)

Permite ao frontend do checkout consultar o estado do pagamento Pix e o progresso da liquidação on-chain em USDT a cada 2 a 3 segundos.

Cabeçalhos HTTP (Headers)

Content-Type

application/json

Padrão

Parâmetros de Rota (Path)

sessionTokenstring

Token da sessão de checkout.

curl
curl -X GET https://api.pactualpay.com.br/v1/public/checkout-sessions/cs_8fa7d9b2c4e109f5a3b2c1d8/status
Resposta da API200 OK
{
  "sessionStatus": "COMPLETED",
  "useStatus": "PIX_CONFIRMED",
  "status": "PAID",
  "settlementStatus": "USDT_SETTLED",
  "netAmountUsdt": "28.50",
  "confirmedAt": "2026-09-15T01:31:14.000Z"
}
POST/v1/public/payment-attempts/:id/simulate-payment

Simular Confirmação Pix (Sandbox / Testes)

Endpoint de ambiente de testes para simular a compensação instantânea do Pix pelo Banco Central e disparar a liquidação em USDT sem necessidade de transação bancária real.

Cabeçalhos HTTP (Headers)

Content-Type

application/json

Padrão

Parâmetros de Rota (Path)

idstring

Identificador da tentativa de pagamento (attemptId).

curl
curl -X POST https://api.pactualpay.com.br/v1/public/payment-attempts/pa_01H9A5Y2B1D7C3E8F4G/simulate-payment
Resposta da API200 OK
{
  "success": true,
  "message": "Pagamento Pix simulado e confirmado com sucesso!",
  "paymentStatus": "CONFIRMED",
  "settlementStatus": "SETTLED",
  "netAmountUsdt": "28.50"
}
POSThttps://seunegocio.com.br/api/webhooks/pactual

Validação de Assinatura Criptográfica HMAC

A PactualPay envia requisições HTTP POST para a URL cadastrada no seu painel ou link. Cada requisição contém o cabeçalho `X-PactualPay-Signature` gerado com HMAC SHA-256 do corpo bruto (raw body) utilizando o seu Webhook Secret.

Cabeçalhos HTTP (Headers)

Content-Type

application/json

Padrão
curl
# Exemplo de payload recebido pelo seu servidor
{
  "event": "pix.payment.confirmed",
  "id": "evt_01H9A7K92M4P6Q8R0S",
  "created_at": "2026-09-15T01:31:14Z",
  "data": {
    "paymentLinkId": "pl_01H9A3X7B4C8D2E1F0G",
    "amountBrl": "150.00",
    "payer": {
      "name": "Carlos Silva Oliveira",
      "document": "123.456.789-00"
    },
    "settlement": {
      "asset": "USDT",
      "network": "TRC20",
      "estimatedUsdt": "28.50"
    }
  }
}
Resposta da API200 OK
{
  "received": true
}
Especificação de Erros

Padrão RFC 9457 Problem Details

Todas as falhas e erros de validação da API PactualPay retornam o padrão de indústria RFC 9457 com cabeçalho application/problem+json, permitindo que seu sistema identifique a causa exata de forma determinística.

{
  "type": "https://pactualpay.com.br/errors/validation_error",
  "title": "Validação Falhou",
  "status": 400,
  "detail": "O campo amountBrl deve ser numérico em BRL com 2 decimais (ex: \"150.00\").",
  "code": "VALIDATION_ERROR",
  "requestId": "req_01H9A9X4N7M2K5P8Q1R",
  "invalidParams": [
    {
      "name": "amountBrl",
      "reason": "Formato decimal inválido. Utilize string com duas casas."
    }
  ]
}