Início rápido

Em dez minutos, no sandbox: obter o token, criar um PIX, consultar e receber o webhook de pago.

Os exemplos usam o sandbox (https://api.sandbox.pagaki.com.br). PHP com Guzzle 7; JavaScript com Node.js 18 ou mais novo (fetch nativo).

1. Antes de começar

No painel do sandbox, em Acesso à API:

crie um client e guarde o client_id e o client_secret (o secret aparece uma vez só);
cadastre o IP de saída do seu servidor na lista de IPs permitidos. Sem IP cadastrado, toda chamada recebe 403 ip_not_allowed.

No sandbox, a conta é criada pela equipe do Pagaki (veja ambientes).

2. Obter o token

O token vale 1 h. Peça um novo antes de expirar e reaproveite-o entre as chamadas.

curl -s https://api.sandbox.pagaki.com.br/oauth/token \
  -d grant_type=client_credentials \
  -d client_id="$PAGAKI_CLIENT_ID" \
  -d client_secret="$PAGAKI_CLIENT_SECRET"

use GuzzleHttp\Client;

$http = new Client(['base_uri' => 'https://api.sandbox.pagaki.com.br']);

$token = json_decode((string) $http->post('/oauth/token', ['form_params' => [
    'grant_type' => 'client_credentials',
    'client_id' => getenv('PAGAKI_CLIENT_ID'),
    'client_secret' => getenv('PAGAKI_CLIENT_SECRET'),
]])->getBody(), true)['access_token'];

const BASE = 'https://api.sandbox.pagaki.com.br';

const { access_token: token } = await fetch(`${BASE}/oauth/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: process.env.PAGAKI_CLIENT_ID,
    client_secret: process.env.PAGAKI_CLIENT_SECRET,
  }),
}).then((r) => r.json());

Resposta:

{ "token_type": "Bearer", "expires_in": 3600, "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9…" }

Confira credencial e IP com GET /v1/me:

curl -s https://api.sandbox.pagaki.com.br/v1/me -H "Authorization: Bearer $TOKEN"

{ "tenant": { "id": "01jaq2m5p8r1t4v7x0z3b6d9f2", "name": "Agill Sistemas", "plan": "standard" } }

3. Criar um PIX

Todo POST exige Idempotency-Key. Gere uma por operação e guarde-a antes de enviar: se a rede cair, você repete com a mesma chave sem cobrar duas vezes (idempotência). Valores em centavos: 12550 é R$ 125,50.

curl -s https://api.sandbox.pagaki.com.br/v1/payments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a0e-8b7d-4e3f-9a21-5c4b3d2e1f00" \
  -d '{
    "method": "pix",
    "amount": 12550,
    "description": "IPTU 2026, parcela 1",
    "external_id": "guia-778899",
    "payer": { "name": "Fulano de Tal", "document": "12345678909", "email": "fulano@example.com" }
  }'

use Ramsey\Uuid\Uuid; // ou qualquer gerador de UUID

$idempotencyKey = Uuid::uuid4()->toString(); // guarde junto do pedido antes de enviar

$response = $http->post('/v1/payments', [
    'headers' => ['Authorization' => "Bearer {$token}", 'Idempotency-Key' => $idempotencyKey],
    'json' => [
        'method' => 'pix',
        'amount' => 12550,
        'description' => 'IPTU 2026, parcela 1',
        'external_id' => 'guia-778899',
        'payer' => ['name' => 'Fulano de Tal', 'document' => '12345678909', 'email' => 'fulano@example.com'],
    ],
    'http_errors' => false,
]);

$payment = json_decode((string) $response->getBody(), true);
// 201: $payment['pix']['qr_code'] pronto. 202: status "processing", o QR chega pelo webhook payment.created.

import { randomUUID } from 'node:crypto';

const idempotencyKey = randomUUID(); // guarde junto do pedido antes de enviar

const response = await fetch(`${BASE}/v1/payments`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({
    method: 'pix',
    amount: 12550,
    description: 'IPTU 2026, parcela 1',
    external_id: 'guia-778899',
    payer: { name: 'Fulano de Tal', document: '12345678909', email: 'fulano@example.com' },
  }),
});
const payment = await response.json();

Resposta 201 Created (resumida; o objeto completo está na referência):

{
  "id": "pay_01jbz3k8q4m7v2x9c5n6p0r1st",
  "object": "payment",
  "method": "pix",
  "status": "pending",
  "amount": 12550,
  "expires_at": "2026-11-03T18:00:00+00:00",
  "pix": { "qr_code": "00020101021226800014br.gov.bcb.pix2558pix.example.com/qr/v2/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865406125.505802BR5913AGILL SISTEMAS6008MACEIO62070503***6304B1C2", "qr_code_image_url": null }
}

Mostre pix.qr_code ao pagador como "copia e cola" e gere a imagem do QR a partir dele (qr_code_image_url hoje é sempre null). Sem expires_at, o PIX vale 30 min.

Resposta	O que fazer
`201`, `status: pending`	Mostre o QR
`202`, `status: processing`	O gateway demorou. Espere o webhook `payment.created` (com o QR) ou `payment.failed`
`422`/`502` com `payment` em `failed`	Veja o `code` no catálogo de erros

4. Consultar

curl -s https://api.sandbox.pagaki.com.br/v1/payments/pay_01jbz3k8q4m7v2x9c5n6p0r1st -H "Authorization: Bearer $TOKEN"

$payment = json_decode((string) $http->get('/v1/payments/pay_01jbz3k8q4m7v2x9c5n6p0r1st', [
    'headers' => ['Authorization' => "Bearer {$token}"],
])->getBody(), true);

const payment = await fetch(`${BASE}/v1/payments/pay_01jbz3k8q4m7v2x9c5n6p0r1st`, {
  headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());

Use a consulta para conferir um webhook ou recuperar o estado, não para ficar perguntando de tempos em tempos: o webhook avisa quando muda, e o limite de requisições é por minuto.

5. Receber o webhook

Cadastre no painel, em Webhooks, uma URL HTTPS sua com o evento payment.paid (ou *) e guarde o segredo whsec_…. Quando o PIX for pago, o Pagaki envia:

{
  "id": "evt_01jbz3q2w5e8r1t4y7k0m3n6p9",
  "type": "payment.paid",
  "created_at": "2026-11-03T17:35:12+00:00",
  "livemode": false,
  "data": { "object": { "id": "pay_01jbz3k8q4m7v2x9c5n6p0r1st", "object": "payment", "status": "paid", "amount": 12550, "amount_paid": 12550, "paid_at": "2026-11-03T17:35:10+00:00" } }
}

(o data.object real é o objeto payment completo). Seu endpoint precisa:

verificar a assinatura do header Pagaki-Signature com o corpo bruto;
ignorar o evento se o id já foi processado;
responder 2xx em até 10 s e processar depois.

O código das três etapas, em curl, PHP e JavaScript, está no guia de webhooks.

Próximos passos

Webhooks: assinatura, reentrega e deduplicação.
Idempotência: quando repetir com a mesma chave e quando usar outra.
Valores e formatos: centavos, datas, IDs e mascaramento.
Ambientes: o que o sandbox simula e o que não simula.
PIX com pagamento de conta.