Checkout transparente
Monte a sua própria tela de pagamento com Pix, sem redirecionar o cliente.
No checkout transparente a tela de pagamento é sua: você gera o Pix pela API, mostra o QR Code no seu site e acompanha o status até o pagamento cair. O cliente não sai da sua página e não precisa ter conta XPayZ.
Por enquanto, só Pix e links em BRL
O pagador é identificado pelo próprio Pix, então não há formulário de nome nem de documento. Veja Pagador sem conta.
Como funciona
- 1Crie o linkNo seu servidor, com as suas credenciais.
- 2Gere o PixPOST /pay sem payer_id devolve o QR Code e o copia e cola.
- 3Mostre e acompanheExiba o QR Code e consulte GET /pay/{id} até sair de pending.
- 4Confirme pelo webhookLibere o pedido no event.completed.
Crie o link
No servidor, como em qualquer integração. Um link de uso único por pedido é o mais simples:
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" \
-d '{ "description": "Pedido #123", "amount": "100.00", "currency": "BRL", "single_use": true, "external_ref": "pedido-123" }'Guarde o id devolvido.
Gere o Pix
POST /pay é público: pode ser chamado do navegador, sem as suas
chaves. Não envie payer_id.
curl -X POST "$XPAYZ_URL/pay" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: pedido-123-tentativa-1" \
-d '{ "link_id": "b3e1c2d4-5f67-4890-9abc-1234567890ab", "payment_method": "pix", "payer_email": "maria@example.com" }'{
"correlation_id": "0d4ba8f5-bbc6-4cbb-ae65-13de2f903271",
"payment_qrcode": "iVBORw0KGgoAAAANSUhEUgAA...",
"payment_content": "00020101021226580014br.gov.bcb.pix...",
"expected_amount": "100",
"symbol": "BRXP"
}| Campo | |
|---|---|
payer_id | Não envie. Quem enviar o Pix vira o pagador. |
payment_method | Sempre pix. |
payer_email | Opcional. Recebe o comprovante. |
amount | Só em link sem valor fixo. |
X-Idempotency-Key | Recomendado. Repetir a chamada com a mesma chave devolve a mesma cobrança em vez de criar outra. |
Mostre o QR Code
payment_qrcode é um PNG em base64; payment_content é o copia e cola.
<img alt="QR Code Pix" src="data:image/png;base64,{payment_qrcode}" width="240" height="240" />
<button onclick="navigator.clipboard.writeText(paymentContent)">Copiar código Pix</button>O QR Code vale 10 minutos.
Acompanhe o status
GET /pay/{id} também é público. Consulte a cada poucos segundos
enquanto o status for pending:
async function waitForPix(id) {
for (;;) {
const { status } = await fetch(`${XPAYZ_URL}/pay/${id}`).then((r) => r.json());
if (status !== 'pending') return status;
await new Promise((r) => setTimeout(r, 3000));
}
}status | O que mostrar |
|---|---|
pending | Aguardando o Pix. |
processing | Pix recebido: mostre "pagamento recebido". |
done | Pagamento concluído. |
expired | O QR Code expirou: chame POST /pay de novo. |
cancelled, rejected | Não foi possível concluir: ofereça uma nova tentativa. |
Confirme pelo webhook
O status na tela é para a experiência. Para liberar o pedido, use o webhook
event.completed no seu servidor: ele é assinado e não depende do navegador do
cliente.
Erros
| Erro | Quando |
|---|---|
422 PGPL0014 | Link em USD sem payer_id, ou Pix não habilitado na sua conta. |
422 0X4002 (field: payer_id) | Meio de pagamento diferente de Pix, sem payer_id. |
422 PGPL0001 | Link não encontrado. |
Testando
No sandbox, o Pix de quem paga sem conta é concluído sozinho em cerca de 5 segundos: o status vai de
pending para processing e você recebe event.created e depois event.completed. Não é preciso
pagar o QR Code.