> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.gomoney.me/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.gomoney.me/_mcp/server.

# API de Cobranças PIX

## Requisitos de autenticação

Para emitir cobranças PIX, use:

* `Authorization: Bearer {{accessToken}}` com o token obtido no login do acesso `INTEGRATION_ONLY`
* `secret-key: {{secretKeyBase64}}`
* `Origin: {{allowedOrigin}}`

Os endpoints de consulta exigem:

* `Authorization: Bearer {{accessToken}}`

## Endpoints disponíveis

| Método | Caminho                       | Finalidade                                                                  |
| ------ | ----------------------------- | --------------------------------------------------------------------------- |
| `POST` | `/pix/create/brl/integration` | Emite uma cobrança PIX em BRL para a integração documentada.                |
| `GET`  | `/pix`                        | Lista cobranças PIX do usuário autenticado com filtro opcional por período. |
| `GET`  | `/pix/{pixId}`                | Consulta o detalhe de uma cobrança PIX específica.                          |

## Criar cobrança PIX em BRL

```http
POST https://api-pix.gomoney.me/pix/create/brl/integration
Authorization: Bearer {{accessToken}}
secret-key: {{secretKeyBase64}}
Origin: {{allowedOrigin}}
Content-Type: application/json
```

### Corpo da requisição

| Campo                    | Tipo      | Obrigatório | Descrição                                          |
| ------------------------ | --------- | ----------- | -------------------------------------------------- |
| `amount`                 | `number`  | Sim         | Valor da cobrança.                                 |
| `payerDocument`          | `string`  | Sim         | Documento do pagador.                              |
| `payerName`              | `string`  | Sim         | Nome do pagador.                                   |
| `allowThirdPartyPayment` | `boolean` | Não         | Permite pagamento por terceiro.                    |
| `correlationId`          | `string`  | Não         | Referência própria do integrador para conciliação. |
| `isCreditGmc`            | `boolean` | Não         | Define o comportamento operacional do crédito.     |
| `customerIdentifier`     | `string`  | Sim         | `_id` ou `taxId` do customer associado à cobrança. |

### Regras operacionais

* a `secret-key` precisa pertencer ao mesmo usuário do token `Bearer`;
* o header `Origin` precisa corresponder ao domínio liberado na integração;
* `customerIdentifier` é obrigatório e pode ser enviado como `_id` ou `taxId`;
* as taxas PIX seguem a hierarquia `customer -> user -> settings`;
* a wallet operacional do usuário precisa estar cadastrada e aprovada para o direcionamento dos recebimentos PIX em GMC.

### Exemplo de requisição

```json
{
  "amount": 150.5,
  "payerDocument": "39053344705",
  "payerName": "Pagador Externo",
  "allowThirdPartyPayment": false,
  "correlationId": "ORDER-1001",
  "isCreditGmc": true,
  "customerIdentifier": "66f0b1b5c1f7b7dc0ce30001"
}
```

### Resposta de sucesso

```json
{
  "_id": "66f0b1b5c1f7b7dc0ce40001",
  "txid": "4b8f5a4f7d8c4b45a5a6258a7e2b1234",
  "amount": 150.5,
  "credit": 146.24,
  "payerDocument": "39053344705",
  "payerName": "Pagador Externo",
  "userId": "66f0b1b5c1f7b7dc0ce20001",
  "valueCreditInGmc": null,
  "status": "opened",
  "isCreditGmc": true,
  "customerIdentifier": "66f0b1b5c1f7b7dc0ce30001",
  "pix": {
    "id": 12001,
    "qrcode": {
      "emv": "0002010102122680...",
      "png": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    "formats": {
      "default": {
        "html": "https://pix.example.com/checkout/4b8f5a4f7d8c4b45a5a6258a7e2b1234",
        "png": "https://pix.example.com/files/default.png",
        "pdf": "https://pix.example.com/files/default.pdf"
      },
      "qrcode": {
        "html": "https://pix.example.com/files/qrcode.html",
        "png": "https://pix.example.com/files/qrcode.png",
        "pdf": "https://pix.example.com/files/qrcode.pdf"
      }
    }
  }
}
```

### Códigos de retorno

| Código | Significado                                                                    | Ação recomendada                                                                   |
| ------ | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| `201`  | Cobrança criada com sucesso.                                                   | Persistir `_id`, `txid`, `customerIdentifier` e o material de pagamento.           |
| `400`  | Dados inválidos, valor inconsistente ou `customerIdentifier` ausente/inválido. | Revisar documento do pagador, valor e vínculo com customer.                        |
| `401`  | Token, `secret-key` ou `Origin` inválidos para a integração.                   | Renovar o token e revisar credencial e domínio liberado.                           |
| `403`  | Usuário sem permissão para a operação.                                         | Confirmar que o acesso usado é do tipo `INTEGRATION` com `INTEGRATION_ONLY` ativo. |
| `503`  | Fluxo GMC indisponível temporariamente.                                        | Reprocessar em janela operacional permitida.                                       |

## Listar cobranças PIX

```http
GET https://api-pix.gomoney.me/pix?initialDate=2026-07-01&finalDate=2026-07-31
Authorization: Bearer {{accessToken}}
```

### Parâmetros de query

| Parâmetro     | Tipo              | Obrigatório | Descrição               |
| ------------- | ----------------- | ----------- | ----------------------- |
| `initialDate` | `string` (`date`) | Não         | Data inicial do filtro. |
| `finalDate`   | `string` (`date`) | Não         | Data final do filtro.   |

### Resposta de sucesso

```json
[
  {
    "_id": "66f0b1b5c1f7b7dc0ce40001",
    "txid": "4b8f5a4f7d8c4b45a5a6258a7e2b1234",
    "amount": 150.5,
    "status": "opened",
    "customerIdentifier": "66f0b1b5c1f7b7dc0ce30001"
  }
]
```

### Códigos de retorno

| Código | Significado                  | Ação recomendada                                                |
| ------ | ---------------------------- | --------------------------------------------------------------- |
| `200`  | Lista retornada com sucesso. | Usar os identificadores recebidos para consulta ou conciliação. |
| `401`  | Token inválido.              | Renovar a sessão da API PIX com o acesso de integração correto. |

## Consultar cobrança PIX por ID

```http
GET https://api-pix.gomoney.me/pix/{{pixId}}
Authorization: Bearer {{accessToken}}
```

### Parâmetro de rota

| Parâmetro | Tipo     | Obrigatório | Descrição                              |
| --------- | -------- | ----------- | -------------------------------------- |
| `pixId`   | `string` | Sim         | Identificador interno da cobrança PIX. |

### Resposta de sucesso

```json
{
  "_id": "66f0b1b5c1f7b7dc0ce40001",
  "txid": "4b8f5a4f7d8c4b45a5a6258a7e2b1234",
  "amount": 150.5,
  "credit": 146.24,
  "status": "paid",
  "customerIdentifier": "66f0b1b5c1f7b7dc0ce30001",
  "paymentDate": 1783189200000,
  "pix": {
    "qrcode": {
      "emv": "0002010102122680...",
      "png": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  }
}
```

### Códigos de retorno

| Código | Significado                                                       | Ação recomendada                                                |
| ------ | ----------------------------------------------------------------- | --------------------------------------------------------------- |
| `200`  | Cobrança encontrada.                                              | Atualizar a conciliação e o estado interno da cobrança.         |
| `401`  | Token inválido.                                                   | Renovar a sessão da API PIX com o acesso de integração correto. |
| `417`  | Cobrança não encontrada ou sem vínculo com o usuário autenticado. | Confirmar o identificador informado e a titularidade da conta.  |

## Fluxo após o pagamento

Depois da confirmação do PIX, a plataforma:

1. valida o valor recebido;
2. localiza a cobrança correspondente;
3. vincula o pagamento ao customer indicado;
4. atualiza o status da cobrança;
5. disponibiliza a cobrança atualizada para consulta;
6. segue o fluxo operacional de notificação previsto para a conta.