PayZu Gateway
Metadados
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:
| Recurso | Na criação | Na alteração |
|---|---|---|
| Plano | Sim | Sim |
| Assinatura | Sim | Sim, menos na incomplete |
| Cliente | Sim | Sim |
| Fatura | Sim | Nã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
metadatado plano. O mapa dela é só o que você enviar na assinatura. - Fatura da assinatura ou da compra pelo link: vem com
metadatanulo, porque o mapa só entra na fatura que você cria. - Cliente no corpo: o
customerenviado na fatura ou na assinatura não aceitametadata. 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:
| Eventos | metadata |
|---|---|
invoice.* | O da fatura, em data.invoice.metadata. |
subscription.* | O da assinatura, em data.subscription.metadata. |
Limites
| Item | Limite |
|---|---|
| Chaves no mapa | Até 20. |
| Tamanho da chave | De 1 a 40 caracteres. |
| Valor | Texto de até 500 caracteres. |
| Número de cartão | Nã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ê envia | O que acontece |
|---|---|
metadata com chaves | Troca 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 campo | O 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.