Fluxo Pix

Receba com QR Code, envie para uma chave Pix e concilie cada transação pelo seu externalId.

Todas as chamadas abaixo usam Authorization: Bearer <seu-token> e a URL base https://api.monkeypay.app/api/v2. Valores são em reais.

	Receber (`pix_in`)	Enviar (`pix_out`)
Chamadas	`POST /payment/pix/qrcode`	`POST /payment/pix/dict` e `POST /payment/pix/send`
Resposta	`202`, transação em `awaiting_payment`	`202`, transação em `processing`
Saldo	Creditado quando a transação chega a `completed`	Debitado em `amount` mais a tarifa
Confirmação	Webhook ou consulta pelo `externalId`	Webhook ou consulta pelo `externalId`

Receber: gerar QR Code

POST /payment/pix/qrcode

A carteira precisa ter uma conta de recebimento ativa vinculada (accPixIn em Consultar carteira). Sem conta vinculada, a API responde 422 em application/problem+json, com type terminado em /wallet-without-receiving-account, e nenhuma transação é criada. Com a conta vinculada, mas inativa ou bloqueada, a resposta é 403 com detail "This account is inactive or blocked". No painel, a conta é vinculada na carteira, aba Conta, em Conta de recebimento; a alteração exige permissão de escrita em carteiras.

2 "walletId": "<wallet-id>",

3 "amount": 10.5,

4 "description": "Pedido 1234",

5 "externalId": "pedido-1234",

6 "info": {

7 "payerDocument": "12345678909",

8 "payerName": "Maria da Silva",

9 "payerEmail": "[email protected]"

10 }

11}

Campo	Obrigatório	Observação
`walletId`	sim	Carteira que recebe
`amount`	sim	Reais; precisa ser maior que a tarifa
`externalId`	sim	Único, até 100 caracteres
`info.payerDocument`	sim	CPF ou CNPJ do pagador
`info.payerName`	sim	Nome do pagador
`info.payerEmail`, `info.payerPhone`	não	—
`description`	não	Texto da cobrança

Resposta 202:

2 "error": null,

3 "success": true,

4 "message": "QR Code generated successfully",

5 "data": {

6 "status": "awaiting_payment",

7 "type": "pix_in",

8 "payload": {

9 "transactionId": "3f1c9a52-6d0e-4b8e-9d7a-2c4b5e6f7a81",

10 "externalId": "pedido-1234",

11 "amount": 10.5,

12 "status": "awaiting_payment",

13 "qrCode": "00020126580014br.gov.bcb.pix..."

14 }

15 }

16}

O exemplo mostra os campos usados na integração; o payload traz também sender e receiver. endToEnd e errorMessage só aparecem quando preenchidos.

O envelope das operações Pix difere do das consultas: no sucesso, error vem null (e não false) e success substitui pagination.

Mostre data.payload.qrCode ao pagador como Pix copia e cola ou converta-o em imagem de QR Code. O pagamento só está confirmado quando a transação chega a completed.

Se o liquidante recusar a emissão, a resposta é 422 com o envelope Pix (success: false) e a transação em failed. Gere nova cobrança com outro externalId.

Enviar: conferir o destinatário e pagar

1. Descubra a conta de saída

GET /resource/wallets/{walletId} devolve data.accPixOut, a conta usada nos envios dessa carteira.

2. Consulte a chave no DICT

POST /payment/pix/dict

2 "accountId": "<accPixOut-da-carteira>",

3 "pixKey": "[email protected]"

A resposta traz o titular em data.owner.name e data.owner.taxIdNumber. Mostre esses dados para quem vai aprovar o pagamento. A consulta não movimenta saldo.

accountId não é o walletId. Com um accountId inexistente ou de conta inativa, a API responde 403 com detail "This account is inactive or blocked".

3. Envie o Pix

POST /payment/pix/send

2 "walletId": "<wallet-id>",

3 "pixKey": "[email protected]",

4 "amount": 10.5,

5 "description": "Pagamento fornecedor 42",

6 "externalId": "pagamento-42"

A carteira é debitada em amount mais a tarifa. A resposta 202 traz a transação em processing:

2 "error": null,

3 "success": true,

4 "message": "Payment in progress successfully",

5 "data": {

6 "status": "processing",

7 "type": "pix_out",

8 "payload": {

9 "transactionId": "7b2e4c10-1a3d-4f5e-8b9c-0d1e2f3a4b5c",

10 "externalId": "pagamento-42",

11 "amount": 10.5,

12 "status": "processing"

13 }

14 }

15}

202 não significa que o dinheiro chegou. Aguarde completed ou failed. Em timeout ou 5xx, consulte pelo externalId antes de reenviar: repetir o envio pode pagar duas vezes.

Conciliar

Consulta	Quando usar
`GET /resource/transactions/external-id/{externalId}`	Conferir uma cobrança ou envio seu, inclusive depois de timeout
`GET /resource/transactions/id/{transactionId}`	Você guardou o `transactionId` da resposta `202`
`GET /resource/transactions/end-to-end/{endToEnd}`	Você tem o identificador end-to-end do Pix
`GET /resource/transactions?walletId=...&status=completed`	Conciliação em lote, paginada

A consulta individual devolve a transação com amount, feeAmount, status, os dados Pix em data.pix (pagador, recebedor e endToEnd) e o lançamento no ledger em data.ledger.

Estados da transação

1Receber (pix_in)

2 awaiting_payment → completed

3 awaiting_payment → expired

4 completed → infraction

6Enviar (pix_out)

7 processing → completed

8 processing → failed

9 completed → refunded

10 completed → partially_refunded

Estado	Significa	Final?
`awaiting_payment`	QR Code emitido, aguardando pagamento	não
`processing`	Envio aceito, em liquidação	não
`completed`	Pix liquidado	sim; um Pix recebido ainda pode passar a `infraction`
`failed`	Recusado ou não liquidado; motivo em `errorMessage`	sim
`expired`	Cobrança venceu sem pagamento	sim
`refunded`, `partially_refunded`	Devolvido total ou parcialmente	sim
`cancelled`	Cancelado	sim
`infraction`	Pix recebido contestado por MED e devolvido ao pagador; veja o guia Infrações e MED	sim

Só libere mercadoria, saldo ou serviço quando o estado for completed, confirmado pela consulta ou por webhook validado.