PagnovoPagnovodocs
Dashboard

Guias

Pagamentos via API

Se você já tem sua própria interface — app, dashboard, marketplace, carteira digital, plataforma P2P, casa de apostas, qualquer coisa — e só precisa receber pagamentos e enviar saques via PIX sem usar o checkout hospedado da Pagnovo, este guia é pra você.

Em uma frase: seu usuário paga via PIX (cash-in), você acompanha o saldo, e quando ele saca você manda PIX de volta (cash-out). Os webhooks fecham o ciclo, notificando seu sistema quando o pagamento chega e quando o saque é confirmado.

É o modelo conhecido como checkout transparente: o usuário final nunca vê tela da Pagnovo — todo o fluxo acontece dentro do seu produto, e a gente só processa o dinheiro nos bastidores. Este guia te leva do zero a um fluxo de produção sem passar pelas partes da API pensadas pra catálogo e cobrança recorrente.

Quando esse modelo se aplica

"Pagamentos via API" cobre qualquer caso onde você controla a UI de pagamento e só precisa de movimentação financeira:

  • Marketplaces — comprador paga, parte vai pro vendedor, parte fica retida.
  • Carteiras / wallets — usuário deposita saldo, gasta dentro do app, saca quando quer.
  • Plataformas P2P — repasse direto entre usuários, com a plataforma intermediando.
  • iGaming / bet — depósito do jogador, pagamento de prêmio.
  • Apps de freelancer / gig economy — pagamento ao prestador após conclusão do serviço.
  • Qualquer SaaS que cobra via PIX sem checkout pronto — você emite a cobrança no seu sistema e usa a API só pra gerar o BR Code.

Se em algum momento você se perguntou "preciso só de uma API que recebe PIX e manda PIX, sem perder tempo com catálogo de produto" — você está no guia certo.

O que você precisa em produção

Cinco etapas cobrem 100% do fluxo:

#EtapaComo você faz
1Receber pagamento de entradaPOST /transactions/v2/purchase com paymentMethod: "PIX"
2Confirmar pagamentoWebhook cashin.paid (Payload v2) ou status: "APPROVED" em Payload v1
3Enviar pagamento de saídaPOST /withdraws/cash-out com a chave PIX do destinatário
4Confirmar saqueWebhook cashout.success (v2) ou status: "WITHDRAW_APPROVED" (v1)
5Acompanhar caixaGET /accounts/balance para conciliação

É só isso. Não há fluxo de catálogo, assinatura, cupom nem checkout hospedado — sua plataforma já tem o cadastro do usuário, você só precisa que o dinheiro entre e saia.

Fluxo de cash-in

1. Seu usuário escolhe um valor pra pagar na sua plataforma.

2. Você cria a transação via API:

bash
curl -X POST "https://api.pagnovo.com/transactions/v2/purchase" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "joao@exemplo.com",
    "cpf": "12345678901",
    "phone": "9876543210",
    "amount": 5000,
    "description": "Pagamento - pedido 1234",
    "responsibleDocument": "12345678901",
    "responsibleExternalId": "user-1234",
    "externalId": "pedido-9876",
    "paymentMethod": "PIX",
    "restrictPayerDocument": true
  }'

amount: 5000 = R$ 50,00. Todos os valores em centavos.

3. Você recebe um pixCode (BR Code copia-e-cola). Mostre como QR Code ou texto pro usuário dentro do seu app.

4. Quando o usuário pagar, você recebe um webhook:

JSON
{
  "event": "cashin.paid",
  "payload": {
    "transaction_id": "17615714245971918718644287",
    "external_id": "pedido-9876",
    "amount": 5000,
    "end_to_end_id": "E182361202026102713240..."
  }
}

5. Seu handler valida assinatura, credita o usuário no seu sistema, retorna 200 OK. Pronto.

💡 restrictPayerDocument: true trava a transação ao CPF que você passou em cpf. Se outra pessoa tentar pagar, o banco rejeita. É a defesa mais forte contra fraude de pagamento por terceiros — terceiro paga, depois contesta, o dinheiro volta, mas o seu usuário já ficou com o crédito. Recomendado sempre que o valor for relevante (especialmente em marketplaces, iGaming e P2P).

Detalhes adicionais: Criar transação, Buscar transação, Estornar transação.

Fluxo de cash-out

1. Seu usuário (ou seu sistema) pede um envio de PIX informando a chave do destinatário.

2. Você valida internamente (saldo disponível, KYC, antifraude) e chama a API:

bash
curl -X POST "https://api.pagnovo.com/withdraws/cash-out" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "pixKey": "joao@exemplo.com",
    "pixType": "EMAIL",
    "document": "12345678901",
    "restrictReceiverDocument": true,
    "externalId": "envio-4321"
  }'

amount: 10000 = R$ 100,00. restrictReceiverDocument: true exige que o CPF retornado pelo DICT bata com o documento informado. Recomendado sempre que você souber pra quem está pagando — protege contra reatribuição de chave PIX (a chave foi excluída e usada por outra pessoa).

3. A resposta é assíncrona — você recebe WITHDRAW_REQUEST e o resultado final chega por webhook em segundos a alguns minutos:

JSON
{
  "event": "cashout.success",
  "payload": {
    "withdrawal_id": "17615714245971918718644287",
    "external_id": "envio-4321",
    "amount": 10000,
    "end_to_end_id": "E182361202026..."
  }
}

4. Estados possíveis para o saque:

Status v2Status v1O que fazer
cashout.successWITHDRAW_APPROVEDConfirme no seu sistema. Fundos saíram do seu saldo.
cashout.failedWITHDRAW_REJECTED / WITHDRAW_ERRORFundos voltam ao seu saldo. Notifique o destinatário.
cashout.returnedWITHDRAW_RETURNEDFoi aprovado e depois devolvido. Fundos voltam. Investigue antes de tentar de novo.

⚠️ Nunca faça retry automático em estado intermediário (WITHDRAW_REQUEST / WITHDRAW_PROCESSING). Aguarde o webhook final. Fazer retry sem confirmação é a forma mais comum de empresas pagarem o mesmo destinatário duas vezes por engano.

Detalhes adicionais: Saque por chave PIX, Saque por QR Code, Buscar saque.

Segurança operacional

Não negocie estes itens em produção:

  • IP allowlist para a chave de cash-out. Chaves com createWithdraw precisam estar travadas a IPs específicos no dashboard. Sem allowlist, uma chave vazada vira saque pra carteira de outra pessoa em minutos. Veja Autenticação e chaves para detalhes.
  • Separe chaves de API por contexto. Uma chave viewBalance pro dashboard interno, uma chave createTransaction pra entrada, uma chave createWithdraw pra saída (com allowlist apertado). Vazamento de uma não compromete as outras.
  • Webhooks idempotentes. Persista transaction_id e withdrawal_id no seu banco e ignore reentregas. A Pagnovo reentrega entregas que falharam com backoff exponencial por até 24h.
  • Verifique a assinatura HMAC. URLs de webhook vazam — sem validar a assinatura, qualquer um que descobrir sua URL pode forjar um cashin.paid e levar crédito de graça. Veja Verificação de assinatura.
  • Persista o x-trace-id. Toda resposta da API e todo webhook carregam um x-trace-id no header. Guarde junto com sua linha de transação — quando algo der estranho, ele é o caminho mais rápido pra investigação. Veja Trace ID e debug.

O que você NÃO precisa

A Pagnovo expõe vários módulos que não fazem sentido pra esse modelo e que você pode ignorar com tranquilidade:

  • Clientes — você já tem o usuário cadastrado na sua plataforma. Não precisa criar um Customer na Pagnovo pra cada pagamento.
  • Produtos / Ofertas — não há catálogo. O que está sendo "vendido" (crédito, serviço, ticket) é gerenciado no seu sistema.
  • Cupons — cupons só funcionam dentro do checkout hospedado da Pagnovo, que esse modelo não usa.
  • Assinaturas / Invoices recorrentes — se você precisa de cobrança recorrente, dá pra gerar uma nova transação no seu próprio agendador. Os módulos de Subscription/Invoice existem pra quem usa o checkout pronto.
  • Checkout hospedado (QuickLinks / Offers) — você usa fluxo dentro do seu próprio app, não link compartilhável.

Se em algum momento você quiser adicionar catálogo, checkout hospedado ou assinatura recorrente em cima desse fluxo, veja o guia Catálogo e Assinaturas.