Comprar pelo link
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.
Consulte o link
curl https://api.sandbox.payzu.dev/v1/checkout/payment-links/pl_4NwK8xQcLb3MzYv7TdRh5E{
"id": "pl_4NwK8xQcLb3MzYv7TdRh5E",
"status": "active",
"name": "Consultoria",
"description": "",
"amount": 10200,
"expires_at": null,
"available": true,
"payment_settings": {
"accepted_methods": ["credit_card", "pix"],
"credit_card": { "max_installments": 3 }
},
"checkout": {
"logo_url": null,
"redirect_url": null
},
"merchant": {
"display_name": "Loja da Maria"
},
"discount": {
"payment_method": "pix",
"type": "percentage",
"value": 5,
"public_description": "5% de desconto no Pix"
}
}Referência: Consultar um link de pagamento pela página
| Campo | O que diz |
|---|---|
available | true 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. |
status | active, paid quando o link atingiu o limite de pagamentos, expired ou canceled. |
expires_at | Link sem expires_at não vence. |
payment_settings | Os meios que o link aceita e que a sua conta recebe, com o máximo de parcelas no cartão. |
discount | O 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.
Compre pelo link
curl -X POST https://api.sandbox.payzu.dev/v1/checkout/payment-links/pl_4NwK8xQcLb3MzYv7TdRh5E/invoices{
"id": "in_8KdW2xQcLb6MzYv3TnRh9E",
"status": "pending",
"url": "https://invoice.payzu.com.br/pay/in_8KdW2xQcLb6MzYv3TnRh9E",
"description": "Consultoria",
"created_at": "2026-11-12T14:08:33.415Z",
"updated_at": "2026-11-12T14:08:33.415Z",
"amounts": {
"subtotal": 10200,
"discount": 0,
"total": 10200,
"paid": 0,
"refunded": 0
},
"billing": {
"cycle_number": null,
"due_at": "2026-11-12T14:08:33.415Z",
"expires_at": "2026-11-27T14:08:33.415Z",
"paid_at": null,
"canceled_at": null,
"refunded_at": null,
"chargedback_at": null
},
"items": [
{ "name": "Consultoria", "sku": null, "quantity": 1, "unit_price": 10200 }
],
"payment_settings": {
"accepted_methods": ["credit_card", "pix"],
"credit_card": { "max_installments": 3 }
},
"checkout": {
"redirect_url": null,
"cancel_url": null
},
"merchant": {
"display_name": "Loja da Maria"
},
"customer": null,
"subscription": null,
"payment_link": {
"id": "pl_4NwK8xQcLb3MzYv7TdRh5E",
"name": "Consultoria",
"discount": {
"payment_method": "pix",
"type": "percentage",
"value": 5,
"public_description": "5% de desconto no Pix"
}
},
"payments": [],
"refunds": []
}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.
| Campo | Na fatura criada |
|---|---|
description, items | O nome do link e um item com o valor cheio. |
amounts | O valor cheio, com discount 0 até a fatura ser paga com o meio do desconto. |
billing | due_at no momento da compra e expires_at 15 dias depois. |
payment_settings | Os meios e o máximo de parcelas do link. |
checkout.redirect_url | O mesmo do link. |
customer | null, até a primeira tentativa de pagamento. |
payment_link | O 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,expiredou vencido, ou sem vaga, responde422, sem criar a fatura.
Pague a fatura do link
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.
{
"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ódigo | HTTP | Mensagem |
|---|---|---|
PZ030 | 403 | Gateway suspenso para esta conta. Fale com o suporte PayZu. |
| - | 404 | Link de pagamento inválido ou expirado. |
PZ101 | 422 | Valor fora do limite desta conta. |
| - | 422 | Este link já foi pago. |
| - | 422 | Este link foi cancelado. |
| - | 422 | Este link expirou. |
| - | 422 | Este link atingiu o limite de pagamentos. |
| - | 422 | Há pagamentos aguardando confirmação neste link. Tente novamente em alguns minutos. |
| - | 429 | Muitas 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.