Pix

Enviar pagamento via PIX

Debita a carteira e envia um Pix para a chave informada. Exige credencial com permissão de Pix. 202 significa que o envio foi aceito e está em processing — não que o dinheiro chegou. O resultado final (completed ou failed) chega pelo webhook ou pela consulta por externalId. Em timeout, consulte antes de reenviar.

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

Fluxo

Antes de chamar

  1. Chamada

    POSTEmitir token bearer

    /resource/auth/token

    Authorization: Bearer <seu-token>

  2. Chamada

    POSTConsultar chave no DICT

    /payment/pix/dict

    Titular conferido e aprovado

  3. Chamada

    GETConsultar saldo

    /resource/wallets/{walletId}/balance

    available cobre amount mais a tarifa

  4. Você

    Gere um externalId único

    Guarde antes de chamar

Esta chamada

POSTEnviar Pix

/payment/pix/send

Respostas possíveis

Depois do sucesso

  1. MonkeyPay

    Liquida o Pix

    O saldo já foi debitado no envio

  2. MonkeyPay

    Webhook completed ou failed

    failed traz o motivo em errorMessage

  3. Chamada

    GETConsultar por ID externo

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

    Confira o status final

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 de origem, que precisa pertencer à organização do token.

Tamanho1 ≤ tamanho
wal_01J9Z8K3M4N5P6Q7R8S9T0V1W2
pixKeystringobrigatório

Chave Pix de quem recebe (CPF, CNPJ, e-mail, telefone ou aleatória). Confira o titular antes com POST /payment/pix/dict.

Tamanho1 ≤ tamanho
[email protected]
amountnumberobrigatório

Valor em reais, com até duas casas decimais (`10.5` = R$ 10,50). Não envie centavos. O saldo da carteira é debitado em `amount` mais a tarifa da operação.

10.5
descriptionstringopcional
Pagamento fornecedor 42
externalIdstringobrigatório

Seu identificador do pagamento. Em timeout ou erro 5xx, consulte GET /resource/transactions/external-id/{externalId} antes de reenviar: a transação pode ter sido criada.

Tamanho1 ≤ tamanho
pagamento-42
customerobjectopcional

Dados opcionais do beneficiário para registro.

<customer>
namestringopcional
<name>
documentstringopcional
<document>
emailstringopcional
<email>
phonestringopcional
<phone>

Respostas

1{
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 "errorMessage": null,
14 "pixKey": "[email protected]",
15 "endToEnd": null,
16 "createdAt": "2026-09-24T12:00:00.000Z",
17 "updatedAt": "2026-09-24T12:00:00.000Z"
18 }
19 }
20}

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_out

<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
<errorMessage>
pixKeystringopcional
<pixKey>
endToEndstringopcional
<endToEnd>
senderobjectopcional
<sender>
receiverobjectopcional
<receiver>
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/send' \
3 --header 'Content-Type: application/json' \
4 --header 'Authorization: Bearer <seu-token>' \
5 --data '{
6 "walletId": "wal_01J9Z8K3M4N5P6Q7R8S9T0V1W2",
7 "pixKey": "[email protected]",
8 "amount": 10.5,
9 "description": "Pagamento fornecedor 42",
10 "externalId": "pagamento-42",
11 "customer": {
12 "name": "<name>",
13 "document": "<document>",
14 "email": "<email>",
15 "phone": "<phone>"
16 }
17 }'

Resposta

1{
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 "errorMessage": null,
14 "pixKey": "[email protected]",
15 "endToEnd": null,
16 "createdAt": "2026-09-24T12:00:00.000Z",
17 "updatedAt": "2026-09-24T12:00:00.000Z"
18 }
19 }
20}