Primeira cobrança Pix
Do zero a um Pix criado, exibido e confirmado no sandbox, em cinco passos.
Este tutorial cria uma cobrança Pix de R$ 19,90 no sandbox, mostra o QR Code e acompanha a confirmação. No fim você terá exercitado as três peças que toda integração usa: criação com idempotência, consulta e webhook.
Você vai precisar de: a chave de API de sandbox (kpa_test_sk_…), curl e um endpoint HTTPS para receber webhooks. Para testes rápidos, um serviço de inspeção de requisições serve como endpoint temporário.
Configure o ambiente
export DM_API_BASE="https://g6idryo27h.execute-api.us-east-1.amazonaws.com"
export DM_API_KEY="kpa_test_sk_..." # sua chave de sandboxCrie a cobrança
curl -X POST "$DM_API_BASE/api/v1/paymentintents" \
-H "Authorization: $DM_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: tutorial-pedido-1-tentativa-1" \
-d '{
"amount": 1990,
"currency": "BRL",
"paymentMethods": [{ "type": "Pix", "amount": 1990 }],
"customer": { "name": "APPROVED", "email": "cliente@example.com" },
"postbackUrl": "https://SEU-ENDPOINT.example.com/webhooks/dm",
"metadata": { "orderId": "tutorial-pedido-1" }
}'O valor é em centavos: 1990 é R$ 19,90. O nome APPROVED aciona, nas contas em que está habilitada, a simulação de pagamento do sandbox.
Você deve receber 201 Created com status: "Processing" e um bloco pixPayment:
{
"id": "8b727267-bf39-48a4-91ea-eb0780cb48a9",
"object": "payment_intent",
"amount": 1990,
"currency": "BRL",
"status": "Processing",
"pixPayment": {
"qrCodeEmv": "00020126...",
"pixCopyPaste": "00020126...",
"expiresAt": "2026-09-08T15:30:00Z"
}
}Guarde o id.
Exiba o QR Code
No checkout, gere a imagem do QR Code a partir de qrCodeEmv e ofereça o botão de copiar com pixCopyPaste. Detalhes em Exiba o QR Code e acompanhe.
Receba a confirmação
Quando o pagamento for confirmado, o seu endpoint recebe:
{ "eventType": "payment_intent.succeeded", "data": { "id": "8b727267-...", "status": "Succeeded", "amount": 1990, "currency": "BRL" } }Responda 200. Em produção, verifique a assinatura HMAC antes de confiar no evento.
Confira pela API
curl "$DM_API_BASE/api/v1/paymentintents/8b727267-bf39-48a4-91ea-eb0780cb48a9" \
-H "Authorization: $DM_API_KEY"Você deve ver "status": "Succeeded".
Se algo não saiu como esperado
| Sintoma | Causa provável | O que fazer |
|---|---|---|
401 {"message":"Unauthorized"} | O cabeçalho Authorization não foi enviado. | Confira a variável DM_API_KEY no terminal. |
500 {"message":"Internal Server Error"} em toda chamada | Chave inválida ou de outro ambiente. | Confira se a chave começa com kpa_test_sk_. |
400 com type: amount_must_be_integer_minor_units | Valor com casas decimais. | Envie 1990, não 19.90. |
Status fica em Processing | A simulação por nome não está habilitada na sua conta. | Peça a habilitação à equipe de integração ou siga o roteiro com Pix pendente. |
| O webhook não chegou | postbackUrl inacessível ou com redirecionamento. | Teste a URL de fora da sua rede. Consulte o PaymentIntent enquanto isso. |