PayZu GatewayCheckout

Comprar pelo link


Nesta páginaConsulte o linkCompre pelo linkPague a fatura do linkErros desta operação

Venda pelo link de pagamento numa página sua. Cada compra cria uma fatura sem cliente, e o comprador informa os dados e paga nela, como em Pagar a fatura pela página.

Crie o link no painel. O id dele é o fim da url do link, e as rotas do link não pedem chave, porque o id identifica a cobrança.

bash
curl https://api.sandbox.payzu.dev/v1/checkout/payment-links/pl_4NwK8xQcLb3MzYv7TdRh5E

Referência: Consultar um link de pagamento pela página

CampoO que diz
availabletrue quando o link está active, dentro de expires_at e com vaga para mais um pagamento. Com false, não ofereça a compra: paid, expired e canceled dizem o motivo; com active, o link passou de expires_at ou está sem vaga enquanto há pagamentos aguardando confirmação.
statusactive, paid quando o link atingiu o limite de pagamentos, expired ou canceled.
expires_atLink sem expires_at não vence.
payment_settingsOs meios que o link aceita e que a sua conta recebe, com o máximo de parcelas no cartão.
discountO desconto do link, que vale só no meio de discount.payment_method. Mostre discount.public_description ao comprador.

No link com limite de pagamentos, cada pagamento e cada tentativa ainda sem desfecho ocupam uma vaga.

bash
curl -X POST https://api.sandbox.payzu.dev/v1/checkout/payment-links/pl_4NwK8xQcLb3MzYv7TdRh5E/invoices

Referência: Comprar pelo link

A rota não tem corpo. A resposta é 201, com a fatura criada na mesma visão de Consulte a fatura, e sai o evento invoice.created para a sua conta. Leve o comprador à url da fatura ou cobre a fatura na sua página, pelo id.

CampoNa fatura criada
description, itemsO nome do link e um item com o valor cheio.
amountsO valor cheio, com discount 0 até a fatura ser paga com o meio do desconto.
billingdue_at no momento da compra e expires_at 15 dias depois.
payment_settingsOs meios e o máximo de parcelas do link.
checkout.redirect_urlO mesmo do link.
customernull, até a primeira tentativa de pagamento.
payment_linkO id, o name e o discount do link.
  • Sem idempotência: cada chamada cria outra fatura. Chame uma vez por compra.
  • Vaga: comprar não ocupa vaga. A vaga acompanha a tentativa de pagamento na fatura, e a fatura criada e nunca paga não segura vaga.
  • Limite da conta: no link sem desconto, o valor cheio é conferido na compra. No link com desconto, a conferência fica para a tentativa, sobre o valor cobrado.
  • Link fechado: o link paid, canceled, expired ou vencido, ou sem vaga, responde 422, sem criar a fatura.

A fatura do link é paga como em Pagar a fatura pela página, com customer no corpo da primeira tentativa. O link é conferido de novo a cada tentativa, com as regras de Na fatura de link.

O desconto do link entra quando a fatura é paga com o meio de payment_link.discount.payment_method. A tentativa sai com o valor descontado, e amounts passa a mostrar o desconto.

Trecho da fatura paga no Pix com o desconto do link
{
  "id": "in_8KdW2xQcLb6MzYv3TnRh9E",
  "status": "paid",
  "amounts": {
    "subtotal": 10200,
    "discount": 510,
    "total": 9690,
    "paid": 9690,
    "refunded": 0
  },
  "payments": [
    {
      "id": "pay_6NzT3wQcLb8MxYv4KdRh2E",
      "status": "paid",
      "method": "pix",
      "amount": 9690
    }
  ]
}

Paga no cartão, a mesma fatura fica no valor cheio, com amounts.discount 0.

As compras do link aparecem em GET /v1/invoices com o filtro payment_link_id, como em Consultar faturas. Pela API, payment_link traz só o id e o name do link.

Erros desta operação

CódigoHTTPMensagem
PZ030403Gateway suspenso para esta conta. Fale com o suporte PayZu.
-404Link de pagamento inválido ou expirado.
PZ101422Valor fora do limite desta conta.
-422Este link já foi pago.
-422Este link foi cancelado.
-422Este link expirou.
-422Este link atingiu o limite de pagamentos.
-422Há pagamentos aguardando confirmação neste link. Tente novamente em alguns minutos.
-429Muitas tentativas. Aguarde um minuto.

Os erros do pagamento estão em Pagar a fatura pela página. Os erros de validação estão no Catálogo de erros.