Documentação da API MonkeyPay

Receba e envie Pix, consulte carteiras e transações e acompanhe eventos por webhook a partir do seu backend.

A API MonkeyPay conecta o seu produto a recebimentos e pagamentos Pix. Você cria cobranças, envia pagamentos, consulta saldos e transações e recebe webhooks quando o estado de uma transação muda.

As páginas de endpoint são geradas a partir do contrato OpenAPI publicado pela API. Os guias mostram como encadear essas operações numa integração completa.

Antes de começar

Você precisa de:

clientId e clientSecret da credencial de integração da sua organização;
ao menos uma carteira ativa na organização;
um backend que guarde segredos e receba requisições HTTPS, para os webhooks.

Conceitos usados em toda a API

Conceito	O que é	Onde obter
Organização	Dona das carteiras e das transações. Vem do token: você não a informa nas chamadas Pix.	Campo `organizationId` das carteiras
Carteira (`walletId`)	Saldo usado para receber e enviar Pix.	`id` em Listar carteiras
Conta de saída (`accPixOut`)	Conta da carteira usada nos envios. É o `accountId` da consulta ao DICT.	Consultar carteira
`externalId`	Seu identificador da cobrança ou do pagamento. Único, até 100 caracteres.	Você gera e guarda
Valores	Sempre em reais, como número decimal: `10.5` é R$ 10,50.	—

Formato das respostas

Respostas de sucesso vêm num envelope, com o resultado em data:

2 "error": false,

3 "message": "Transaction fetched successfully",

4 "data": { "id": "3f1c9a52-6d0e-4b8e-9d7a-2c4b5e6f7a81", "status": "completed" },

5 "pagination": null

As operações Pix trocam pagination por success. Toda resposta JSON traz também requestId, o mesmo valor do header x-request-id. Os erros seguem os formatos de Erros e respostas.

Operações assíncronas

Gerar QR Code e enviar Pix respondem 202: a operação foi aceita, ainda não concluída. O resultado final chega pelo webhook e pode ser confirmado consultando a transação pelo externalId.

11. Seu backend → POST /payment/pix/send

22. MonkeyPay → 202, processing

33. MonkeyPay → envia ao liquidante

44. Liquidante → confirma

55. MonkeyPay → webhook completed

Mapa da integração

Siga os guias nesta ordem. Os dois últimos só são necessários quando você receber contestações ou precisar exportar dados.

Ordem	Guia	Para quê
1	Primeiros passos	Do token à primeira cobrança, em seis passos
2	Autenticação	Emitir, usar e renovar o token
3	Fluxo Pix	Receber com QR Code, enviar e conciliar
4	Webhooks	Receber as mudanças de estado no seu backend
5	Erros e respostas	Tratar erros e repetir sem pagar duas vezes
6	Infrações e MED	Responder a contestações de Pix recebido
7	Relatórios	Exportar transações, lançamentos e saldo