# Cobrança (PIX, boleto, link)

Pedido de pagamento: o contato vê o valor e as formas de pagar. `pix`, `boleto` e `link` podem ir juntos, e aparecem os que vierem.

- `amount`: o valor (obrigatório na cobrança; sem ele e só com `pix`, sai o [Botão PIX](/docs/envio-pix)).
- `text`: a nota da cobrança.
- `reference_id`: o número do pedido ou da fatura.
- `items[]`: o item cobrado (`name` e `quantity`). Por enquanto, um item por cobrança, sem valor próprio: o valor é o `amount`.
- `pix`: a chave (`key`), o tipo dela (`key_type`: `cpf`, `cnpj`, `email`, `phone` ou `evp`) e o nome de quem recebe (`merchant_name`).
- `boleto`: a linha digitável.
- `link`: o link de pagamento (só domínios homologados pelo WhatsApp).
- `invoice`: a fatura em PDF (`url` ou `base64`, e `filename`).
- `order_id`: para cobrar um pedido que o contato mandou, o `id` da mensagem do pedido.

## Canais

| Canal | Funciona | Observação |
|---|---|---|
| WhatsApp (Web) | Sim |  |
| WhatsApp (API oficial) | Não |  |
| Instagram | Não |  |
| Messenger | Não |  |
| Telegram | Não |  |

## Pedido

`POST /messages` com `"type": "payment"`. [Testar](/endpoint/post/messages)

```json
{
  "to": "5511999999999",
  "type": "payment",
  "amount": 349.5,
  "text": "Pedido #457",
  "reference_id": "457",
  "items": [
    {
      "name": "Kit de ferramentas",
      "quantity": 1
    }
  ],
  "pix": {
    "key": "12345678000190",
    "key_type": "cnpj",
    "merchant_name": "Loja Exemplo LTDA"
  },
  "boleto": "34191.79001 01043.510047 91020.150008 5 97340000034950",
  "invoice": {
    "url": "https://loja.exemplo/boleto-457.pdf",
    "filename": "boleto-457.pdf"
  }
}
```

### Na uazapi

`POST /send/request-payment`, que continua funcionando. Na uazapi o pedido do contato ia em `orderMessageId`; na Orkesio, em `order_id`.

```lado-a-lado
{
  "uazapi (POST /send/request-payment)": {
    "number": "5511999999999",
    "amount": 349.5,
    "text": "Pedido #457",
    "invoiceNumber": "457",
    "itemName": "Kit de ferramentas",
    "pixKey": "12345678000190",
    "pixType": "CNPJ",
    "pixName": "Loja Exemplo LTDA",
    "boletoCode": "34191.79001 01043.510047 91020.150008 5 97340000034950",
    "fileUrl": "https://loja.exemplo/boleto-457.pdf",
    "fileName": "boleto-457.pdf"
  },
  "Orkesio (POST /messages)": {
    "to": "5511999999999",
    "type": "payment",
    "amount": 349.5,
    "text": "Pedido #457",
    "reference_id": "457",
    "items": [
      {
        "name": "Kit de ferramentas",
        "quantity": 1
      }
    ],
    "pix": {
      "key": "12345678000190",
      "key_type": "cnpj",
      "merchant_name": "Loja Exemplo LTDA"
    },
    "boleto": "34191.79001 01043.510047 91020.150008 5 97340000034950",
    "invoice": {
      "url": "https://loja.exemplo/boleto-457.pdf",
      "filename": "boleto-457.pdf"
    }
  }
}
```

## Resposta

A própria mensagem (`OrkesioMessage`), no formato do `message.sent` e da busca. No WhatsApp Web volta na hora com `status: queued`: por padrão o envio vai pela fila (com `options.async: false`, espera o envio e volta a mensagem enviada). É o pedido no formato da mensagem: o arquivo, a miniatura e a prévia do link chegam no `message.sent`. Na API oficial volta depois que a Meta aceita, com `status: pending`. O resultado chega em `message.status` (a falha também em `message.failed`).

```json
{
  "id": "3EB05DCE1D4036FCE241C6",
  "chat_id": "5511999999999@s.whatsapp.net",
  "author": {
    "id": "5511888888888@s.whatsapp.net",
    "phone": "5511888888888"
  },
  "direction": "out",
  "sent_at": "2026-10-17T12:00:00.000Z",
  "category": "unsent",
  "type": "payment",
  "amount": 349.5,
  "reference_id": "457",
  "text": "Pedido #457",
  "pix": {
    "key": "12345678000190",
    "key_type": "cnpj",
    "merchant_name": "Loja Exemplo LTDA"
  },
  "boleto": "34191.79001 01043.510047 91020.150008 5 97340000034950",
  "sent_by": "api",
  "status": "queued"
}
```

### Na uazapi

O `content` da uazapi é o proto do WhatsApp; aqui vai resumido (`...`).

```lado-a-lado
{
  "uazapi": {
    "id": "5511888888888:3EB05DCE1D4036FCE241C6",
    "messageid": "3EB05DCE1D4036FCE241C6",
    "chatid": "5511999999999@s.whatsapp.net",
    "chatlid": "123456789012345@lid",
    "fromMe": true,
    "isGroup": false,
    "groupName": "",
    "sender": "987654321098765@lid",
    "sender_pn": "5511888888888@s.whatsapp.net",
    "sender_lid": "987654321098765@lid",
    "senderName": "",
    "messageType": "InteractiveMessage",
    "mediaType": "",
    "messageTimestamp": 1792238400000,
    "source": "web",
    "status": "",
    "text": "Pedido #457",
    "content": {
      "body": {
        "text": "Pedido #457"
      },
      "nativeFlowMessage": {
        "buttons": [
          {
            "name": "review_and_pay",
            "buttonParamsJSON": "..."
          }
        ]
      }
    },
    "quoted": "",
    "edited": "",
    "reaction": "",
    "vote": "",
    "buttonOrListid": "",
    "convertOptions": "",
    "pinned": false,
    "owner": "5511888888888",
    "wasSentByApi": true,
    "track_source": "",
    "track_id": "",
    "response": {
      "status": "success",
      "message": "Message sent successfully"
    }
  },
  "Orkesio": {
    "id": "3EB05DCE1D4036FCE241C6",
    "chat_id": "5511999999999@s.whatsapp.net",
    "author": {
      "id": "5511888888888@s.whatsapp.net",
      "phone": "5511888888888"
    },
    "direction": "out",
    "sent_at": "2026-10-17T12:00:00.000Z",
    "category": "unsent",
    "type": "payment",
    "amount": 349.5,
    "reference_id": "457",
    "text": "Pedido #457",
    "pix": {
      "key": "12345678000190",
      "key_type": "cnpj",
      "merchant_name": "Loja Exemplo LTDA"
    },
    "boleto": "34191.79001 01043.510047 91020.150008 5 97340000034950",
    "sent_by": "api",
    "status": "queued"
  }
}
```

## No webhook

O que chega no seu webhook (ou em `GET /events`) depois do envio.

### message.sent

Quando a mensagem sai. [O evento `message.sent`](/webhook/message.sent)

```json
{
  "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD5H",
  "type": "message.sent",
  "created_at": "2026-10-17T12:00:00.000Z",
  "inbox": {
    "id": "r0269625d29bfbd",
    "name": "loja",
    "phone": "5511888888888",
    "channel": "whatsapp_web"
  },
  "data": {
    "message": {
      "id": "3EB05DCE1D4036FCE241C6",
      "chat_id": "5511999999999@s.whatsapp.net",
      "author": {
        "id": "5511888888888@s.whatsapp.net",
        "phone": "5511888888888"
      },
      "direction": "out",
      "sent_at": "2026-10-17T12:00:00.000Z",
      "category": "conversation",
      "type": "payment",
      "amount": 349.5,
      "currency": "BRL",
      "reference_id": "457",
      "text": "Pedido #457",
      "items": [
        {
          "name": "Kit de ferramentas",
          "quantity": 1,
          "amount": 349.5
        }
      ],
      "pix": {
        "key": "12345678000190",
        "key_type": "cnpj",
        "merchant_name": "Loja Exemplo LTDA"
      },
      "boleto": "34191.79001 01043.510047 91020.150008 5 97340000034950",
      "sent_by": "api"
    },
    "chat": {
      "id": "5511999999999@s.whatsapp.net",
      "lid": "123456789012345@lid",
      "type": "direct"
    }
  }
}
```

### message.status

`sent`, `delivered`, `read` e `played` (áudio e voz), um evento por mudança; `failed` se o envio falhar. [O evento `message.status`](/webhook/message.status)

```json
{
  "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD6J",
  "type": "message.status",
  "created_at": "2026-10-17T12:00:05.000Z",
  "inbox": {
    "id": "r0269625d29bfbd",
    "name": "loja",
    "phone": "5511888888888",
    "channel": "whatsapp_web"
  },
  "data": {
    "chat": {
      "id": "5511999999999@s.whatsapp.net",
      "lid": "123456789012345@lid",
      "type": "direct"
    },
    "status": "delivered",
    "at": "2026-10-17T12:00:05.000Z",
    "messages": [
      {
        "id": "3EB05DCE1D4036FCE241C6"
      }
    ]
  }
}
```