Links de pagamento
Valor fixo ou aberto, expiração, status, taxas e idempotência.
Valor fixo ou aberto
Com amount | Sem amount | |
|---|---|---|
| Valor | Travado no link | O pagador informa |
expiration | Respeitada | Ignorada |
| Bom para | Pedidos, faturas | Doações, gorjetas, cobranças avulsas |
{
"description": "Pedido #123",
"amount": "100.00",
"currency": "BRL",
"expiration": 1798761599
}amount é uma string decimal com ponto ("100.00"), para não perder precisão.
expiration é um Unix timestamp em segundos, UTC.
Uso único
Com single_use: true, o link aceita um pagamento concluído e passa para used. Sem ele, o mesmo
link pode ser pago várias vezes: útil para um link fixo de produto no Instagram, por exemplo.
Status
Prop
Tipo
Para saber se um pedido foi pago, prefira o webhook event.completed a consultar o link em loop.
Pré-preenchendo o checkout
Tudo o que você já sabe do cliente pode ir em metadata. O checkout abre com os campos preenchidos
e o pagador só confere:
{
"description": "Pedido #123",
"amount": "100.00",
"metadata": {
"name": "John Doe",
"document": "12345678909",
"email": "john.doe@example.com",
"phone": "+5511999999999",
"street": "Av. Paulista",
"number": "1000",
"complement": "Apto 101",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"zip_code": "01311000"
}
}Taxas e parcelas no cartão
| Campo | Valores | Padrão |
|---|---|---|
fee_mode | customer_pays: a taxa é somada ao valor do pagador.merchant_absorbs: a taxa é descontada do que você recebe. | customer_pays |
max_installments | 1 a 12. 0 usa o padrão da conta. | 12 |
Para não repetir em todo link, defina os padrões da conta em
PUT /configuration/settings. O que vier no link tem
prioridade.
Identidade visual
O checkout mostra o logo da sua conta, enviado em
PUT /configuration/images. Para um link específico, passe
logo_url.
Idempotência
Redes falham. Se a criação do link der timeout, você não sabe se ele foi criado. Envie
X-Idempotency-Key com um valor único por operação (o ID do pedido, por exemplo) e repita a
requisição com a mesma chave sem medo: a API devolve o link criado na primeira vez em vez de
criar outro.
curl -X POST "$XPAYZ_URL/links" \
-H "X-Idempotency-Key: pedido-123" \
...Se você não enviar a chave, a API gera uma e a devolve no header X-Idempotency-Key da resposta.
Excluindo um link
DELETE /links/{id} remove o link. Não é possível excluir um link com
pagamento pendente. Pagamentos de um link já excluído não disparam mais webhooks.