Começo rápido
Crie um link, pague no sandbox e receba o webhook.
Pegue suas credenciais
No painel, gere uma credencial de API. Você recebe um Secret ID e uma Secret Key. Guarde a Secret Key no seu servidor: ela não deve ir para o front-end nem para o app.
export XPAYZ_URL="https://sandbox.xpayz.us/payment-link"
export XPAYZ_SECRET_ID="seu-secret-id"
export XPAYZ_SECRET_KEY="sua-secret-key"Cadastre um webhook
Diga onde quer receber os eventos. Para testar, um endpoint do webhook.site serve.
curl -X POST "$XPAYZ_URL/webhook" \
-H "Content-Type: application/json" \
-H "X-Secret-ID: $XPAYZ_SECRET_ID" \
-H "X-Secret-Key: $XPAYZ_SECRET_KEY" \
-d '{
"endpoint": "https://webhook.site/seu-id",
"topics": ["event.created", "event.completed", "event.rejected", "event.expired"]
}'{ "id": "6f1c2b9e-0d4a-4c1e-9b7a-2f3e4d5c6b7a" }Depois, chame GET /webhook para pegar o secret que assina os eventos.
Você vai usá-lo para validar a assinatura.
Crie o link
curl -X POST "$XPAYZ_URL/links" \
-H "Content-Type: application/json" \
-H "X-Secret-ID: $XPAYZ_SECRET_ID" \
-H "X-Secret-Key: $XPAYZ_SECRET_KEY" \
-H "X-Idempotency-Key: pedido-123" \
-d '{
"description": "Pedido #123",
"amount": "100.00",
"currency": "BRL",
"single_use": true,
"external_ref": "pedido-123",
"back_url": "https://sualoja.com/obrigado"
}'{
"id": "b3e1c2d4-5f67-4890-9abc-1234567890ab",
"url": "https://checkout.xpayz.us/p/b3e1c2d4-5f67-4890-9abc-1234567890ab"
}Pague no sandbox
Abra a url e pague com um dos valores de teste. Eles decidem o resultado:
| Método | Use | Resultado |
|---|---|---|
| Pix | CPF 000.000.001-91 | event.completed |
| Cartão | 4200 0000 0000 0000 | event.completed |
Veja todos os cenários (cancelado, expirado, recusado) em Simular pagamentos.
Receba o evento
Alguns segundos depois, seu endpoint recebe:
{
"topic": "event.completed",
"data": {
"external_id": "0d4ba8f5-bbc6-4cbb-ae65-13de2f903271",
"amount": "100",
"currency": "BRL",
"status": "done",
"method": "pix",
"payer": { "name": "John Doe", "email": "john@example.com", "document": "***.000.001-**" },
"link": { "external_id": "b3e1c2d4-5f67-4890-9abc-1234567890ab", "external_ref": "pedido-123" }
}
}Use data.link.external_ref para achar o pedido no seu sistema e liberá-lo.
Próximos passos
Entenda as opções do link em Links de pagamento e prepare seu endpoint para produção em Webhooks.