Valores em dinheiro
Todo valor em dinheiro é um número inteiro em centavos de real, sem ponto nem vírgula.
Centavos
Um amount de 8990 é R$ 89,90, na requisição e na resposta. A mesma regra vale para:
- o preço de cada item, em
unit_price; - o desconto
fixed_amount; - os valores da fatura, em
amounts; - o valor de cada tentativa, em
payments[].amount, e de cada estorno, emrefunds[].amount.
Envie o valor como número JSON. Número com casas decimais ou valor em texto responde 400, com o campo e o motivo em fields.
No desconto percentual, o valor é a porcentagem, e não centavos.
No percentage, o value vai de 1 a 99, no plano, na assinatura avulsa e na fatura.
Valores mínimos
| Onde | Mínimo |
|---|---|
| Fatura, também depois do desconto | 500 (R$ 5,00) |
| Plano, também depois do desconto ativo | 500 (R$ 5,00) |
| Assinatura avulsa, também depois do desconto | 500 (R$ 5,00) |
| Novo valor de uma assinatura, também com o desconto em vigor | 500 (R$ 5,00) |
| Preço de um item | 1 |
Abaixo do mínimo, a resposta é 400, e o motivo vem num lugar diferente em cada operação:
| Operação | Onde vem o motivo |
|---|---|
| Criar uma fatura ou um plano | Em fields: O valor mínimo é R$ 5,00. no campo amount ou O valor com desconto precisa ser de no mínimo R$ 5,00. no campo discount.value. |
| Criar uma assinatura avulsa ou mudar o valor de uma assinatura | Em fields, no campo amount, quando o valor está abaixo do mínimo. Quando é o desconto que deixa o ciclo abaixo do mínimo, o erro é o do valor da assinatura, na tabela abaixo. |
| Alterar um plano | Em message, com os mesmos textos e sem fields. |
{
"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": "amount", "message": "O valor mínimo é R$ 5,00." }
]
}Na alteração de um plano, o mínimo é conferido quando muda o amount ou o desconto. O plano e a assinatura gravados com valor abaixo de 500 antes dessa regra seguem cobrando o próprio valor.
Cada cobrança também precisa caber no limite de valor da sua conta.
O limite vale para o total já com o desconto, na criação da fatura, em cada tentativa de pagamento e na adesão da assinatura. Na compra pelo link com desconto, ele só é conferido na tentativa, sobre o valor do meio escolhido. Fora dele, nada é cobrado.
Itens e desconto
| Campo | Regra |
|---|---|
items | De 1 a 100 itens, na fatura. A soma de quantity vezes unit_price precisa ser igual ao amount. Para o item padrão, deixe o campo de fora. |
quantity | De 1 a 15 em cada item. |
Desconto fixed_amount | Menor que o valor do plano ou da fatura. |
Sem items, a fatura traz um item só, com a description e o amount da cobrança.
Na fatura, amounts.subtotal é o valor cheio, amounts.discount o desconto e amounts.total o valor a pagar, igual a subtotal menos discount. amounts.paid soma tudo o que entrou e amounts.refunded tudo o que foi devolvido.
{
"amounts": {
"subtotal": 15990,
"discount": 1599,
"total": 14391,
"paid": 14391,
"refunded": 0
}
}Erros de valor
| Código | HTTP | Mensagem |
|---|---|---|
| - | 400 | O valor mínimo é R$ 5,00. |
| - | 400 | O valor com desconto precisa ser de no mínimo R$ 5,00. |
| - | 400 | O desconto fixo deve ser menor que o valor do plano. |
PZ503 | 400 | O valor da assinatura, com o desconto em vigor, precisa ser de no mínimo R$ 5,00. |
PZ100 | 422 | A soma dos itens é diferente do valor da fatura. |
PZ101 | 422 | Valor fora do limite desta conta. |
Todos os códigos do PayZu Gateway estão no Catálogo de erros.