PayZu Gateway

Metadados


Nesta páginaOnde existeLimitesNa alteração

Guarde no próprio recurso um dado do seu sistema, como o código interno do cliente ou o id do pedido, e receba esse dado de volta em toda resposta.

Onde existe

O campo metadata é um mapa de texto para texto e existe em quatro recursos:

RecursoNa criaçãoNa alteração
PlanoSimSim
AssinaturaSimSim, menos na incomplete
ClienteSimSim
FaturaSimNão
json
{
  "metadata": { "internal_id": "1234" }
}

O mapa volta igual em toda resposta da API sobre o recurso, inclusive nos itens das listas, e vem null quando nunca foi enviado. As rotas do checkout não trazem metadata.

  • Assinatura: não herda o metadata do plano. O mapa dela é só o que você enviar na assinatura.
  • Fatura da assinatura ou da compra pelo link: vem com metadata nulo, porque o mapa só entra na fatura que você cria.
  • Cliente no corpo: o customer enviado na fatura ou na assinatura não aceita metadata. O mapa do cliente vai em Cadastrar um cliente ou em Alterar um cliente.

Nos webhooks, os eventos de fatura e de assinatura trazem o recurso inteiro, com o metadata dele:

Eventosmetadata
invoice.*O da fatura, em data.invoice.metadata.
subscription.*O da assinatura, em data.subscription.metadata.

Limites

ItemLimite
Chaves no mapaAté 20.
Tamanho da chaveDe 1 a 40 caracteres.
ValorTexto de até 500 caracteres.
Número de cartãoNão pode aparecer na chave nem no valor.

Fora disso, a resposta é 400, com o motivo em fields:

json
{
  "status_code": 400,
  "error": "bad_request",
  "message": "A solicitação possui erros de validação.",
  "code": "PZ001",
  "request_id": "a1b2c3d4-0000-4000-8000-000000000000",
  "fields": [
    { "name": "metadata", "message": "Envie no máximo 20 chaves em metadata." }
  ]
}

Na alteração

Você enviaO que acontece
metadata com chavesTroca o mapa inteiro. Mande todas as chaves que devem ficar, e não só a que mudou.
metadata vazio, {}Apaga todas as chaves.
Nada, sem o campoO mapa não muda.

O metadata não serve de filtro nas listas.

Para achar a fatura de um pedido, envie o identificador dele em external_reference na criação e use o filtro external_reference da lista de faturas.