Valores e formatos

Valores em centavos

Todo valor na API é um inteiro em centavos: no pedido, na resposta e nos webhooks.

• Nunca envie decimal (125.50) nem texto ("12550"): o amount precisa ser inteiro, senão 422 validation_failed.
• Não use float para dinheiro no seu sistema: 0.1 + 0.2 não dá 0.3. Guarde centavos em inteiro e converta para reais só na tela.
• A moeda é sempre BRL.

Conversão só na hora de mostrar:

$cents = 12550;
echo 'R$ '.number_format(intdiv($cents, 100), 0, ',', '.').','.str_pad((string) ($cents % 100), 2, '0', STR_PAD_LEFT); // R$ 125,50

const cents = 12550;
new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' }).format(cents / 100); // "R$ 125,50"

cents=12550; printf 'R$ %d,%02d\n' $((cents / 100)) $((cents % 100))   # R$ 125,50

Para somar ou comparar (por exemplo, a composição de um pagamento de conta), some os inteiros, nunca os valores em reais.

Datas

• Formato ISO 8601 com fuso: 2026-11-03T14:30:00-03:00.
• A API devolve em UTC: 2026-11-03T17:30:00+00:00 é o mesmo instante. Converta para o fuso de quem lê só na tela.
• Na entrada, aceita qualquer fuso. Mande sempre o fuso: sem ele, o horário é lido como UTC.
• expires_at precisa estar no futuro; sem ele, o PIX vale 30 min.
• Datas sem horário (o due_date do pagamento de conta, planejado) usam AAAA-MM-DD.

IDs com prefixo

Todo ID tem o prefixo do tipo e um ULID em minúsculas (26 caracteres):

• Trate o ID como texto opaco: não extraia data do ULID nem monte IDs à mão.
• ID com prefixo errado ou de outro tenant responde 404 not_found.
• Exceções de hoje: o tenant.id de GET /v1/me e o request_id saem sem prefixo. O request_id é um ULID em maiúsculas, o mesmo do header X-Request-Id.
• gateway.provider_payment_id é o ID da cobrança no gateway (no Asaas, pay_… também, mas é outro sistema). Não o confunda com o id do Pagaki.

Dados pessoais mascarados

Os dados do pagador são guardados criptografados e sempre saem mascarados, nas respostas e nos webhooks. Para casar um pagamento com o seu cadastro, use external_id ou metadata, nunca o documento.

Valor fora do formato esperado vira ***: a API nunca devolve o dado original.

Texto livre

Não ponha dado pessoal em description, external_id nem metadata: esses campos voltam sem máscara.

Campos novos

A API pode ganhar campos, eventos e códigos de erro sem mudar de versão. Ignore o que você não conhece em vez de recusar a resposta.