> ## 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.

# Cobranças e assinaturas

> API pública v1 para cobranças avulsas (boleto, cartão, PIX), assinaturas recorrentes e bureau de crédito na Conta Padrão.

Cobranças comerciais na **Conta Padrão** (trilho **PADRAO**), para contas **PF ou PJ** verificadas. Use chave `gp_live_...` com as permissões abaixo.

## Base URL e autenticação

```
https://api.goatpay.com.br/v1
```

```bash theme={null}
curl 'https://api.goatpay.com.br/v1/billings/list' \
  -H 'X-API-Key: gp_live_SUA_CHAVE'
```

O trilho **PADRAO** vem da **API key**, não do body. Respostas seguem o [envelope padrão](/api-reference/overview#envelope-de-resposta).

## Módulos

| Produto           | Prefixo `/v1`      | Seção                                                              |
| ----------------- | ------------------ | ------------------------------------------------------------------ |
| Cobrança avulsa   | `/billings/*`      | [Cobranças avulsas](#cobrancas-avulsas) — boleto, cartão e PIX     |
| Assinatura        | `/subscriptions/*` | [Assinaturas](#assinaturas)                                        |
| Bureau de crédito | `/serasa/*`        | [Bureau de crédito](#bureau-de-credito) — negativação e relatórios |

<Warning>
  **Cobrança avulsa ≠ assinatura:** `POST /billings/create` gera **um** pagamento. `POST /subscriptions/create` cria **recorrência** com ciclo fixo.
</Warning>

## Permissões na API key

Ative na criação da chave (dashboard → Integrações):

| Grupo             | Permissões                                             |
| ----------------- | ------------------------------------------------------ |
| Cobranças         | `billings/create`, `get`, `list`, `refund`, `tokenize` |
| Assinaturas       | `subscriptions/create`, `get`, `list`, `cancel`        |
| Bureau de crédito | `serasa/dunnings/*`, `serasa/reports/*`                |

Lista completa: [Permissões](/pages/guides/api-permissions) · Mapa geral: [Rotas da API](/api-reference/escopo-api-publica).

## PIX: receber vs cobrar

| Caso                      | Rota                                        | Quando usar                                                                |
| ------------------------- | ------------------------------------------- | -------------------------------------------------------------------------- |
| QR PIX direto (receber)   | `POST /payment-pix/create`                  | Checkout rápido, links, e-commerce — [guia PIX](/api-reference/guides/pix) |
| PIX em cobrança comercial | `POST /billings/create` com `method: "PIX"` | Boleto/cartão/PIX no mesmo módulo de cobranças comerciais                  |

## Fluxo típico — cobrança avulsa

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

  App->>GoatPay: POST /v1/customers/create (opcional)
  App->>GoatPay: POST /v1/billings/create
  GoatPay-->>App: bankSlipUrl / pixCopyPaste / status
  App->>Pagador: Entregar boleto, PIX ou link
  GoatPay-->>App: webhook payment.paid
  App->>GoatPay: GET /v1/billings/get/:id
```

1. Cadastre o pagador em `/customers/*` ou envie `customer` inline no create.
2. `POST /v1/billings/create` com `method`, `amount` e `customer`.
3. Entregue boleto (`bankSlipUrl`, `digitableLine`), PIX (`pixCopyPaste`) ou confirme cartão.
4. Acompanhe com `GET /v1/billings/get/{id}` ou webhooks.
5. Estorne com `POST /v1/billings/refund` se necessário.

## Fluxo típico — assinatura

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

  App->>GoatPay: POST /v1/subscriptions/create
  GoatPay-->>App: subscriptionId, status ACTIVE
  loop A cada ciclo
    GoatPay-->>App: cobrança gerada + webhooks
  end
  App->>GoatPay: POST /v1/subscriptions/cancel/:id
```

1. `POST /v1/subscriptions/create` com `method`, `amount`, `cycle`, `nextDueDate` e `customer`.
2. Consulte com `GET /v1/subscriptions/get/{id}` ou [liste](/api-reference/endpoint/subscriptions/list) com filtros.
3. Cancele a recorrência com `POST /v1/subscriptions/cancel/{id}`.

<h2 id="clientes">
  Clientes
</h2>

Base de pagadores usada em cobranças e assinaturas. As mesmas rotas servem a [Loja](/api-reference/guides/loja#clientes).

### Rotas

| Método | Rota                       | Permissão          | Documentação                                          |
| ------ | -------------------------- | ------------------ | ----------------------------------------------------- |
| POST   | `/v1/customers/create`     | `customers/create` | [Criar](/api-reference/endpoint/customers/create)     |
| GET    | `/v1/customers/get/:id`    | `customers/get`    | [Consultar](/api-reference/endpoint/customers/get)    |
| GET    | `/v1/customers/list`       | `customers/list`   | [Listar](/api-reference/endpoint/customers/list)      |
| PATCH  | `/v1/customers/update/:id` | `customers/update` | [Atualizar](/api-reference/endpoint/customers/update) |
| DELETE | `/v1/customers/delete/:id` | `customers/delete` | [Excluir](/api-reference/endpoint/customers/delete)   |

No `billings/create` e `subscriptions/create`, o objeto `customer` aceita `name`, `taxId` (CPF ou CNPJ), `email`, `phone` e `id` opcional (referência interna).

<h2 id="cobrancas-avulsas">
  Cobranças avulsas
</h2>

Pagamento **único**: boleto, cartão ou PIX comercial.

### Rotas

| Método | Rota                         | Permissão           | Documentação                                                       |
| ------ | ---------------------------- | ------------------- | ------------------------------------------------------------------ |
| POST   | `/v1/billings/create`        | `billings/create`   | [Criar](/api-reference/endpoint/billings/create)                   |
| POST   | `/v1/billings/tokenize-card` | `billings/tokenize` | [Tokenizar cartão](/api-reference/endpoint/billings/tokenize-card) |
| GET    | `/v1/billings/get/:id`       | `billings/get`      | [Consultar](/api-reference/endpoint/billings/get)                  |
| GET    | `/v1/billings/list`          | `billings/list`     | [Listar](/api-reference/endpoint/billings/list)                    |
| POST   | `/v1/billings/refund`        | `billings/refund`   | [Estornar](/api-reference/endpoint/billings/refund)                |

### Métodos (`method`)

| Valor          | Descrição                                          |
| -------------- | -------------------------------------------------- |
| `BOLETO`       | Boleto bancário com PDF e linha digitável          |
| `CARD_CREDIT`  | Cartão de crédito — veja [Cartão](#cartao)         |
| `CARD_DEBIT`   | Cartão de débito                                   |
| `CARD_VOUCHER` | Voucher / benefício                                |
| `PIX`          | PIX via rota comercial (distinto de `payment-pix`) |

<h3 id="cartao">
  Cartão
</h3>

Fluxo recomendado:

1. **Primeira cobrança:** `POST /billings/create` com `method: "CARD_CREDIT"`, `creditCard`, `creditCardHolderInfo` e `remoteIp` (IP do pagador).
2. **Resposta:** guarde `data.charge.creditCardToken` — é o token para reutilizar.
3. **Próximas cobranças:** envie `cardToken` + `remoteIp` (sem PAN/CVV).
4. **Alternativa:** `POST /billings/tokenize-card` gera o token sem cobrar; depois use `cardToken` no create.

Campos de cartão: `creditCard` (dados do cartão), `creditCardHolderInfo` (titular). O `creditCardToken` retornado é reutilizado como `cardToken` nas próximas cobranças.

<Warning>
  `remoteIp` deve ser o IP do **comprador**, não do seu servidor. Nunca armazene número completo do cartão ou CVV após a transação.
</Warning>

### Status da cobrança

| Status      | Significado          |
| ----------- | -------------------- |
| `PENDING`   | Aguardando pagamento |
| `CONFIRMED` | Confirmado (cartão)  |
| `RECEIVED`  | Pago                 |
| `OVERDUE`   | Vencido              |
| `CANCELED`  | Cancelado            |
| `REFUNDED`  | Estornado            |
| `FAILED`    | Falha                |

Detalhes dos campos de resposta: [Consultar cobrança](/api-reference/endpoint/billings/get).

<h2 id="assinaturas">
  Assinaturas
</h2>

Cobrança **recorrente** com ciclo fixo.

### Rotas

| Método | Rota                           | Permissão              | Documentação                                             |
| ------ | ------------------------------ | ---------------------- | -------------------------------------------------------- |
| POST   | `/v1/subscriptions/create`     | `subscriptions/create` | [Criar](/api-reference/endpoint/subscriptions/create)    |
| GET    | `/v1/subscriptions/list`       | `subscriptions/list`   | [Listar](/api-reference/endpoint/subscriptions/list)     |
| GET    | `/v1/subscriptions/get/:id`    | `subscriptions/get`    | [Consultar](/api-reference/endpoint/subscriptions/get)   |
| POST   | `/v1/subscriptions/cancel/:id` | `subscriptions/cancel` | [Cancelar](/api-reference/endpoint/subscriptions/cancel) |

### Ciclos (`cycle`)

`WEEKLY`, `BIWEEKLY`, `MONTHLY`, `BIMONTHLY`, `QUARTERLY`, `SEMIANNUALLY`, `YEARLY`.

### Métodos

`BOLETO`, `CARD_CREDIT` ou `PIX` — para cartão use o mesmo fluxo de [Cartão](#cartao) (`creditCard` + titular na primeira vez, ou `cardToken` depois).

<h2 id="bureau-de-credito">
  Bureau de crédito
</h2>

Negativação de inadimplentes e consultas de crédito via bureau integrado à GoatPay. Exige conta verificada no trilho **PADRAO**.

### Negativação (dunnings)

Fluxo típico:

1. Tenha uma cobrança em atraso (`billings`) com o devedor cadastrado.
2. Opcional: [Simular](/api-reference/endpoint/serasa/dunnings-simulate) com `?payment={id}` para verificar elegibilidade.
3. [Solicitar negativação](/api-reference/endpoint/serasa/dunnings-create) via `multipart/form-data` (dados do devedor, endereço e documentos).
4. Acompanhe com [Listar](/api-reference/endpoint/serasa/dunnings-list) ou [Consultar](/api-reference/endpoint/serasa/dunnings-get).

| Método | Rota                        | Documentação                                                |
| ------ | --------------------------- | ----------------------------------------------------------- |
| POST   | `/serasa/dunnings/create`   | [Criar](/api-reference/endpoint/serasa/dunnings-create)     |
| GET    | `/serasa/dunnings/list`     | [Listar](/api-reference/endpoint/serasa/dunnings-list)      |
| GET    | `/serasa/dunnings/get/:id`  | [Consultar](/api-reference/endpoint/serasa/dunnings-get)    |
| GET    | `/serasa/dunnings/simulate` | [Simular](/api-reference/endpoint/serasa/dunnings-simulate) |

<Note>
  Taxa de referência para negativação: R\$ 12,90 por solicitação. Campos principais no create: `payment` (ID da cobrança), `type=CREDIT_BUREAU`, dados do devedor e `documents` (arquivo).
</Note>

### Relatórios de crédito

Consulta de crédito por CPF/CNPJ vinculada a um cliente cadastrado.

| Método | Rota                      | Documentação                                            |
| ------ | ------------------------- | ------------------------------------------------------- |
| POST   | `/serasa/reports/create`  | [Criar](/api-reference/endpoint/serasa/reports-create)  |
| GET    | `/serasa/reports/list`    | [Listar](/api-reference/endpoint/serasa/reports-list)   |
| GET    | `/serasa/reports/get/:id` | [Consultar](/api-reference/endpoint/serasa/reports-get) |

Envie `customer` (ID do cliente em `POST /customers/create`) e `cpfCnpj` em `POST /serasa/reports/create`. Taxa de referência: R\$ 19,90.

## Webhooks

Confirme pagamentos sem polling. Eventos relevantes: `payment.created`, `payment.paid`, `payment.refunded`. Veja [Webhooks](/api-reference/guides/webhooks).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Criar cobrança" icon="receipt" href="/api-reference/endpoint/billings/create">
    Boleto, cartão ou PIX (pagamento único).
  </Card>

  <Card title="Listar assinaturas" icon="list" href="/api-reference/endpoint/subscriptions/list">
    Paginação e filtros por status.
  </Card>

  <Card title="Criar assinatura" icon="repeat" href="/api-reference/endpoint/subscriptions/create">
    Plano recorrente com ciclo fixo.
  </Card>

  <Card title="Negativar inadimplente" icon="file-circle-exclamation" href="/api-reference/endpoint/serasa/dunnings-create">
    Bureau de crédito.
  </Card>

  <Card title="Consulta de crédito" icon="magnifying-glass-chart" href="/api-reference/endpoint/serasa/reports-create">
    Relatório de crédito.
  </Card>
</CardGroup>