Pix

Gerar QR Code para recebimento PIX

Cria uma cobrança Pix na carteira informada. Exige credencial com permissão de Pix. 202 significa que o QR Code foi emitido (data.payload.qrCode) e a transação está em awaiting_payment; o pagamento só está confirmado quando a transação chega a completed — acompanhe pelo webhook ou pela consulta por externalId.

POSThttps://api.monkeypay.app/api/v2/payment/pix/qrcodeBearer

Fluxo

Antes de chamar

  1. Chamada

    POSTEmitir token bearer

    /resource/auth/token

    Authorization: Bearer <seu-token>

  2. Chamada

    GETListar carteiras

    /resource/wallets

    walletId da carteira que recebe

  3. Você

    Gere um externalId único

    Até 100 caracteres; único em toda a plataforma

Esta chamada

POSTGerar QR Code Pix

/payment/pix/qrcode

Respostas possíveis

Depois do sucesso

  1. Pagador

    Paga o Pix

    Sem pagamento, a cobrança vira expired

  2. MonkeyPay

    Webhook completed

    Na URL cadastrada para completed

  3. Chamada

    GETConsultar por ID externo

    /resource/transactions/external-id/{externalId}

    Confirme completed antes de liberar

Autorização

BearerRequer autenticação Bearer

Parâmetros

x-customer-idstringcabeçalhoopcional

Opcional. A versão atual da API não lê nem grava este header: a organização é sempre deduzida do token bearer. Enviá-lo não altera o resultado da chamada.

<x-customer-id>

Body

walletIdstringobrigatório

Carteira que recebe o Pix (`id` de GET /resource/wallets).

Tamanho1 ≤ tamanho
wal_01J9Z8K3M4N5P6Q7R8S9T0V1W2
amountnumberobrigatório

Valor em reais, com até duas casas decimais (`10.5` = R$ 10,50). Não envie centavos. Valor menor ou igual à tarifa da operação é recusado com 400.

10.5
descriptionstringopcional

Texto livre exibido na cobrança.

Pedido 1234
infoobjectobrigatório

Dados de quem vai pagar.

<info>
payerDocumentstringobrigatório

CPF ou CNPJ do pagador, somente dígitos.

Tamanho1 ≤ tamanho
12345678909
payerNamestringobrigatório
Tamanho1 ≤ tamanho
Maria da Silva
payerPhonestringopcional
+5511999999999
payerEmailstringopcional
[email protected]
externalIdstringobrigatório

Seu identificador da cobrança. Guarde-o: é por ele que você consulta a transação (GET /resource/transactions/external-id/{externalId}) e concilia os webhooks.

Tamanho1 ≤ tamanho
pedido-1234

Respostas

1{
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.pix0136...6304ABCD",
14 "receiver": {
15 "account": "123456",
16 "agency": "0001",
17 "document": "12345678000190",
18 "name": "Minha Empresa LTDA",
19 "bankIspb": "12345678",
20 "bankName": "Banco Liquidante"
21 },
22 "sender": {
23 "account": null,
24 "agency": null,
25 "document": "12345678909",
26 "name": "Maria da Silva",
27 "bankIspb": null,
28 "bankName": null
29 },
30 "createdAt": "2026-09-24T12:00:00.000Z",
31 "updatedAt": "2026-09-24T12:00:00.000Z"
32 }
33 }
34}

Campos da resposta

errorobjectopcional

`null` no sucesso; mensagem de falha quando `success` é `false`.

<error>
successbooleanopcional
<success>
messagestringopcional
<message>
dataobjectopcional
<data>
statusstringopcional

`awaiting_payment` (QR gerado, aguardando pagamento) e `processing` (envio aceito) são estados intermediários. Só trate como final `completed`, `failed`, `cancelled`, `expired`, `refunded` e `partially_refunded`.

valores: createdpendingprocessingawaiting_paymentcompletedfailedcancelledrefundedpartially_refundedexpiredinfraction

<status>
typestringopcional

valores: pix_in

<type>
payloadobjectopcional
<payload>
transactionIdstring (uuid)opcional
<transactionId>
externalIdstringopcional
<externalId>
amountnumberopcional
<amount>
statusstringopcional

`awaiting_payment` (QR gerado, aguardando pagamento) e `processing` (envio aceito) são estados intermediários. Só trate como final `completed`, `failed`, `cancelled`, `expired`, `refunded` e `partially_refunded`.

valores: createdpendingprocessingawaiting_paymentcompletedfailedcancelledrefundedpartially_refundedexpiredinfraction

<status>
errorMessagestringopcional

Presente só quando a emissão falha; ausente no sucesso.

<errorMessage>
qrCodestringopcional
<qrCode>
endToEndstringopcional

Ausente até o pagamento ser identificado.

<endToEnd>
receiverobjectopcional
<receiver>
senderobjectopcional
<sender>
createdAtstring (date-time)opcional
<createdAt>
updatedAtstring (date-time)opcional
<updatedAt>
Credenciais

Requisição

1curl --request POST \
2 --url 'https://api.monkeypay.app/api/v2/payment/pix/qrcode' \
3 --header 'Content-Type: application/json' \
4 --header 'Authorization: Bearer <seu-token>' \
5 --data '{
6 "walletId": "wal_01J9Z8K3M4N5P6Q7R8S9T0V1W2",
7 "amount": 10.5,
8 "description": "Pedido 1234",
9 "info": {
10 "payerDocument": "12345678909",
11 "payerName": "Maria da Silva",
12 "payerPhone": "+5511999999999",
13 "payerEmail": "[email protected]"
14 },
15 "externalId": "pedido-1234"
16 }'

Resposta

1{
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.pix0136...6304ABCD",
14 "receiver": {
15 "account": "123456",
16 "agency": "0001",
17 "document": "12345678000190",
18 "name": "Minha Empresa LTDA",
19 "bankIspb": "12345678",
20 "bankName": "Banco Liquidante"
21 },
22 "sender": {
23 "account": null,
24 "agency": null,
25 "document": "12345678909",
26 "name": "Maria da Silva",
27 "bankIspb": null,
28 "bankName": null
29 },
30 "createdAt": "2026-09-24T12:00:00.000Z",
31 "updatedAt": "2026-09-24T12:00:00.000Z"
32 }
33 }
34}