Links de pagamento
Um checkout pronto, com a sua marca, para enviar ao cliente.
Com um link de pagamento você não monta tela nenhuma: cria o link, envia a url ao cliente, e ele preenche os dados, paga com Pix e vê o comprovante num checkout com a sua marca.
Criar
curl -X POST https://api.wysepay.com.br/api/v1/payment-links \
-H "x-api-key: wyp_test_sua_chave" \
-H "Content-Type: application/json" \
-d '{
"amountCents": 15900,
"description": "Caneca WysePay",
"maxPayments": 1,
"askAddress": true,
"returnUrl": "https://loja.com.br/obrigado?pedido=1042",
"metadata": { "orderId": "1042" }
}'A resposta traz a url do checkout, como https://app.wysepay.com.br/checkout/pay_…. Envie por WhatsApp, e-mail ou redirecione o cliente para ela.
Opções
| Campo | O que faz |
|---|---|
maxPayments | Quantos pagamentos o link aceita. 1 = uso único; omitido ou null = ilimitado. Depois do limite, o link mostra "esgotado". |
expiresAt | Até quando o link aceita pagamentos. |
askAddress | O checkout pede o endereço, na mesma tela dos dados. O CEP preenche rua, bairro e cidade. |
returnUrl | Para onde o cliente volta depois de pagar (precisa ser https). |
metadata | Dados seus. Cada cobrança gerada pelo link aponta para ele em paymentLinkId. |
Voltar para a sua loja
Com returnUrl, o comprovante mostra o botão Voltar para a loja e, logo depois do pagamento, leva o cliente de volta sozinho em 8 segundos (ele pode ficar, se quiser). A URL recebe o id da cobrança paga:
https://loja.com.br/obrigado?pedido=1042&wysepay_transaction_id=txn_01k6g8m2v4x7z9b3c5d7f9h0j2Confirme o pedido pelo webhook, não pelo retorno
Qualquer pessoa pode abrir essa URL com um id inventado. Use o retorno só para mostrar a página de "obrigado". Libere o pedido quando chegar o webhook transaction.paid, ou consultando a transação pela API com a sua chave.
Como o pagamento aparece para você
Cada vez que alguém gera um Pix no link, nasce uma cobrança (transaction.created). Quando paga, chega transaction.paid, com paymentLinkId apontando para o link e os dados que o cliente preencheu em customer.
Listar, consultar e desativar
GET /api/v1/payment-links: os links, com o filtroactive.GET /api/v1/payment-links/{id}: um link e se ainda aceita pagamentos (active).POST /api/v1/payment-links/{id}/deactivate: o link para de aceitar pagamentos. Os Pix já gerados por ele continuam valendo até vencer.
A marca do checkout
Logo, cores, fonte e textos do checkout são configurados no painel, em Cobranças → Personalizar checkout, e valem para todos os links. Veja Personalizar o checkout.