> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goatpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Receber PIX

> Tutorial: gerar QR, exibir no checkout, confirmar pagamento e reconciliar

Fluxo completo para **receber PIX** na sua aplicação usando a API pública v1.

## Visão geral

```mermaid theme={null}
sequenceDiagram
  participant App
  participant GoatPay
  participant Pagador

  App->>GoatPay: POST /payment-pix/create
  GoatPay-->>App: QR + copyPaste + id
  App->>Pagador: Exibe QR ou copia e cola
  Pagador->>GoatPay: Paga via app do banco
  GoatPay-->>App: webhook payment.paid
  App->>App: Libera produto / pedido
```

Permissões necessárias: `payment-pix/create`, `payment-pix/get` (opcional), `webhooks/create` (recomendado).

## 1. Criar a cobrança

```bash theme={null}
curl -X POST https://api.goatpay.com.br/v1/payment-pix/create \
  -H "X-API-Key: gp_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.90,
    "description": "Pedido #1042",
    "coverFee": false,
    "externalReference": "pedido-1042"
  }'
```

### Campos importantes

| Campo               | Descrição                                                           |
| ------------------- | ------------------------------------------------------------------- |
| `amount`            | Valor em reais (decimal)                                            |
| `coverFee`          | `false` = valor bruto do QR; `true` = líquido que você quer receber |
| `externalReference` | ID do seu pedido — use em webhooks e extrato                        |
| `description`       | Texto no extrato e no QR                                            |
| `subaccountId`      | Opcional — credita subconta merchant                                |

### Resposta

Guarde `data.id` e exiba ao pagador:

* `copyPaste` — string PIX
* `qrCodeBase64` — imagem PNG em base64
* `qrcodeUrl` — URL da imagem

Status inicial: `PENDING`. Após pagamento: `COMPLETED`.

[Documentação do endpoint](/api-reference/endpoint/payment-pix/create)

## 2. Exibir no checkout

**Web:** decodifique `qrCodeBase64` ou use `qrcodeUrl` em `<img>`. Ofereça botão "Copiar PIX" com `copyPaste`.

**Mobile:** deep link para apps bancários com o copia e cola.

Não feche o pedido até confirmar o pagamento (webhook ou consulta).

## 3. Confirmar pagamento

### Recomendado: webhook

Cadastre endpoint para `payment.paid`. O payload traz `data.externalReference` e `data.amount`.

[Webhooks na prática](/pages/guides/webhooks-pratica)

### Alternativa: consulta

```bash theme={null}
curl "https://api.goatpay.com.br/v1/payment-pix/get/ID_DA_COBRANCA" \
  -H "X-API-Key: gp_live_SUA_CHAVE"
```

Use com moderação — [rate limit](/api-reference/rate-limiting) de 100 req/min. Polling a cada 2–5 s em muitos pedidos pode estourar o limite.

## 4. Reconciliar

| Fonte                       | Uso                                      |
| --------------------------- | ---------------------------------------- |
| `externalReference`         | Liga cobrança ao pedido no seu sistema   |
| `data.endToEndId`           | Identificador PIX no SPI (suporte e MED) |
| `GET /account/transactions` | Extrato completo com todos os tipos      |
| `GET /payment-pix/list`     | Só entradas PIX                          |

Filtre por data, status e `externalReference` nas listagens.

## Casos comuns

### Split com parceiro

Na criação, envie `splitUser` (e-mail GoatPay) e `splitTax` (percentual do líquido).

### Subconta merchant

Envie `subaccountId` no `create`. O líquido credita a subconta, não a conta principal.

[Guia de subcontas](/api-reference/guides/subcontas)

### QR expirado

Evento `payment.pix.expired`. Gere nova cobrança ou consulte status `CANCELED`.

### Reembolso

Somente depósitos `COMPLETED` no trilho **PADRAO**. Use `POST /refunds/create` com `transactionId` ou `e2eId`.

[Guia PIX — reembolso](/api-reference/guides/pix#reembolsar-depósito)

## Erros frequentes

| Código | Causa          | Solução                           |
| ------ | -------------- | --------------------------------- |
| 401    | Chave inválida | Header `X-API-Key`                |
| 403    | Sem permissão  | `payment-pix/create` na chave     |
| 400    | Valor mínimo   | PADRAO: mín. R\$ 3,00 na cobrança |

Mais erros: [Troubleshooting](/pages/guides/troubleshooting) · [Erros da API](/api-reference/guides/errors).