O que é payload

O termo vem do transporte: a carga pela qual se paga, separada do veículo. Numa requisição HTTP, o veículo são o método, o endereço e os headers. O payload é o corpo.

Payload em APIs e webhooks

Na API da xFlow, os payloads são JSON em UTF-8, com valores em centavos:

• Requisição. O corpo de POST /api/v1/charges traz amountCents, customer e, se você quiser, description e external_reference.
• Resposta. A cobrança criada volta no corpo do 201, com id, status e o objeto pix.
• Webhook. Cada evento chega como { event, data, createdAt }. A assinatura do header x-webhook-signature é calculada sobre os bytes exatos desse payload. Por isso ele é validado antes de virar objeto, como explica o verbete de HMAC.

Payload no Pix

O Banco Central usa a palavra em dois sentidos:

1. Payload do QR Code. O Manual BR Code chama de payload a sequência de bytes lidos do QR Code, organizada em objetos no formato ID, tamanho e valor. É o mesmo texto do Pix copia e cola. Na xFlow, ele vem pronto em pix.copyPaste. Veja o BR Code.
2. Payload JSON. No QR Code dinâmico, o Manual de Padrões para Iniciação do Pix (versão 2.10.0) chama de payload JSON o conteúdo recuperado pela URL lida no código, que representa a cobrança. Os campos, exceto a assinatura, formam um payload JSON assinado.

Na integração com a xFlow você não monta nenhum dos dois. A API entrega o texto e a imagem do QR Code, como mostra o guia de Pix copia e cola por API.

Exemplo

Payload de uma requisição de cobrança:

{
  "amountCents": 1990,
  "customer": {
    "name": "Cliente Exemplo",
    "email": "cliente@exemplo.com",
    "document": "00000000000"
  },
  "description": "Pedido #1234",
  "external_reference": "pedido-1234"
}

Se o payload estiver inválido, a resposta é 400 validation, com o campo details apontando o problema.

Termos relacionados

• BR Code: o padrão do payload do QR Code Pix.
• Webhook: o payload que a API envia para o seu sistema.
• API REST: o modelo em que o payload viaja no corpo.

Conteúdo informativo, atualizado em 25/10/2026. Não substitui orientação jurídica.