# Woovi Developers

> Instant payments Docs, APIs, SDKs

This file contains all documentation content in a single document following the llmstxt.org standard.

## Como duplicar uma Conta via api

Este documento irá ajudá-lo a duplicar uma conta usando api.

### 1. Duplicando uma conta bancária

- Utilize o endpoint de conta para duplicar.
- Utilize o AppID da conta que deseja duplicar.
- Faça a requisição.

```json
curl -X POST "https://api.woovi.com/api/v1/account" \
  -H "Authorization: {APP_ID}" \
  -H "Content-Type: application/json" 
```
- Caso tudo ocorra corretamente, um código 200 será retornado.
- No corpo da resposta terá:

```json
{
  "account": {
    "accountId": "6840aeca23c0d1fe48c856a3",
    "taxId": "12.345.678/0001-90",
    "isDefault": true,
    "balance": {
      "total": 0,
      "blocked": 0,
      "available": 0
    }
  }
}
```

OBS: para utilizar esse endpoint é nescessario ter um appId do tipo MASTER
caso não consiga gerar um appId MASTER será nescessario solicitar ativação no suporte

---

## Primeiros passos com a API de Account Limits

Este documento irá ajudá-lo a começar a utilizar a API pública de Account Limits.

## Criando uma nova chave de API

O primeiro passo para começar a integrar com a API é criar uma nova chave de API.

### Passo 1 - Criar um novo aplicativo

Vá para `Api/Plugins` na barra lateral e clique em `Nova API/Plugin`.

:::caution
Caso você não esteja visualizando o sidebar API/Plugins é necessário ter a permissão correta, veja com o admin da sua empresa.
:::

### Passo 2 - Nome da integração

Dentro da tela de criação, coloque um nome para a integração e selecione `API` para integrações backend.

### Passo 3 - Criando a chave

Clique em `Salvar` para criar a nova chave de API.

### Passo 4 - Fator de autenticação

Para que a API possa ser utilizada, é necessário colocar um fator duplo de autenticação para garantir maior segurança na geração de chaves.

### Passo 5 - Copiando as credenciais

Após criar a nova chave, copie o **clientId** e o **clientSecret** para utilizar em suas integrações.

## Como utilizar a API

Todas as `requests` e `responses` da API usam o formato JSON.

A autenticação é feita via **HTTP Basic Auth** usando o `clientId` como usuário e o `clientSecret` como senha. Codifique a combinação `clientId:clientSecret` em base64 e envie no header `Authorization`.

```json
{
  "Authorization": "Basic <base64(clientId:clientSecret)>"
}
```

Exemplo:

```sh
curl -X GET https://api.woovi.com/api/v1/limits/SEU_ACCOUNT_ID \
  -H "Content-Type: application/json" \
  -u "SEU_CLIENT_ID:SEU_CLIENT_SECRET"
```

### Requisitos

- A empresa deve possuir a feature **ACCOUNT_LIMITS_PUBLIC_API** habilitada
- A aplicação deve possuir o scope **`ACCOUNT_LIMITS_GET`**

## Restrições de API

- Todas as requisições devem ser criptografadas usando `https`
- As credenciais de API são extremamente poderosas e devem ser armazenadas com cuidado extra
- Não compartilhe `clientId`/`clientSecret` com terceiros
- Não reutilize chaves entre ambientes
- Apenas gere chaves quando for necessário
- Desative chaves não utilizadas

## Erros de autenticação

Pode ocorrer de você receber uma resposta com o HTTP Status `401`, indicando credenciais ausentes, inválidas ou em formato incorreto. O envelope segue o padrão público da Woovi:

```json
{
  "data": null,
  "errors": [{ "message": "Invalid appID" }]
}
```

Caso sua aplicação não tenha o scope necessário, você receberá HTTP Status `403`:

```json
{
  "error": "Application does not have required scope: ACCOUNT_LIMITS_GET"
}
```

Caso a empresa não tenha a feature `ACCOUNT_LIMITS_PUBLIC_API` habilitada, você receberá HTTP Status `403`:

```json
{
  "error": "API not allowed"
}
```

Caso as credenciais sejam inválidas, é recomendado gerar um novo par de `clientId`/`clientSecret` da sua aplicação e adicionar novamente em seu sistema.

## URL Base

| Ambiente | URL |
|----------|-----|
| Produção | `https://api.woovi.com/api/v1/limits` |

:::tip Referência completa
Para o schema, parâmetros e exemplos interativos do endpoint, veja a [API Reference](/api#tag/account-limits/GET/api/v1/limits/{accountId}).
:::

---

## Como consultar os limites de uma conta via API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para consultar os limites configurados em uma conta bancária do merchant, utilize o _endpoint_ `GET /api/v1/limits/{accountId}`.

O endpoint retorna o conjunto mais recente de limites configurados para a conta, contendo apenas os campos públicos — campos internos são filtrados antes da resposta.

A resposta tem dois blocos: `limits`, com os tetos configurados na conta, e `usage`, com
**quanto de cada teto já foi consumido** na janela em vigor — veja
[Consumo em tempo real](#consumo-em-tempo-real-usage).

:::info
Antes de usar este endpoint, garanta que sua empresa tenha a feature **`ACCOUNT_LIMITS_PUBLIC_API`** habilitada e que sua aplicação possua o scope **`ACCOUNT_LIMITS_GET`**. Veja [Primeiros passos com a API de Account Limits](./api-getting-started.mdx) para detalhes.
:::

:::tip Referência completa
Para o schema, parâmetros e exemplos interativos, veja a [API Reference](/api#tag/account-limits/GET/api/v1/limits/{accountId}).
:::

:::info Precisa de mais limite?
Para pedir aumento pela API — subindo o comprovante e acompanhando até a decisão — veja
[Como solicitar aumento de limite pela API](../apis/api-account-limits-increase-request.md).
:::

## Parâmetros

### Path

- **`accountId`** _(obrigatório)_: Identificador (`ObjectId`) da conta bancária da empresa para a qual os limites serão retornados.

## Exemplo de resposta

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `200` e o `body` da resposta retornará o objeto `limits` com os campos públicos:

```json
{
  "limits": {
    "pixDayLimit": 4000000,
    "pixNightLimit": 100000,
    "pixOutSameHolderDayLimit": 4000000,
    "pixOutDifferentHolderDayLimit": 4000000,
    "pixOutSameHolderNightLimit": 100000,
    "pixOutDifferentHolderNightLimit": 100000,
    "pixInSameHolderDayLimit": 100000000,
    "pixInDifferentHolderDayLimit": 100000000,
    "pixInSameHolderNightLimit": 100000000,
    "pixInDifferentHolderNightLimit": 100000000,
    "dayStartAt": "06:00",
    "nightStartAt": "20:00",
    "boletoEmissionLimit": 200,
    "boletoMaximumValueLimit": 1000000,
    "stableInDayLimit": 500000,
    "stableOutDayLimit": 500000,
    "tedInLimit": 500000,
    "tedOutLimit": 500000
  },
  "usage": { "...": "..." }
}
```

:::info
Todos os valores monetários são expressos em **centavos**. Os horários `dayStartAt`/`nightStartAt` estão no formato `HH:mm`. Campos sem teto configurado não aparecem na resposta.
:::

## Campos da resposta

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `pixDayLimit` | number | Limite total diário Pix (centavos) |
| `pixNightLimit` | number | Limite total noturno Pix (centavos) |
| `pixOutSameHolderDayLimit` | number | Limite diário Pix saída mesmo titular (centavos) |
| `pixOutDifferentHolderDayLimit` | number | Limite diário Pix saída titulares distintos (centavos) |
| `pixOutSameHolderNightLimit` | number | Limite noturno Pix saída mesmo titular (centavos) |
| `pixOutDifferentHolderNightLimit` | number | Limite noturno Pix saída titulares distintos (centavos) |
| `pixInSameHolderDayLimit` | number | Limite diário Pix entrada mesmo titular (centavos) |
| `pixInDifferentHolderDayLimit` | number | Limite diário Pix entrada titulares distintos (centavos) |
| `pixInSameHolderNightLimit` | number | Limite noturno Pix entrada mesmo titular (centavos) |
| `pixInDifferentHolderNightLimit` | number | Limite noturno Pix entrada titulares distintos (centavos) |
| `dayStartAt` | string | Início da janela diurna (`HH:mm`) |
| `nightStartAt` | string | Início da janela noturna (`HH:mm`) |
| `boletoEmissionLimit` | number | Máximo de boletos emitidos por dia |
| `boletoMaximumValueLimit` | number | Valor máximo por boleto emitido (centavos) |
| `stableIn*` / `stableOut*` | number | Limites de compra e venda de stablecoin, diurno/noturno e por transação (centavos) |
| `tedIn*` / `tedOut*` | number | Limites de TED recebida e enviada, total do dia e por transação (centavos) |
| `tedRefundReceived*` / `tedRefundSent*` | number | Limites de devolução de TED recebida e enviada (centavos) |

## Consumo em tempo real (`usage`)

Junto de `limits`, a resposta traz o bloco `usage`: **quanto de cada limite já foi consumido** na
janela em vigor. É o que responde "ainda dá para mandar esse Pix agora?" sem precisar tentar e
tomar a rejeição.

O bloco sai do mesmo documento de limites que alimenta `limits`, somado aos contadores ao vivo —
não há chamada extra a fazer. O teto já vem **resolvido para a janela em vigor** (diurna ou
noturna), então você nunca precisa escolher entre `*DayLimit` e `*NightLimit` na mão.

:::info Compatível com quem já integra
O objeto `limits` não mudou. `usage` é um campo novo ao lado dele, então integrações existentes
continuam funcionando sem alteração.
:::

```json
{
  "limits": { "...": "..." },
  "usage": {
    "window": "DAY",
    "asOf": "2026-01-15T14:00:00-03:00",
    "aggregate": {
      "pixOut": {
        "period": "DAY_WINDOW",
        "totalLimit": 4000000,
        "usedValue": 1250000,
        "availableValue": 2750000,
        "usedPercentage": 31.25,
        "resetsAt": "2026-01-15T20:00:00-03:00"
      },
      "pixOutMonthly": {
        "period": "MONTH",
        "totalLimit": null,
        "usedValue": 500000,
        "availableValue": null,
        "usedPercentage": null,
        "resetsAt": "2026-02-01T00:00:00-03:00"
      },
      "tedOut": {
        "period": "CALENDAR_DAY",
        "totalLimit": 500000,
        "usedValue": 0,
        "availableValue": 500000,
        "usedPercentage": 0,
        "resetsAt": "2026-01-16T00:00:00-03:00"
      },
      "...": "..."
    },
    "perTransaction": {
      "pixOutSameHolder": 4000000,
      "pixOutDifferentHolder": 4000000,
      "boletoMaximumValue": 1000000,
      "...": "..."
    }
  }
}
```

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `window` | string | Janela em vigor para a conta agora: `DAY` ou `NIGHT`. |
| `asOf` | string | Instante em que o retrato foi tirado (ISO-8601, `America/Sao_Paulo`). |
| `aggregate` | object | Os 12 contadores que acumulam gasto na janela. |
| `perTransaction` | object | Os 15 tetos cobrados por transação, que não têm contador. |

### `usage.aggregate` — os contadores que acumulam

São 12: `pixOut`, `pixOutMonthly`, `internalTransferOut`, `internalTransferIn`, `boletoOut`,
`pixRefundSent`, `stableIn`, `stableOut`, `tedIn`, `tedOut`, `tedRefundReceived` e
`tedRefundSent`.

:::note Pix de entrada não aparece aqui
Pix recebido não tem contador acumulado — só teto por transação. Os campos `pixIn*` aparecem em
`usage.perTransaction`, nunca em `usage.aggregate`.
:::

Cada contador tem o mesmo formato:

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `period` | string | Tipo do balde: `DAY_WINDOW`, `CALENDAR_DAY` ou `MONTH` (veja abaixo). |
| `totalLimit` | number \| null | Teto em vigor agora, em centavos, já resolvido para a janela. |
| `usedValue` | number | Quanto já foi consumido no balde atual, em centavos. Sempre um número — `0` quando o contador ainda não foi tocado. |
| `availableValue` | number \| null | `max(totalLimit - usedValue, 0)`, em centavos. |
| `usedPercentage` | number \| null | `usedValue / totalLimit * 100`, arredondado em 2 casas. |
| `resetsAt` | string | Quando esse balde vira (ISO-8601, `America/Sao_Paulo`). |

:::caution `null` e `0` querem dizer coisas diferentes
- **`totalLimit: null`** — não há teto configurado, o fluxo é **ilimitado**. `availableValue` e
  `usedPercentage` também vêm `null`, e `usedValue` continua sendo reportado.
- **`totalLimit: 0`** — o fluxo está **bloqueado**. `availableValue` é `0` (um número, não `null`)
  e `usedPercentage` é `null`, porque não existe razão a expressar.

Não trate os dois como "sem limite": um libera tudo, o outro não deixa passar nada.
:::

`availableValue` **nunca é negativo** — se o teto for reduzido no meio da janela e o consumo já
estiver acima dele, o disponível é `0`, não um número negativo. Já `usedPercentage` **não é travado
em 100**: nesse mesmo caso ele passa de 100, de propósito, para a anomalia continuar visível.

### `period` — quando o contador zera

| `period` | Vira quando | Quem usa |
|----------|-------------|----------|
| `DAY_WINDOW` | Na troca entre as janelas diurna e noturna da conta (`dayStartAt` / `nightStartAt`) | Pix, transferência interna, boleto, devolução de Pix, stablecoin |
| `CALENDAR_DAY` | À meia-noite de Brasília, independente da janela | os quatro contadores de TED |
| `MONTH` | No dia 1º do mês seguinte | `pixOutMonthly` |

`resetsAt` vem do relógio e das janelas configuradas na própria conta — não do TTL de nenhuma
chave interna.

### `usage.perTransaction` — os tetos por transação

São os 15 tetos cobrados sobre **uma** transação, em centavos, já resolvidos para a janela em vigor
(`null` quando não há teto configurado): `pixOutSameHolder`, `pixOutDifferentHolder`,
`pixInSameHolder`, `pixInDifferentHolder`, `internalTransferOut`, `internalTransferIn`,
`boletoOut`, `boletoMaximumValue`, `pixRefundSent`, `stableIn`, `stableOut`, `tedIn`, `tedOut`,
`tedRefundReceived` e `tedRefundSent`.

Eles não têm contador: passar do teto por transação reprova aquele pagamento, sem consumir nada.

### Exemplo: dá para mandar esse Pix agora?

```js
const { usage } = await response.json();

const amount = 150000; // centavos
const { availableValue } = usage.aggregate.pixOut;
const perTransaction = usage.perTransaction.pixOutDifferentHolder;

const fitsInTheDayTotal = availableValue === null || amount <= availableValue;
const fitsInOneTransaction = perTransaction === null || amount <= perTransaction;

if (fitsInTheDayTotal && fitsInOneTransaction) {
  // manda
} else {
  // espera o `usage.aggregate.pixOut.resetsAt` ou peça aumento de limite
}
```

## Códigos de resposta

| Status | Descrição |
|--------|-----------|
| `200` | Limites retornados com sucesso |
| `400` | `accountId` não é um `ObjectId` válido |
| `401` | Credenciais ausentes, malformadas ou inválidas |
| `403` | Aplicação sem o scope `ACCOUNT_LIMITS_GET` ou empresa sem a feature `ACCOUNT_LIMITS_PUBLIC_API` |
| `404` | Conta não pertence à empresa autenticada, ou nenhum limite configurado para a conta |

### Exemplos de erro

```json
{
  "error": "Account ID is invalid"
}
```

```json
{
  "data": null,
  "errors": [{ "message": "Invalid appID" }]
}
```

```json
{
  "error": "Application does not have required scope: ACCOUNT_LIMITS_GET"
}
```

```json
{
  "error": "API not allowed"
}
```

```json
{
  "error": "Account not found"
}
```

```json
{
  "error": "No limits configured for this account"
}
```

## Exemplos em código

  

```sh
curl 'https://api.woovi.com/api/v1/limits/SEU_ACCOUNT_ID' -X GET \
    -H "Accept: application/json" \
    -u "SEU_CLIENT_ID:SEU_CLIENT_SECRET"
```

  
  

```js
const clientId = 'SEU_CLIENT_ID';
const clientSecret = 'SEU_CLIENT_SECRET';
const accountId = 'SEU_ACCOUNT_ID';

const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

const response = await fetch(`https://api.woovi.com/api/v1/limits/${accountId}`, {
  method: 'GET',
  headers: {
    'Authorization': `Basic ${credentials}`,
  },
});

const data = await response.json();

console.log(data.limits.pixDayLimit);
// 4000000

console.log(data.usage.aggregate.pixOut.availableValue);
// 2750000
```

---

## Visão geral da API de Antecipação

A **API de Antecipação** permite que um sistema externo (ERP, folha de pagamento
ou backoffice) cadastre beneficiários e sincronize os saldos antecipáveis de uma
empresa que utiliza o produto de Antecipação da Woovi.

É uma API REST no estilo Woovi: autenticação por `app_id` no cabeçalho
`Authorization`, corpo em JSON, valores monetários **em centavos** e escopos por
funcionalidade.

:::info
Para utilizar esta API é necessário que a empresa possua a funcionalidade de
Antecipação (Pix Out) habilitada. Caso contrário, as requisições retornam `403`.
:::

## Ambiente e URL base

A API de Antecipação usa os mesmos hosts das demais APIs Woovi:

| Ambiente | URL base |
| --- | --- |
| Produção | `https://api.woovi.com` |
| Sandbox (testes) | `https://api.woovi-sandbox.com` |

Todos os endpoints ficam sob o prefixo `/api/v1/anticipation`.

## Autenticação

A autenticação segue o mesmo modelo das demais APIs Woovi: um **App ID** enviado
no cabeçalho `Authorization`.

1. Crie uma aplicação em [app.woovi.com](https://app.woovi.com) e copie o `app_id`.
2. Envie-o no cabeçalho `Authorization` de toda requisição.
3. A empresa é resolvida a partir do `app_id` — você nunca informa o `companyId`.

```sh
Authorization: {SEU_APP_ID}
Content-Type: application/json
```

Além do `app_id`, a autenticação valida:

- **IP allowlist** — se a aplicação tiver lista de IPs configurada, o IP de
  origem precisa estar liberado.
- **Escopo** — a aplicação precisa possuir o escopo exigido pelo endpoint.
- **Funcionalidade** — a empresa precisa ter Antecipação (Pix Out) habilitada.

### Escopos

| Escopo | Permite |
| --- | --- |
| `ANTICIPATION_BENEFICIARY_POST` | Cadastrar, ativar e desativar beneficiários |
| `ANTICIPATION_BALANCE_POST` | Sincronizar saldos de beneficiários em lote |

## Convenções

- **Valores monetários** são sempre inteiros **em centavos** (ex.: `10000` = R$ 100,00).
- **`taxID`** (chave de pagamento do beneficiário) pode ser CPF ou CNPJ, com ou
  sem máscara — os dígitos são normalizados no servidor.
- Datas são retornadas como strings **ISO 8601**.

## Endpoints

| Método | Endpoint | Escopo |
| --- | --- | --- |
| `POST` | `/api/v1/anticipation/beneficiary` | `ANTICIPATION_BENEFICIARY_POST` |
| `POST` | `/api/v1/anticipation/balance/batch` | `ANTICIPATION_BALANCE_POST` |
| `POST` | `/api/v1/anticipation/beneficiary/{taxID}/activate` | `ANTICIPATION_BENEFICIARY_POST` |
| `POST` | `/api/v1/anticipation/beneficiary/{taxID}/deactivate` | `ANTICIPATION_BENEFICIARY_POST` |

Consulte a referência completa na página [API](/api-redoc/) (tag **anticipation**).

## Erros

| Status | Significado |
| --- | --- |
| `400` | Corpo/parâmetros inválidos. Formato: `{ "error": "mensagem" }` |
| `401` | `app_id` inválido ou IP não autorizado. Formato: `{ "data": null, "errors": [{ "message": "Invalid appID" }] }` |
| `403` | Escopo ausente ou Antecipação não habilitada para a empresa. Formato: `{ "error": "mensagem" }` |
| `404` | Beneficiário não encontrado (nas rotas por `taxID`). |
| `409` | Beneficiário já existe para o CPF/CNPJ (no cadastro). |

---

## Como ativar ou desativar um beneficiário via API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Você pode ativar ou desativar um beneficiário pelo seu `taxID` (a chave de
pagamento, CPF ou CNPJ). Um beneficiário **desativado** não consegue solicitar
novas antecipações nem acessar o aplicativo.

Ambos os _endpoints_ exigem o escopo `ANTICIPATION_BENEFICIARY_POST`.

| Ação | Endpoint |
| --- | --- |
| Ativar | `POST /api/v1/anticipation/beneficiary/{taxID}/activate` |
| Desativar | `POST /api/v1/anticipation/beneficiary/{taxID}/deactivate` |

O `{taxID}` pode ir com ou sem máscara — apenas os dígitos são considerados. Se
não existir beneficiário com aquele `taxID` na empresa, a resposta é `404`.

### Exemplos em código

  

```sh
# Desativar
curl 'https://api.woovi.com/api/v1/anticipation/beneficiary/12345678909/deactivate' -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: {SEU_APP_ID}"

# Ativar
curl 'https://api.woovi.com/api/v1/anticipation/beneficiary/12345678909/activate' -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: {SEU_APP_ID}"
```

  
  

```js
const taxID = '12345678909';

fetch(`https://api.woovi.com/api/v1/anticipation/beneficiary/${taxID}/deactivate`, {
  method: 'POST',
  headers: {
    Authorization: '{SEU_APP_ID}',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

  

### Exemplo de resposta

```json
{
  "beneficiary": {
    "name": "João da Silva",
    "taxID": {
      "taxID": "12345678909",
      "type": "BR:CPF"
    },
    "isActive": false,
    "availableAmount": 500000,
    "maxAdvanceableAmount": 350000,
    "notifyEmail": "joao@empresa.com",
    "notifyPhone": "+5511999999999",
    "verified": true,
    "createdAt": "2026-07-15T12:00:00.000Z"
  }
}
```

---

## Como aprovar ou rejeitar uma antecipação via API?

Quando a empresa pagadora exige aprovação, cada antecipação solicitada pelo
beneficiário fica no status `PENDING` **antes da liquidação** (Pix Out). Você
aprova ou rejeita cada solicitação via API antes que o pagamento seja enviado.

| Ação | Endpoint | Escopo |
| --- | --- | --- |
| Listar pendentes | `GET /api/v1/anticipation?status=PENDING` | `anticipation.request.read` |
| Aprovar | `POST /api/v1/anticipation/{id}/approve` | `anticipation.request.approve` |
| Rejeitar | `POST /api/v1/anticipation/{id}/reject` | `anticipation.request.approve` |

O `{id}` é o `id` da antecipação retornado na listagem. Todas as respostas são
escopadas à sua empresa (uma antecipação de outra empresa responde `404`).

## 1. Descubra as solicitações pendentes

Faça _polling_ das solicitações `PENDING` (o `beneficiaryTaxID` ajuda a
reconciliar com o seu sistema):

```sh
curl 'https://api.woovi.com/api/v1/anticipation?status=PENDING' \
    -H "Authorization: {SEU_APP_ID}"
```

### Exemplo de resposta

```json
{
  "anticipations": [
    {
      "id": "6290ccfd42831958a405debc",
      "status": "PENDING",
      "beneficiaryTaxID": "12345678909",
      "requestedAmount": 100000,
      "feeAmount": 7000,
      "netAmount": 93000,
      "feeMode": "PERCENTAGE",
      "monthlyFeePercentage": 7,
      "daysUntilDue": 7,
      "dueDate": "2026-07-25T03:00:00.000Z",
      "approvedAt": null,
      "cancelledAt": null,
      "cancelReason": null,
      "endToEndId": null,
      "failureCode": null,
      "failureReason": null,
      "createdAt": "2026-07-18T11:59:00.000Z"
    }
  ],
  "count": 1
}
```

## 2. Aprove (dispara o Pix Out)

```sh
curl 'https://api.woovi.com/api/v1/anticipation/{id}/approve' -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: {SEU_APP_ID}"
```

Aprovar dispara a liquidação: o status passa a `PROCESSING` e depois a
`CONFIRMED` quando o pagamento é enviado.

### Exemplo de resposta

```json
{
  "anticipation": {
    "id": "6290ccfd42831958a405debc",
    "status": "PROCESSING",
    "beneficiaryTaxID": "12345678909",
    "requestedAmount": 100000,
    "feeAmount": 7000,
    "netAmount": 93000,
    "feeMode": "PERCENTAGE",
    "monthlyFeePercentage": 7,
    "daysUntilDue": 7,
    "dueDate": "2026-07-25T03:00:00.000Z",
    "approvedAt": "2026-07-18T12:00:00.000Z",
    "cancelledAt": null,
    "cancelReason": null,
    "endToEndId": null,
    "failureCode": null,
    "failureReason": null,
    "createdAt": "2026-07-18T11:59:00.000Z"
  }
}
```

## 3. Rejeite (opcionalmente com motivo)

```sh
curl 'https://api.woovi.com/api/v1/anticipation/{id}/reject' -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: {SEU_APP_ID}" \
    -d '{"reason": "acima do limite"}'
```

### Exemplo de resposta

```json
{
  "anticipation": {
    "id": "6290ccfd42831958a405debc",
    "status": "CANCELED",
    "beneficiaryTaxID": "12345678909",
    "requestedAmount": 100000,
    "feeAmount": 7000,
    "netAmount": 93000,
    "feeMode": "PERCENTAGE",
    "monthlyFeePercentage": 7,
    "daysUntilDue": 7,
    "dueDate": "2026-07-25T03:00:00.000Z",
    "approvedAt": null,
    "cancelledAt": "2026-07-18T12:05:00.000Z",
    "cancelReason": "acima do limite",
    "endToEndId": null,
    "failureCode": null,
    "failureReason": null,
    "createdAt": "2026-07-18T11:59:00.000Z"
  }
}
```

## Idempotência e estados

- As duas ações são **idempotentes**: reenviar a mesma decisão retorna `200`
  com o estado atual. Aprovar uma solicitação já aprovada, ou rejeitar uma já
  cancelada, é um _no-op_.
- Uma decisão que conflita com o estado atual (ex.: aprovar uma rejeitada)
  retorna `409`.
- Se você não decidir, a solicitação **expira** automaticamente conforme o
  prazo configurado (`expirationDays`) e é cancelada.

---

## Como cadastrar um beneficiário via API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para cadastrar um beneficiário na Antecipação você utiliza o _endpoint_
`POST /api/v1/anticipation/beneficiary`.

O beneficiário fica vinculado à empresa identificada pelo `app_id` do cabeçalho
`Authorization`. Requer o escopo `ANTICIPATION_BENEFICIARY_POST`.

## Campos do corpo

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `name` | string | Sim | Nome do beneficiário (2 a 120 caracteres). |
| `taxID` | string | Sim | Chave de pagamento (CPF ou CNPJ), com ou sem máscara. |
| `cpf` | string | Condicional | CPF da pessoa. Obrigatório quando `taxID` é um CNPJ. |
| `notifyEmail` | string | Não | E-mail para notificações. |
| `notifyPhone` | string | Não | Telefone para notificações. |
| `availableAmount` | integer | Não | Saldo disponível, em centavos. |
| `maxAdvanceableAmount` | integer | Não | Limite antecipável, em centavos. |
| `autoApprove` | boolean | Não | Sobrescreve a aprovação automática da empresa para este beneficiário. |
| `feeDestinationAccountId` | string | Não | Conta de destino da taxa (sobrescreve a configuração da empresa). |
| `paymentDaysOverride` | integer[] | Não | Dias de pagamento (1–31) específicos deste beneficiário. |
| `frequencyOverride` | object | Não | `{ maxAdvances, periodDays }` — janela de frequência específica. |
| `correlationID` | string | Não | Identificador seu, devolvido na resposta para reconciliação. |

## Idempotência

O `taxID` é único por empresa. Se você reenviar um `taxID` já cadastrado, a API
retorna `409`. Para tornar a chamada idempotente, envie a _query string_
`?return_existing=true`: nesse caso o beneficiário existente é retornado com
`200` em vez de erro.

### Exemplos em código

  

```sh
curl 'https://api.woovi.com/api/v1/anticipation/beneficiary?return_existing=true' -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: {SEU_APP_ID}" \
    -d '{
      "name": "João da Silva",
      "taxID": "12345678909",
      "notifyEmail": "joao@empresa.com",
      "notifyPhone": "+5511999999999",
      "availableAmount": 500000,
      "maxAdvanceableAmount": 350000,
      "correlationID": "erp-benef-42"
    }'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/anticipation/beneficiary?return_existing=true', {
  method: 'POST',
  headers: {
    Authorization: '{SEU_APP_ID}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'João da Silva',
    taxID: '12345678909',
    notifyEmail: 'joao@empresa.com',
    notifyPhone: '+5511999999999',
    availableAmount: 500000,
    maxAdvanceableAmount: 350000,
    correlationID: 'erp-benef-42',
  }),
}).then((res) => res.json());
```

  

### Exemplo de resposta

```json
{
  "beneficiary": {
    "name": "João da Silva",
    "taxID": {
      "taxID": "12345678909",
      "type": "BR:CPF"
    },
    "isActive": true,
    "availableAmount": 500000,
    "maxAdvanceableAmount": 350000,
    "notifyEmail": "joao@empresa.com",
    "notifyPhone": "+5511999999999",
    "verified": false,
    "createdAt": "2026-07-15T12:00:00.000Z"
  },
  "correlationID": "erp-benef-42"
}
```

:::note
`type` é `BR:CPF` ou `BR:CNPJ`. `verified` indica se o beneficiário já concluiu a
verificação de identidade (pix-auth) no aplicativo.
:::

---

## Como sincronizar saldos de beneficiários em lote via API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para atualizar os saldos antecipáveis de vários beneficiários de uma vez — o caso
típico é a carga noturna vinda da folha de pagamento — use o _endpoint_
`POST /api/v1/anticipation/balance/batch`.

Requer o escopo `ANTICIPATION_BALANCE_POST`.

## Como funciona

- O valor é um **set absoluto**: `availableAmount` e `maxAdvanceableAmount`
  passam a valer exatamente o que você enviar (não é incremento). Por isso a
  operação é naturalmente idempotente — reenviar o mesmo lote é seguro.
- Cada lote aceita no **máximo 1000 itens**.
- Falhas parciais **não** abortam o lote: a resposta traz um relatório por item
  para você reconciliar no ERP.

## Campos do corpo

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `items` | array | Sim | Lista de itens (1 a 1000). |
| `items[].taxID` | string | Sim | Chave de pagamento (CPF ou CNPJ) do beneficiário. |
| `items[].availableAmount` | integer | Sim | Saldo disponível, em centavos (≥ 0). |
| `items[].maxAdvanceableAmount` | integer | Sim | Limite antecipável, em centavos (≥ 0, ≤ `availableAmount`). |

:::caution
Regras de validação por item: `taxID` obrigatório, valores inteiros não
negativos e `maxAdvanceableAmount` não pode exceder `availableAmount`. Itens que
violem qualquer regra — ou cujo beneficiário não exista na empresa — retornam
`ok: false` com o motivo, sem afetar os demais.
:::

### Exemplos em código

  

```sh
curl 'https://api.woovi.com/api/v1/anticipation/balance/batch' -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: {SEU_APP_ID}" \
    -d '{
      "items": [
        { "taxID": "12345678909", "availableAmount": 500000, "maxAdvanceableAmount": 350000 },
        { "taxID": "98765432100", "availableAmount": 120000, "maxAdvanceableAmount": 120000 }
      ]
    }'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/anticipation/balance/batch', {
  method: 'POST',
  headers: {
    Authorization: '{SEU_APP_ID}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      { taxID: '12345678909', availableAmount: 500000, maxAdvanceableAmount: 350000 },
      { taxID: '98765432100', availableAmount: 120000, maxAdvanceableAmount: 120000 },
    ],
  }),
}).then((res) => res.json());
```

  

### Exemplo de resposta

```json
{
  "processed": 2,
  "succeeded": 1,
  "failed": 1,
  "results": [
    { "taxID": "12345678909", "ok": true },
    { "taxID": "98765432100", "ok": false, "error": "beneficiary not found" }
  ]
}
```

O beneficiário precisa já estar cadastrado (veja
[Cadastrar beneficiário](./how-to-register-a-beneficiary-using-api.mdx)); itens
apontando para um `taxID` inexistente na empresa voltam com
`error: "beneficiary not found"`.

---

## Como solicitar aumento de limite pela API

Aumentar o limite de uma conta deixou de ser um pedido manual pelo console: dá para abrir a
solicitação pela API, anexar o comprovante que a justifica e acompanhar até a decisão.

São **dois endpoints**, e a ordem importa:

1. **`POST /api/v1/files`** — sobe o comprovante e devolve um `file.id`.
2. **`POST /api/v1/limits/request`** — abre o pedido mandando esse `file.id`.

Depois é só fazer _polling_ no `GET /api/v1/limits/request/{limitRequestId}` até o `status`
sair de `IN_REVIEW`.

:::caution O documento **não** vai no corpo do pedido
Um erro comum é tentar mandar o arquivo (ou uma URL dele) direto no `POST /api/v1/limits/request`.
Não funciona: o pedido só aceita o `fileId` de um arquivo que já está na Woovi. Suba o arquivo
primeiro.
:::

## Requisitos

Seu AppID precisa de três escopos ([como adicionar escopos](./api-scopes.md)):

| Escopo | Para quê |
| --- | --- |
| `FILE_POST` | subir o comprovante no endpoint de arquivos |
| `ACCOUNT_LIMITS_REQUEST_POST` | abrir o pedido de aumento |
| `ACCOUNT_LIMITS_GET` | consultar o limite atual e fazer o _polling_ do pedido |

## 1. Subir o comprovante

O arquivo vai como `multipart/form-data` no campo `file`, com **`purpose=ACCOUNT_LIMIT_REQUEST`**.
Aceita `application/pdf`, `image/png`, `image/jpeg` e `image/webp`, até 10 MiB por arquivo
(detalhes em [Como fazer upload de um arquivo](../arquivos/upload-de-arquivo.md)).

```bash
curl -X POST "https://api.woovi.com/api/v1/files" \
  -H "Authorization: <appID>" \
  -F "file=@faturamento.pdf" \
  -F "purpose=ACCOUNT_LIMIT_REQUEST"
```

```json
{
  "file": {
    "id": "68c7d0a1f0b2c3d4e5f60718",
    "correlationID": "3fa17751-d522-426d-8425-80a3ef65d622",
    "purpose": "ACCOUNT_LIMIT_REQUEST",
    "fileName": "faturamento.pdf",
    "contentType": "application/pdf",
    "size": 20480,
    "url": "https://woovi-files.s3.amazonaws.com/...",
    "urlExpiresAt": "2026-09-03T18:04:45.987Z",
    "createdAt": "2026-09-03T17:49:45.968Z"
  }
}
```

Guarde o **`file.id`** — é ele que vai no passo 2.

:::tip
O `purpose` importa. Um arquivo subido com outro `purpose` (por exemplo `DISPUTE_EVIDENCE`)
**não** é aceito no pedido de limite. Se isso acontecer, suba de novo com o `purpose` certo;
não é preciso apagar o primeiro.
:::

## 2. Consultar o limite atual

O pedido usa o mesmo vocabulário de campos do
[`GET /api/v1/limits/{accountId}`](../account-limits/api-limits-get.mdx), então o caminho
natural é ler o limite atual, subir os campos que você precisa e mandar de volta.

```bash
curl "https://api.woovi.com/api/v1/limits/6842ef6d05629d74e34d05cd" \
  -H "Authorization: <appID>"
```

```json
{ "limits": { "pixDayLimit": 4000000, "pixNightLimit": 100000, "...": "..." } }
```

## 3. Abrir o pedido com o `fileId`

```bash
curl -X POST "https://api.woovi.com/api/v1/limits/request" \
  -H "Authorization: <appID>" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "companyBankAccountId": "6842ef6d05629d74e34d05cd",
    "pixDayLimit": 5000000,
    "pixNightLimit": 200000,
    "documents": [{ "fileId": "68c7d0a1f0b2c3d4e5f60718" }],
    "description": "faturamento dos ultimos 12 meses"
  }'
```

| Campo | Obrigatório | Descrição |
| --- | --- | --- |
| `companyBankAccountId` | Sim | A conta cujo limite deve subir. |
| `pixDayLimit` / `pixNightLimit` | Sim | Limite diurno e noturno pedidos, **em centavos**. |
| `pixOut*` / `pixIn*` por titularidade | Não | Os oito campos por titularidade, com os mesmos nomes do `GET` de limites. |
| `documents` | Sim | De 1 a 10 itens, cada um com o `fileId` do passo 1. |
| `description` | Não | Texto livre para o analista que vai revisar. |
| `limitRequestReason` | Não | Motivo do pedido. |

Resposta `201`:

```json
{
  "limitRequest": {
    "id": "68c7d0a1f0b2c3d4e5f6071a",
    "companyBankAccountId": "6842ef6d05629d74e34d05cd",
    "status": "IN_REVIEW",
    "requestedLimits": { "pixDayLimit": 5000000, "pixNightLimit": 200000 },
    "documents": [{ "fileName": "faturamento.pdf", "contentType": "application/pdf" }],
    "description": "faturamento dos ultimos 12 meses",
    "createdAt": "2026-09-03T17:49:59.204Z",
    "updatedAt": "2026-09-03T17:49:59.204Z"
  }
}
```

Guarde o **`limitRequest.id`** para acompanhar o pedido.

### Regras que o pedido precisa respeitar

- Nenhum campo pode vir **abaixo** do valor atual da conta.
- Pelo menos um campo precisa vir **acima** do atual — um pedido que não sobe nada é recusado.
- Só pode existir **um pedido `IN_REVIEW` por conta** de cada vez.

## 4. Acompanhar até a decisão

```bash
curl "https://api.woovi.com/api/v1/limits/request/68c7d0a1f0b2c3d4e5f6071a" \
  -H "Authorization: <appID>"
```

O `status` fica em `IN_REVIEW` enquanto a Woovi analisa, e depois vira:

- **`APPROVED`** — o campo `approvedLimits` traz o que foi de fato concedido, que **pode ser
  menor do que você pediu**. Os limites efetivos da conta mudam no mesmo momento, então o
  `GET /api/v1/limits/{accountId}` já reflete os novos valores.
- **`REJECTED`** — nada mudou na conta. Depois que o pedido é decidido, você pode abrir um novo.

```json
{
  "limitRequest": {
    "id": "68c7d0a1f0b2c3d4e5f6071a",
    "status": "APPROVED",
    "requestedLimits": { "pixDayLimit": 5000000, "pixNightLimit": 200000 },
    "approvedLimits": { "pixDayLimit": 4500000, "pixNightLimit": 200000 },
    "documents": [{ "fileName": "faturamento.pdf", "contentType": "application/pdf" }],
    "createdAt": "2026-09-03T17:49:59.204Z",
    "updatedAt": "2026-09-03T19:12:03.881Z"
  }
}
```

:::info
`approvedLimits` **não aparece** enquanto o pedido está `IN_REVIEW`. A ausência do campo é a
forma de saber que ainda não há decisão — não trate `approvedLimits` vazio como aprovação.
:::

Para listar todos os pedidos da sua empresa, do mais novo para o mais antigo, use
`GET /api/v1/limits/request` (aceita `limit`, máximo 100, e `skip`).

## Erros

| Status | Quando acontece | Corpo |
| --- | --- | --- |
| `400` | O `fileId` não existe, é de **outra empresa**, ou foi subido com outro `purpose` | `{"error":"Document 68c7…: File not found"}` |
| `400` | Algum limite veio abaixo do valor atual | `{"error":"Requested limit cannot be less than the current value"}` |
| `400` | Nenhum limite é maior que o atual | `{"error":"At least one limit must be greater than the current value"}` |
| `400` | Nenhum documento enviado | `{"error":"documents At least one document is required"}` |
| `403` | O AppID não tem o escopo `ACCOUNT_LIMITS_REQUEST_POST` | `{"error":"Application does not have required scope: ACCOUNT_LIMITS_REQUEST_POST"}` |
| `404` | A conta não existe **ou é de outra empresa** | `{"error":"Account not found"}` |
| `409` | A conta já tem um pedido em análise | `{"error":"Limit request already in review"}` |

:::caution Isolamento entre empresas
Tanto a conta quanto o arquivo são sempre filtrados pela empresa do seu AppID. Uma conta de
outra empresa responde `404` (nunca um `403`), e um `fileId` de outra empresa responde `400`
`File not found` — o id sozinho nunca confirma que o recurso existe.
:::

:::tip Referência completa
Schemas, parâmetros e exemplos interativos na
[API Reference, em **Account Limits**](/api#tag/account-limits).
:::

---

## Changelog da API

Registro datado das mudanças relevantes da API pública. Mudanças **aditivas** (novos
endpoints, campos ou parâmetros opcionais) são compatíveis e não exigem ação. Depreciações e
remoções seguem a [Política de Versionamento e Depreciação](./api-versioning-deprecation),
com anúncio prévio e prazo de _sunset_.

Tipos: **Adicionado** · **Alterado** · **Depreciado** · **Removido**.

## 2026-09

- **Adicionado** — `GET /api/v1/subscriptions/{id}/payment-book`, que emite as cobranças
  das parcelas de uma assinatura `RECURRENT` até o mês/ano informados e devolve o carnê
  em PDF (`application/pdf`). `month` e `year` são obrigatórios e vão no máximo até o
  final do ano que vem. **A chamada cria cobranças** — com `chargeType: BOLETO` cada uma
  é um boleto registrado — e é idempotente por parcela, então repetir não cobra de novo.
  Exige o escopo `SUBSCRIPTION_PAYMENT_BOOK_GET`. Veja
  [Como gerar carnê de assinatura usando a API?](../subscription-recurrence/subscription-payment-book-api.mdx).

## 2026-08

- **Adicionado** — campo opcional `fileId` nos itens de `documents` em
  `POST /api/v1/dispute/{id}/evidence`, apontando para um arquivo já enviado em
  `POST /api/v1/files` com `purpose` `DISPUTE_EVIDENCE`. Envie `url` ou `fileId`, não os
  dois. Exige a feature `DISPUTE_EVIDENCE_FILE_ID`; sem ela a resposta é `403` com
  `errorCode` `DISPUTE_EVIDENCE_FILE_ID_NOT_ALLOWED`. Veja
  [Como adicionar uma nova evidência em uma disputa?](../disputa/how-add-new-evidence-in-evidence.md).
- **Adicionado** — `POST /api/v1/files`, que armazena um arquivo e devolve seus metadados
  com uma URL de download temporária, para uso em outras APIs da Woovi. Exige o escopo
  `FILE_POST`. Veja [Como fazer upload de um arquivo?](../arquivos/upload-de-arquivo.md).
- **Adicionado** — query string opcional `companyBankAccount` em
  `GET /api/v1/statement` e `GET /api/v1/transaction/{id}`. Uma aplicação `MASTER` de
  uma empresa com a feature `MASTER_APP_READ_ANY_ACCOUNT` lê o extrato e a transação de
  outra conta da mesma empresa, sem criar um AppId por conta. Veja
  [Controlando as contas no modo BAAS](../baas/baas-api-master.md).
- **Adicionado** — `GET /api/v1/application/scopes`, que lista os grupos de escopos que uma
  aplicação pode solicitar. Não exige escopo.
- **Adicionado** — `POST /api/v1/application/rotate-secret`, que gera um novo `clientSecret`
  para uma aplicação da mesma empresa. Exige o escopo `APPLICATION_ROTATE_POST` e uma
  aplicação `MASTER`.

## 2026-04

- **Removido** — endpoints de _account register_ (`POST`/`PATCH`), previamente depreciados,
  foram removidos do contrato público após o período de depreciação.

## 2026-02

- **Adicionado** — bloqueio de saque em subconta (_subaccount withdraw block_).

---

> Este changelog passa a ser mantido de forma contínua. Mudanças aditivas entram como
> **Adicionado**; qualquer depreciação será anunciada aqui **com data de _sunset_** antes do
> desligamento, conforme a política.

---

## Campos Comum

Este documento irá ajudá-lo a entender como alguns campos retornados pela API funcionam.

### taxID

Os campos de taxID retornam um objeto com duas chaves, `type` e `taxID`:

```ts
taxID: {
  type: string,
  taxID: string,
}
```

O campo de `type` significa o tipo daquele `taxID`, como por exemplo `BR:CNPJ` ou `BR:CPF`, ja o campo de `taxID` dentro do objeto refere ao valor do documento em si.

### value

Os campos de `value` quando dentro do contexto de fundos monetários, sempre retornam o valor em **centavos**, por exemplo:

```ts
value: 1000;
```

Isso significa que o valor equivale a **R$10,00**.

---

## Explorador de API

import BrowserOnly from '@docusaurus/BrowserOnly';
import ApiExplorer from '@site/src/components/ApiExplorer/ApiExplorer';

# Explorador de endpoints da API

Selecione um endpoint na barra lateral, escolha entre **Request** e **Response**, e copie o payload em **JSON**, **TypeScript types**, **JSON Schema**, **Yup** ou **Zod**.
Os tipos e schemas são inferidos automaticamente a partir dos exemplos da [especificação OpenAPI](/api-redoc/).

  {() => }

---

## Começando

Este documento irá ajudá-lo a começar a utilizar as APIs e Plugins da Woovi.
## Criando uma nova chave de API/Plugin

O primeiro passo para começar a integrar com a API é criar uma nova chave de API, para que possa ser feitas as requisições.

### Passo 1 - Criar um novo aplicativo

Vá para `Api/Plugins` na barra lateral e clique em `Nova API/Plugin`.

:::caution
Caso você não esteja visualizando o sidebar API/Plugins é necessário ter a permissão correta, veja com o admin da sua empresa.
:::

![appid-1](./__assets__/api-plugins.png)

### Passo 2 - Nome da integração

Dentro da tela de criação, coloque um nome para a integração, e selecione `API` para integrações backend, ou `Plugin` para integrações frontend.

![appid-2](./__assets__/new-api-plugin.png)

### Passo 3 - Criando uma nova chave de API/Plugin

Clique em `Salvar` para criar a nova chave de API/Plugin.

![appid-3](./__assets__/save-new-api.png)

### Passo 4 - Colocando o fator de autenticação

Para que a API/Plugin possa ser utilizada, é necessário colocar um fator duplo de autenticação para garantir maior segurança na geração de chaves.

![appid-4](./__assets__/token-new-api.png)

### Passo 5 - Copiando o AppID

Após criar a nova chave de API/Plugin, você pode copiar o AppID para utilizar em suas integrações.

![appid-5](./__assets__/copy-appid-new-api.png)

## Como utilizar a API

Todas as `requests` e `responses` da API usam o formato JSON

Para que a requisição seja válida, é necessário enviar o `AppID`/`Token` no header `Authorization` da requisição.

Não utilize o prefixo `Bearer`. Envie o valor bruto do `AppID` no header.

```json
{
  "Authorization": "<AppID>"
}
```

Exemplo:

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/charge \
  --header 'Authorization: SEU_APPID_AQUI'
```

## Restrições de APIs

Os IPs e certificados dos servidores backend da API mudam constantemente, não armazene em cache nem IPs do servidor nem certificados

Todas as solicitações (requests) devem ser criptografadas usando `https`

As chaves de API são extremamente poderosas, pois podem criar ou ler dados de sua empresa, e devem ser armazenadas e compartilhadas com cuidado extra.

Orientações da API:

- Não compartilhe chaves com terceiros
- Não reutilize chaves - Chaves de acessos, você pode gerar várias chaves
- Apenas gere chaves quando for necessário
- Desative chaves não utilizadas

## AppID Inválido

Pode ocorrer de você receber uma resposta com o HTTP Status 401, que está relacionado à um appID inválido, sendo passado no header mencionado acima.

```json
{
  "data": null,
  "errors": [
    {
      "message": "appID inválido"
    }
  ]
}
```

Caso seja inválido é retornado esse erro caso seja de appID inválido.

Caso você obtenha esse erro, é recomendado gerar um novo appID dá sua aplicação, ou regerar o appID, caso já tenha uma aplicação criada, e adicionar novamente em seu sistema.

---

## Criando um API MASTER

### 1. Para criar uma nova API MASTER

Vá para `Api/Plugins` na barra lateral e clique em `Nova API/Plugin`.

:::caution
Caso você não esteja visualizando o sidebar API/Plugins é necessário ter a permissão correta, veja com o admin da sua empresa. E é necessário ter a permissão correta para criar esta api.
:::

![appid-1](./__assets__/api-plugins.png)

![appid-2](./__assets__/new-api-plugin.png)

### 2. Coloque o tipo de API como **MASTER**.
![appid-3](./__assets__/master-api.png)

- Coloque o tipo de API como MASTER.
- Selecione a Conta Bancaria Woovi IP principal.

### 3. Crie a nova API MASTER
- A API precisa ser do tipo MASTER porquê ela precisa ser capaz de criar novas integrações.
- A conta bancária relacionada a essa API será utilizada no processo de criação das novas contas bancárias, elas usarão os dados desta para serem criadas.

### 4. Coloque o código de validação
![appid-4](./__assets__/validation.png)

- Esse AppID deve ser armazenado de forma **segura** em sua base de dados.  
- Ele será a **chave principal** enviada em toda requisição de criação de nova conta bancária.

---

## Começando Campanha Usando Chave Pix

### 1 Crie uma nova API

Vá para `Api/Plugins` na barra lateral e clique em `Nova API/Plugin`.

:::caution
Caso você não esteja visualizando o sidebar API/Plugins é necessário ter a permissão correta, veja com o admin da sua empresa.
:::

:::info
Atenção: Somente para clientes BaaS.
:::

![appid-1](./__assets__/api-plugins.png)

![appid-2](./__assets__/new-api-plugin.png)

### 2. Coloque o tipo de API como **MASTER**.
![appid-3](./__assets__/master-api.png)

- Coloque o tipo de API como MASTER.
- Selecione a Conta Bancaria Woovi IP principal.

### 3. Crie a nova API MASTER
- A API precisa ser do tipo MASTER porquê ela precisa ser capaz de criar novas integrações.
- A conta bancária relacionada a essa API será utilizada no processo de criação das novas contas bancárias, elas usarão os dados desta para serem criadas.

### 4. Coloque o código de validação
![appid-4](./__assets__/validation.png)

- Esse AppID deve ser armazenado de forma **segura** em sua base de dados.  
- Ele será a **chave principal** enviada em toda requisição de criação de nova conta bancária.

## Sequência da integração 
![sequence](./__assets__/sequence-integration.png)

## Como começar uma nova campanha?
- Crie uma nova conta bancária usando o AppID da conta principal.
- Armazene o accountId retornado pela requisição de criação de conta bancária.
- Crie uma nova aplicação utilizando o accountId retornado na última requisição.
- Armazene o AppID relacionado a essa conta. Você usará ele para pegar o saldo de uma campanha.
- Crie uma nova chave pix utilizando o AppID da conta que deseja.
- Cada conta bancária tem um saldo, então é recomendado que crie uma nova conta bancária para cada campanha.

### 1. Criando uma conta bancária

- Utilize o endpoint de criação de conta bancária para criar uma nova conta.
- Utilize o AppID da conta principal, o criado no slide 7.
- Faça a requisição.

```json
curl -X POST "https://api.woovi.com/api/v1/account" \
  -H "Authorization: {APP_ID}" \
  -H "Content-Type: application/json" 
```
- Caso tudo ocorra corretamente, um código 200 será retornado.
- No corpo da resposta terá:

```json
{
  "account": {
    "accountId": "6840aeca23c0d1fe48c856a3",
    "taxId": "12.345.678/0001-90",
    "isDefault": true,
    "balance": {
      "total": 0,
      "blocked": 0,
      "available": 0
    }
  }
}
```

### 2. Criando uma Aplicação

- Utilize o endpoint de criação de aplicação.
- A aplicação será a chave que será utilizada para acessar os dados de uma conta bancária específica.
- Utilize o AppID retornado pelo último endpoint, para relacioná-lo com a nova conta bancária.

```json
curl -X POST "https://api.woovi.com/api/v1/application" \
  -H "Authorization: {{BANK_ACCOUNT_APP_ID}}" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "{{ACCOUNT_ID}}",
    "application": {
      "name": "My Test Application",
      "type": "API"
    }
  }'
```

- O retorno do endpoint de criação de uma aplicação, se tudo ocorrer bem, será um código 201.
- No corpo da resposta conterá:
```json
{
  "application": {
    "name": "My Test Application",
    "isActive": true,
    "type": "API",
    "clientId": "client_123abc",
    "clientSecret": "secret_456def",
    "appID": {{APPLICATION_APP_ID}},
    "companyBankAccount": "{{ACCOUNT_ID}}"
  }
}
```

### 3. Criando uma Chave Pix

- Utilize o endpoint de criação de chave pix.
- Utilize o AppID retornado pelo último endpoint, para criar a chave pix naquela conta específica.

```json
curl -X POST "https://api.woovi.com/api/v1/pix-keys" \
  -H "Authorization: {{APPLICATION_APP_ID}}" \
  -H "Content-Type: application/json" \
  -d '{
    "pixKey": "campanha@woovi.com",
    "type": "EMAIL"
  }'
```

- Se tudo ocorrer bem, o código de retorno será 201.
- O retorno serão os dados daquela chave pix criada.
```json
{
  "pixKey": {
    "key": "campanha@woovi.com",
    "type": "EMAIL"
  }
}
```
- Com esse fluxo, já será possível criar novas campanhas com suas respectivas chaves pix.
- Ainda temos endpoints que permitem a visualização do saldo, as informações de uma conta e as chaves pix atreladas a ela.

### 4. Consultando Chaves Pix

- Utilize o AppID da conta bancária que você quer consultar.
```json
curl -X GET "https://api.woovi.com/api/v1/pix-keys" \
  -H "Authorization: {{APPLICATION_APP_ID}}"
```

- O retorno terá status 200.
- O corpo da resposta será:
```json
{
  "pixKeys": [
    {
      "key": "teste-woovi@woovi.com",
      "type": "EMAIL"
    },
    {
      "key": "random-evp-key",
      "type": "EVP"
    }
  ],
  "account": {
    "accountId": "6840aeca23c0d1fe48c856a3",
    "isDefault": true,
    "balance": {
      "total": 100000,
      "blocked": 0,
      "available": 100000
    }
  }
}
```

### 5. Deletando Chaves Pix
- Caso uma campanha chegue ao fim, apagar a chave pix garantirá que nenhum dinheiro seja mandado a ela novamente.
- Existe um endpoint que permite que uma chave pix seja deletada.
- Utilize o AppID da conta que está atrelada a chave pix.
- O retorno será um código 204, se tudo ocorrer bem.

```json
curl -X DELETE "https://api.woovi.com/api/v1/pix-keys/{{PIX_KEY_VALUE}}" \
  -H "Authorization: {{APPLICATION_APP_ID}}"
```

---

## Postman

Você também pode testar a API usando [Woovi Postman](pathname:///openpixPostman.json)

---

## Exemplos

Aqui, temos 2 exemplos de como integrar a API Woovi em seu backend. Ele demonstra o seguinte:
- como criar uma nova cobrança
- como registrar um webhook
- como lidar com o webhook recebido para atualizar o status de cobrança

[Integração Node Backend](https://github.com/Open-Pix/node-backend-integration)

[Integração Frontend](https://github.com/Open-Pix/frontend-integration)

---

## Adicionando escopos ao seu AppID

Para aumentar a segurança das suas integrações, você pode restringir um AppID para que ele tenha acesso apenas às rotas da API que ele realmente precisa, atribuindo **escopos** (scopes) a ele.

Um AppID com escopos definidos só consegue acessar os endpoints liberados para o(s) escopo(s) atribuído(s). Por exemplo, ao atribuir apenas o escopo `CHARGE_POST` a um AppID, ele poderá exclusivamente criar cobranças, e nada mais.

É possível atribuir múltiplos escopos a um mesmo AppID conforme a necessidade da sua integração.

## Adicionando escopos ao criar uma nova API/Plugin

Ao criar uma nova API ou Plugin (veja o passo a passo em [Primeiros Passos](./api-getting-started.md)), você pode selecionar os escopos desejados durante o fluxo de criação, antes de confirmar a geração do AppID.

## Adicionando escopos a um AppID já existente

Você também pode editar os escopos de uma API/Plugin já criada. Para isso, acesse os detalhes da API na [lista de APIs](https://app.woovi.com.br/home/applications/tab/list) e adicione ou remova os escopos desejados.

:::caution
Caso nenhum escopo seja definido, o AppID mantém acesso completo a todas as rotas liberadas para o tipo de API/Plugin escolhido.
:::

## Catálogo de escopos disponíveis

Os escopos abaixo estão organizados por recurso:

### ACCOUNT

- `ACCOUNT_GET`
- `ACCOUNT_GET_LIST`
- `ACCOUNT_POST`
- `ACCOUNT_DELETE`
- `ACCOUNT_WITHDRAW_POST`

### ACCOUNT_LIMITS

- `ACCOUNT_LIMITS_GET`
- `ACCOUNT_LIMITS_REQUEST_POST`

### ACCOUNT_REGISTER

- `ACCOUNT_REGISTER_POST`
- `ACCOUNT_REGISTER_PATCH`
- `ACCOUNT_REGISTER_GET`
- `ACCOUNT_REGISTER_DELETE`
- `ACCOUNT_REGISTER_UNLOCKED_POST`

### APPLICATION

- `APPLICATION_POST`
- `APPLICATION_DELETE`
- `APPLICATION_ROTATE_POST`

### AUTH

- `TOKEN_VALIDATE_GET`

### CASHBACK_FIDELITY

- `CASHBACK_FIDELITY_BALANCE_GET`
- `CASHBACK_FIDELITY_POST`

### CHARGE

- `CHARGE_GET`
- `CHARGE_GET_LIST`
- `CHARGE_POST`
- `CHARGE_PATCH`
- `CHARGE_DELETE`
- `CHARGE_BRCODE_IMAGE_GET`
- `CHARGE_IMAGE_GET`

### CHARGE_REFUND

- `CHARGE_REFUND_GET_LIST`
- `CHARGE_REFUND_POST`

### COMPANY

- `COMPANY_GET`

### CUSTOMER

- `CUSTOMER_GET`
- `CUSTOMER_GET_LIST`
- `CUSTOMER_POST`
- `CUSTOMER_PATCH`

### DECODE

- `DECODE_EMV_POST`

### DISPUTE

- `DISPUTE_POST`
- `DISPUTE_GET`
- `DISPUTE_GET_LIST`

### FILE

- `FILE_POST`

### GIFTBACK

- `GIFTBACK_BALANCE_GET`

### PARTNER

- `PARTNER_COMPANY_POST`
- `PARTNER_COMPANY_GET`
- `PARTNER_COMPANY_GET_LIST`
- `PARTNER_APPLICATION_POST`

### PAYMENT

- `PAYMENT_GET`
- `PAYMENT_GET_LIST`
- `PAYMENT_POST`
- `PAYMENT_APPROVE_POST`

### PIX_QRCODE

- `PIX_QRCODE_GET`
- `PIX_QRCODE_GET_LIST`
- `PIX_QRCODE_POST`
- `PIX_QRCODE_DELETE`

### PSP

- `PSP_GET_LIST`

### REFUND

- `REFUND_GET`
- `REFUND_GET_LIST`
- `REFUND_POST`

### STATEMENT

- `STATEMENT_GET`

### SUBACCOUNT

- `SUBACCOUNT_GET`
- `SUBACCOUNT_GET_LIST`
- `SUBACCOUNT_POST`
- `SUBACCOUNT_WITHDRAW_POST`
- `SUBACCOUNT_TRANSFER_POST`
- `SUBACCOUNT_DELETE`
- `SUBACCOUNT_DEBIT_POST`

### SUBSCRIPTION

- `SUBSCRIPTION_GET`
- `SUBSCRIPTION_GET_LIST`
- `SUBSCRIPTION_POST`
- `SUBSCRIPTION_VALUE_PUT`
- `SUBSCRIPTION_CANCEL_PUT`
- `SUBSCRIPTION_INSTALLMENT_GET_LIST`
- `SUBSCRIPTION_INSTALLMENT_GET`
- `SUBSCRIPTION_INSTALLMENT_COBR_POST`
- `SUBSCRIPTION_INSTALLMENT_COBR_RETRY_POST`
- `SUBSCRIPTION_PAYMENT_BOOK_GET`

### TRANSACTION

- `TRANSACTION_GET`
- `TRANSACTION_GET_LIST`

### TRANSFER

- `TRANSFER_POST`

### WEBHOOK

- `WEBHOOK_GET`
- `WEBHOOK_GET_LIST`
- `WEBHOOK_POST`
- `WEBHOOK_DELETE`
- `WEBHOOK_IPS_GET`
- `WEBHOOK_EVENTS_GET_LIST`
- `WEBHOOK_TOGGLE_ACTIVATION_GET`

:::info
Artigo Original [https://ajuda.woovi.com/hc/duvidas-frequentes/articles/1769459329-adicionado-escopos-no-app_id](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/1769459329-adicionado-escopos-no-app_id)
:::

---

## Adicionando filtro de IP à sua API

Como forma de garantir uma melhor segurança no uso da sua API, você pode adicionar uma lista de permissões de IP à sua API.
Assim, apenas os IPs que estão na lista de permissões poderão acessar sua API.

Vamos ver como você pode adicionar uma lista de permissões de IP à sua API.

## Adicionando uma lista de permissões de IP à sua API

Primeiramente, como um requisito, você precisa ter uma API criada.
Se você ainda não criou uma API, pode seguir os passos no guia [Primeiros Passos](./api-getting-started.md).

Após criar a API, você pode acessar os detalhes dela clicando no nome da API na [lista de APIs](https://app.woovi.com.br/home/applications/tab/list).

![Detalhe da API](./__assets__/api-detail-route.png)

Nos detalhes da API, você pode clicar na seção de "IPs permitidos" para adicionar um novo IP.

Após clicar no modal, irá aparecer um campo onde poderá inserir o IP que deseja adicionar à lista de permissões.

![Detalhe da API mostrando o modal de adição de IPs](./__assets__/api-detail-allowed-ip-modal.png)

Após a adição, será necessário efetuar a confirmação utilizando um código multi-fator,
é o meio de assegurar que somente você poderá adicionar IPs à lista de permissões.

Após a confirmação, o IP será adicionado à lista de permissões e poderá acessar a API.

Lembrando que, caso não tenha adicionado nenhum IP a lista de permissões, a API poderá estar
sendo utilizada por quaisquer IPs.

## Como posso pegar o IP da minha máquina?

Existe algumas ferramentas que facilitam a obtenção do IP da sua máquina, como por exemplo:

- [Meu IP](https://meuip.com/).
- [ifconfig.me](https://ifconfig.me/)

Com essas ferramentas, é possível saber qual IP você deve inserir na lista de permissões da sua API.

---

## Retorno de Data e hora na API

## Horários retornados na API

Todos os horários retornados pela API woovi são fornecidos em UTC (Tempo Universal Coordenado). Este é o padrão utilizado para transações financeiras no Brasil, garantindo consistência e precisão nas informações de tempo, independentemente da localização geográfica.

Exemplos de campos de data e hora retornados em UTC:
- `paidAt`: "2025-04-17T21:24:58.683Z"
- `createdAt`: "2025-04-17T21:08:15.036Z"
- `updatedAt`: "2025-04-17T21:25:09.816Z"
- `expiresDate`: "2025-04-18T21:08:11.130Z"

O sufixo "Z" ao final das datas indica que o horário está em UTC (também conhecido como "Zulu time").

## Fusos horários no Brasil

É importante considerar que o Brasil possui diferentes fusos horários:

- Horário de Brasília (BRT): UTC-3 - Utilizado na maior parte do país, incluindo as regiões Sul, Sudeste, Nordeste e os estados de Goiás, Distrito Federal, Tocantins, Pará e Amapá.
- Horário do Amazonas: UTC-4 - Utilizado nos estados do Amazonas, Rondônia, Roraima e parte do Pará.
- Horário do Acre: UTC-5 - Utilizado no estado do Acre e parte do Amazonas.

Ao integrar com a API woovi, recomendamos converter os horários recebidos de UTC para o fuso horário adequado da sua aplicação ou usuário final.

## Conversão de horários para exibição

Para exibir os horários corretamente aos usuários, é importante converter o tempo UTC para o fuso horário local. Abaixo estão exemplos de como realizar esta conversão em diferentes linguagens:

```javascript
// JavaScript
const utcDate = new Date("2025-04-17T21:24:58.683Z");
// Converte para horário de Brasília (UTC-3)
const brasiliaTime = new Intl.DateTimeFormat('pt-BR', {
  timeZone: 'America/Sao_Paulo',
  dateStyle: 'full',
  timeStyle: 'long'
}).format(utcDate);
```

```python
# Python com pytz
import datetime
import pytz

utc_date = datetime.datetime.fromisoformat("2025-04-17T21:24:58.683Z".replace('Z', '+00:00'))
brasilia_tz = pytz.timezone('America/Sao_Paulo')
brasilia_time = utc_date.astimezone(brasilia_tz)
```

---

## Versionamento e Depreciação da API

A Woovi se compromete a **não quebrar silenciosamente** integrações em produção.
Esta página descreve como versionamos a API, o que garantimos de compatibilidade, e como
conduzimos a depreciação de recursos com prazo de _sunset_ e comunicação prévia.

## Versionamento

- A API é versionada no **caminho da URL**: `https://api.woovi.com/api/v1/...`
  (produção) e `https://api.woovi-sandbox.com/api/v1/...` (sandbox).
- Seguimos **[SemVer](https://semver.org/lang/pt-BR/)**: a versão é composta por
  `major.minor.patch`. **Mudanças compatíveis não geram nova versão _major_.**
- Uma mudança **incompatível** (que quebra contrato) **nunca** é aplicada na major vigente:
  ela só entra em uma **nova major** (ex.: `/api/v2`), e a major anterior continua no ar.

## Garantia de compatibilidade

Dentro de uma mesma major, aplicamos apenas **mudanças aditivas**, que podem ocorrer a
qualquer momento e **não exigem ação** do integrador:

- novos endpoints;
- novos parâmetros **opcionais**;
- novos campos na resposta;
- novos valores em enumerações;
- reordenação de campos.

> **Regra de ouro do cliente:** ignore campos que você não conhece e não dependa da ordem
> dos campos. Assim sua integração absorve mudanças aditivas sem quebrar.

São consideradas **mudanças incompatíveis** (só em nova major): remover ou renomear um campo
ou endpoint, mudar o tipo de um campo, tornar obrigatório um parâmetro antes opcional, ou
remover um valor de enumeração.

## Depreciação e _sunset_

Quando um recurso (endpoint, campo ou versão) precisa ser aposentado, seguimos este rito:

1. **Depreciação:** o recurso é marcado como depreciado (na documentação/OpenAPI e, quando
   aplicável, via headers HTTP `Deprecation` e `Sunset` — [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)),
   mas **continua funcionando**.
2. **Prazo de _sunset_:** definimos uma **data de desligamento** com antecedência mínima de
   **90 dias** (3 meses) a partir do anúncio, período em que o recurso depreciado segue ativo.
3. **Comunicação prévia:** a depreciação é registrada no [Changelog](./api-changelog) e
   comunicada aos integradores afetados (e-mail e/ou painel) antes do _sunset_.
4. **Desligamento:** somente após o prazo o recurso é efetivamente removido.

Mudanças que quebram contrato **sem** caminho de migração não são feitas na major vigente —
elas motivam uma nova major, com o mesmo rito de anúncio e prazo.

## Comunicação e Changelog

- Toda mudança relevante é publicada no **[Changelog da API](./api-changelog)**, com data.
- Depreciações e _sunsets_ são anunciados no Changelog e comunicados diretamente aos
  integradores afetados antes da data de desligamento.

## Estabilidade do `v1`

A `v1` é estável desde o lançamento. Não houve nenhuma mudança incompatível não anunciada;
as depreciações realizadas seguiram anúncio prévio antes da remoção.

---

## Começando a Integração

## Criando uma nova chave de API/Plugin

O primeiro passo para começar a integrar com a API é criar uma nova chave de API, para que possa ser feitas as requisições.

### Passo 1 - Criar um novo aplicativo

Vá para `Api/Plugins` na barra lateral e clique em `Nova API/Plugin`.

:::caution
Caso você não esteja visualizando o sidebar API/Plugins é necessário ter a permissão correta, veja com o admin da sua empresa.
:::

![appid-1](./__assets__/api-plugins.png)

### Passo 2 - Nome da integração

Dentro da tela de criação, coloque um nome para a integração, e selecione `API` para integrações backend, ou `Plugin` para integrações frontend.

![appid-2](./__assets__/new-api-plugin.png)

### Passo 3 - Criando uma nova chave de API/Plugin

Clique em `Salvar` para criar a nova chave de API/Plugin.

![appid-3](./__assets__/save-new-api.png)

### Passo 4 - Colocando o fator de autenticação

Para que a API/Plugin possa ser utilizada, é necessário colocar um fator duplo de autenticação para garantir maior segurança na geração de chaves.

![appid-4](./__assets__/token-new-api.png)

### Passo 5 - Copiando o AppID

Após criar a nova chave de API/Plugin, você pode copiar o AppID para utilizar em suas integrações.

![appid-5](./__assets__/copy-appid-new-api.png)

## Como utilizar a API

Todas as `requests` e `responses` da API usam o formato JSON

Para que a requisição seja válida, é necessário enviar o `AppID`/`Token` no header `Authorization` da requisição.

Não utilize o prefixo `Bearer`. Envie o valor bruto do `AppID` no header.

```json
{
  "Authorization": "<AppID>"
}
```

Exemplo:

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/charge \
  --header 'Authorization: SEU_APPID_AQUI'
```

## Restrições de APIs

Os IPs e certificados dos servidores backend da API mudam constantemente, não armazene em cache nem IPs do servidor nem certificados

Todas as solicitações (requests) devem ser criptografadas usando `https`

As chaves de API são extremamente poderosas, pois podem criar ou ler dados de sua empresa, e devem ser armazenadas e compartilhadas com cuidado extra.

Orientações da API:

- Não compartilhe chaves com terceiros
- Não reutilize chaves - Chaves de acessos, você pode gerar várias chaves
- Apenas gere chaves quando for necessário
- Desative chaves não utilizadas

## AppID Inválido

Pode ocorrer de você receber uma resposta com o HTTP Status 401, que está relacionado à um appID inválido, sendo passado no header mencionado acima.

```json
{
  "data": null,
  "errors": [
    {
      "message": "appID inválido"
    }
  ]
}
```

Caso seja inválido é retornado esse erro caso seja de appID inválido.

Caso você obtenha esse erro, é recomendado gerar um novo appID dá sua aplicação, ou regerar o appID, caso já tenha uma aplicação criada, e adicionar novamente em seu sistema.

---

## Como fazer upload de um arquivo?

O endpoint de arquivos guarda um arquivo na Woovi e devolve os metadados dele junto com uma URL de download temporária. Use esse arquivo em outras APIs da Woovi que consomem documentos, como a [evidência de uma disputa](../disputa/how-add-new-evidence-in-evidence.md) ou o comprovante de um [pedido de aumento de limite](../apis/api-account-limits-increase-request.md), sem precisar hospedar o arquivo por conta própria.

O `purpose` diz qual é esse uso, e cada API só aceita o `purpose` dela: um arquivo subido como `DISPUTE_EVIDENCE` não serve num pedido de limite, e vice-versa.

| `purpose` | Usado por |
| --- | --- |
| `DISPUTE_EVIDENCE` | [Evidência de disputa](../disputa/how-add-new-evidence-in-evidence.md) |
| `ACCOUNT_LIMIT_REQUEST` | [Pedido de aumento de limite](../apis/api-account-limits-increase-request.md) |

## Requisitos

- Um AppID com o escopo `FILE_POST` ([como adicionar escopos](../apis/api-scopes.md)).
- Um arquivo por requisição, de até 10 MiB (`10485760` bytes).
- Content type entre `application/pdf`, `image/png`, `image/jpeg` e `image/webp`. Os bytes iniciais do arquivo precisam bater com o content type declarado.

## 1. Fazer a requisição

O arquivo é enviado como `multipart/form-data` no campo `file`, junto com o `purpose`, que descreve para que o arquivo serve.

```bash
curl -X POST "https://api.woovi.com/api/v1/files" \
  -H "Authorization: <appID>" \
  -F "file=@evidence.png" \
  -F "purpose=DISPUTE_EVIDENCE" \
  -F "correlationID=evidence-2026-08-1042"
```

| Campo           | Obrigatório | Descrição                                                                                     |
| --------------- | ----------- | --------------------------------------------------------------------------------------------- |
| `file`          | Sim         | O arquivo em si.                                                                                |
| `purpose`       | Sim         | Para que o arquivo será usado. Aceita `DISPUTE_EVIDENCE` e `ACCOUNT_LIMIT_REQUEST`.             |
| `correlationID` | Não         | Seu identificador para o upload. Quando não enviado, um UUID é gerado para você.                |

## 2. Entendendo o retorno

Um upload novo responde `201`:

```json
{
  "file": {
    "id": "6712c2ac7c2f1e0012a4b8d1",
    "correlationID": "evidence-2026-08-1042",
    "purpose": "DISPUTE_EVIDENCE",
    "fileName": "evidence.png",
    "contentType": "image/png",
    "size": 20480,
    "url": "https://woovi-files.s3.amazonaws.com/company/6712c1f07c2f1e0012a4b8c9/dispute_evidence/6712c2ac7c2f1e0012a4b8d1?X-Amz-Signature=...",
    "urlExpiresAt": "2026-08-22T15:30:00.000Z",
    "createdAt": "2026-08-22T14:30:00.000Z"
  }
}
```

A `url` é pré-assinada e para de funcionar em `urlExpiresAt`. Peça o arquivo novamente para obter uma URL nova.

## Repetindo a requisição com segurança

Quando você envia um `correlationID`, repetir a requisição com o mesmo `correlationID` e o mesmo `purpose` devolve o arquivo já armazenado com status `200`, em vez de subir uma segunda cópia. Isso torna o envio seguro para retentativa.

Sem `correlationID`, cada chamada gera um novo arquivo.

## Erros

| Código | Quando acontece                                                                                     |
| ------ | ---------------------------------------------------------------------------------------------------- |
| `400`  | `purpose` desconhecido, `correlationID` vazio, campo `file` ausente ou mais de um arquivo enviado.      |
| `401`  | Credenciais ausentes ou inválidas.                                                                     |
| `403`  | A aplicação não tem o escopo `FILE_POST`.                                                              |
| `413`  | Arquivo maior que o tamanho máximo aceito.                                                             |
| `415`  | Content type fora da lista permitida, ou bytes iniciais que não batem com o content type declarado.    |
| `502`  | O arquivo não pôde ser armazenado. A requisição pode ser repetida.                                     |

O corpo do erro traz a mensagem no idioma da empresa que fez a requisição (pt-BR, en ou es):

```json
{
  "error": "Invalid value for the field purpose"
}
```

## Usando o arquivo em outra API

Pegue o `file.id` do retorno e envie no campo correspondente da API que vai consumir o documento. Para disputas, ele vai no `fileId` de cada item de `documents` em `POST /api/v1/dispute/{id}/evidence` — veja [Como adicionar uma nova evidência em uma disputa?](../disputa/how-add-new-evidence-in-evidence.md).

## Casos de Uso

- Envio de evidências de disputa

---

## Ativando o modo BaaS

Este documento mostra como habilitar o modo BaaS na sua conta Woovi e deixar tudo pronto para criar as contas dos seus clientes.

## Pré-requisitos

- Conta Woovi ativa, com CNPJ e cadastro aprovado
- Caso de uso descrito — o time da Woovi avalia o modelo de negócio na ativação

## 1. Solicite a ativação das features

O modo BaaS depende de duas features habilitadas na sua conta: **BaaS** e **Criação de conta**.

A ativação é feita pelo time da Woovi — fale com o **suporte** (chat ou WhatsApp) ou com o seu **gerente de conta**. A ativação costuma sair em até 2 dias úteis.

## 2. Crie a API Master

Na plataforma, acesse **API/Plugins → Nova API/Plugin** e crie uma API do tipo **MASTER**.

Ela precisa ser desse tipo porque é a única capaz de criar credenciais (applications) para as outras contas. A conta bancária vinculada a essa API é usada como base no processo de criação das novas contas.

O passo a passo de criação de uma chave de API — incluindo o fator duplo de autenticação — está em [Primeiros passos com a API](./kyc/api-getting-started.mdx).

:::caution Guarde o AppID com segurança
O AppID da API Master administra todas as suas contas. Armazene-o em um cofre de segredos e nunca o exponha em front-end ou repositórios de código.
:::

## 3. Confira se está tudo ativo

Faça uma chamada de teste listando as suas contas:

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/account \
  --header 'Authorization: <MASTER_APP_ID>'
```

Se os endpoints de criação de conta responderem `403` com `"You need feature BAAS to access this endpoint"`, a feature ainda não foi habilitada — volte ao passo 1.

## Próximo passo

Com o modo BaaS ativo, [prepare os documentos e dados de KYC](./documentos-kyc.md) para criar a primeira conta.

---

## Controlando as contas no modo BAAS

Este documento irá ajudá-lo a entender como criar APIs para as contas abertas no modo BaaS e como um AppId **MASTER** lê o extrato e as transações de outra conta da mesma empresa.

### API mestre

A API mestre é um conceito que permite você criar APIs das várias contas do modo BaaS.

![api-mestre](__assets__/api-mestre.png)

Visualização das várias contas:

![api-mestre](__assets__/accounts.png)

Uma aplicação `MASTER` fica ligada a **uma** conta bancária, como qualquer AppId `API`. Sem a feature descrita abaixo, para ler dados de outra conta você precisa criar um AppId para aquela conta.

### Como criar um AppId por conta

Primeiro vá na plataforma em API/PLUGINS e crie uma API **MASTER**.

Em seguida, use o AppId da API mestre para criar o AppId da conta que você selecionou no endpoint [`POST /api/v1/application`](/api#tag/application).

É necessário ter o `accountId` da conta para a qual você quer criar a API. Liste as contas com [`GET /api/v1/account`](/api#tag/account):

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/account \
  --header 'Authorization: <MASTER_APP_ID>'
```

Resposta:

```json
{
  "pageInfo": {
    "skip": 0,
    "limit": 10,
    "hasPreviousPage": false,
    "hasNextPage": true
  },
  "accounts": [
    {
      "accountId": "6290ccfd42831958a405debc",
      "isDefault": true,
      "balance": {
        "total": 129430,
        "blocked": 0,
        "available": 129430
      }
    },
    {
      "accountId": "6286b467a7910113577e00ce",
      "isDefault": false,
      "balance": {
        "total": 130,
        "blocked": 100,
        "available": 30
      }
    }
  ]
}
```

Crie a aplicação da conta com `POST /api/v1/application`:

```json
{
  "accountId": "6286b467a7910113577e00ce",
  "application": {
    "name": "application",
    "type": "API"
  }
}
```

O retorno será:

```json
{
  "application": {
    "name": "application",
    "isActive": true,
    "type": "API",
    "clientId": "Client_Id",
    "clientSecret": "Client_Secret6uWhGA=",
    "appID": "appId"
  }
}
```

Com o `appID` em mãos, você consegue acessar qualquer endpoint daquela conta.

## Lendo outra conta com o AppId MASTER

Se a sua empresa tem a feature **`MASTER_APP_READ_ANY_ACCOUNT`**, o mesmo AppId MASTER lê o **statement** e a **transaction** de qualquer conta da **própria empresa**, sem criar um AppId por conta.

Passe o `accountId` (o mesmo retornado por `GET /api/v1/account`) na query string `companyBankAccount`.

:::info Pré-requisitos

- a aplicação autenticada precisa ser do tipo **MASTER**
- a empresa precisa ter a feature **`MASTER_APP_READ_ANY_ACCOUNT`** (solicite ao suporte)
- o `companyBankAccount` precisa ser uma conta **ativa** da mesma empresa
- somente leitura: nenhum endpoint de escrita usa essa query string

:::

Endpoints que aceitam `companyBankAccount` hoje:

| Método | Endpoint | Escopo |
| --- | --- | --- |
| `GET` | [`/api/v1/statement`](/api#tag/statement) | `STATEMENT_GET` |
| `GET` | [`/api/v1/transaction/{id}`](/api#tag/transactions | `TRANSACTION_GET` |

Sem a query string, o comportamento não muda: o statement continua da conta ligada ao AppId, e a transaction continua no escopo da empresa.

### 1. Obtenha o `accountId` da conta de destino

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/account \
  --header 'Authorization: <MASTER_APP_ID>'
```

Use o campo `accountId` da conta que você quer ler — por exemplo `6286b467a7910113577e00ce`.

### 2. Ler o statement de outra conta

`GET /api/v1/statement` filtra pelo ledger da conta pedida. Com `companyBankAccount`, o extrato é o daquela conta, não o da conta ligada ao AppId MASTER.

```bash
curl --request GET \
  --url 'https://api.woovi.com/api/v1/statement?companyBankAccount=6286b467a7910113577e00ce&start=2026-01-01T00:00:00Z&end=2026-01-31T23:59:59Z' \
  --header 'Authorization: <MASTER_APP_ID>'
```

Resposta `200`:

```json
[
  {
    "id": "507f1f77bcf86cd799439011",
    "time": "2026-01-15T10:30:00.000Z",
    "description": "Payment received from customer",
    "balance": 1500,
    "value": 100,
    "type": "CREDIT"
  }
]
```

Os mesmos filtros de período e paginação (`start`, `end`, `skip`, `limit`) continuam válidos.

### 3. Ler uma transaction de outra conta

`GET /api/v1/transaction/{id}` aceita o `id` da transação Woovi ou o `endToEndId` do banco. Com `companyBankAccount`, a busca **restringe** a transação àquela conta. Se a transação existir na empresa, mas em outra conta, a API responde `400` com `Transaction not found`.

```bash
curl --request GET \
  --url 'https://api.woovi.com/api/v1/transaction/E18236120202012032010s0133872GZA?companyBankAccount=6286b467a7910113577e00ce' \
  --header 'Authorization: <MASTER_APP_ID>'
```

Resposta `200`:

```json
{
  "transaction": {
    "customer": {
      "name": "Dan",
      "email": "email0@example.com",
      "phone": "5511999999999",
      "taxID": {
        "taxID": "31324227036",
        "type": "BR:CPF"
      },
      "correlationID": "9134e286-6f71-427a-bf00-241681624586"
    },
    "payer": {
      "name": "Dan",
      "email": "email0@example.com",
      "phone": "5511999999999",
      "taxID": {
        "taxID": "31324227036",
        "type": "BR:CPF"
      },
      "correlationID": "9134e286-6f71-427a-bf00-241681624586"
    },
    "value": 100,
    "time": "2026-01-15T10:30:00.536Z",
    "transactionID": "transactionID",
    "type": "PAYMENT",
    "endToEndId": "E18236120202012032010s0133872GZA",
    "globalID": "UGl4VHJhbnNhY3Rpb246NzE5MWYxYjAyMDQ2YmY1ZjUzZGNmYTBi"
  }
}
```

O `id` no path também pode ser o `_id` da transação:

```bash
curl --request GET \
  --url 'https://api.woovi.com/api/v1/transaction/7191f1b02046bf5f53dcfa0b?companyBankAccount=6286b467a7910113577e00ce' \
  --header 'Authorization: <MASTER_APP_ID>'
```

### Exemplo em Node.js

O mesmo AppId MASTER lista as contas, lê o statement de uma delas e busca uma transaction naquela conta:

```js
const MASTER_APP_ID = process.env.WOOVI_MASTER_APP_ID;
const baseUrl = 'https://api.woovi.com';

const headers = { Authorization: MASTER_APP_ID };

const accountsResponse = await fetch(`${baseUrl}/api/v1/account`, { headers });
const { accounts } = await accountsResponse.json();

const targetAccountId = accounts.find((account) => !account.isDefault).accountId;

const statementResponse = await fetch(
  `${baseUrl}/api/v1/statement?companyBankAccount=${targetAccountId}&start=2026-01-01T00:00:00Z&end=2026-01-31T23:59:59Z`,
  { headers },
);
const statement = await statementResponse.json();

const transactionResponse = await fetch(
  `${baseUrl}/api/v1/transaction/E18236120202012032010s0133872GZA?companyBankAccount=${targetAccountId}`,
  { headers },
);
const { transaction } = await transactionResponse.json();

console.log({ targetAccountId, statement, transaction });
```

Não use o prefixo `Bearer`. Envie o AppId MASTER cru no header `Authorization`.

### Erros

Não há fallback silencioso para a conta do MASTER. Se a query `companyBankAccount` for rejeitada, a API responde o erro correspondente:

| Caso | Status | `error` |
| --- | --- | --- |
| A aplicação não é MASTER | `403` | `Only a MASTER application can read another account` |
| A empresa não tem `MASTER_APP_READ_ANY_ACCOUNT` | `403` | `Module MASTER APP READ ANY ACCOUNT is not enabled, contact support to enable the module.` |
| A conta não existe, foi removida ou é de outra empresa | `403` | `Company bank account not found` |
| `companyBankAccount` inválido (não é um ObjectId) | `400` | `Account ID is invalid` |
| A transaction não pertence à conta pedida | `400` | `Transaction not found` |

```json
{
  "error": "Only a MASTER application can read another account"
}
```

```json
{
  "error": "Module MASTER APP READ ANY ACCOUNT is not enabled, contact support to enable the module."
}
```

```json
{
  "error": "Company bank account not found"
}
```

### Quando usar cada abordagem

| Objetivo | Abordagem |
| --- | --- |
| Ler statement ou uma transaction de várias contas BaaS | um AppId MASTER + `?companyBankAccount=<accountId>` |
| Operar (criar cobrança, pagar, etc.) em uma conta específica | crie um AppId `API` para aquela conta com `POST /api/v1/application` |

---

## Configurando a emissão de nota fiscal via API

Este documento irá ajudá-lo a configurar, via API, a emissão de nota fiscal eletrônica de serviço (NFS-e) de uma conta, do cadastro da integração até a emissão da nota de teste que valida tudo.

:::info

Todos os endpoints deste documento operam sobre a **conta que está no token**, sem nenhum parâmetro de conta no corpo da requisição. O fluxo é o mesmo para qualquer conta.

A única diferença no modo BaaS é **como você obtém o appId**: em vez de criar a API pela plataforma, você gera o appId da conta a partir da sua API mestre. Veja [Controlando as contas no modo BAAS](/docs/baas/baas-api-master).

:::

:::caution

Esta documentação espera que:

- a feature de nota fiscal esteja habilitada para a sua empresa (disponível apenas por solicitação via chat);
- a conta já esteja com o cadastro **aprovado** — a identidade fiscal da nota é a da própria conta;
- você tenha em mãos o certificado digital **A1** (arquivo `.pfx`/`.p12`) e a senha dele.

:::

## Autenticação

Todas as requisições usam o padrão da API REST da Woovi: o appId vai no header `Authorization`.

```
Authorization: <appId>
Content-Type: application/json
```

O **escopo é definido pelo próprio token**: a integração criada, o certificado enviado e a nota de teste emitida pertencem à conta do appId utilizado.

## Fluxo da configuração

A integração só fica pronta para emitir notas reais quando o provedor de nota fiscal **confirma a nota de teste por webhook**. É por isso que a emissão de teste é o último passo: ela é o que fecha a configuração.

![Fluxo de requests da integração de nota fiscal via API](./__assets__/baas-invoice-integration-flow.png)

<!-- Diagrama gerado a partir de ./__assets__/baas-invoice-integration-flow.mmd (mermaid).
     Para atualizar: edite o .mmd e re-renderize a imagem. -->

## 1. Criando a integração

O primeiro passo cria a integração de nota fiscal da conta e grava as informações fiscais dela. Essas informações garantem a conformidade tributária e podem ser obtidas com o auxílio do contador do titular da conta.

`POST /api/v1/invoice/integration`

Todos os campos do corpo são opcionais — envie os que se aplicam ao município e ao regime tributário da conta:

| Campo                       | Tipo      | Descrição                                                               |
| --------------------------- | --------- | ----------------------------------------------------------------------- |
| `cityServiceCode`           | `string`  | Código de serviço municipal, conforme a lista de serviços da prefeitura |
| `municipalSubscription`     | `string`  | Inscrição/assinatura municipal do prestador de serviço                  |
| `rpsNumber`                 | `string`  | Número do RPS (Recibo Provisório de Serviços)                           |
| `specialTax`                | `string`  | Regime de imposto especial                                              |
| `taxRegime`                 | `string`  | Regime tributário da empresa                                            |
| `federalTaxDetermination`   | `string`  | Determinação de tributos federais                                       |
| `municipalTaxDetermination` | `string`  | Determinação de tributos municipais                                     |
| `isPortalNacional`          | `boolean` | Indica se o município emite pelo Portal Nacional da NFS-e               |
| `isActive`                  | `boolean` | Ativa a integração (só é permitido depois de configurada)               |

```bash
curl 'https://api.woovi.com/api/v1/invoice/integration' -X POST \
  -H 'Authorization: <appId>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "cityServiceCode": "2690",
    "municipalSubscription": "123456",
    "rpsNumber": "1",
    "taxRegime": "LimitedProfit",
    "specialTax": "None",
    "isPortalNacional": false
  }'
```

Resposta `201`:

```json
{
  "integration": {
    "id": "67001bbf0b0621890af7dc28",
    "type": "NFEIO",
    "status": "CONFIGURING",
    "isActive": false,
    "companyBankAccount": "66f8c1a20b0621890af7aa11",
    "metadata": {
      "nfeio": {
        "cityServiceCode": "2690",
        "municipalSubscription": "123456",
        "rpsNumber": "1",
        "taxRegime": "LimitedProfit",
        "specialTax": "None",
        "isPortalNacional": false
      }
    }
  }
}
```

:::info

O campo `companyBankAccount` na resposta confirma a qual conta a integração ficou vinculada. O status `CONFIGURING` indica que a integração existe, mas ainda não está apta a emitir notas.

:::

## 2. Enviando o certificado digital A1

Com a integração criada, envie o certificado A1 da conta. O arquivo `.pfx`/`.p12` deve ser convertido para **base64** e enviado no corpo em JSON.

`POST /api/v1/invoice/integration/certificate`

| Campo        | Tipo      | Obrigatório | Descrição                                                                     |
| ------------ | --------- | ----------- | ----------------------------------------------------------------------------- |
| `pcks12`     | `string`  | Sim         | Certificado A1 (pkcs12) codificado em base64                                  |
| `passphrase` | `string`  | Sim         | Senha do certificado                                                          |
| `test`       | `boolean` | Não         | Quando `true`, o certificado não é enviado ao provedor (validação é ignorada) |

Para gerar o base64 do certificado:

```bash
base64 -w 0 certificado.pfx > certificado.base64
```

```bash
curl 'https://api.woovi.com/api/v1/invoice/integration/certificate' -X POST \
  -H 'Authorization: <appId>' \
  -H 'Content-Type: application/json' \
  --data-raw "{
    \"pcks12\": \"$(cat certificado.base64)\",
    \"passphrase\": \"senha-do-certificado\"
  }"
```

Resposta `200`:

```json
{
  "integration": {
    "status": "CONFIGURING"
  }
}
```

:::info

A resposta devolve apenas o status resultante da integração. O certificado, a senha e as credenciais nunca são retornados pela API.

:::

## 3. Emitindo a nota fiscal de teste

Este é o passo que fecha a configuração. A emissão de teste leva a integração para `VALIDATING` e, quando o provedor confirma a nota por webhook, a integração passa para `CONFIGURED` e `isActive: true` — é isso que libera a emissão de notas reais.

`POST /api/v1/invoice/integration/test`

Não há corpo a ser enviado: a conta e a integração são resolvidas pelo token.

```bash
curl 'https://api.woovi.com/api/v1/invoice/integration/test' -X POST \
  -H 'Authorization: <appId>' \
  -H 'Content-Type: application/json'
```

Resposta `200`:

```json
{
  "invoice": {
    "id": "67001c5b0b0621890af7dc44"
  },
  "integration": {
    "id": "67001bbf0b0621890af7dc28"
  }
}
```

Guarde o `invoice.id`: é o identificador da nota de teste gerada, que você pode consultar depois pelos endpoints de nota fiscal.

## 4. Confirmando que a integração está configurada

A confirmação da nota de teste chega por webhook do provedor, então o status muda de forma assíncrona. Consulte a integração da conta para acompanhar:

`GET /api/v1/invoice/integration`

```bash
curl 'https://api.woovi.com/api/v1/invoice/integration' -X GET \
  -H 'Authorization: <appId>'
```

Resposta `200` com a configuração concluída:

```json
{
  "integration": {
    "id": "67001bbf0b0621890af7dc28",
    "type": "NFEIO",
    "status": "CONFIGURED",
    "isActive": true,
    "companyBankAccount": "66f8c1a20b0621890af7aa11",
    "metadata": {
      "nfeio": {
        "nfeioCompanyId": "9f1c4b2e5a7d",
        "cityServiceCode": "2690",
        "municipalSubscription": "123456",
        "rpsNumber": "1",
        "taxRegime": "LimitedProfit",
        "specialTax": "None",
        "isPortalNacional": false
      }
    }
  }
}
```

:::info

Com `status: "CONFIGURED"` e `isActive: true`, a conta está pronta para emitir notas fiscais. Vale validar o documento da nota de teste com o contador do titular da conta antes de começar a emitir notas reais.

:::

## Próximos passos

Agora que a integração da conta está configurada, o próximo passo é emitir notas fiscais de verdade pela API:

- [Criar Nota Fiscal de serviço via API](/docs/invoice/how-to-issue-invoice-by-api)
- [Baixar PDF e XML da nota via API](/docs/invoice/how-to-get-invoice-files-by-api)
- [Cancelar uma nota emitida via API](/docs/invoice/how-to-cancel-issued-invoice-by-api)

---

## Split para a Conta Principal no modo BaaS

Este documento irá ajudá-lo a entender como configurar o split para a conta principal no modo BaaS.

### Visão Geral

No modo BaaS (Banking as a Service), você pode ter várias contas bancárias gerenciadas em uma única plataforma. Uma funcionalidade importante é a capacidade de configurar splits automáticos para a conta principal quando ocorrem transações em qualquer uma das contas secundárias.

![api-mestre](__assets__/accounts.png)

### Como Funciona o Split para a Conta Principal

Quando uma transação é realizada em qualquer uma das contas gerenciadas no modo BaaS, é possível configurar para que uma porcentagem ou valor fixo dessa transação seja automaticamente creditado na conta principal.

### Configuração do Split

Para configurar o split para a conta principal, utilize o seguinte formato na criação da cobrança:

```ts
{
  "value": 1000,
  "correlationID": "correlationId",
  "splits": [
    {
      "value": 30,
      "pixKey": "pix-key-main-default-account",
      "splitType": "SPLIT_INTERNAL_TRANSFER"
    }
  ]
}
```

Onde:
- `value`: Valor total da transação (em centavos)
- `correlationID`: Identificador único da transação
- `splits`: Array contendo as configurações de split
  - `value`: Valor a ser transferido para a conta principal (em centavos)
  - `pixKey`: Chave PIX da conta principal que receberá o valor do split
  - `splitType`: Tipo de split, neste caso "SPLIT_INTERNAL_TRANSFER" para transferência interna

### Observações Importantes

1. A conta principal deve estar corretamente configurada no sistema
2. A chave PIX da conta principal deve ser válida e ativa
3. O valor do split não pode exceder o valor total da transação
4. É possível configurar múltiplos splits para diferentes contas em uma única transação

Para mais informações sobre a criação e gerenciamento de APIs no modo BaaS, consulte o documento [API Mestre para modo BaaS](./baas-api-master.md).

---

## Fluxo básico de Baas

Este documento irá ajudá-lo a entender o fluxo básico de BaaS.

## Pré-requisitos

Antes de começar a utilizar a API BaaS é necessário duas coisas:

- Solicitar ativação das features: BaaS e Criação de conta
- Gerar uma chave de API master

A API precisa ser do tipo MASTER porque ela precisa ser capaz de criar novas integrações. A conta bancária relacionada a essa API será utilizada no processo de criação das novas contas bancárias, elas usarão os dados desta para serem criadas.

Assim estamos prontos para iniciar a sequência de integração.

## Sequência da integração

![basic-flux-baas](__assets__/basic-flux-baas.png)

## 1. Registrando uma conta

- Utilize o endpoint de registro de conta para registrar uma nova conta
- Utilize a chave de API master para autenticar a requisição
- Faça a requisição:

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/kyc/onboarding \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"taxID":"string","correlationID":"string","redirectUrl":"https://partner.example.com/kyc-done","representatives":[{"taxID":"string","name":"string"}]}'
```

Caso tudo ocorra corretamente, um código 201 será retornado. No corpo da resposta terá:

```json
{
  "linkOnboarding": "https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5...",
  "redirectUrl": "https://partner.example.com/kyc-done",
  "accountRegister": {
    "status": "PENDING",
    "officialName": "RAZAO_SOCIAL_DA_EMPRESA",
    "tradeName": "NOME_FANTASIA_DA_EMPRESA",
    "taxID": {
      "taxID": "XXXXXXXX0001XX",
      "type": "BR:CNPJ"
    },
    "correlationID": "my-unique-id",
    "representatives": [
      {
        "name": "NOME_DO_SOCIO",
        "taxID": {
          "taxID": "XXXXXXXXXXX",
          "type": "BR:CPF"
        }
      }
    ]
  }
}
```

## 2. Aguarde a aprovação da conta

Cadastre um webhook ouvindo o seguinte evento: `ACCOUNT_REGISTER_APPROVED`.

Para cadastrar um webhook faça a seguinte request:

```bash
curl --location --request POST 'https://api.woovi.com/api/openpix/v1/webhook' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: <apiMasterKey>' \
  --data-raw '{
    "webhook": {
      "name": "webhook via api",
      "event": "ACCOUNT_REGISTER_APPROVED",
      "url": "https://minhaurl.test/webhook",
      "authorization": "auth_key",
      "isActive": true
    }
  }'
```

No corpo da resposta terá:

```json
{
  "event": "ACCOUNT_REGISTER_APPROVED",
  "accountRegister": {
    "correlationID": "<CNPJ>",
    "officialName": "<NOME-COMPLETO>",
    "taxID": {
      "taxID": "<CNPJ>",
      "type": "BR:CNPJ"
    },
    "status": "APPROVED"
  },
  "account": {
    "status": "OPEN",
    "accountId": "6a1ec49c050ca1d11348008f",
    "account": "00000000000006588018",
    "branch": "0001"
  }
}
```

## 3. Gere uma chave de API padrão

- Utilize o endpoint de application para gerar uma chave de API para a conta recém criada
- Utilize a chave de API master para autenticar a requisição
- Faça a requisição:

```bash
curl -X POST "https://api.woovi.com/api/v1/application" \
  -H "Authorization: <apiMasterKey>" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "accountId": "6a10805a342fd2a76aa0e5ac",
    "application": {
      "name": "Teste API",
      "type": "API",
      "scopes": [
        "CHARGE_GET"
      ]
    }
  }'
```

Caso tudo ocorra corretamente, um código 201 será retornado. No corpo da resposta terá:

```json
{
  "application": {
    "name": "Teste API",
    "isActive": true,
    "type": "API",
    "clientId": "Client_Id_791f667b-c885-45e4-bbe1-468de247a9f6",
    "clientSecret": "Client_Secret_JgDrJ3fedGz9DXlBqPUogNy8HxAucm47l/FWwfSInl8=",
    "appID": "<APID>",
    "scopes": [
      "CHARGE_GET"
    ]
  }
}
```

## 4. Gere uma chave PIX aleatória

- Utilize o endpoint pix-keys para gerar uma chave para a conta
- Utilize o appID gerado no passo anterior para autenticar a requisição
- Faça a requisição:

```bash
curl -X POST "https://api.woovi.com/api/v1/pix-keys" \
  -H "Authorization: <appID>" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "type": "EVP"
  }'
```

Caso tudo ocorra corretamente, um código 200 será retornado. No corpo da resposta terá:

```json
{
  "pixKey": {
    "pixKey": "",
    "type": "EVP",
    "isDefault": false
  }
}
```

Para outros tipos de chave e gerenciamento, veja [Chaves Pix das contas](./chaves-pix-contas.md).

---

## Chaves Pix das contas

Cada conta precisa de ao menos uma chave Pix — é a chave _default_ da conta que as cobranças usam. Gerencie as chaves de uma conta com o **AppID da própria conta**.

## Criando uma chave aleatória (EVP)

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/pix-keys \
  --header 'Authorization: <APP_ID_DA_CONTA>' \
  --header 'Content-Type: application/json' \
  --data-raw '{ "type": "EVP" }'
```

Resposta `200`:

```json
{
  "pixKey": {
    "pixKey": "b6295ee1-f054-4b8f-a8b4-dfe4ad2d8e9f",
    "type": "EVP",
    "isDefault": false
  }
}
```

## Tipos suportados

| Tipo              | Campo `pixKey`        | Observações                                     |
| ----------------- | --------------------- | ----------------------------------------------- |
| `EVP`             | não enviar — é gerada | recomendado: sem dado pessoal, criação imediata |
| `CNPJ`            | obrigatório           | o CNPJ da conta                                 |
| `EMAIL` / `PHONE` | obrigatório           | dependem de verificação — fale com o suporte    |
| `CPF`             | —                     | não suportado via API                           |

Para os tipos que exigem o campo, envie a chave em `pixKey`:

```json
{ "pixKey": "11222333000181", "type": "CNPJ" }
```

## Gerenciando as chaves

- `GET /api/v1/pix-keys` — lista as chaves da conta
- `PUT /api/v1/pix-keys/:pixKey/default` — define a chave padrão das cobranças
- `DELETE /api/v1/pix-keys/:pixKey` — remove a chave
- `GET /api/v1/pix-keys/:pixKey/check` — verifica a situação da chave

:::info
A API de chaves opera sobre a conta vinculada ao AppID usado no header. AppIDs criados pela API Master para uma conta (veja [Controlando as contas no modo BAAS](./baas-api-master.md)) já atendem a esse requisito.
:::

Para criar chaves pela plataforma, veja [Como criar uma nova chave Pix](../pix-keys/how-to-create-new-pix-key.md).

---

## Criando cobranças para uma conta

Este documento mostra como criar uma cobrança Pix para uma conta específica do modo BaaS.

:::tip A conta é definida pela credencial
Não existe um "parâmetro de conta" na API de cobrança: **a cobrança é criada na conta dona do AppID usado no header `Authorization`**. Cobrança criada com o AppID de uma conta é creditada no saldo daquela conta.
:::

## Passo a passo

1. Gere o AppID da conta com a sua API Master — veja [Controlando as contas no modo BAAS](./baas-api-master.md)
2. Garanta que a conta tem uma chave Pix — veja [Chaves Pix das contas](./chaves-pix-contas.md)
3. Crie a cobrança usando o AppID **daquela conta** no header:

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/charge \
  --header 'Authorization: <APP_ID_DA_CONTA>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "correlationID": "pedido-9134",
    "value": 1500,
    "comment": "Pedido 9134"
  }'
```

O `value` é sempre em **centavos**. Resposta (resumida):

```json
{
  "charge": {
    "status": "ACTIVE",
    "value": 1500,
    "correlationID": "pedido-9134",
    "brCode": "000201010212...",
    "qrCodeImage": "https://api.woovi.com/openpix/charge/brcode/image/...",
    "paymentLinkUrl": "https://openpix.com.br/pay/...",
    "expiresDate": "2026-09-24T18:00:00.000Z",
    "globalID": "Q2hhcmdlOi4uLg=="
  }
}
```

Todos os demais recursos de cobrança — expiração, dados do cliente, desconto, informações adicionais — funcionam normalmente. Veja a [documentação de cobrança](../charge/how-to-create-charge-using-api.mdx) e a [API Reference](https://developers.woovi.com/api#tag/charge).

## Confirmação de pagamento

Registre o webhook `OPENPIX:CHARGE_COMPLETED` **com o AppID da mesma conta** — veja [Webhooks por conta](./webhooks-por-conta.md). Quando o Pix for pago, o evento chega com os dados da cobrança e do pagador.

## Repassando uma parte para a conta principal

Para reter uma tarifa da sua plataforma em cada cobrança, use o split de transferência interna na criação da cobrança:

```json
{
  "value": 1500,
  "correlationID": "pedido-9134",
  "splits": [
    {
      "value": 150,
      "pixKey": "<CHAVE_PIX_DA_CONTA_PRINCIPAL>",
      "splitType": "SPLIT_INTERNAL_TRANSFER"
    }
  ]
}
```

Veja os detalhes e as regras em [Split para a conta principal no modo BaaS](./baas-split.md).

---

## Visão geral do BaaS

BaaS significa _Bank as a Service_ — "banco como serviço". Com o BaaS da Woovi, sua empresa oferece serviços bancários e financeiros como se fosse um banco, sem precisar ser uma instituição financeira. A Woovi fornece toda a estrutura necessária — tecnologia, regulamentação, segurança e APIs — para que você crie contas digitais para seus clientes, com a sua marca.

Em outras palavras: você cria contas bancárias digitais dentro do seu próprio sistema, com saldo, Pix, extrato e muito mais. Tudo isso funciona sobre a infraestrutura da Woovi, que é conectada ao Banco Central e segue todas as regras exigidas.

## Como as contas se relacionam

- **Conta principal** — a conta da sua empresa. Nela vive a **API Master**, a credencial administradora que cria contas e gera as credenciais de cada conta.
- **Contas dos seus clientes** — cada uma tem saldo próprio e isolado, chaves Pix, extrato e o próprio **AppID**, usado para operar aquela conta.

![contas no modo BaaS](__assets__/accounts.png)

:::tip Regra de ouro
O header `Authorization` define em qual conta a operação acontece. **API Master** = administração (criar contas, gerar credenciais, ler extratos). **AppID da conta** = operação (criar cobranças, pagar, webhooks).
:::

## O que cada conta pode fazer

- Receber Pix (via QR Code ou cobrança) e pagar com Pix
- Cadastrar chaves Pix e consultar extrato
- Receber notificações automáticas (webhooks) quando um Pix é recebido, enviado ou devolvido
- Ter saldo próprio, isolado das demais contas

Tudo acontece em tempo real: o Pix entra em milissegundos e pode ser automatizado.

## Benefícios de utilizar o BaaS da Woovi

- Você começa rápido: ativação em até 2 dias úteis
- Licença bancária integrada: IP regulada e participante direta da rede Pix
- Tudo pronto: sem precisar negociar com bancos
- Marca própria: os serviços aparecem com a cara da sua empresa
- APIs e webhooks de fácil integração

## Casos de uso comuns

Bancos e fintechs, e-commerces e marketplaces, empresas de varejo, sistemas ERP, corretoras — qualquer negócio que precise oferecer contas digitais aos próprios clientes.

## A jornada de integração

1. [Ative o modo BaaS](./ativacao-baas.md) e crie a sua API Master
2. [Prepare os documentos e dados de KYC](./documentos-kyc.md) do seu cliente
3. Crie a conta com o [link de onboarding KYC](./kyc/api-onboarding-create.mdx) — o seu cliente preenche os dados em uma tela hospedada pela Woovi
4. Acompanhe a aprovação por [webhook](./webhooks-por-conta.md) ou [consultando o cadastro](./kyc/api-account-register-get.mdx)
5. [Gere as credenciais da conta](./baas-api-master.md) com a API Master
6. [Crie uma chave Pix para a conta](./chaves-pix-contas.md)
7. [Crie cobranças para a conta](./cobrancas-por-conta.md)
8. Configure [webhooks](./webhooks-por-conta.md) e gerencie [saque, transferência e extrato](./movimentando-saldo.md)

O [fluxo básico de BaaS](./basic-flux.md) mostra essa mesma sequência em um único exemplo de ponta a ponta.

---

## Documentos e compliance (KYC)

Abrir uma conta passa por um processo de compliance estruturado em três etapas: **levantamento de documentação e informações**, **análise e validação** e **registro da conta**.

A Woovi é uma instituição regulada pelo Banco Central do Brasil. Por isso, determinadas responsabilidades regulatórias não podem ser delegadas: cabe a você iniciar o cadastro e ao seu cliente enviar a documentação; as etapas de análise, validação e registro da conta são de responsabilidade exclusiva da Woovi.

## Como funciona na prática

O caminho recomendado é a **API de KYC Onboarding**: você cria o onboarding com uma única chamada e recebe um link hospedado pela Woovi, onde o próprio cliente preenche os dados cadastrais e envia os documentos — sem que você precise coletar, hospedar ou transferir arquivos.

```bash
curl 'https://api.woovi.com/api/v1/kyc/onboarding' -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: <APP_ID>" \
  --data-binary '{
    "taxID": "XX.XXX.XXX/0001-XX",
    "correlationID": "conta-cliente-001",
    "representatives": [
      { "taxID": "XXX.XXX.XXX-XX" }
    ]
  }'
```

A resposta `201` traz o `linkOnboarding`, que você envia ao seu cliente:

```json
{
  "linkOnboarding": "https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5...",
  "accountRegister": {
    "status": "PENDING",
    "correlationID": "conta-cliente-001"
  }
}
```

O passo a passo completo do endpoint — campos, idempotência por `correlationID` e códigos de erro — está em [Como criar um onboarding KYC via API](./kyc/api-onboarding-create.mdx) e na [API Reference](https://developers.woovi.com/api#tag/kyc/POST/api/v1/kyc/onboarding).

O fluxo, do início ao fim:

1. **Você cria o onboarding via API** — apenas o CNPJ e, opcionalmente, os CPFs dos sócios
2. **Envia o `linkOnboarding` ao cliente** — por e-mail, WhatsApp ou dentro do seu produto
3. **O cliente preenche o cadastro** — dados da empresa, endereço, contrato social e documentos dos sócios
4. **O cadastro entra em análise** — o status muda para `IN_REVIEW`; a análise pode levar até 72h
5. **Aprovação ou rejeição** — acompanhe por [webhook](./webhooks-por-conta.md) (`ACCOUNT_REGISTER_APPROVED` / `_REJECTED` / `_PENDING`) ou [consultando o cadastro](./kyc/api-account-register-get.mdx)

## O que você envia na API

| Campo                     | Obrigatório | Descrição                                                                |
| ------------------------- | ----------- | ------------------------------------------------------------------------ |
| `taxID`                   | sim         | CNPJ da empresa do seu cliente, com ou sem máscara                       |
| `correlationID`           | não         | Identificador único para idempotência; sem ele, o CNPJ assume esse papel |
| `representatives[].taxID` | não         | CPFs dos sócios/representantes, para adiantar o preenchimento            |

Os demais dados — razão social, nome fantasia e nomes dos sócios — são preenchidos automaticamente pelo enriquecimento de dados quando disponíveis, e confirmados pelo cliente na tela de onboarding.

## O que o seu cliente precisa ter em mãos

Orientar o cliente antes de enviar o link acelera a aprovação. No formulário, ele vai precisar de:

### Documentos dos representantes (sócios/administradores)

| Documento      | Descrição                          |
| -------------- | ---------------------------------- |
| Foto de perfil | Selfie do representante            |
| CNH            | Completa, ou frente e verso        |
| RG             | Frente e verso (alternativa à CNH) |

Cada representante precisa da **foto de perfil mais uma identificação válida** (CNH ou RG).

### Documentos da empresa

| Documento         | Quem precisa       |
| ----------------- | ------------------ |
| Contrato social   | ONG, Igreja e LTDA |
| Estatuto          | ONG, Igreja e LTDA |
| Ata da assembleia | LTDA               |

**MEI** não precisa de documentos da empresa — apenas os dos sócios.

### Dados cadastrais

- Razão social, nome fantasia e CNPJ (ativo)
- Endereço comercial
- Website ou principal canal de vendas
- Produtos/serviços oferecidos, tempo de mercado e objetivo ao usar a conta

## Boas práticas que aceleram a aprovação

- Arquivos de até **10 MB**, legíveis, coloridos e sem cortes
- Dados idênticos aos registrados na Receita Federal (razão social, endereço, quadro societário)
- CNPJ ativo e representantes com CPF regular

Atividades ilegais não são permitidas.

## O que acontece na análise

Com a documentação completa, o cadastro entra em análise pelo time da Woovi. Recusas comuns: documentação inválida ou ilegível, divergência de dados cadastrais, CNPJ inativo e restrições de perfil de risco.

Se o cadastro voltar para `PENDING`, o seu cliente pode reabrir o mesmo `linkOnboarding` para corrigir os dados — e você acompanha tudo por [webhook](./webhooks-por-conta.md) ou pelo endpoint de [consulta do KYC](./kyc/api-account-register-get.mdx).

---

## Como recuperar os dados do KYC via API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Depois que o seu cliente final preenche o link de KYC ([criado via API](./api-onboarding-create.mdx)), você pode recuperar todos os dados cadastrados — incluindo a selfie, documento de identidade e contrato social — através do _endpoint_ `GET /api/v1/account-register/:id`.

Esse endpoint é útil para sincronizar o status do cadastro com o seu sistema, exibir os dados do KYC no painel do merchant ou armazenar uma cópia dos documentos enviados.

:::info
Antes de usar este endpoint, garanta que sua empresa possui a feature **BAAS** habilitada e que sua aplicação tenha o scope **`ACCOUNT_REGISTER_GET`**. Veja [Primeiros passos com a API de KYC Onboarding](./api-getting-started.mdx) para detalhes de autenticação.
:::

:::tip Referência completa
Para o schema, parâmetros e exemplos interativos, veja a [API Reference](/api#tag/account-register).
:::

## Path Parameter

- **`:id`**: pode ser tanto o **CNPJ** quanto o **`correlationID`** do registro de conta. A API detecta automaticamente o formato:
  - Se o valor for um CNPJ válido (com ou sem máscara), buscamos pelo `taxID`.
  - Caso contrário, buscamos pelo `correlationID` informado na criação do onboarding.

A API filtra os resultados pela sua empresa — você só consegue recuperar registros vinculados à conta que está autenticando a chamada.

## Exemplo de resposta

Após uma requisição bem-sucedida, o _status code_ será `200` e o `body` da resposta retornará os dados do `AccountRegister`:

```json
{
  "status": "APPROVED",
  "officialName": "RAZAO_SOCIAL_DA_EMPRESA",
  "tradeName": "NOME_FANTASIA_DA_EMPRESA",
  "type": "LIMITED_COMPANY",
  "taxID": {
    "taxID": "XXXXXXXXXXXXXX",
    "type": "BR:CNPJ"
  },
  "correlationID": "my-unique-id",
  "requestReason": null,
  "documents": [
    {
      "type": "SOCIAL_CONTRACT",
      "url": "https://woovi-baas.s3.amazonaws.com/...?X-Amz-Signature=..."
    }
  ],
  "representatives": [
    {
      "name": "NOME_DO_SOCIO",
      "taxID": {
        "taxID": "XXXXXXXXXXX",
        "type": "BR:CPF"
      },
      "birthdate": "1990-01-15",
      "email": "socio@empresa.com",
      "address": {
        "zipcode": "XXXXXXXX",
        "street": "Rua Exemplo",
        "number": "100",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP",
        "complement": "Sala 1"
      },
      "documents": [
        {
          "type": "PICTURE",
          "url": "https://woovi-baas.s3.amazonaws.com/...?X-Amz-Signature=..."
        },
        {
          "type": "IDENTITY_FRONT",
          "url": "https://woovi-baas.s3.amazonaws.com/...?X-Amz-Signature=..."
        },
        {
          "type": "IDENTITY_BACK",
          "url": "https://woovi-baas.s3.amazonaws.com/...?X-Amz-Signature=..."
        }
      ]
    }
  ]
}
```

:::warning URLs dos documentos são temporárias
Os campos `url` dentro de `documents` e `representatives[].documents` são **URLs pré-assinadas** do S3 e expiram após alguns minutos. Não armazene a URL — se você precisa manter uma cópia do documento, baixe o arquivo e armazene-o no seu próprio storage.
:::

:::info Conta bancária criada
Quando o `status` for `APPROVED`, a resposta também inclui os dados da `companyBankAccount` provisionada (número da conta, agência, etc.).
:::

## Status possíveis

| Status | Significado |
|--------|-------------|
| `PENDING` | Cadastro criado, aguardando o cliente final preencher o link |
| `IN_REVIEW` | Cliente submeteu os dados; em análise pela Woovi |
| `APPROVED` | KYC aprovado e conta bancária provisionada |
| `REJECTED` | KYC rejeitado — verifique o campo `requestReason` para o motivo |
| `FAILED` | Erro na criação da conta — necessário reenvio |
| `CREATING` | Provisionamento da conta em andamento |
| `DELETED` | Cadastro removido pelo cliente final |

## Tipos de documento

**Documentos da empresa** (`documents[].type`):

- `SOCIAL_CONTRACT` — Contrato social
- `ATA` — Ata
- `BYLAWS` — Estatuto

**Documentos do representante** (`representatives[].documents[].type`):

- `PICTURE` — Selfie do sócio
- `IDENTITY_FRONT` — RG (frente)
- `IDENTITY_BACK` — RG (verso)
- `CNH` — CNH (documento único)
- `CNH_FRONT` — CNH (frente)
- `CNH_BACK` — CNH (verso)

## Códigos de resposta

| Status | Descrição |
|--------|-----------|
| `200` | Dados retornados com sucesso |
| `400` | Header `Authorization` ausente, `id` inválido ou empresa não encontrada |
| `401` | Credenciais inválidas |
| `403` | Empresa sem feature BAAS habilitada ou aplicação sem o scope `ACCOUNT_REGISTER_GET` |
| `404` | Nenhum `AccountRegister` encontrado para o `id` informado |
| `500` | Erro interno |

### Exemplos de erro

```json
{
  "error": "Invalid Authorization header"
}
```

```json
{
  "error": "account register not found"
}
```

## Exemplos em código

  

```sh
# Buscar por CNPJ
curl 'https://api.woovi.com/api/v1/account-register/XX.XXX.XXX/0001-XX' \
    -H "Accept: application/json" \
    -H "Authorization: SEU_APPID_AQUI"

# Buscar por correlationID
curl 'https://api.woovi.com/api/v1/account-register/my-unique-id' \
    -H "Accept: application/json" \
    -H "Authorization: SEU_APPID_AQUI"
```

  
  

```js
const appId = 'SEU_APPID_AQUI';

// Pode ser CNPJ (com ou sem máscara) ou correlationID
const id = 'my-unique-id';

const response = await fetch(
  `https://api.woovi.com/api/v1/account-register/${encodeURIComponent(id)}`,
  {
    method: 'GET',
    headers: {
      'Accept': 'application/json',
      'Authorization': appId,
    },
  },
);

const accountRegister = await response.json();

console.log(accountRegister.status);
// APPROVED

const selfie = accountRegister.representatives[0].documents.find(
  (doc) => doc.type === 'PICTURE',
);

console.log(selfie.url);
// https://woovi-baas.s3.amazonaws.com/...?X-Amz-Signature=...
```

  

## Fluxo recomendado

1. **Crie o onboarding** via [`POST /api/v1/kyc/onboarding`](./api-onboarding-create.mdx) e envie o `linkOnboarding` ao seu cliente.
2. **Aguarde o preenchimento** — o cliente final acessa o link, preenche os dados e envia os documentos.
3. **Detecte a conclusão** — aguarde os webhooks do onboarding (veja [Como acompanhar o onboarding em tempo real por webhooks](./webhooks-ciclo-de-vida.mdx)) ou, em último caso, faça polling neste endpoint.
4. **Quando `status` for `APPROVED`** — chame este endpoint para sincronizar os dados no seu sistema e baixar os documentos enviados (lembre-se que as URLs são temporárias).

---

## Como enviar o cadastro (KYC) via API? (legado)

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::caution Endpoint descontinuado (legado)
O _endpoint_ `POST /api/v1/account-register` é o **formato antigo** de cadastro (KYC) por API e está **descontinuado**. Ele é mantido apenas para os clientes que já estão integrados com ele e por isso esta página **não aparece no menu lateral nem na busca** — o acesso é somente por link direto.

Para **novas integrações**, use o link de onboarding: [`POST /api/v1/kyc/onboarding`](./api-onboarding-create.mdx). Nesse fluxo o seu cliente final preenche os dados e envia os documentos por uma tela hospedada pela Woovi, sem que você precise coletar, hospedar e enviar arquivos.

Este endpoint também **não está publicado** na [API Reference](/api) — o schema abaixo é a documentação de referência dele.
:::

Neste formato legado, é a **sua aplicação** que coleta todos os dados cadastrais da empresa (razão social, CNPJ, endereço de cobrança, dados do negócio), dos sócios e as URLs dos documentos, e envia tudo de uma vez para a Woovi através do _endpoint_ `POST /api/v1/account-register`.

O cadastro é criado com `status` `PENDING` e segue para análise. Depois disso, você acompanha o andamento e recupera os dados pelo _endpoint_ [`GET /api/v1/account-register/:id`](./api-account-register-get.mdx).

:::info
Antes de usar este endpoint, garanta que sua empresa possui a feature **BAAS** habilitada e que sua aplicação tenha o scope **`ACCOUNT_REGISTER_POST`**. A autenticação é feita pelo header `Authorization` com o seu **AppID**, igual ao [endpoint de consulta](./api-account-register-get.mdx). Veja [Primeiros passos com a API de KYC Onboarding](./api-getting-started.mdx) para detalhes de autenticação.
:::

:::tip Você provavelmente quer o link de onboarding
Se você ainda não está integrado com este endpoint, pare por aqui e siga [Como criar um onboarding KYC via API?](./api-onboarding-create.mdx). O fluxo com link é o suportado hoje e evita que você precise armazenar documentos e dados sensíveis dos sócios.
:::

## Requisição

- **Método/URL**: `POST https://api.woovi.com/api/v1/account-register`
- **Content-Type**: `application/json`
- **Scope necessário**: `ACCOUNT_REGISTER_POST`

## Campos do body

### Obrigatórios

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `officialName` | `string` | Razão social da empresa |
| `tradeName` | `string` | Nome fantasia da empresa |
| `taxID` | `string` | CNPJ da empresa |
| `documents` | `array` | Documentos da empresa (veja [Documentos da empresa](#documentos-da-empresa)) |
| `representatives` | `array` | Sócios/representantes (veja [Representantes](#representantes)) |
| `billingAddress` | `object` | Endereço de cobrança (veja [Endereço de cobrança](#endereço-de-cobrança)) |
| `businessDescription` | `string` | Website ou portal de vendas |
| `businessProduct` | `string` | Serviços que a empresa provê |
| `businessLifetime` | `string` | Há quanto tempo a empresa opera no mercado |
| `businessGoal` | `string` | Objetivo ao usar a Woovi |

### Opcionais

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `correlationID` | `string` | Identificador único do registro de conta. Se não informado, um `uuid` é gerado |

### Documentos da empresa

Cada item de `documents` é um objeto:

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `url` | `string` | URL pública do documento |
| `type` | `enum` | `SOCIAL_CONTRACT` (contrato social), `ATA` (ata) ou `BYLAWS` (estatuto) |

### Representantes

Cada item de `representatives` é um sócio. Campos **obrigatórios**: `name`, `birthDate`, `email`, `phone`, `taxID`, `address` e `documents`.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `name` | `string` | Nome do sócio |
| `birthDate` | `string` | Data de nascimento (ex: `1990-01-01T00:00:00.000Z`) |
| `email` | `string` | E-mail do sócio (formato `email`) |
| `phone` | `string` | Telefone do sócio |
| `taxID` | `string` | CPF do sócio |
| `type` | `enum` | `ADMIN` |
| `address` | `object` | Endereço do sócio (veja abaixo) |
| `documents` | `array` | Documentos do sócio (veja abaixo) |

Cada item de `representatives[].documents`:

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `url` | `string` | URL pública do documento — **obrigatório** |
| `type` | `enum` | **Obrigatório**. `IDENTITY_FRONT` (RG frente), `IDENTITY_BACK` (RG verso), `CNH_FRONT` (CNH frente), `CNH_BACK` (CNH verso) ou `PICTURE` (selfie) |

O `address` do representante tem os campos `zipcode`, `street`, `number`, `neighborhood`, `city`, `state`, `complement` e `taxID` — todos obrigatórios **exceto** `complement`.

### Endereço de cobrança

O `billingAddress` tem os campos `zipcode`, `street`, `number`, `neighborhood`, `city`, `state` e `complement` — todos obrigatórios **exceto** `complement`.

## Exemplo de requisição

```json
{
  "officialName": "Company Official Name",
  "tradeName": "Company Trade Name",
  "taxID": "12345678901234",
  "billingAddress": {
    "zipcode": "12345678",
    "street": "Test Street",
    "number": "123",
    "neighborhood": "Test Neighborhood",
    "city": "Test City"
  },
  "businessDescription": "Technology and Financial Services",
  "businessProduct": "Digital payment solutions and banking services",
  "businessLifetime": "3 years",
  "businessGoal": "To expand digital payment capabilities and improve customer experience",
  "representatives": [
    {
      "name": "John Doe",
      "birthDate": "1990-01-01T00:00:00.000Z",
      "email": "john@example.com",
      "taxID": "12345678901",
      "type": "ADMIN",
      "address": {
        "zipcode": "12345678",
        "street": "Test Street",
        "number": "123",
        "neighborhood": "Test Neighborhood",
        "city": "Test City",
        "state": "ST"
      }
    }
  ]
}
```

## Exemplo de resposta

Após uma requisição bem-sucedida, o _status code_ será `200` e o `body` da resposta retornará o `AccountRegister` criado:

```json
{
  "officialName": "Company Official Name",
  "tradeName": "Company Trade Name",
  "taxID": {
    "taxID": "12345678901234"
  },
  "status": "PENDING",
  "requestedDocuments": [],
  "correlationID": "6fe18d8e-5009-4f57-8f1d-5b084b6b83ac",
  "missingDocumentsDescription": ""
}
```

:::warning Documentos pendentes
Quando faltarem documentos para a análise, os campos `requestedDocuments` e `missingDocumentsDescription` indicam o que ainda precisa ser enviado. O cadastro permanece em `PENDING` até que a documentação esteja completa.
:::

## Códigos de resposta

| Status | Descrição |
|--------|-----------|
| `200` | Cadastro criado com sucesso |
| `400` | Erro de validação, header `Authorization` inválido ou empresa não encontrada |
| `403` | Feature não habilitada para a sua empresa |
| `500` | Erro interno |

### Exemplos de erro

O campo `error` pode ser uma **string** ou um **array** de erros de validação (`code`, `message`, `path`).

```json
{
  "error": "Invalid Authorization header"
}
```

```json
{
  "error": "Company not found"
}
```

```json
{
  "error": [
    {
      "code": "too_small",
      "message": "Official name is required",
      "path": ["officialName"]
    }
  ]
}
```

```json
{
  "error": "This feature is not enabled for your company. Contact us to active."
}
```

## Exemplos em código

  

```sh
curl --request POST \
    --url 'https://api.woovi.com/api/v1/account-register' \
    --header 'Accept: application/json' \
    --header 'Authorization: SEU_APPID_AQUI' \
    --header 'Content-Type: application/json' \
    --data '{
      "officialName": "Company Official Name",
      "tradeName": "Company Trade Name",
      "taxID": "12345678901234",
      "billingAddress": {
        "zipcode": "12345678",
        "street": "Test Street",
        "number": "123",
        "neighborhood": "Test Neighborhood",
        "city": "Test City"
      },
      "businessDescription": "Technology and Financial Services",
      "businessProduct": "Digital payment solutions and banking services",
      "businessLifetime": "3 years",
      "businessGoal": "To expand digital payment capabilities and improve customer experience",
      "representatives": [
        {
          "name": "John Doe",
          "birthDate": "1990-01-01T00:00:00.000Z",
          "email": "john@example.com",
          "taxID": "12345678901",
          "type": "ADMIN",
          "address": {
            "zipcode": "12345678",
            "street": "Test Street",
            "number": "123",
            "neighborhood": "Test Neighborhood",
            "city": "Test City",
            "state": "ST"
          }
        }
      ]
    }'
```

  
  

```js
const appId = 'SEU_APPID_AQUI';

const accountRegisterPayload = {
  officialName: 'Company Official Name',
  tradeName: 'Company Trade Name',
  taxID: '12345678901234',
  billingAddress: {
    zipcode: '12345678',
    street: 'Test Street',
    number: '123',
    neighborhood: 'Test Neighborhood',
    city: 'Test City',
  },
  businessDescription: 'Technology and Financial Services',
  businessProduct: 'Digital payment solutions and banking services',
  businessLifetime: '3 years',
  businessGoal:
    'To expand digital payment capabilities and improve customer experience',
  representatives: [
    {
      name: 'John Doe',
      birthDate: '1990-01-01T00:00:00.000Z',
      email: 'john@example.com',
      taxID: '12345678901',
      type: 'ADMIN',
      address: {
        zipcode: '12345678',
        street: 'Test Street',
        number: '123',
        neighborhood: 'Test Neighborhood',
        city: 'Test City',
        state: 'ST',
      },
    },
  ],
};

const response = await fetch('https://api.woovi.com/api/v1/account-register', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': appId,
  },
  body: JSON.stringify(accountRegisterPayload),
});

const accountRegister = await response.json();

console.log(accountRegister.status);
// PENDING

console.log(accountRegister.correlationID);
// 6fe18d8e-5009-4f57-8f1d-5b084b6b83ac
```

  

## Fluxo (legado)

1. **Colete os dados** da empresa, dos sócios e hospede os documentos em URLs acessíveis.
2. **Envie o cadastro** com `POST /api/v1/account-register` — o registro é criado em `PENDING`.
3. **Guarde o `correlationID`** retornado; ele é a chave para consultar o cadastro depois.
4. **Acompanhe o status** com [`GET /api/v1/account-register/:id`](./api-account-register-get.mdx) até que ele seja `APPROVED` (conta provisionada) ou `REJECTED`.

:::tip Migrando para o fluxo atual
Para migrar, troque o passo 1 e 2 por uma chamada a [`POST /api/v1/kyc/onboarding`](./api-onboarding-create.mdx) e envie o `linkOnboarding` retornado ao seu cliente. Os passos 3 e 4 continuam iguais — a consulta é feita pelo mesmo [endpoint de consulta](./api-account-register-get.mdx).
:::

---

## Primeiros passos com a API de KYC Onboarding

Este documento irá ajudá-lo a começar a utilizar a API de KYC Onboarding.

## Criando uma nova chave de API

O primeiro passo para começar a integrar com a API é criar uma nova chave de API.

### Passo 1 - Criar um novo aplicativo

Vá para `Api/Plugins` na barra lateral e clique em `Nova API/Plugin`.

:::caution
Caso você não esteja visualizando o sidebar API/Plugins é necessário ter a permissão correta, veja com o admin da sua empresa.
:::

### Passo 2 - Nome da integração

Dentro da tela de criação, coloque um nome para a integração e selecione `API` para integrações backend.

### Passo 3 - Criando a chave

Clique em `Salvar` para criar a nova chave de API.

### Passo 4 - Fator de autenticação

Para que a API possa ser utilizada, é necessário colocar um fator duplo de autenticação para garantir maior segurança na geração de chaves.

### Passo 5 - Copiando o AppID

Após criar a nova chave, copie o **AppID** para utilizar em suas integrações.

## Como utilizar a API

Todas as `requests` e `responses` da API usam o formato JSON.

Para que a requisição seja válida, é necessário enviar o `AppID` no header `Authorization` da requisição.

Não utilize o prefixo `Bearer`. Envie o valor bruto do `AppID` no header.

```json
{
  "Authorization": "<AppID>"
}
```

Exemplo:

```sh
curl -X POST https://api.woovi.com/api/v1/kyc/onboarding \
  -H "Content-Type: application/json" \
  -H "Authorization: SEU_APPID_AQUI" \
  -d '{"taxID": "51.238.607/0002-26"}'
```

### Requisitos

- A empresa deve possuir as features **BAAS** e **KYC_ONBOARDING_LINK** habilitadas
- A aplicação deve possuir o scope **`KYC_ONBOARDING_POST`**

## Restrições de API

- Todas as requisições devem ser criptografadas usando `https`
- As chaves de API são extremamente poderosas e devem ser armazenadas com cuidado extra
- Não compartilhe chaves com terceiros
- Não reutilize chaves entre ambientes
- Apenas gere chaves quando for necessário
- Desative chaves não utilizadas

## Erros de autenticação

Pode ocorrer de você receber uma resposta com o HTTP Status `401`, que está relacionado a um AppID inválido.

```json
{
  "error": "Unauthorized"
}
```

Caso a empresa não possua a feature BAAS habilitada, você receberá o HTTP Status `403`:

```json
{
  "error": "Company does not have BaaS feature enabled"
}
```

Caso seja inválido, é recomendado gerar um novo AppID da sua aplicação e adicionar novamente em seu sistema.

## URL Base

| Ambiente | URL |
|----------|-----|
| Produção | `https://api.woovi.com/api/v1/kyc/onboarding` |

:::tip Referência completa
Para o schema, parâmetros e exemplos interativos do endpoint, veja a [API Reference](/api#tag/kyc/POST/api/v1/kyc/onboarding).
:::

---

## Como criar um onboarding KYC via API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para iniciar o processo de KYC (Know Your Customer) de um merchant, você utiliza o _endpoint_ `POST /api/v1/kyc/onboarding`.

Este endpoint cria um registro de conta (AccountRegister) e retorna um link de onboarding que deve ser enviado ao merchant para que ele preencha seus dados cadastrais.

:::info
Antes de usar este endpoint, garanta que sua empresa possui as features **BAAS** e **KYC_ONBOARDING_LINK** habilitadas e que sua aplicação tenha o scope **`KYC_ONBOARDING_POST`**. Veja [Primeiros passos com a API de KYC Onboarding](./api-getting-started.mdx) para detalhes.
:::

:::tip Referência completa
Para o schema, parâmetros e exemplos interativos, veja a [API Reference](/api#tag/kyc/POST/api/v1/kyc/onboarding).
:::

## Campos

### Obrigatórios

- **`taxID`**: CNPJ da empresa do merchant. Aceita formato com ou sem máscara (ex: `XX.XXX.XXX/0001-XX` ou `XXXXXXXXXXXXXX`). Validado como CNPJ.

### Opcionais

- **`correlationID`**: Identificador único para idempotência. Se não informado, o CNPJ será usado como correlationID. Se a mesma `correlationID` for enviada novamente, a API retorna o link existente (200) ao invés de criar um novo.
- **`website`**: Site do merchant. Se informado, é persistido no AccountRegister e o merchant não precisa redigitá-lo no formulário de onboarding.
- **`businessDescription`**: Descrição da atividade do merchant. Se informado, é persistido no AccountRegister e **destrava automaticamente a etapa `COMPANY_DATA`** do formulário — o merchant não precisa redigitá-lo. Útil quando o parceiro BaaS já coletou essa informação no próprio funil.
- **`representatives`**: Array de sócios/representantes da empresa. Cada representante deve conter:
  - **`taxID`**: CPF do representante. Validado como CPF. Aceita formato com ou sem máscara.

:::info Não-destrutivo
`website` e `businessDescription` só são preenchidos quando estão vazios no AccountRegister. Em uma chamada idempotente (mesmo `correlationID`), um valor já informado pelo merchant **nunca é sobrescrito**.
:::

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "taxID": "XX.XXX.XXX/0001-XX",
  "correlationID": "my-unique-id",
  "website": "https://loja-do-merchant.com.br",
  "businessDescription": "Loja de roupas e acessórios femininos",
  "representatives": [
    { "taxID": "XXX.XXX.XXX-XX" },
    { "taxID": "XXX.XXX.XXX-XX" }
  ]
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `201` e no `body` da resposta, retornaremos o link de onboarding e os dados do registro de conta.

Retornaremos a seguinte resposta de exemplo:

```json
{
  "linkOnboarding": "https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5...",
  "accountRegister": {
    "status": "PENDING",
    "officialName": "RAZAO_SOCIAL_DA_EMPRESA",
    "tradeName": "NOME_FANTASIA_DA_EMPRESA",
    "taxID": {
      "taxID": "XXXXXXXXXXXXXX",
      "type": "BR:CNPJ"
    },
    "correlationID": "my-unique-id",
    "representatives": [
      {
        "name": "NOME_DO_SOCIO",
        "taxID": {
          "taxID": "XXXXXXXXXXX",
          "type": "BR:CPF"
        }
      }
    ]
  }
}
```

:::info
Os campos `officialName`, `tradeName` e `representatives[].name` são preenchidos automaticamente pelo enriquecimento de dados quando disponíveis.
:::

## Idempotência

A API é idempotente pelo campo `correlationID`. Se você enviar a mesma `correlationID` para a mesma empresa, a API retornará **200 OK** com o link de onboarding existente, sem criar um novo registro.

```sh
# Primeira chamada → 201 Created
curl -X POST https://api.woovi.com/api/v1/kyc/onboarding \
  -H "Content-Type: application/json" \
  -H "Authorization: SEU_APPID_AQUI" \
  -d '{"taxID": "XX.XXX.XXX/0001-XX", "correlationID": "order-123"}'

# Segunda chamada com mesmo correlationID → 200 OK (mesmo link)
curl -X POST https://api.woovi.com/api/v1/kyc/onboarding \
  -H "Content-Type: application/json" \
  -H "Authorization: SEU_APPID_AQUI" \
  -d '{"taxID": "XX.XXX.XXX/0001-XX", "correlationID": "order-123"}'
```

## Códigos de resposta

| Status | Descrição |
|--------|-----------|
| `200` | Onboarding já existe para este `correlationID` (idempotente) |
| `201` | Onboarding criado com sucesso |
| `400` | Input inválido (taxID ausente ou CNPJ inválido) |
| `401` | Credenciais inválidas |
| `403` | Empresa sem feature BAAS ou KYC_ONBOARDING_LINK habilitada |
| `405` | Método HTTP não permitido (use POST) |
| `409` | Já existe um onboarding para este CNPJ com outro correlationID |

### Exemplos de erro

```json
{
  "error": "Invalid input: taxID is required"
}
```

```json
{
  "error": "Invalid CNPJ"
}
```

```json
{
  "error": "An onboarding already exists for this taxID"
}
```

```json
{
  "error": "Method Not Allowed. Use POST to create an onboarding."
}
```

```json
{
  "error": "Company does not have BaaS feature enabled"
}
```

## Exemplos em código

  

```sh
curl 'https://api.woovi.com/api/v1/kyc/onboarding' -X POST \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: SEU_APPID_AQUI" \
    --data-binary '{
      "taxID": "XX.XXX.XXX/0001-XX",
      "correlationID": "my-unique-id",
      "representatives": [
        { "taxID": "XXX.XXX.XXX-XX" }
      ]
    }'
```

  
  

```js
const appId = 'SEU_APPID_AQUI';

const response = await fetch('https://api.woovi.com/api/v1/kyc/onboarding', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': appId,
  },
  body: JSON.stringify({
    taxID: 'XX.XXX.XXX/0001-XX',
    correlationID: 'my-unique-id',
    representatives: [
      { taxID: 'XXX.XXX.XXX-XX' },
    ],
  }),
});

const data = await response.json();

console.log(data.linkOnboarding);
// https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5...
```

  

## Fluxo completo

1. **Chamada da API** → Cria o onboarding e retorna o `linkOnboarding`
2. **Envie o link ao merchant** → O merchant acessa o formulário e preenche os dados
3. **Merchant preenche o cadastro** → Dados da empresa, endereço, contrato social, documentos dos sócios
4. **Merchant submete** → O status muda para `IN_REVIEW`
5. **Análise** → A equipe analisa os documentos (pode levar até 72h)
6. **Aprovação/Rejeição** → O status muda para `APPROVED` ou `REJECTED`

---

## Como incorporar o link de KYC Onboarding no seu site?

import { useState } from 'react';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

export const KycPreview = () => {
  const [status, setStatus] = useState('PENDING');
  return (
    
      <label style={{display:'flex',alignItems:'center',gap:8,marginBottom:12,fontSize:14,fontWeight:500,flexWrap:'wrap'}}>
        Renderizar com status:
        <select
          value={status}
          onChange={(e) => setStatus(e.target.value)}
          style={{padding:'6px 10px',borderRadius:6,border:'1px solid #d1d5db',background:'#fff'}}
        >
          <option value="PENDING">PENDING — em preenchimento</option>
          <option value="IN_REVIEW">IN_REVIEW — em análise</option>
          <option value="APPROVED">APPROVED — aprovado</option>
          <option value="REJECTED">REJECTED — rejeitado</option>
          <option value="NOT_FOUND">NOT_FOUND — link inválido</option>
        </select>
      </label>
      <iframe
        src={`https://kyc.woovi.com/onboarding?status=${status}`}
        title={`Pré-visualização do KYC Onboarding (${status})`}
        style={{
          width: '100%',
          height: '800px',
          border: '1px solid #e5e7eb',
          borderRadius: '12px',
          display: 'block',
          margin: '0 auto 24px',
        }}
        allow="camera; clipboard-read; clipboard-write"
      />
    
  );
};

Depois de gerar um `linkOnboarding` com o _endpoint_ [`POST /api/v1/kyc/onboarding`](./api-onboarding-create.mdx), você pode entregá-lo ao merchant de três formas:

1. **Redirecionamento** — enviar o merchant diretamente para a página de KYC (recomendado)
2. **Nova aba / popup** — abrir o KYC sem perder o contexto do seu site
3. **Iframe** — renderizar o KYC dentro de uma página do seu site

Este guia cobre as três abordagens e como detectar a conclusão do onboarding.

:::info Pré-requisitos
Antes de incorporar, você precisa ter o `linkOnboarding` em mãos. Caso ainda não tenha, siga [Como criar um onboarding KYC via API?](./api-onboarding-create.mdx).
:::

:::tip Referência completa
Para o schema, parâmetros e exemplos interativos do endpoint que gera o `linkOnboarding`, veja a [API Reference](/api#tag/kyc/POST/api/v1/kyc/onboarding).
:::

:::tip Experiência white-label (sem a logo da Woovi)
Para uma integração white-label, você pode ocultar a logo da Woovi no topo do formulário adicionando `?embed=true` à URL de onboarding. Veja [Como ocultar a logo da Woovi no link de onboarding?](./api-onboarding-white-label.mdx).
:::

## Opção 1 — Redirecionamento (recomendado)

A forma mais simples e segura de integrar é redirecionar o merchant diretamente para o `linkOnboarding`. O merchant preenche todo o cadastro na página da Woovi e, quando terminar, você pode trazê-lo de volta via um botão no seu sistema ou consultando o status pela API.

```html
<a href="https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5..." >
  Iniciar cadastro KYC
</a>
```

Ou, programaticamente:

```js
window.location.href = data.linkOnboarding;
```

## Opção 2 — Nova aba / popup

Se você quer manter o merchant no seu site enquanto ele preenche o KYC, abra o link em uma nova aba:

```html
<a
  href="https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5..."
  target="_blank"
  rel="noopener noreferrer"
>
  Iniciar cadastro KYC
</a>
```

Ou como popup:

```js
const popup = window.open(
  data.linkOnboarding,
  'woovi-kyc',
  'width=480,height=800',
);
```

## Opção 3 — Iframe

O frontend de KYC **não envia headers `X-Frame-Options` nem `Content-Security-Policy: frame-ancestors`**, então é possível renderizá-lo dentro de um `<iframe>` no seu site.

```html
<iframe
  src="https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5..."
  width="100%"
  height="900"
  style="border: 0; max-width: 640px;"
  title="Cadastro KYC"
  allow="camera; clipboard-read; clipboard-write"
></iframe>
```

### Atributos recomendados

| Atributo | Valor sugerido | Por quê |
|----------|----------------|---------|
| `width` | `100%` (até ~640px) | O formulário é otimizado para telas estreitas/mobile |
| `height` | `900` ou mais | O formulário é multi-step e pode precisar de scroll interno |
| `allow` | `camera; clipboard-read; clipboard-write` | Útil para upload de documentos via câmera e colar dados |
| `title` | `Cadastro KYC` | Acessibilidade |

### Limitações do iframe

- **Não há comunicação `postMessage`** do KYC para a página pai. Você não recebe eventos de "formulário enviado" ou "passo concluído" dentro do iframe.
- Para saber quando o merchant finalizou o cadastro, você precisa [consultar o status via API](#detectando-a-conclusão-do-onboarding).
- Upload de arquivos dentro de iframe pode ter restrições em alguns navegadores mobile — teste o fluxo completo antes de subir para produção.

## Detectando a conclusão do onboarding

A API **não envia webhook** quando o merchant conclui o cadastro. Para saber em que estágio ele está, consulte o status do `AccountRegister` usando o `correlationID` ou `taxID` enviados na criação.

### Estados possíveis

| Status | Significado |
|--------|-------------|
| `PENDING` | Link criado, merchant ainda não submeteu |
| `IN_REVIEW` | Merchant submeteu — em análise pela equipe |
| `APPROVED` | Cadastro aprovado |
| `REJECTED` | Cadastro rejeitado |

### Estratégias

- **Polling**: consulte a cada N minutos, especialmente se o merchant estiver dentro de um iframe
- **Callback manual**: coloque um botão "Já finalizei o cadastro" no seu site que dispara a consulta
- **Verificação antes de liberar funcionalidades**: consulte o status sempre que o merchant tentar acessar recursos que dependem de KYC aprovado

## Exemplo completo — backend + iframe

  

```js
// 1. Crie o onboarding a partir do seu backend
app.post('/start-kyc', async (req, res) => {
  const { taxID, correlationID } = req.body;

  const response = await fetch('https://api.woovi.com/api/v1/kyc/onboarding', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': process.env.WOOVI_APPID,
    },
    body: JSON.stringify({
      taxID,
      correlationID,
    }),
  });

  const data = await response.json();

  // Devolva apenas o link para o frontend (nunca o AppID!)
  res.json({ linkOnboarding: data.linkOnboarding });
});
```

  
  

```html
<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Cadastro KYC — Woovi</title>
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&display=swap" rel="stylesheet">
  <style>
    *,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
    :root{
      --woovi-green:#03D69D;
      --woovi-green-dark:#02b584;
      --woovi-green-light:#e6faf4;
      --bg:#f7f8fa;
      --surface:#fff;
      --text-primary:#1a1a2e;
      --text-secondary:#6b7280;
      --text-tertiary:#9ca3af;
      --border:#e5e7eb;
      --radius:16px;
      --radius-sm:10px;
      --shadow-card:0 1px 3px rgba(0,0,0,0.04), 0 4px 24px rgba(0,0,0,0.06);
      --shadow-soft:0 1px 2px rgba(0,0,0,0.03);
    }
    html{font-family:'DM Sans',system-ui,sans-serif;color:var(--text-primary);background:var(--bg);-webkit-font-smoothing:antialiased}
    body{min-height:100vh;display:flex;flex-direction:column;align-items:center}

    .page-header{
      width:100%;
      padding:20px 24px;
      display:flex;
      align-items:center;
      justify-content:center;
      background:var(--surface);
      border-bottom:1px solid var(--border);
      position:sticky;top:0;z-index:10;
    }
    .page-header-inner{
      max-width:960px;width:100%;
      display:flex;align-items:center;justify-content:space-between;
    }
    .logo-area{display:flex;align-items:center;gap:10px}
    .logo-mark{
      width:36px;height:36px;border-radius:var(--radius-sm);
      background:var(--woovi-green);
      display:flex;align-items:center;justify-content:center;
    }
    .logo-mark svg{width:20px;height:20px}
    .logo-text{font-size:18px;font-weight:600;letter-spacing:-0.3px}
    .header-badge{
      font-size:12px;font-weight:500;
      color:var(--woovi-green-dark);
      background:var(--woovi-green-light);
      padding:5px 12px;border-radius:20px;
      display:flex;align-items:center;gap:5px;
    }
    .header-badge svg{width:14px;height:14px}

    .main-content{
      width:100%;max-width:960px;
      padding:32px 16px 48px;
      flex:1;display:flex;flex-direction:column;
    }

    .card{
      background:var(--surface);
      border-radius:var(--radius);
      box-shadow:var(--shadow-card);
      overflow:hidden;
      position:relative;
    }
    .card-header{
      padding:24px 28px 20px;
      border-bottom:1px solid var(--border);
    }
    .card-title{font-size:17px;font-weight:600;letter-spacing:-0.2px;margin-bottom:4px}
    .card-subtitle{font-size:13px;color:var(--text-secondary);line-height:1.5}

    .iframe-wrap{
      position:relative;
      min-height:860px;
      background:var(--surface);
    }
    .iframe-wrap iframe{
      display:block;
      width:100%;
      height:900px;
      border:0;
      opacity:0;
      transition:opacity 0.4s ease;
    }
    .iframe-wrap iframe.loaded{opacity:1}

    .loader{
      position:absolute;inset:0;
      display:flex;flex-direction:column;
      align-items:center;justify-content:center;
      gap:16px;
      transition:opacity 0.3s ease;
      pointer-events:none;
    }
    .loader.hidden{opacity:0}
    .spinner{
      width:36px;height:36px;
      border:3px solid var(--border);
      border-top-color:var(--woovi-green);
      border-radius:50%;
      animation:spin 0.8s linear infinite;
    }
    @keyframes spin{to{transform:rotate(360deg)}}
    .loader-text{font-size:13px;color:var(--text-tertiary);font-weight:500}

    .trust-bar{
      display:flex;align-items:center;justify-content:center;
      gap:20px;padding:20px 28px;
      border-top:1px solid var(--border);
      background:var(--bg);
      border-radius:0 0 var(--radius) var(--radius);
    }
    .trust-item{
      display:flex;align-items:center;gap:6px;
      font-size:12px;color:var(--text-tertiary);font-weight:500;
    }
    .trust-item svg{width:14px;height:14px;color:var(--text-tertiary);flex-shrink:0}

    .footer-note{
      text-align:center;
      margin-top:24px;
      font-size:12px;
      color:var(--text-tertiary);
      line-height:1.6;
    }
    .footer-note a{
      color:var(--woovi-green-dark);
      text-decoration:none;
      font-weight:500;
    }
    .footer-note a:hover{text-decoration:underline}

    @media(max-width:520px){
      .card-header{padding:20px 20px 16px}
      .trust-bar{gap:12px;padding:16px 16px;flex-wrap:wrap}
      .header-badge{display:none}
    }
  </style>
</head>
<body>

  <header class="page-header">
    <div class="page-header-inner">
      <div class="logo-area">
        <div class="logo-mark">
          <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
            <path d="M12 3L20 7.5V16.5L12 21L4 16.5V7.5L12 3Z" fill="white" fill-opacity="0.9"/>
            <path d="M12 8L16 10.5V15L12 17.5L8 15V10.5L12 8Z" fill="white" fill-opacity="0.4"/>
          </svg>
        </div>
        <span class="logo-text">Woovi</span>
      </div>
      <div class="header-badge">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
          <path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/>
        </svg>
        Ambiente seguro
      </div>
    </div>
  </header>

  <main class="main-content">
    <div class="card">
      <div class="card-header">
        <div class="card-title">Cadastro de conta</div>
        <div class="card-subtitle">Preencha seus dados para ativar sua conta Woovi. O processo leva menos de 5 minutos.</div>
      </div>

      <div class="iframe-wrap" id="iframe-wrap">
        <div class="loader" id="loader">
          <div class="spinner"></div>
          <div class="loader-text">Carregando formulário…</div>
        </div>
      </div>

      <div class="trust-bar">
        <div class="trust-item">
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
            <rect x="3" y="11" width="18" height="11" rx="2" ry="2"/>
            <path d="M7 11V7a5 5 0 0110 0v4"/>
          </svg>
          Criptografia TLS
        </div>
        <div class="trust-item">
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
            <path d="M22 11.08V12a10 10 0 11-5.93-9.14"/>
            <polyline points="22 4 12 14.01 9 11.01"/>
          </svg>
          Regulado pelo BACEN
        </div>
        <div class="trust-item">
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
            <path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/>
          </svg>
          Dados protegidos
        </div>
      </div>
    </div>

    <p class="footer-note">
      Ao continuar, você concorda com os
      <a href="#">Termos de Uso</a> e a
      <a href="#">Política de Privacidade</a> da Woovi.
    </p>
  </main>

  <script>
    (function() {
      // Substitua pelo linkOnboarding recebido do seu backend
      var linkOnboarding = 'https://kyc.woovi.com/onboarding?status=PENDING';
      var wrap = document.getElementById('iframe-wrap');
      var loader = document.getElementById('loader');

      var iframe = document.createElement('iframe');
      iframe.src = linkOnboarding;
      iframe.title = 'Cadastro KYC Woovi';
      iframe.allow = 'camera; clipboard-read; clipboard-write;';

      iframe.addEventListener('load', function() {
        iframe.classList.add('loaded');
        loader.classList.add('hidden');
      });

      wrap.appendChild(iframe);
    })();
  </script>
</body>
</html>
```

  

### Pré-visualização

Selecione um status para renderizar o `linkOnboarding` correspondente:

:::caution Nunca exponha o AppID no frontend
Sempre gere o `linkOnboarding` no seu backend. O `AppID` é uma credencial sensível e não deve ser enviado para o navegador.
:::

## Boas práticas

- **Use sempre HTTPS** na página que hospeda o iframe — browsers bloqueiam iframes HTTP em páginas HTTPS.
- **Envie um `correlationID` único** (ex: o ID do pedido no seu sistema) para facilitar a consulta de status depois.
- **Reutilize o link**: a API é idempotente por `correlationID`. Se o merchant fechar o site antes de terminar, você pode devolver o mesmo link sem criar um registro novo.
- **Comunique o passo ao merchant**: antes de abrir o iframe/redirect, explique que ele será levado para o cadastro da Woovi.
- **Trate o retorno**: após detectar `APPROVED`, libere as funcionalidades do BaaS no seu produto.

---

## Como ocultar a logo da Woovi no link de onboarding?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Ao incorporar o KYC Onboarding no seu produto (via [iframe, redirecionamento ou popup](./api-onboarding-embed.mdx)), você pode querer uma experiência **white-label**, sem a logo da Woovi no topo da página.

Para isso, o formulário tem um **modo embedded**: basta adicionar o parâmetro de query **`?embed=true`** à URL de onboarding. Quando presente, o cabeçalho com a logo da Woovi **não é exibido**.

:::info Como funciona
O modo embedded é controlado pela própria URL. Não há configuração de conta, feature ou chamada de API extra para ativá-lo — é só o parâmetro `?embed=true`. Você pode aplicá-lo a qualquer `linkOnboarding`.
:::

## O que o `?embed=true` oculta (e o que não oculta)

| Elemento | Com `?embed=true` |
|----------|-------------------|
| Cabeçalho com a logo da Woovi (topo da página) | **Ocultado** |
| Formulário multi-step (dados, endereço, sócios, documentos, termos) | Inalterado |
| Texto contratual ("WOOVI INSTITUIÇÃO DE PAGAMENTO LTDA." nos Termos) | **Mantido** — é conteúdo regulatório e não pode ser removido |
| Link "termos de uso e política de privacidade da Woovi" | Mantido |
| Título da aba do navegador (`Woovi \| KYC`) | Inalterado |

:::caution
O `?embed=true` remove apenas o **elemento visual de branding** (a logo no cabeçalho). As menções contratuais à Woovi nos Termos de Abertura de Conta são obrigatórias por regulação (BACEN) e permanecem no documento.
:::

## Como aplicar

O `linkOnboarding` retornado pela API [`POST /api/v1/kyc/onboarding`](./api-onboarding-create.mdx) vem **sem** o parâmetro. Para o modo white-label, basta anexá-lo ao link que você recebeu:

```
https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5...?embed=true
```

:::tip Combinando com outros parâmetros
Se a URL já tiver uma query string, use `&embed=true` em vez de `?embed=true`. Ex.: `...?foo=bar&embed=true`.
:::

  

```html
<iframe
  src="https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5...?embed=true"
  width="100%"
  height="900"
  style="border: 0; max-width: 640px;"
  title="Cadastro KYC"
  allow="camera; clipboard-read; clipboard-write"
></iframe>
```

  
  

```js
// linkOnboarding recebido do seu backend (sem embed)
const url = new URL(data.linkOnboarding);
url.searchParams.set('embed', 'true');

// Redireciona / abre em modo white-label
window.location.href = url.toString();
```

  

## Veja também

- [Como criar um onboarding KYC via API?](./api-onboarding-create.mdx)
- [Como incorporar o link de KYC Onboarding no seu site?](./api-onboarding-embed.mdx)

---

## Como acompanhar o onboarding em tempo real por webhooks?

Entre "criei o link de onboarding" e "a conta foi aprovada" existe um processo de vários passos que pode durar dias: o seu cliente final preenche os dados da empresa, sobe o contrato social, cadastra os sócios, faz a selfie, autoriza o BC Protege+ e assina os termos — e, no meio disso, pode ser que a análise peça um documento novo e devolva o cadastro para ele.

Em vez de fazer _polling_ no [`GET /api/v1/account-register/:id`](./api-account-register-get.mdx), você pode receber cada uma dessas transições por webhook. Esta página descreve **todos** os eventos do ciclo de vida, o que vem em cada payload e como montar, do seu lado, uma visão de "onde esse cliente parou e ele já tentou de novo?".

:::info
Os eventos `ACCOUNT_REGISTER_*` pertencem à **API Master** (a credencial BaaS que criou o onboarding), e não ao AppID da subconta — a subconta ainda nem existe quando eles começam a ser emitidos. Veja [Webhooks por conta](../webhooks-por-conta.md).
:::

## Visão geral do ciclo

```mermaid
stateDiagram-v2
    [*] --> PENDING: onboarding criado
    PENDING --> PENDING: ACCOUNT_REGISTER_STEP_UPDATED (um por passo concluido)
    PENDING --> IN_REVIEW: ACCOUNT_REGISTER_IN_REVIEW (cliente enviou)
    IN_REVIEW --> IN_REVIEW: ACCOUNT_REGISTER_DOCUMENTS_REQUESTED (RFI aberta)
    IN_REVIEW --> PENDING: ACCOUNT_REGISTER_PENDING + DOCUMENTS_REQUESTED (devolvido)
    IN_REVIEW --> IN_REVIEW: ACCOUNT_REGISTER_RFI_RESOLVED (documentos reenviados)
    IN_REVIEW --> APPROVED: ACCOUNT_REGISTER_APPROVED
    IN_REVIEW --> REJECTED: ACCOUNT_REGISTER_REJECTED
    APPROVED --> [*]
    REJECTED --> [*]
```

O ponto importante: **`IN_REVIEW` não é um estado final**. Um cadastro pode entrar em análise, voltar para `PENDING` porque faltou um documento, ser reenviado e entrar em análise de novo — quantas vezes for necessário. Todo evento carrega um contador (`retryCount`) exatamente para você saber em qual dessas voltas está.

## Os eventos

| Evento | Dispara quando | Tem `step`? |
| --- | --- | --- |
| `ACCOUNT_REGISTER_STEP_UPDATED` | o cliente conclui **um passo** do onboarding — ou o BC Protege+ bloqueia um | sim |
| `ACCOUNT_REGISTER_IN_REVIEW` | o cadastro entra em análise (envio do cliente **ou** promoção por um operador) | não |
| `ACCOUNT_REGISTER_DOCUMENTS_REQUESTED` | a análise pede documentos novos (RFI) | não |
| `ACCOUNT_REGISTER_RFI_RESOLVED` | o cliente respondeu a todos os documentos pedidos | não |
| `ACCOUNT_REGISTER_PENDING` | o cadastro volta para o cliente com pendências | não |
| `ACCOUNT_REGISTER_APPROVED` | KYC aprovado e conta provisionada | não |
| `ACCOUNT_REGISTER_REJECTED` | KYC reprovado | não |

:::tip Um evento por passo, não um evento por nome de passo
Existe **um único** evento para os onze passos do onboarding: `ACCOUNT_REGISTER_STEP_UPDATED`, com o passo dentro do payload. Um `Webhook` casa com **uma** string de evento, então um nome por passo obrigaria você a cadastrar a mesma URL onze vezes — onze linhas no console, onze segredos HMAC para rotacionar. Você faz um `switch` no campo `step` e resolve com um `if`.
:::

## Registrando os webhooks

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/webhook \
  --header 'Authorization: <SUA_API_MASTER>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "webhook": {
      "name": "onboarding - passos",
      "event": "ACCOUNT_REGISTER_STEP_UPDATED",
      "url": "https://minhaurl.exemplo/webhook/kyc",
      "authorization": "meu-token-de-verificacao",
      "isActive": true
    }
  }'
```

Repita para cada evento que você quer receber. A lista completa e sempre atualizada está em `GET /api/v1/webhook/events`.

No cadastro a Woovi faz um _handshake_: sua URL recebe um POST de teste e precisa responder `200` (use `?validate=false` para pular). A resposta traz o `hmacSecretKey` da assinatura.

## Envelope e assinatura

Todos os eventos chegam no mesmo formato, com o nome do evento no corpo:

```json
{
  "event": "ACCOUNT_REGISTER_STEP_UPDATED",
  "accountRegister": { "...": "..." }
}
```

E com os mesmos _headers_ de assinatura de qualquer webhook da Woovi:

| Header | O que é |
| --- | --- |
| `x-webhook-signature` | assinatura RSA-SHA256 em base64, feita com a chave privada da Woovi — **use esta** ([como validar](../../webhook/seguranca/webhook-signature-validation.mdx)) |
| `x-openpix-signature` | HMAC-SHA1 em base64 com o `hmacSecretKey` do seu webhook ([como validar](../../webhook/seguranca/webhook-hmac.mdx)) |

## `ACCOUNT_REGISTER_STEP_UPDATED` {#account-register-step-updated}

O evento de progresso. Um disparo por passo concluído, na hora em que o passo é concluído.

### Payload

```json
{
  "event": "ACCOUNT_REGISTER_STEP_UPDATED",
  "accountRegister": {
    "accountRegisterId": "66f0c2a1d4b2f10012ab34cd",
    "correlationID": "my-unique-id",
    "taxID": { "taxID": "12345678000199", "type": "BR:CNPJ" },
    "officialName": "EMPRESA EXEMPLO LTDA",
    "status": "PENDING",
    "completedSteps": ["COMPANY_DATA", "ADDRESS"],
    "pendingSteps": ["SOCIAL_CONTRACT", "PARTNERS", "TERMS", "REVIEW"],
    "step": "ADDRESS",
    "stepStatus": "COMPLETED",
    "stepScope": "COMPANY",
    "stepCompletedAt": "2026-09-04T14:02:11.482Z",
    "retrying": false,
    "retryCount": 0
  }
}
```

| Campo | Descrição |
| --- | --- |
| `accountRegisterId` | id do registro de conta na Woovi |
| `correlationID` | o seu identificador, informado na criação do onboarding |
| `status` | status do cadastro **no momento do evento** (`PENDING`, `IN_REVIEW`, …) |
| `completedSteps` | todos os passos de **empresa** já concluídos, acumulado |
| `pendingSteps` | os passos de empresa que ainda faltam para este cadastro |
| `step` | o passo que acabou de mudar (nome público, veja a tabela abaixo) |
| `stepStatus` | `COMPLETED` ou `BLOCKED` |
| `stepScope` | `COMPANY` ou `REPRESENTATIVE` |
| `stepCompletedAt` | quando o passo mudou (ISO 8601) |
| `retrying` / `retryCount` | veja [O cliente está tentando de novo?](#o-cliente-está-tentando-de-novo) |
| `representative` | presente quando `stepScope` é `REPRESENTATIVE` |
| `bcProtection` | presente quando o BC Protege+ bloqueia |

### Os passos

| `step` | `stepScope` | Concluído quando |
| --- | --- | --- |
| `COMPANY_DATA` | `COMPANY` | dados da empresa preenchidos |
| `ADDRESS` | `COMPANY` | endereço da empresa preenchido |
| `SOCIAL_CONTRACT` | `COMPANY` | contrato social (ou CCMEI, para MEI) enviado |
| `PARTNERS` | `COMPANY` | quadro societário completo e válido |
| `BC_PROTEGE` | `COMPANY` ou `REPRESENTATIVE` | autorização do BC Protege+ liberada |
| `TERMS` | `COMPANY` | termos aceitos |
| `REPRESENTATIVE_DOCUMENTS` | `REPRESENTATIVE` | documento de identidade do sócio enviado |
| `REPRESENTATIVE_FACEMATCH` | `REPRESENTATIVE` | selfie do sócio aprovada |
| `REPRESENTATIVE_ADDRESS` | `REPRESENTATIVE` | endereço do sócio preenchido (com ou sem comprovante) |
| `PIX_AUTH` | `REPRESENTATIVE` | autenticação por Pix do sócio concluída |

:::note
Não existe evento para o passo `REVIEW`: a conclusão da revisão **é** o `ACCOUNT_REGISTER_IN_REVIEW`. `REVIEW` aparece em `pendingSteps` até o cliente enviar o cadastro.

Um sócio do tipo `LEGAL_ENTITY` (uma holding no quadro societário) é dispensado de selfie, documentos e Pix auth — ele nunca gera eventos de escopo `REPRESENTATIVE`.
:::

### Passo de um sócio

Quando `stepScope` é `REPRESENTATIVE`, o payload identifica de qual sócio se trata e traz os passos concluídos **daquele sócio**:

```json
{
  "event": "ACCOUNT_REGISTER_STEP_UPDATED",
  "accountRegister": {
    "accountRegisterId": "66f0c2a1d4b2f10012ab34cd",
    "correlationID": "my-unique-id",
    "status": "PENDING",
    "completedSteps": ["COMPANY_DATA", "ADDRESS", "SOCIAL_CONTRACT"],
    "pendingSteps": ["PARTNERS", "TERMS", "REVIEW"],
    "step": "REPRESENTATIVE_FACEMATCH",
    "stepStatus": "COMPLETED",
    "stepScope": "REPRESENTATIVE",
    "stepCompletedAt": "2026-09-04T15:31:02.117Z",
    "retrying": false,
    "retryCount": 0,
    "representative": {
      "taxID": { "taxID": "12345678901", "type": "BR:CPF" },
      "type": "ADMIN",
      "completedSteps": ["REPRESENTATIVE_DOCUMENTS", "REPRESENTATIVE_FACEMATCH"]
    }
  }
}
```

:::caution `completedSteps` usa os nomes internos
`step` é o nome **público** e estável do passo. Já `completedSteps` (tanto o da empresa quanto o do sócio) é o array cru do cadastro, que pode conter nomes que você não verá em `step` — por exemplo `REPRESENTATIVE_ADDRESS_PROOF` (endereço com comprovante anexado) aparece ali, mas é reportado como `step: "REPRESENTATIVE_ADDRESS"`, e nomes de fluxos legados também podem aparecer. Faça a sua lógica em cima de `step`; use `completedSteps` só para exibir progresso.
:::

### Bloqueio do BC Protege+

O BC Protege+ é o único passo que também reporta um estado negativo. Quando o CNPJ ou o CPF de um sócio **não está autorizado**, o mesmo evento chega com `stepStatus: "BLOCKED"`:

```json
{
  "event": "ACCOUNT_REGISTER_STEP_UPDATED",
  "accountRegister": {
    "accountRegisterId": "66f0c2a1d4b2f10012ab34cd",
    "correlationID": "my-unique-id",
    "status": "PENDING",
    "completedSteps": ["COMPANY_DATA", "ADDRESS", "SOCIAL_CONTRACT"],
    "pendingSteps": ["BC_PROTEGE", "PARTNERS", "TERMS", "REVIEW"],
    "step": "BC_PROTEGE",
    "stepStatus": "BLOCKED",
    "stepScope": "REPRESENTATIVE",
    "stepCompletedAt": "2026-09-04T16:10:44.900Z",
    "retrying": false,
    "retryCount": 0,
    "bcProtection": {
      "scope": "REPRESENTATIVE",
      "unauthorizedTaxID": "12345678901",
      "situation": "UNAUTHORIZED"
    }
  }
}
```

- `bcProtection.scope`: `CNPJ` (a empresa) ou `REPRESENTATIVE` (um sócio)
- `bcProtection.unauthorizedTaxID`: o documento que precisa autorizar
- `bcProtection.situation`: `UNAUTHORIZED` ou `UNVERIFIED`

Quando a autorização é concedida, chega o mesmo evento com `step: "BC_PROTEGE"` e `stepStatus: "COMPLETED"`. É o gancho certo para avisar o seu cliente que ele precisa abrir o app do banco dele — é a causa mais comum de onboarding travado sem erro aparente.

## `ACCOUNT_REGISTER_IN_REVIEW` {#account-register-in-review}

O cadastro entrou em análise: a bola está com a Woovi. Chega dos **dois** caminhos possíveis, com o mesmo formato:

1. o cliente final concluiu o `REVIEW` e enviou o cadastro;
2. um operador da Woovi promoveu de volta para análise um cadastro que estava `PENDING`.

```json
{
  "event": "ACCOUNT_REGISTER_IN_REVIEW",
  "accountRegister": {
    "accountRegisterId": "66f0c2a1d4b2f10012ab34cd",
    "correlationID": "my-unique-id",
    "taxID": { "taxID": "12345678000199", "type": "BR:CNPJ" },
    "officialName": "EMPRESA EXEMPLO LTDA",
    "status": "IN_REVIEW",
    "completedSteps": ["COMPANY_DATA", "ADDRESS", "SOCIAL_CONTRACT", "PARTNERS", "TERMS"],
    "pendingSteps": ["REVIEW"],
    "retrying": true,
    "retryCount": 1
  }
}
```

Como é um evento de ciclo de vida e não de passo, ele **não** traz `step`, `stepStatus`, `stepScope` nem `stepCompletedAt`. Traz `retrying`/`retryCount`, e é aí que eles mais importam: `retrying: true` significa "este cadastro já tinha sido devolvido antes — é a segunda (ou n-ésima) vez que ele entra em análise".

## `ACCOUNT_REGISTER_DOCUMENTS_REQUESTED` {#account-register-documents-requested}

A análise pediu documentos (uma RFI — _request for information_). É o evento que diz **o que exatamente** foi pedido, e quais passos o cliente vai ter que refazer:

```json
{
  "event": "ACCOUNT_REGISTER_DOCUMENTS_REQUESTED",
  "accountRegister": {
    "accountRegisterId": "66f0c2a1d4b2f10012ab34cd",
    "correlationID": "my-unique-id",
    "taxID": { "taxID": "12345678000199", "type": "BR:CNPJ" },
    "officialName": "EMPRESA EXEMPLO LTDA",
    "status": "IN_REVIEW",
    "completedSteps": ["COMPANY_DATA", "ADDRESS", "PARTNERS", "TERMS"],
    "pendingSteps": ["SOCIAL_CONTRACT", "REVIEW"],
    "retrying": false,
    "retryCount": 1,
    "requestDocuments": ["SOCIAL_CONTRACT"],
    "requestDocumentsRepresentatives": [],
    "invalidatedSteps": ["SOCIAL_CONTRACT"]
  }
}
```

| Campo | Descrição |
| --- | --- |
| `requestDocuments` | documentos pedidos para a **empresa** |
| `requestDocumentsRepresentatives` | documentos pedidos por **sócio**, com o `taxId` de cada um |
| `invalidatedSteps` | os passos que voltaram a ficar pendentes por causa do pedido |

Pedido para um sócio:

```json
{
  "requestDocuments": [],
  "requestDocumentsRepresentatives": [
    {
      "taxId": { "taxID": "12345678901", "type": "BR:CPF" },
      "requestDocuments": ["PICTURE", "IDENTITY_DOCUMENT"]
    }
  ],
  "invalidatedSteps": ["REPRESENTATIVE_FACEMATCH", "REPRESENTATIVE_DOCUMENTS", "PARTNERS"]
}
```

Que passo cada documento invalida:

| Documento pedido | Passo que volta a pendente |
| --- | --- |
| `SOCIAL_CONTRACT`, `CCMEI`, `ATA`, `BYLAWS` | `SOCIAL_CONTRACT` |
| `ADDRESS_PROOF` (empresa) | `ADDRESS` |
| `PICTURE` | `REPRESENTATIVE_FACEMATCH` |
| `IDENTITY_DOCUMENT`, `IDENTITY_FRONT`, `IDENTITY_BACK`, `CNH`, `CNH_FRONT`, `CNH_BACK` | `REPRESENTATIVE_DOCUMENTS` |
| `ADDRESS_PROOF` (sócio) | `REPRESENTATIVE_ADDRESS_PROOF` |
| `PIX_AUTHENTICATION` | `REPRESENTATIVE_PIX_AUTH` |
| `WEBSITE`, `BUSINESS_DESCRIPTION` | nenhum — o pedido vive só em `requestDocuments` |

:::info Nem toda RFI devolve o cadastro
Uma RFI pode ser aberta com o cadastro ainda `IN_REVIEW` (o `status` do payload mostra isso). Quando a análise **devolve** o cadastro para o cliente, você recebe `ACCOUNT_REGISTER_DOCUMENTS_REQUESTED` **e** `ACCOUNT_REGISTER_PENDING` — este último com o `requestReason`, o texto que explica a pendência para o seu cliente. Os dois chegam sem ordem garantida entre si.
:::

## `ACCOUNT_REGISTER_RFI_RESOLVED` {#account-register-rfi-resolved}

O cliente respondeu: todos os documentos pedidos foram enviados e a RFI foi fechada. Mesmo formato de `IN_REVIEW`, sem campos de passo:

```json
{
  "event": "ACCOUNT_REGISTER_RFI_RESOLVED",
  "accountRegister": {
    "accountRegisterId": "66f0c2a1d4b2f10012ab34cd",
    "correlationID": "my-unique-id",
    "taxID": { "taxID": "12345678000199", "type": "BR:CNPJ" },
    "officialName": "EMPRESA EXEMPLO LTDA",
    "status": "IN_REVIEW",
    "completedSteps": ["COMPANY_DATA", "ADDRESS", "SOCIAL_CONTRACT", "PARTNERS", "TERMS"],
    "pendingSteps": ["REVIEW"],
    "retrying": false,
    "retryCount": 1
  }
}
```

O par `DOCUMENTS_REQUESTED` → `RFI_RESOLVED` é o que você usa para medir **quanto tempo o seu cliente levou para responder** a uma pendência, e para cobrar quem não respondeu.

## `ACCOUNT_REGISTER_PENDING`, `_APPROVED` e `_REJECTED`

São os três eventos que já existiam e continuam iguais:

- [`ACCOUNT_REGISTER_PENDING`](../../webhook/examples/account-register-pending-payload.mdx) — o cadastro voltou para o cliente, com `requestDocuments`, `requestReason` e `requestDocumentsRepresentatives`
- [`ACCOUNT_REGISTER_APPROVED`](../../webhook/examples/account-register-approved-payload.mdx) — aprovado; o payload traz o bloco `account` com o `accountId`, agência e conta provisionados
- [`ACCOUNT_REGISTER_REJECTED`](../../webhook/examples/account-register-rejected-payload.mdx) — reprovado, com `rejectedReason` e `rejectionCategory`

## O cliente está tentando de novo?

Todos os sete eventos carregam os mesmos dois campos:

| Campo | Significado |
| --- | --- |
| `retryCount` | quantas vezes este cadastro **já foi devolvido** para o cliente. `0` = primeira passagem |
| `retrying` | depende do evento (veja abaixo) |
| `invalidatedAt` | quando o passo foi invalidado. Só aparece em `STEP_UPDATED` com `retrying: true` |

O `retrying` responde a perguntas diferentes conforme o evento:

- em `ACCOUNT_REGISTER_STEP_UPDATED`: **este passo específico está sendo refeito**. `retrying: true` significa que o passo já tinha sido concluído, foi invalidado por uma solicitação de documentos, e o cliente acabou de refazê-lo. `invalidatedAt` diz desde quando ele estava pendente.
- em `ACCOUNT_REGISTER_IN_REVIEW`: **o cadastro inteiro está reentrando em análise** (`retryCount > 0`).
- nos demais eventos, `retrying` é sempre `false` — use `retryCount`.

:::note Só uma devolução marca uma retentativa
`retrying` sai de uma marca gravada no cadastro quando a RFI invalida o passo, e essa marca
é consumida no momento em que o passo é reconcluído. Duas consequências práticas:

- **é por passo, nunca pelo cadastro inteiro.** Uma devolução que pediu só o contrato social
  não marca `TERMS` como retentativa quando o cliente passa por ele de novo;
- **refazer um passo sem uma nova devolução não emite nada.** O evento sai só na transição
  de pendente para concluído: reenviar o mesmo documento, ou salvar o mesmo formulário duas
  vezes, não gera um segundo `STEP_UPDATED`.
:::

Na prática:

```js
const onWebhook = (body) => {
  const ar = body.accountRegister;

  if (body.event === 'ACCOUNT_REGISTER_STEP_UPDATED' && ar.retrying) {
    // o cliente refez um passo que tinha sido devolvido
    const desde = new Date(ar.invalidatedAt);
    metrics.timing('kyc.step.retry', Date.now() - desde.getTime(), {
      step: ar.step,
    });
  }

  if (body.event === 'ACCOUNT_REGISTER_IN_REVIEW' && ar.retryCount >= 2) {
    // segunda devolução: vale acionar o time de suporte
    suporte.abrirTicket(ar.correlationID, ar.retryCount);
  }
};
```

## Acompanhando o progresso

`completedSteps` e `pendingSteps` são acumulados e vêm em **todos** os eventos — inclusive nos de ciclo de vida. Isso significa que você não precisa reconstruir o estado a partir do histórico de webhooks: qualquer evento sozinho já diz onde o cadastro está.

```js
const progresso = (ar) => {
  const total = ar.completedSteps.length + ar.pendingSteps.length;

  return {
    percentual: Math.round((ar.completedSteps.length / total) * 100),
    faltando: ar.pendingSteps,
  };
};
```

`pendingSteps` é calculado para **aquele** cadastro: um MEI, uma LTDA e uma empresa sem BC Protege+ têm listas diferentes. Não presuma uma lista fixa de passos no seu código.

Para detectar **abandono**, use o `stepCompletedAt` do último `STEP_UPDATED` que você recebeu: se passaram N dias e o cadastro ainda está `PENDING` com `pendingSteps` não vazio, o cliente parou no meio. O `step` do último evento diz exatamente onde.

## Entrega, ordem e idempotência

- **A ordem não é garantida.** Cada evento é despachado de forma independente; dois eventos disparados no mesmo segundo podem chegar fora de ordem. Use `stepCompletedAt` e o par `completedSteps`/`pendingSteps` para ordenar, nunca a ordem de chegada.
- **A entrega é "pelo menos uma vez".** Nós evitamos duplicatas, mas não as tornamos impossíveis: trate o processamento como idempotente. Uma boa chave de deduplicação é `accountRegisterId` + `step` + `stepStatus` + `retryCount` (para `STEP_UPDATED`) ou `accountRegisterId` + `event` + `retryCount` (para os demais).
- **Retentativas:** se a sua URL não responder `200`, a Woovi tenta de novo em intervalos exponenciais — veja [Regras de retentativa](../../webhook/webhook-retry.md) e [Timeout](../../webhook/webhook-timeout.md).
- **Cadastros que nunca chegam a existir:** um onboarding que o cliente nunca abriu não gera nenhum evento além da criação. Não espere um evento de "expirou".

## Checklist de integração

1. Cadastre os webhooks com a **API Master**, um por evento que você quer receber.
2. Valide `x-webhook-signature` em toda entrega antes de processar.
3. Responda `200` rápido e processe de forma assíncrona.
4. Faça o processamento idempotente pelas chaves acima.
5. Guarde `completedSteps`/`pendingSteps` do último evento como o estado atual do cadastro — não reconstrua a partir do histórico.
6. Trate `stepStatus: "BLOCKED"` com `step: "BC_PROTEGE"` como um aviso acionável para o seu cliente final.
7. Reconcilie periodicamente com o [`GET /api/v1/account-register/:id`](./api-account-register-get.mdx): o webhook é o caminho rápido, a API é a fonte da verdade.

---

## woovi-kyc: Wizard React para KYC Onboarding

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# woovi-kyc

[![npm version](https://img.shields.io/npm/v/woovi-kyc.svg)](https://www.npmjs.com/package/woovi-kyc)
[![npm downloads](https://img.shields.io/npm/dm/woovi-kyc.svg)](https://www.npmjs.com/package/woovi-kyc)

Biblioteca React open-source que implementa um wizard completo de KYC Onboarding para abertura de contas Woovi. Ao invés de construir toda a UI do zero, você integra o componente `<KYCWizard />` e ele cuida de todos os passos: dados da empresa, endereço, upload de documentos, informações dos representantes e revisão final.

**Links:** [GitHub](https://github.com/jgcmarins/woovi-kyc) · [npm](https://www.npmjs.com/package/woovi-kyc) · [Demo](https://woovi-kyc-demo.vercel.app/) · [Documentação completa](https://woovi-kyc-docs.vercel.app/)

:::info Biblioteca da Comunidade
Esta biblioteca foi criada pela comunidade e **não é mantida oficialmente pela Woovi**. Para a API oficial de KYC Onboarding, consulte os [Primeiros Passos](./api-getting-started.mdx) e [Como criar um onboarding via API](./api-onboarding-create.mdx).
:::

## Instalação

  

```bash
pnpm add woovi-kyc
```

  
  

```bash
npm install woovi-kyc
```

  
  

```bash
yarn add woovi-kyc
```

  

**Peer dependencies:** `react` (>=18) e `react-dom` (>=18).

## Uso básico

```tsx
import { KYCWizard } from 'woovi-kyc';
import 'woovi-kyc/styles.css';

function App() {
  return (
    <KYCWizard
      cnpj="12345678000100"
      onFileUploaded={async (file, metadata) => {
        const url = await myUploadFunction(file, metadata);
        return url;
      }}
      onSubmit={(data) => {
        // Envie os dados para seu backend → encaminhe para a API Woovi
        console.log('Dados do onboarding:', data);
      }}
      onError={(error) => console.error(error)}
    />
  );
}
```

## Funcionalidades

- **Auto-preenchimento de CNPJ** — busca dados da empresa via BrasilAPI
- **Auto-preenchimento de CEP** — busca endereço via BrasilAPI
- **Storage agnostic** — você controla o upload de arquivos (S3, R2, GCS, etc.)
- **Callback-driven** — callbacks em cada etapa para controle total do fluxo
- **Wizard de 5 etapas** — Dados da Empresa → Endereço → Documentos → Representantes → Revisão

## Props

| Prop | Tipo | Obrigatório | Descrição |
|------|------|:-----------:|-----------|
| `cnpj` | `string` | Sim | CNPJ da empresa (somente dígitos). Auto-busca dados via BrasilAPI. |
| `onNext` | `(data) => void` | Não | Chamado quando o usuário avança uma etapa. |
| `onBack` | `(data) => void` | Não | Chamado quando o usuário volta uma etapa. |
| `onFileUploaded` | `(file, metadata) => Promise<string>` | Não | Chamado ao selecionar arquivo. Retorne a URL pública. |
| `onFileRemoved` | `(fileUrl, data) => void` | Não | Chamado ao remover um arquivo. |
| `onSubmit` | `(data) => void \| Promise<void>` | Não | Chamado ao finalizar o wizard. |
| `onError` | `(error: Error) => void` | Não | Chamado em caso de erro. |

## Integração com a API Woovi

O wizard coleta todos os dados necessários para o endpoint [`POST /api/v1/kyc/onboarding`](./api-onboarding-create.mdx). No callback `onSubmit`, envie os dados para seu backend que então encaminha para a API Woovi:

```tsx
<KYCWizard
  cnpj="12345678000100"
  onSubmit={async (data) => {
    // Seu backend recebe os dados e chama a API Woovi
    await fetch('/api/kyc/onboarding', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    });
  }}
/>
```

---

## Baas e Med

Este documento irá ajudá-lo a entender os principais conceitos de MED e qual a sua relação com BaaS.

### Gestão de MEDs (Devoluções Pix) para clientes BAAS

O MED (Mecanismo Especial de Devolução) é uma regra criada pelo Banco Central que permite que um Pix seja devolvido automaticamente quando há suspeita de fraude ou erro.

**Exemplo simples:**

Alguém fez um Pix para uma conta da sua plataforma, mas depois abriu uma reclamação dizendo que foi enganado. Esse pedido de devolução entra como um MED. Ele não devolve o dinheiro automaticamente, mas abre uma disputa entre os bancos e empresas envolvidas.

#### O que acontece quando um MED é aberto

 1. A Woovi avisa sua empresa na hora, via Webhook.
 2. Você tem 3 dias para enviar provas (como prints, conversas, termos de uso).
 3. O banco tem até 7 dias para analisar e decidir se o dinheiro será devolvido ou não.
 4. A Woovi te ajuda nesse processo — inclusive com API para envio das evidências.

#### Como a Woovi ajuda nisso

 * Envia notificação em tempo real
 * Permite enviar provas pela API
 * Tem um time de suporte pronto para te orientar
 * Dá apoio extra para empresas com muitos MEDs

---

## Saque, transferência e extrato

Este documento mostra como movimentar o saldo das contas do modo BaaS: saque, transferência entre contas e extrato.

## Saque de uma conta (API Master)

Envia o saldo da conta para a conta bancária de destino configurada para ela. O `value` é em **centavos**:

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/account/6290ccfd42831958a405debc/withdraw \
  --header 'Authorization: <MASTER_APP_ID>' \
  --header 'Content-Type: application/json' \
  --data-raw '{ "value": 7000 }'
```

Resposta `200`:

```json
{
  "withdraw": {
    "account": {
      "accountId": "6290ccfd42831958a405debc",
      "isDefault": false,
      "balance": {
        "total": 122430,
        "available": 122430,
        "blocked": 0
      }
    },
    "transaction": {
      "endToEndId": "E23114447202205191817cx6VMrbwtw6",
      "value": 7000
    }
  }
}
```

O `accountId` é o mesmo retornado por `GET /api/v1/account` — veja [Controlando as contas no modo BAAS](./baas-api-master.md).

## Transferência entre contas

Transferência interna e instantânea entre contas da sua estrutura, identificadas **pelas chaves Pix** de origem e destino:

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/transfer \
  --header 'Authorization: <APP_ID>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "value": 5000,
    "fromPixKey": "<CHAVE_PIX_DA_CONTA_ORIGEM>",
    "toPixKey": "<CHAVE_PIX_DA_CONTA_DESTINO>",
    "correlationID": "repasse-2026-08-001"
  }'
```

Resposta `200`:

```json
{
  "transaction": {
    "value": 5000,
    "time": "2026-08-24T15:33:27.165Z",
    "correlationID": "repasse-2026-08-001"
  }
}
```

:::info Habilitação
A transferência entre contas depende de habilitação na sua empresa — e o sentido conta principal → conta de cliente depende de uma habilitação adicional. Solicite ao suporte. Origem e destino precisam ser contas Woovi.
:::

O `correlationID` é opcional, mas recomendado: a API rejeita duplicatas, garantindo idempotência. Mais detalhes em [Como transferir valores entre contas](../transfer/how-to-transfer-values-between-accounts.mdx).

## Extrato

Com o AppID da própria conta:

```bash
curl --request GET \
  --url 'https://api.woovi.com/api/v1/statement?start=2026-08-01T00:00:00Z&end=2026-08-24T23:59:59Z&skip=0&limit=100' \
  --header 'Authorization: <APP_ID_DA_CONTA>'
```

Resposta `200`:

```json
[
  {
    "id": "64f1c9e8a1b2c3d4e5f60718",
    "time": "2026-08-20T14:03:11.000Z",
    "description": "Pix recebido",
    "balance": 129430,
    "value": 1500,
    "type": "CREDIT"
  }
]
```

- `limit` máximo de 100 por página; use `start`/`end` (ISO 8601) para janelas de tempo
- A API Master também pode ler o extrato de qualquer conta da empresa com `?companyBankAccount=<accountId>` — veja [Lendo outra conta com o AppId MASTER](./baas-api-master.md#lendo-outra-conta-com-o-appid-master)

---

## Suporte Baas

### Estrutura de Suporte e Ouvidoria BAAS

A Woovi oferece um suporte completo e humanizado para empresas que utilizam a solução de BaaS, garantindo que os times técnicos e operacionais consigam avançar com agilidade e segurança na integração e uso da plataforma.

**Canais de suporte disponíveis:**

 * __Chat e WhatsApp__\
Atendimento direto com o time de suporte, de segunda a sexta, das 9h às 22h. Ideal para dúvidas rápidas e resolução de problemas pontuais.

 * __Sistema de tickets__\
Para demandas mais complexas ou que envolvam investigações técnicas, é possível abrir tickets com acompanhamento estruturado.

 * __Grupo de WhatsApp com engenheiros__\
As empresas têm acesso a um grupo exclusivo com o time técnico da Woovi, o que facilita respostas rápidas durante a fase de integração ou operação em produção.

---

## Webhooks por conta

No BaaS você opera duas coisas ao mesmo tempo: a **abertura** das contas dos seus clientes e o que acontece **dentro** de cada conta aberta. São dois grupos de eventos, e eles se cadastram com credenciais diferentes.

## A regra: cada webhook pertence à credencial que o cadastrou

| O que você quer saber                                                        | Cadastre com        | Por quê                                                                       |
| ---------------------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------- |
| o andamento e o desfecho da **abertura de conta** (`ACCOUNT_REGISTER_*`)      | **API Master**      | a subconta ainda não existe quando esses eventos começam a ser emitidos       |
| o que acontece **dentro de uma conta** aberta (cobrança paga, Pix recebido…)  | **AppID da conta**  | o evento é da conta, e a entrega sai da própria conta                         |

:::caution Cadastrar no lugar errado não dá erro — dá silêncio
Os eventos `ACCOUNT_REGISTER_*` são entregues para a empresa **dona do cadastro**, que é a sua empresa master. Se você registrar `ACCOUNT_REGISTER_APPROVED` com o AppID de uma subconta, o `POST` retorna `200`, o webhook aparece cadastrado, e nada nunca chega.
:::

## Cadastrando um webhook

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/webhook \
  --header 'Authorization: <APP_ID_DA_CONTA>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "webhook": {
      "name": "pagamentos conta cliente 001",
      "event": "OPENPIX:CHARGE_COMPLETED",
      "url": "https://minhaurl.exemplo/webhook/conta-001",
      "authorization": "meu-token-de-verificacao",
      "isActive": true
    }
  }'
```

Um webhook escuta **um** evento. Para receber cinco eventos na mesma URL, faça cinco `POST` — o par URL + evento é único, então a mesma URL com eventos diferentes é aceita, e a mesma URL com o mesmo evento não.

No cadastro a Woovi faz um _handshake_: sua URL recebe um POST de teste e precisa responder `200`. Para pular essa validação (útil quando o seu endpoint ainda não está no ar), adicione `?validate=false` ao endereço do endpoint. A resposta do cadastro traz o `hmacSecretKey` daquele webhook, usado na validação de assinatura HMAC.

## Eventos de abertura de conta — cadastre com a API Master

| Evento                                 | Dispara quando                                                                    |
| -------------------------------------- | --------------------------------------------------------------------------------- |
| `ACCOUNT_REGISTER_STEP_UPDATED`        | o seu cliente conclui um passo do onboarding — ou o BC Protege+ bloqueia um passo  |
| `ACCOUNT_REGISTER_IN_REVIEW`           | o cadastro entra em análise                                                       |
| `ACCOUNT_REGISTER_DOCUMENTS_REQUESTED` | a análise pede documentos novos (RFI)                                             |
| `ACCOUNT_REGISTER_RFI_RESOLVED`        | o seu cliente respondeu a todos os documentos pedidos                             |
| `ACCOUNT_REGISTER_PENDING`             | o cadastro volta para o seu cliente com pendências                                |
| `ACCOUNT_REGISTER_APPROVED`            | KYC aprovado, conta provisionada — o payload traz `accountId`, agência e conta     |
| `ACCOUNT_REGISTER_REJECTED`            | KYC reprovado, com o motivo                                                       |

Com esses sete eventos você acompanha o onboarding inteiro sem _polling_ e sem console: cada entrega diz em que passo o cliente está, o que falta e se ele já foi devolvido antes. O detalhamento de cada payload, os onze nomes de passo, o bloqueio do BC Protege+ e o par RFI estão em **[Como acompanhar o onboarding em tempo real por webhooks](./kyc/webhooks-ciclo-de-vida.mdx)**.

## Eventos de uma conta aberta — cadastre com o AppID da conta

| Evento                                                   | Dispara quando                                |
| -------------------------------------------------------- | --------------------------------------------- |
| `OPENPIX:CHARGE_COMPLETED`                               | uma cobrança da conta é paga                  |
| `OPENPIX:CHARGE_CREATED` / `OPENPIX:CHARGE_EXPIRED`      | uma cobrança é criada / expira                |
| `OPENPIX:TRANSACTION_RECEIVED`                           | a conta recebe um Pix                         |
| `OPENPIX:TRANSACTION_REFUND_RECEIVED`                    | a conta recebe uma devolução                  |
| `OPENPIX:MOVEMENT_CONFIRMED` / `OPENPIX:MOVEMENT_FAILED` | um envio de Pix da conta é confirmado / falha |
| `COMPANY_BANK_ACCOUNT_BLOCKED`                           | os bloqueios da conta mudam                   |

A lista completa e sempre atualizada — os dois grupos juntos — está em `GET /api/v1/webhook/events`, em [Tipos de eventos de webhook](../webhook/webhook-events-type.md) e no [Explorador de eventos](../webhook/webhook-events-explorer.mdx), onde você copia o payload de exemplo já como tipo TypeScript, JSON Schema, Yup ou Zod.

## Um endpoint por conta ou um único endpoint?

Os dois funcionam, e com muitas contas o **endpoint único** é o que se sustenta: um webhook por conta significa manter N cadastros, N segredos HMAC e N rotações.

Para saber de qual conta veio cada entrega, escolha um destes:

- **caminho da URL** que você cadastrou (`/webhook/conta-001`) — o mais simples;
- **header `authorization`** configurado por webhook;
- **o próprio payload**: os eventos de conta trazem o bloco `account` (com o `clientId` da credencial) e `company`.

Nos eventos de abertura de conta use o `correlationID` — é o identificador que **você** enviou ao criar o onboarding, e ele volta em toda entrega.

## Segurança

Toda entrega chega com dois cabeçalhos de autenticidade, e eles não são a mesma coisa:

| Header                | O que é                                                                                                              |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `x-webhook-signature` | assinatura RSA-SHA256 (base64) feita com a chave privada da Woovi — **é a que você deve validar** ([como](../webhook/seguranca/webhook-signature-validation.mdx)) |
| `x-openpix-signature` | HMAC-SHA1 (base64) com o `hmacSecretKey` daquele webhook ([como](../webhook/seguranca/webhook-hmac.mdx))              |

- Valide a assinatura **antes** de processar o corpo, e rejeite a entrega que não tiver assinatura válida.
- Restrinja a origem aos [IPs oficiais da Woovi](../webhook/seguranca/webhook-ips.md).
- Responda `200` rápido e processe de forma assíncrona: quem responde devagar entra na fila de retentativas por _timeout_, não por erro.

## Limites

- Máximo de **50 webhooks por empresa** — outro motivo para preferir um endpoint único a um por conta.
- O mesmo par URL + evento não pode se repetir.
- Sem `200`, a Woovi tenta de novo — veja [Regras de retentativa](../webhook/webhook-retry.md) e [Timeout](../webhook/webhook-timeout.md).

## Não está chegando nada?

Nesta ordem:

1. **Credencial errada.** `ACCOUNT_REGISTER_*` com o AppID da subconta nunca entrega. Recadastre com a API Master.
2. **O cadastro falhou no _handshake_.** Se a sua URL não respondeu `200` no POST de teste, o webhook não foi criado. Confira listando com `GET /api/v1/webhook`.
3. **Assinatura.** Se você valida `x-webhook-signature` com a chave pública errada, a entrega chega e o seu lado descarta. As chaves estão em [Chaves públicas](../webhook/seguranca/webhook-public-keys.md).
4. **Limite de 50** atingido: o `POST` responde com erro de limite, não com `200`.
5. **Reenvie para conferir.** Veja [Reenvio de webhook](../webhook/webhook-resend.md) e [Testando webhooks](../webhook/webhook-test.md).

Se você precisa saber o estado de um cadastro agora, sem esperar evento, o [`GET /api/v1/account-register/:id`](./kyc/api-account-register-get.mdx) é a fonte da verdade — o webhook é o caminho rápido, a API é a confirmação.

---

## Cobrar Pix usando conta corrente do Banco do Brasil

### Integrando sua corrente do Banco Brasil na Woovi

## Resumo

Este documento explica como conectar a conta corrente da sua empresa, domiciliada no Banco Brasil, na Woovi. Após conectar a sua conta na Woovi é possível gerar QrCodes Pix, Links de Pagamento, usar Plugins para eCommerce, acessar APIs, gerenciar e acompanhar cobranças Pix.

Nesta modalidade os valores Pix pagos pelos seus clientes são depositados diretamente na conta corrente da sua empresa no Banco Brasil.

> *Este é um dos setups mais comuns da plataforma é usado por grandes empresas ou empresas com grandes volumes.* 
*Nesta modalidade não há necessidade de se criar uma nova conta corrente, já que é usada a conta corrente existente da sua empresa junto ao Banco Brasil.*

## 1. Obtendo o Client ID , Client Secret e Developer Api Key da sua conta Banco Brasil

Para operar usando uma conta corrente existente é necessário solicitar o  `Client ID`, `Client Secret` e `Developer Api Key` da sua conta. Para solicitar é necessário entrar em [Portal Developers BB](https://developers.bb.com.br/)

Crie uma nova Aplicação para a Woovi [Criar App BB](https://app.developers.bb.com.br/#/menu/criar?origem=criar)

![BB Woovi App](/img/integrations/bb-openpix-app.png)
![BB Woovi Link Api](/img/integrations/bb-openpix-app-vincular.png)

Consulte as Credencias da sua Aplicação BB [Consultar credenciais](https://app.developers.bb.com.br/#/menu/credenciais?origem=criar)

![BB Credentials](/img/integrations/bb-credentials.png)

## 2. Cadastrando o Client ID, Client Secret e o Developer Api Key da Sua conta corrente na plataforma Woovi

Uma vez recebido as credenciais de produção no portal Banco Brasil Developers basta cadastrar o Client ID, Client Secret e Developer Api Key 

![BB Setup](/img/integrations/setup-bb-dev.png)

É possível cadastrar mais de um token, ou múltiplas contas 

> *Nota uma vez cadastrado as credencias serão criptogrado e guardadas em ambiente com chave Assimétrica HSM. Se o token for perdido esta operação terá que ser refeita.* 

## 3. Testando o Token

Após cadastrar o Token na plataforma é possível realizar cobranças para seus clientes.

---

## Cobrar Pix usando conta corrente do Banco Original

### Integrando sua conta corrente do Banco Original

## Resumo

Este documento explica como conectar a conta corrente da sua empresa, domiciliada no Banco Original, na Woovi. Após conectar a sua conta na Woovi é possível gerar QrCodes Pix, Links de Pagamento, usar Plugins para eCommerce, acessar APIs, gerenciar e acompanhar cobranças Pix.

Nesta modalidade os valores Pix pagos pelos seus clientes são depositados diretamente na conta corrente da sua empresa no Banco Original

> *Este é um dos setups mais comuns da plataforma é usado por grandes empresas ou empresas com grandes volumes.* 
*Nesta modalidade não há necessidade de se criar uma nova conta corrente, já que é usada a conta corrente existente da sua empresa junto ao Banco Original.*

## 1. Obtendo o Client ID e Client Secret da sua conta Banco Original

Para operar usando uma conta corrente existente é necessário criar uma nova API Key em sua conta.

Veja em [Documentação](https://www.originalhub.com.br/documentacaohttps://www.originalhub.com.br/documentacao)
do Banco Original

## 2. Cadastrando Credenciais do Banco Original da sua conta corrente na plataforma Woovi

Uma vez recebido as credenciais de produção no portal do Banco Original basta cadastrá-las 

É possível cadastrar mais de um token, ou múltiplas contas 

> *Nota uma vez cadastrado as credencias serão criptogrado e guardadas em ambiente com chave Assimétrica HSM. Se o token for perdido esta operação terá que ser refeita.* 

## 3. Testando o Token

Após cadastrar o Token na plataforma é possível realizar cobranças para seus clientes.

---

## Woovi suporta quais bancos?

| Banco                                                                            | Suportamos? |
| :------------------------------------------------------------------------------- | ----------: |
| Banco do Brasil S.A.                                                             |         Sim |
| Banco da Amazônia S.A.                                                           |         Sim |
| Banco do Nordeste do Brasil S.A.                                                 |         Sim |
| Banco Nacional de Desenvolvimento Econômico e Social BNDES                       |         Sim |
| Credicoamo Crédito Rural Cooperativa                                             |         Sim |
| Credit Suisse Hedging-Griffo Corretora de Valores S.A.                           |         Sim |
| Banco Inbursa S.A.                                                               |         Sim |
| Natixis Brasil S.A. Banco Múltiplo                                               |         Sim |
| UBS Brasil Corretora de Câmbio, Títulos e Valores Mobiliários S.A.               |         Sim |
| Coop de Créd. Mútuo dos Despachantes de Trânsito de SC e Rio Grande do Sul       |         Sim |
| BNY Mellon Banco S.A.                                                            |         Sim |
| Banco Tricury S.A.                                                               |         Sim |
| Banestes S.A. Banco do Estado do Espírito Santo                                  |         Sim |
| Banco Bandepe S.A.                                                               |         Sim |
| Banco Alfa S.A.                                                                  |         Sim |
| Banco Itaú Consignado S.A.                                                       |         Sim |
| Banco Santander (Brasil) S. A.                                                   |         Sim |
| Banco Bradesco BBI S.A.                                                          |         Sim |
| Banco do Estado do Pará S.A.                                                     |         Sim |
| Banco Cargill S.A.                                                               |         Sim |
| Banco do Estado do Rio Grande do Sul S.A.                                        |         Sim |
| Banco do Estado de Sergipe S.A.                                                  |         Sim |
| Confidence Corretora de Câmbio S.A.                                              |         Sim |
| Hipercard Banco Múltiplo S.A.                                                    |         Sim |
| Banco Bradescard S.A.                                                            |         Sim |
| Goldman Sachs do Brasil Banco Múltiplo S. A.                                     |         Sim |
| Banco AndBank (Brasil) S.A.                                                      |         Sim |
| Banco Morgan Stanley S. A.                                                       |         Sim |
| Banco Crefisa S.A.                                                               |         Sim |
| Banco de Brasília S.A.                                                           |         Sim |
| Banco J. Safra S.A.                                                              |         Sim |
| Banco ABN Amro S.A.                                                              |         Sim |
| Banco KDB do Brasil S.A.                                                         |         Sim |
| Banco Inter S.A.                                                                 |         Sim |
| Haitong Banco de Investimento do Brasil S.A.                                     |         Sim |
| Banco Original do Agronegócio S.A.                                               |         Sim |
| BT Corretora de Câmbio Ltda.                                                     |         Sim |
| BBN Banco Brasileiro de Negocios S.A.                                            |         Sim |
| Banco Topazio S.A.                                                               |         Sim |
| Banco da China Brasil S.A.                                                       |         Sim |
| Uniprime Norte do Paraná - Cooperativa de Crédito Ltda.                          |         Sim |
| Cooperativa Central de Crédito - Ailos                                           |         Sim |
| Cooperativa de Crédito Rural da Região da Mogiana                                |         Sim |
| Central de Cooperativas de Economia e Crédito Mútuo do Est RS - Unicred          |         Sim |
| BRK S.A. Crédito, Financiamento e Investimento                                   |         Sim |
| Pólocred Sociedade de Crédito ao Microempreendedor e à Empresa de Pequeno Porte  |         Sim |
| Banco Finaxis S.A.                                                               |         Sim |
| Banco Confidence de Câmbio S.A.                                                  |         Sim |
| Banco B3 S.A.                                                                    |         Sim |
| Cooperativa Central de Crédito Noroeste Brasileiro Ltda - CentralCredi           |         Sim |
| Credialiança Cooperativa de Crédito Rural                                        |         Sim |
| Uniprime Central – Central Interestadual de Cooperativas de Crédito Ltda.        |         Sim |
| Planner Corretora de Valores S.A.                                                |         Sim |
| Renascença Distribuidora de Títulos e Valores Mobiliários Ltda.                  |         Sim |
| XP Investimentos Corretora de Câmbio Títulos e Valores Mobiliários S.A.          |         Sim |
| Caixa Econômica Federal                                                          |         Sim |
| Lecca Crédito, Financiamento e Investimento S/A                                  |         Sim |
| Banco Bocom BBM S.A.                                                             |         Sim |
| PortoCred S.A. Crédito, Financiamento e Investimento                             |         Sim |
| Oliveira Trust Distribuidora de Títulos e Valores Mobiliários S.A.               |         Sim |
| Magliano S.A. Corretora de Cambio e Valores Mobiliarios                          |         Sim |
| Central Cooperativa de Crédito no Estado do Espírito Santo - CECOOP              |         Sim |
| Advanced Corretora de Câmbio Ltda.                                               |         Sim |
| Standard Chartered Bank (Brasil) S.A. Banco de Investimento                      |         Sim |
| Banco Western Union do Brasil S.A.                                               |         Sim |
| Banco Rodobens SA                                                                |         Sim |
| Banco Agibank S.A.                                                               |         Sim |
| Banco Bradesco BERJ S.A.                                                         |         Sim |
| Banco Woori Bank do Brasil S.A.                                                  |         Sim |
| Brasil Plural S.A. Banco Múltiplo                                                |         Sim |
| BR Partners Banco de Investimento S.A.                                           |         Sim |
| valuepe Corretora de Valores e Câmbio S.A.                                       |         Sim |
| MS Bank S.A. Banco de Câmbio                                                     |         Sim |
| UBS Brasil Banco de Investimento S.A.                                            |         Sim |
| Caruana S.A. Sociedade de Crédito, Financiamento e Investimento                  |         Sim |
| Tullett Prebon Brasil Corretora de Valores e Câmbio Ltda.                        |         Sim |
| ICBC do Brasil Banco Múltiplo S.A.                                               |         Sim |
| Confederação Nacional das Cooperativas Centrais de Crédito e Economia Familiar e |         Sim |
| BGC Liquidez Distribuidora de Títulos e Valores Mobiliários Ltda.                |         Sim |
| Confederação Nacional das Cooperativas Centrais Unicred Ltda – Unicred do Brasil |         Sim |
| Multimoney Corretora de Câmbio Ltda                                              |         Sim |
| Get Money Corretora de Câmbio S.A.                                               |         Sim |
| Intesa Sanpaolo Brasil S.A. - Banco Múltiplo                                     |         Sim |
| Easynvest - Título Corretora de Valores SA                                       |         Sim |
| Broker Brasil Corretora de Câmbio Ltda.                                          |         Sim |
| Treviso Corretora de Câmbio S.A.                                                 |         Sim |
| Bexs Banco de Câmbio S.A.                                                        |         Sim |
| Levycam - Corretora de Câmbio e Valores Ltda.                                    |         Sim |
| Guitta Corretora de Câmbio Ltda.                                                 |         Sim |
| Facta Financeira S.A. - Crédito Financiamento e Investimento                     |         Sim |
| ICAP do Brasil Corretora de Títulos e Valores Mobiliários Ltda.                  |         Sim |
| Casa do Crédito S.A. Sociedade de Crédito ao Microempreendedor                   |         Sim |
| Commerzbank Brasil S.A. - Banco Múltiplo                                         |         Sim |
| Banco Olé Bonsucesso Consignado S.A.                                             |         Sim |
| Albatross Corretora de Câmbio e Valores S.A                                      |         Sim |
| BRL Trust Distribuidora de Títulos e Valores Mobiliários S.A.                    |         Sim |
| Pernambucanas Financiadora S.A. Crédito, Financiamento e Investimento            |         Sim |
| Guide Investimentos S.A. Corretora de Valores                                    |         Sim |
| CM Capital Markets Corretora de Câmbio, Títulos e Valores Mobiliários Ltda.      |         Sim |
| Dacasa Financeira S/A - Sociedade de Crédito, Financiamento e Investimento       |         Sim |
| Socred S.A. - Sociedade de Crédito ao Microempreendedor                          |         Sim |
| Banco Itaú BBA S.A.                                                              |         Sim |
| Ativa Investimentos S.A. Corretora de Títulos Câmbio e Valores                   |         Sim |
| HS Financeira S/A Crédito, Financiamento e Investimentos                         |         Sim |
| Cooperativa de Economia e Crédito Mútuo dos Servidores Públicos Estaduais do Rio |         Sim |
| Nova Futura Corretora de Títulos e Valores Mobiliários Ltda.                     |         Sim |
| Parmetal Distribuidora de Títulos e Valores Mobiliários Ltda.                    |         Sim |
| Fair Corretora de Câmbio S.A.                                                    |         Sim |
| Stone Pagamentos S.A.                                                            |         Sim |
| Banco Bradesco Cartões S.A.                                                      |         Sim |
| Banco BTG Pactual S.A.                                                           |         Sim |
| Banco Original S.A.                                                              |         Sim |
| Banco Arbi S.A.                                                                  |         Sim |
| Banco John Deere S.A.                                                            |         Sim |
| Banco BS2 S.A.                                                                   |         Sim |
| Banco Credit Agrícole Brasil S.A.                                                |         Sim |
| Banco Fibra S.A.                                                                 |         Sim |
| Banco Cifra S.A.                                                                 |         Sim |
| Banco Bradesco S.A.                                                              |         Sim |
| Banco Clássico S.A.                                                              |         Sim |
| Banco Máxima S.A.                                                                |         Sim |
| Banco ABC Brasil S.A.                                                            |         Sim |
| Banco Investcred Unibanco S.A.                                                   |         Sim |
| BCV - Banco de Crédito e Varejo S/A                                              |         Sim |
| Bexs Corretora de Câmbio S/A                                                     |         Sim |
| Parana Banco S. A.                                                               |         Sim |
| Nu Pagamentos S.A.                                                               |         Sim |
| Banco Fator S.A.                                                                 |         Sim |
| Banco Cédula S.A.                                                                |         Sim |
| Barigui Companhia Hipotecária                                                    |         Sim |
| HSBC Brasil S.A. Banco de Investimento                                           |         Sim |
| Sagitur Corretora de Câmbio Ltda.                                                |         Sim |
| IB Corretora de Câmbio, Títulos e Valores Mobiliários Ltda.                      |         Sim |
| Cooperativa de Crédito Rural de São Miguel do Oeste - Sulcredi/São Miguel        |         Sim |
| Senff S.A. - Crédito, Financiamento e Investimento                               |         Sim |
| Genial Investimentos Corretora de Valores Mobiliários S.A.                       |         Sim |
| Cooperativa de Crédito Rural de Primavera do Leste                               |         Sim |
| Avista S.A. Crédito, Financiamento e Investimento                                |         Sim |
| Cooperativa de Crédito Rural Coopavel                                            |         Sim |
| RB Capital Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda.    |         Sim |
| Frente Corretora de Câmbio Ltda.                                                 |         Sim |
| Cooperativa de Crédito Rural de Ouro Sulcredi/Ouro                               |         Sim |
| Carol Distribuidora de Títulos e Valores Mobiliários Ltda.                       |         Sim |
| BS2 Distribuidora de Títulos e Valores Mobiliários S.A.                          |         Sim |
| Lastro RDV Distribuidora de Títulos e Valores Mobiliários Ltda.                  |         Sim |
| Vip's Corretora de Câmbio Ltda.                                                  |         Sim |
| Banco de la Nacion Argentina                                                     |         Sim |
| BPP Instituição de Pagamento S.A.                                                |         Sim |
| Terra Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda.         |         Sim |
| Vortx Distribuidora de Títulos e Valores Mobiliários Ltda.                       |         Sim |
| Banco BMG S.A.                                                                   |         Sim |
| China Construction Bank (Brasil) Banco Múltiplo S/A                              |         Sim |
| Itaú Unibanco S.A.                                                               |         Sim |
| Banco Société Générale Brasil S.A.                                               |         Sim |
| Banco Mizuho do Brasil S.A.                                                      |         Sim |
| Banco J. P. Morgan S. A.                                                         |         Sim |
| Banco Mercantil do Brasil S.A.                                                   |         Sim |
| Banco Bradesco Financiamentos S.A.                                               |         Sim |
| Kirton Bank S.A. - Banco Múltiplo                                                |         Sim |
| Banco Capital S. A.                                                              |         Sim |
| Banco Safra S.A.                                                                 |         Sim |
| Banco MUFG Brasil S.A.                                                           |         Sim |
| Banco Sumitomo Mitsui Brasileiro S.A.                                            |         Sim |
| Banco Caixa Geral - Brasil S.A.                                                  |         Sim |
| Citibank N.A.                                                                    |         Sim |
| Banco ItauBank S.A.                                                              |         Sim |
| Deutsche Bank S.A. - Banco Alemão                                                |         Sim |
| JPMorgan Chase Bank, National Association                                        |         Sim |
| ING Bank N.V.                                                                    |         Sim |
| Banco de La Republica Oriental del Uruguay                                       |         Sim |
| Banco de La Provincia de Buenos Aires                                            |         Sim |
| Banco Credit Suisse (Brasil) S.A.                                                |         Sim |
| Senso Corretora de Câmbio e Valores Mobiliários S.A.                             |         Sim |
| Banco Luso Brasileiro S.A.                                                       |         Sim |
| Banco Industrial do Brasil S.A.                                                  |         Sim |
| Banco VR S.A.                                                                    |         Sim |
| Banco Paulista S.A.                                                              |         Sim |
| Banco Guanabara S.A.                                                             |         Sim |
| Omni Banco S.A.                                                                  |         Sim |
| Banco Pan S.A.                                                                   |         Sim |
| Banco Ficsa S. A.                                                                |         Sim |
| Banco Intercap S.A.                                                              |         Sim |
| Banco Rendimento S.A.                                                            |         Sim |
| Banco Triângulo S.A.                                                             |         Sim |
| Banco Sofisa S. A.                                                               |         Sim |
| Banco Alvorada S.A.                                                              |         Sim |
| Banco Pine S.A.                                                                  |         Sim |
| Itaú Unibanco Holding S.A.                                                       |         Sim |
| Banco Indusval S. A.                                                             |         Sim |
| Banco A. J. Renner S.A.                                                          |         Sim |
| Banco Votorantim S.A.                                                            |         Sim |
| Banco Daycoval S.A.                                                              |         Sim |
| Banco Ourinvest S.A.                                                             |         Sim |
| Banco Cetelem S.A.                                                               |         Sim |
| Banco Ribeirão Preto S.A.                                                        |         Sim |
| Banco Semear S.A.                                                                |         Sim |
| Banco Citibank S.A.                                                              |         Sim |
| Banco Modal S.A.                                                                 |         Sim |
| Banco Rabobank International Brasil S.A.                                         |         Sim |
| Banco Cooperativo Sicredi S. A.                                                  |         Sim |
| Scotiabank Brasil S.A. Banco Múltiplo                                            |         Sim |
| Banco BNP Paribas Brasil S.A.                                                    |         Sim |
| Novo Banco Continental S.A. - Banco Múltiplo                                     |         Sim |
| Banco Sistema S.A.                                                               |         Sim |
| Bank of America Merrill Lynch Banco Múltiplo S.A.                                |         Sim |
| Banco Cooperativo do Brasil S/A - Bancoob                                        |         Sim |
| Banco Keb Hana do Brasil S. A.                                                   |         Sim |

---

## Cobrar Pix usando conta corrente do Bradesco

### Integrando sua corrente do Bradesco na Woovi

## Resumo

Este documento explica como conectar a conta corrente da sua empresa, domiciliada no Bradesco, na Woovi. Após conectar a sua conta na Woovi é possível gerar QrCodes Pix, Links de Pagamento, usar Plugins para eCommerce, acessar APIs, gerenciar e acompanhar cobranças Pix.

Nesta modalidade os valores Pix pagos pelos seus clientes são depositados diretamente na conta corrente da sua empresa no Bradesco.

> *Este é um dos setups mais comuns da plataforma é usado por grandes empresas ou empresas com grandes volumes.*
*Nesta modalidade não há necessidade de se criar uma nova conta corrente, já que é usada a conta corrente existente da sua empresa junto ao Bradesco.*

## 1. Certificado A1 ou e-CNPJ
O Bradesco usa o certificado digital da sua empresa para te autenticar. Caso você  ainda não tenha ele você  consegue obter ele nesse link [Obter Certificado Digital](https://www.gov.br/pt-br/servicos/obter-certificacao-digital)

## 2. Obtendo o Client ID e Client Secret da sua conta Bradesco

Para operar usando uma conta corrente existente é necessário solicitar o `Client ID` e o `Client Secret` da sua conta. Para solicitar é necessário entrar em contato junto ao seu gerente de conta. Basta entrar em contato com seu gerente Bradesco. Este processo deverá durar alguns dias.

Uma vez cadastrado você receberá um email do Bradesco com o seu `Client ID` e `Client Secret`

Após seu cadastro no Bradesco developers você terá os seguintes elementos do Bradesco:

- `ClientID`
- `ClientSecret`
- `Certificado A1`
- `Senha Certificado A1`

## 3. Cadastrando o Token da Sua conta corrente na plataforma Woovi

Após receber o `Client ID`, `Client Secret`, `Certificado A1` e `Senha Certificado A1` você terá que cadastrar eles na platforma Woovi

![Bradesco Setup](/img/integrations/bradesco-setup.png)

É possível cadastrar mais de um token, ou múltiplas contas

> *Nota uma vez cadastrado o Token será criptogrado e guardando em ambiente com chave Assimétrica HSM. Se o token for perdido esta operação terá que ser refeita.*

## 4. Testando o Token

Após cadastrar o Token na plataforma é possível realizar cobranças para seus clientes.

---

## Cobrar Pix usando conta corrente do BS2

### Integrando sua conta corrente do BS2

## Resumo

Este documento explica como conectar a conta corrente da sua empresa, domiciliada no BS2, na Woovi. Após conectar a sua conta na Woovi é possível gerar QrCodes Pix, Links de Pagamento, usar Plugins para eCommerce, acessar APIs, gerenciar e acompanhar cobranças Pix.

Nesta modalidade os valores Pix pagos pelos seus clientes são depositados diretamente na conta corrente da sua empresa no BS2

> *Este é um dos setups mais comuns da plataforma é usado por grandes empresas ou empresas com grandes volumes.* 
*Nesta modalidade não há necessidade de se criar uma nova conta corrente, já que é usada a conta corrente existente da sua empresa junto ao BS2.*

## 1. Obtendo o Client ID e Client Secret da sua conta BS2

Para operar usando uma conta corrente existente é necessário criar uma nova API Key no Portal da [BS2 Empresas](https://app.empresas.bs2.com/bs2/). 

Clique em API Banking para gerar uma nova chave de API para ser utilizada na Woovi

![BS2 Api key ](/img/integrations/bs2-key-api.png)

## 2. Cadastrando o Client ID e Client Secret sua conta corrente na plataforma Woovi

Uma vez recebido as credenciais de produção no portal BS2 basta cadastrar o Client ID, Client Secret e Developer Api Key 

![BS2 Setup](/img/integrations/bs2-setup.png)

É possível cadastrar mais de um token, ou múltiplas contas 

> *Nota uma vez cadastrado as credencias serão criptogrado e guardadas em ambiente com chave Assimétrica HSM. Se o token for perdido esta operação terá que ser refeita.* 

## 3. Testando o Token

Após cadastrar o Token na plataforma é possível realizar cobranças para seus clientes.

---

## Cobrar Pix usando conta corrente do Flagship

### Integrando sua corrente do Flagship

## Resumo

Este documento explica como conectar a conta corrente da sua empresa, domiciliada no Flagship, na Woovi. Após conectar a sua conta na Woovi é possível gerar QrCodes Pix, Links de Pagamento, usar Plugins para eCommerce, acessar APIs, gerenciar e acompanhar cobranças Pix.

Nesta modalidade os valores Pix pagos pelos seus clientes são depositados diretamente na conta corrente da sua empresa no Flagship

> *Este é um dos setups mais comuns da plataforma é usado por grandes empresas ou empresas com grandes volumes.* 
*Nesta modalidade não há necessidade de se criar uma nova conta corrente, já que é usada a conta corrente existente da sua empresa junto ao Flagship.*

## 1. Obtendo o Account ID da sua conta Flagship

Entre em contato com o suporte da Woovi para abrir sua conta Flagship

## 2. Cadastrando o Account ID da sua conta corrente na plataforma Woovi

Uma vez recebido as credenciais de produção da sua conta no Flagship basta cadastrar o Account ID e Developer Api Key

Procure no Menu Administrador por `Ajustes` > `Pix`. Clique em `Conectar com Conta Corrente`.

![ConnectWithCompanyBankAccount](/img/integrations/new-bank-account.png)

![Flagship Setup](/img/integrations/flagship-setup.png)

É possível cadastrar mais de um token, ou múltiplas contas 

> *Nota uma vez cadastrado as credencias serão criptogrado e guardadas em ambiente com chave Assimétrica HSM. Se o token for perdido esta operação terá que ser refeita.* 

## 3. Testando o Token

Após cadastrar o Token na plataforma é possível realizar cobranças para seus clientes.

---

## Cobrar Pix usando conta corrente da Gerencia Net

### Integrando conta corrente da sua empresa da Gerencia Net na plataforma Woovi

## Resumo

Este documento explica como conectar a conta corrente da sua empresa, domiciliada na Gerencia Net, na Woovi. Após conectar a sua conta na Woovi é possível gerar QrCodes Pix, Links de Pagamento, usar Plugins para eCommerce, acessar APIs, gerenciar e acompanhar cobranças Pix.

Nesta modalidade os valores Pix pagos pelos seus clientes são depositados diretamente na conta corrente da sua empresa da Gerencia Net.

> *Este é um dos setups mais comuns da plataforma é usado por grandes empresas ou empresas com grandes volumes.* 
*Nesta modalidade é usada a conta corrente existente da sua empresa junto a Gerencia Net.*

## 1. Obtendo o Client ID e Cliente Secret na Gerencia Net

Para obter o `Client ID` e `Client Secret` na Gerencia Net, você precisa criar uma Nova Aplicação [Cadastre Nova Aplicação aqui](https://sistema.gerencianet.com.br/api/minhas-aplicacoes/nova-aplicacao). Permita todos os escopos da API Pix para produção e homologação.

Habilite todos os escopos API PIX:

![Permissoes](/img/integrations/gn-permisions.png)

## 2. Certificado de Produção

Gere um Certificado de produção na Gerencia Net para completar a integração

![Certificado](/img/integrations/gn-certificado.png)

## 3. Cadastro Chave Pix

Primeiro temos que cadastrar a sua chave Pix da sua conta Gerencianet. Normalmente é o CNPJ da sua empresa.

![Pix Key](/img/integrations/pix-key.png)

## 4. Cadastro Credenciais Gerencia Net na plataforma Woovi

![GN Setup](/img/integrations/gn-setup.png)

É possível cadastrar mais de um conta corrente na Woovi.

## 5. Pronto!

Agora você já pode cobrar os seus clientes usando a Woovi.

---

## Cobrar Pix usando conta corrente do Itaú

### Integrando conta corrente da sua empresa do Itaú na plataforma Woovi

## Resumo

Este documento explica como conectar a conta corrente da sua empresa, domiciliada no Itaú, na Woovi. Após conectar a sua conta na Woovi é possível gerar QrCodes Pix, Links de Pagamento, usar Plugins para eCommerce, acessar APIs, gerenciar e acompanhar cobranças Pix.

Nesta modalidade os valores Pix pagos pelos seus clientes são depositados diretamente na conta corrente da sua empresa do Itaú.

> *Este é um dos setups mais comuns da plataforma é usado por grandes empresas ou empresas com grandes volumes.* 
*Nesta modalidade é usada a conta corrente existente da sua empresa junto ao Itaú.*

## 1. Obtendo o código de acesso ao Itaú Developers

Para operar usando uma conta corrente existente é necessário solicitar um `Token de Acesso` *(também conhecido como código de acesso)* à sua conta. Este código permite acessar as APIs do Itaú relacionadas a sua conta corrente.

### Entre em contato com o gerente da sua conta

Para solicitar é necessário entrar em contato junto ao seu gerente de conta. Ao entrar em contato com seu gerente Itaú solicite o `Token de acesso` ao Itaú Developers. O Retorno deste processo deverá durar alguns dias.

**Importante** solicite o token para o tipo de Autenticação 2 - client credentials e mTLS.

> *Nota: Não confundir Token de Acesso, com sua chave Pix. O `Token de Acesso` permite acessar APIs e a plataforma Itaú Developers*.

### Itaú irá enviar um email com dados de acesso temporários

Uma vez cadastrado você receberá um email do Itaú com um `ClientID` e um `Código de acesso` temporário para cadastrar sua conta no Itaú developers. [Itaú Developers](https://developer.itau.com.br/) Importante esta primeira senha somente é válida por 72 horas, caso o prazo expire uma nova solicitação deve ser realizada junto ao seu gerente de conta.

![Setup Itau Developers](/img/integrations/itau-developers-setup.png)

Após concluir esta etapa você terá os seguintes elementos do Itaú:

- `ClientID` *(Enviado no corpo do email)*
- `AccessTokenTemp` *(Enviado no email dentro de um arquivo Excel anexado ao email)*

## 2. Cadastro da Chave Pix

Primeiro temos que cadastrar a sua chave Pix da sua conta Itaú. Normalmente é o CNPJ da sua empresa.

![Pix Key](/img/integrations/pix-key.png)

## 3. Cadastro do Token temporário enviado pelo Itaú na plataforma Woovi

Uma vez recebido seu `ClientID` e `AccessTokenTemp` do Itaú basta cadastrar os dados na plataforma. 

> Para sua segurança estes tokens de acesso são temporários, o certificado de acesso será gerado somente pela plataforma, sendo totalmente criptografado. Desta forma esta operação tem que ser realizada em até 72 horas. Caso o praso expire basta solicitar um novo token de acesso temporário.

### Cadastro do ClientID e AccessTokenTemp (temporário)

Para finalizar o cadastro basta cadastrar o seu `ClientID` e `AccessTokenTemp` na plataforma. Basta ir no Menu Administrador em `Ajustes` > `Pix` > `Conectar com Conta Corrente` selecionar o Banco Itaú e informar os dados.

![ConnectWithCompanyBankAccount](/img/integrations/new-bank-account.png)

![Add Token](/img/integrations/itau-bank-setup.png)

É possível cadastrar mais de um token, ou múltiplas contas. A partir desta etapa você pode descartar o email recebido com o token temporário.

## 4. Certificado em Produção

Após cadastrado dos dados temporário a própria Plataforma gera certificado de produção. A plataforma também irá regularmente manter o certificado e tokens de acessos em produção atulizados.

> *Nota: Seguindo elevados padrões de segurança uma vez gerado o certificado de produção será criptogrado, guardando em ambiente seguro com chave assimétrica e hardware HSM e não poderá ser alterado. Caso seja necessário cadastro de outra conta corrente basta repetir o processo*

## 5. Pronto!

Após cadastrar o Token na plataforma é possível realizar cobranças para seus clientes, ou criar aplicações!

---

## Visão Geral

## Integrando com o seu Banco

Essa seção contêm informações especificas do que é necessário para a integrar com 1 ou mais bancos

### Como funciona a integração?

Para a integração das APIs dos seus bancos é necessário o `Client ID` e o `Client Secret` e certificados de criptografia.

A Woovi guarda esses dados de forma criptograda e utilizada eles para acessar a API do seu banco

---

## Cobrar Pix usando conta corrente do Santander

### Integrando sua conta corrente do Santander

## Resumo

Este documento explica como conectar a conta corrente da sua empresa, domiciliada no Santander, na Woovi. Após conectar a sua conta na Woovi é possível gerar QrCodes Pix, Links de Pagamento, usar Plugins para eCommerce, acessar APIs, gerenciar e acompanhar cobranças Pix.

Nesta modalidade os valores Pix pagos pelos seus clientes são depositados diretamente na conta corrente da sua empresa no Santander

> *Este é um dos setups mais comuns da plataforma é usado por grandes empresas ou empresas com grandes volumes.* 
*Nesta modalidade não há necessidade de se criar uma nova conta corrente, já que é usada a conta corrente existente da sua empresa junto ao Santander.*

## 1. Obtendo as Crendenciais de acesso do Santander

Você consegue utilizar o ambiente de desenvolvimento (sandbox) do Santander. Para isso, basta realizar o [login](https://developer.santander.com.br/user/login), criar sua aplicação e acessar suas credenciais. Com elas, você poderá baixar a collection do postman ou integrar diretamente do seu sistema para explorar as APIs. Estas informações podem ser encontradas na [documentação técnica](https://developer.santander.com.br/api/documentacao/pix#/Cob/put_cob__txid_).

## 2. Cadastrando Credenciais Santander da sua conta corrente na plataforma Woovi

Uma vez recebido as credenciais de produção da sua conta no Santander basta cadastrar o Client ID, Client Secret e Developer Api Key

Procure no Menu Administrador por `Ajustes` > `Pix`. Clique em `Conectar com Conta Corrente`.

![ConnectWithCompanyBankAccount](/img/integrations/new-bank-account.png)

![Santander Setup](/img/integrations/santander-setup.png)

É possível cadastrar mais de um token, ou múltiplas contas 

> *Nota uma vez cadastrado as credencias serão criptogrado e guardadas em ambiente com chave Assimétrica HSM. Se o token for perdido esta operação terá que ser refeita.* 

## 4. Testando o Token

Após cadastrar o Token na plataforma é possível realizar cobranças para seus clientes.

---

## Cobrar Pix usando conta corrente do Sicoob

### Integrando sua conta corrente do Sicoob

## Resumo

Este documento explica como conectar a conta corrente da sua empresa, domiciliada no Sicoob, na Woovi. Após conectar a sua conta na Woovi é possível gerar QrCodes Pix, Links de Pagamento, usar Plugins para eCommerce, acessar APIs, gerenciar e acompanhar cobranças Pix.

Nesta modalidade os valores Pix pagos pelos seus clientes são depositados diretamente na conta corrente da sua empresa no Sicoob

> *Este é um dos setups mais comuns da plataforma é usado por grandes empresas ou empresas com grandes volumes.* 
*Nesta modalidade não há necessidade de se criar uma nova conta corrente, já que é usada a conta corrente existente da sua empresa junto ao Sicoob.*

## 1. Criando uma aplicação de teste

Depois de cadastrado no Portal Developers acesse o menu [Dashboard](https://developers.sicoob.com.br/#!/home) você terá disponibilizado às credenciais de acesso ao ambiente Sandbox. Crie sua aplicação e informe a sua `URL de Callback`

## 2. Obtendo as Crendenciais de acesso do Sicoob

As credenciais de acesso em Sandbox são disponibilizadas no menu [Dashboard](https://developers.sicoob.com.br/#!/home) que estará disponível após efetuar o login no Portal Developers. Existem três tipos de acesso para as APIs do Sicoob: `Associado`, `Associado PJ` e `Yoou`. Entenda qual tipo de autenticação você precisa utilizar no seu caso de uso e prossiga com os testes.

![Sicoob Setup](/img/integrations/dashboard-sicoob.png)

## 3. Cadastrando Credenciais Sicoob da sua conta corrente na plataforma Woovi

Uma vez recebido as credenciais de produção da sua conta no Sicoob basta cadastrar o Client ID, Client Secret e Developer Api Key

Procure no Menu Administrador por `Ajustes` > `Pix`. Clique em `Conectar com Conta Corrente`.

![ConnectWithCompanyBankAccount](/img/integrations/new-bank-account.png)

![Sicoob Setup](/img/integrations/setup-sicoob.png)

É possível cadastrar mais de um token, ou múltiplas contas 

> *Nota uma vez cadastrado as credencias serão criptogrado e guardadas em ambiente com chave Assimétrica HSM. Se o token for perdido esta operação terá que ser refeita.* 

## 4. Testando o Token

Após cadastrar o Token na plataforma é possível realizar cobranças para seus clientes.

---

## Como usar o Boleto via API

# Como utilizar o Boleto via API

## Resumo

Este documento explica como utilizar o Boleto via API para gerar e gerenciar boletos de cobrança. A integração com a API permite que você automatize a emissão de boletos, consulta de status e outras operações relacionadas.

---

## 1. Requisitos Iniciais

Antes de começar, você precisará de:

- **Funcionalidade boleto ativa**: É necessário entrar em contato com a nossa equipe para analisarmos seu modelo de negócio e habilitar essa funcionalidade.

---

## 2. Utilizando a API

Para criar uma cobrança do tipo *Boleto* você precisará acessar o endpoint de criação de cobrança:

[Criar cobrança](/api#tag/charge/GET/api/v1/charge)

O processo de criaçao de um boleto é bem simples. Basta utilizar o mesmo endpoint que o de cobrança, porém, com a adição do parâmetro `type` com o valor `BOLETO`.

:::warning Endereço do cliente é obrigatório
Diferente de uma cobrança Pix, o Boleto **exige os dados do cliente (`customer`), incluindo o endereço completo (`address`)**. Caso algum campo do endereço esteja ausente, a criação da cobrança falha com um erro como `{"error":"O código do estado do cliente é obrigatório"}`.

Os campos obrigatórios do cliente são:

- `name` — nome do cliente
- `taxID` — CPF/CNPJ do cliente
- `address.street` — logradouro
- `address.number` — número
- `address.zipcode` — CEP
- `address.neighborhood` — bairro
- `address.city` — cidade
- `address.state` — sigla do estado (UF, ex.: `SP`)

O campo `address.complement` é opcional.
:::

```json
{
  "correlationID": "9134e286-6f71-427a-bf00-241681624587",
  "value": 350,
  "type": "BOLETO",
  "comment": "good",
  "customer": {
    "name": "Dan",
    "taxID": "31324227036",
    "email": "email0@example.com",
    "phone": "5511999999999",
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Sala 10",
      "zipcode": "01310100",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP"
    }
  },
  "additionalInfo": [
    {
      "key": "Product",
      "value": "Pencil"
    },
    {
      "key": "Invoice",
      "value": "18476"
    },
    {
      "key": "Order",
      "value": "302"
    }
  ]
}
```

A resposta deve ser algo como:

```json
{
	"charge": {
		"customer": {
			"name": "Dan",
			"email": "email0@example.com",
			"phone": "+551****9999",
			"taxID": {
				"taxID": "31324227036",
				"type": "BR:CPF"
			},
			"correlationID": "7bd7e7b3-f94e-4409-8dbe-a2bc6c3ec798",
		},
		"value": 350,
		"identifier": "127a26a450414064dd0950d2f8b8a7c148e",
		"correlationID": "2fbab115-9b6a-4922-bvfe-29b21c6e490d",
		"transactionID": "127a26a450414064dd0950d2f8b8a7c148e",
		"status": "ACTIVE",
		"additionalInfo": [],
		"fee": 299,
		"discount": 0,
		"valueWithDiscount": 350,
		"expiresDate": "2025-03-20T21:44:28.313Z",
		"type": "BOLETO",
		"paymentLinkID": "f5b43c31-7466-4313-aa4e-f840818912fd",
		"createdAt": "2025-02-18T21:44:30.579Z",
		"updatedAt": "2025-02-18T21:44:30.579Z",
		"brCode": "000201010212261060014br.gov.bcb.pix2584https://api.woovi.com.br/woovi/testing?transactionID=867ba5173c734202ac659721306b38c952040000530398654040.015802BR5909LOCALHOST6009Sao Paulo62360532867ba5173c734202ac659721306b38c963044BCA",
		"expiresIn": 2592000,
		"pixKey": "a5203038ac-a0c1-410d-8028-e97b17d574bc",
		"paymentLinkUrl": "https://api.woovi.com.br/woovi/charge/brcode/image/9134e286-6f71-427a-bf00-24168162458",
		"qrCodeImage": "https://api.woovi.com.br/woovi/charge/brcode/image/9134e286-6f71-427a-bf00-241681624586.png",
		"globalID": "Q2hhcmdl3030sqY3YjRmZjNlZGQyMTBiMmxyMGFmNDZkYQ==",
		"paymentMethods": {
			"boleto": {
				"method": "BOLETO",
				"correlationID": "1",
				"boletoBarcode": "34196102600000003501099089627460513984203000",
				"boletoDigitable": "34191099098962746051539842030007610260000000350",
				"status": "CREATED",
				"value": 350,
				"fee": 299,
				"barcodeImage": "https://api.woovi.com.br/api/image/barcode/f5b43c31-7466-4313-aa4e-f83131.png"
			},
			"pix": {
				"method": "PIX_COB",
				"status": "ACTIVE",
				"value": 350,
				"txId": "73A39E313131319482855068B2FE",
				"fee": 299,
				"brCode": "Paulo62360532867ba5173c734202ac659721306b38c963044BCA",
				"transactionID": "73A39E1FE6964C8B819482855068B2FE",
				"identifier": "73A39E1FE6964C8B819482855068B2FE",
				"qrCodeImage": "https://api.woovi.com.br/woovi/charge/brcode/image/f5b43c31-7466-4313-aa4e-f840818912fd.png"
			}
		}
	},
	"correlationID": "3131313114-9b6a-4922-bvfe-29b21c6e490d",
	"brCode": "000201010212261060014br.gov.bcb.pix2584https://api.woovi.com.br/woovi/testing?transactionID=867ba5173c734202ac659721306b38c952040000530398654040.015802BR5909LOCALHOST6009Sao Paulo62360532867ba5173c734202ac659721306b38c963044BCA"
}
```

A criação de um boleto também gera um pix. É possível pagar com qualquer uma das duas opções.

---

## Boleto em Assinaturas


## Resumo

Além das cobranças avulsas, você pode usar o **boleto como forma de cobrança de
uma assinatura (recorrência)**. Nesse modelo, a cada ciclo da assinatura geramos
automaticamente um novo boleto para o seu cliente — que também pode ser pago via
Pix, já que todo boleto emitido pela Woovi expõe um QR Code Pix.

:::info Boleto precisa estar habilitado
A cobrança por boleto exige que a funcionalidade esteja ativa na sua conta. Entre
em contato com o nosso time para habilitar.
:::

---

## Como criar

Crie a assinatura pelo endpoint `POST /api/v1/subscriptions` informando:

- **`type`**: `RECURRENT`
- **`chargeType`**: `BOLETO`

```json
{
  "value": 15000,
  "type": "RECURRENT",
  "chargeType": "BOLETO",
  "customer": {
    "name": "Dan",
    "taxID": "31324227036",
    "email": "email0@example.com",
    "phone": "5511999999999"
  }
}
```

O passo a passo completo, com a resposta esperada e exemplos em cURL/JavaScript,
está em
**[Como criar uma Assinatura cobrada com Boleto usando a API?](../subscription-recurrence/subscription-with-boleto-create-api.mdx)**.

Consulte também a referência do endpoint na
[API Reference](/api#tag/subscription/POST/api/v1/subscriptions).

---

## Ciclo de vida

A cada parcela (definida por `frequency` e `dayGenerateCharge`) geramos uma
**cobrança do tipo boleto**. Essa cobrança segue o mesmo formato da
[cobrança de boleto avulsa](./boleto-api.md): traz `paymentMethods.boleto` (com
`boletoBarcode` e `boletoDigitable`) e também um Pix, de forma que o cliente pode
quitar por qualquer uma das duas opções.

---

## Webhook

Quando o boleto de uma parcela é **pago**, disparamos o webhook
`OPENPIX:CHARGE_COMPLETED` — o mesmo evento do fluxo de boleto avulso. O payload
completo, o cadastro e a validação da assinatura estão em
**[Webhook de Boleto pago](./boleto-webhook.md)**.

:::warning Pagamento não é liquidação
O webhook indica que o boleto foi **pago**, não que o valor já está disponível. A
**liquidação** ocorre depois (tipicamente D+3). Trate o webhook como "parcela
quitada", não como saldo disponível. Veja
[Conciliação de liquidação do Boleto](./boleto-reconciliation.md).
:::

---

## Resumo rápido

| Pergunta | Resposta |
| --- | --- |
| Como cobro uma assinatura por boleto? | `POST /api/v1/subscriptions` com `type: RECURRENT` e `chargeType: BOLETO`. |
| Cada parcela gera um boleto? | Sim. A cada ciclo geramos um novo boleto (que também aceita Pix). |
| Qual webhook recebo? | `OPENPIX:CHARGE_COMPLETED`, no pagamento de cada parcela. |
| O dinheiro já está disponível? | Não. Pagamento ≠ liquidação (≈ D+3). |

---

## Como usar o Boleto com Juros e Multa via API

# Como utilizar o Boleto com Juros e Multa via API

## Resumo

Este documento explica como utilizar o Boleto via API com configuração de juros e multa para gerar boletos de cobrança que aplicam encargos em caso de atraso no pagamento. A integração permite que você configure valores de juros e multa que serão aplicados após o vencimento do boleto.

---

## Observações Importantes

Antes de começar, é fundamental entender os seguintes conceitos:

### Basis Points - Como Calcular

Os valores de juros (`interests.value`) e multa (`fines.value`) devem ser informados em **basis points**.

**Basis point** é uma unidade de medida igual a 0,01% (um centésimo de um por cento). A conversão é simples:

- **1 basis point = 0,01%**
- **100 basis points = 1%**
- **1000 basis points = 10%**

**Fórmula de conversão:**
```
Valor em basis points = Percentual desejado × 100
```

**Exemplos práticos:**
- Para configurar **1% de juros**: informe `100` (1 × 100 = 100)
- Para configurar **1,5% de juros**: informe `150` (1,5 × 100 = 150)
- Para configurar **2% de multa**: informe `200` (2 × 100 = 200)
- Para configurar **0,5% de juros**: informe `50` (0,5 × 100 = 50)

### Data Limite de Pagamento (daysAfterDueDate)

O campo `daysAfterDueDate` define o **prazo adicional** após a data de vencimento do boleto para que o pagamento ainda possa ser realizado. Este campo estabelece a **data limite de pagamento**, que é distinta da data de vencimento.

**Exemplo prático:**
- Data de vencimento: **20 de janeiro**
- `daysAfterDueDate`: **5 dias**
- Data limite de pagamento: **25 de janeiro** (20 + 5 dias)

Neste exemplo, o boleto pode ser pago até o dia 25 de janeiro, mesmo tendo vencido no dia 20.

### Outras Observações

- A criação de um boleto também gera um PIX. É possível pagar com qualquer uma das duas opções.

---

## 1. Requisitos Iniciais

Antes de começar, você precisará de:

- **Funcionalidade boleto ativa**: É necessário entrar em contato com a nossa equipe para analisarmos seu modelo de negócio e habilitar essa funcionalidade.

---

## 2. Utilizando a API

Para criar uma cobrança do tipo *Boleto* com juros e multa, você precisará acessar o endpoint de criação de cobrança:

[Criar cobrança](/api#tag/charge/GET/api/v1/charge)

O processo de criação de um boleto com juros e multa é similar ao boleto comum, porém com a adição dos seguintes parâmetros:

- `interests`: Objeto contendo o valor dos juros a serem aplicados
- `fines`: Objeto contendo o valor da multa a ser aplicada
- `daysAfterDueDate`: Número de dias extras após o vencimento para ainda poder realizar o pagamento (data limite de pagamento)

### Parâmetros de Juros e Multa

- **interests.value**: Valor dos juros em basis points. Consulte a seção [Basis Points - Como Calcular](#basis-points---como-calcular) acima para entender como converter percentuais em basis points.
- **fines.value**: Valor da multa em basis points. Consulte a seção [Basis Points - Como Calcular](#basis-points---como-calcular) acima para entender como converter percentuais em basis points.
- **daysAfterDueDate**: Define o prazo adicional após a data de vencimento para que o pagamento ainda possa ser realizado, estabelecendo assim a data limite de pagamento. Consulte a seção [Data Limite de Pagamento (daysAfterDueDate)](#data-limite-de-pagamento-daysafterduedate) acima para mais detalhes.

### Exemplo de Requisição

```json
{
  "correlationID": "9134e286-6f716-427a-bf00-241681624580",
  "value": 350,
  "type": "BOLETO",
  "comment": "Produto X",
  "interests": {
    "value": 100
  },
  "fines": {
    "value": 100
  },
  "daysAfterDueDate": 1,
  "customer": {
    "name": "John Doe",
    "taxID": "31324227036",
    "email": "email0@example.com",
    "phone": "5511999999999",
    "address": {
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "TESTE",
      "number": 1,
      "street": "Rua a b e C",
      "zipcode": "00000000"
    }
  },
  "additionalInfo": [
    {
      "key": "Product",
      "value": "Pencil"
    },
    {
      "key": "Invoice",
      "value": "18476"
    },
    {
      "key": "Order",
      "value": "302"
    }
  ]
}
```

### Exemplo de Resposta

A resposta deve ser algo como:

```json
{
  "charge": {
    "customer": {
      "name": "John Doe",
      "email": "email0@example.com",
      "phone": "+5511999999999",
      "taxID": {
        "taxID": "31324227036",
        "type": "BR:CPF"
      },
      "correlationID": "dee90bf2-56ca-43ec-a21e-af387b12b2a5",
      "address": {
        "zipcode": "00000000",
        "street": "Rua a b e C",
        "number": "1",
        "neighborhood": "TESTE",
        "city": "São Paulo",
        "state": "SP"
      }
    },
    "value": 350,
    "comment": "Produto X",
    "identifier": "86f79ae121314f9d8f7f25e2aaa8f62a",
    "correlationID": "9134e286-6f716-427a-bf00-241681624580",
    "transactionID": "86f79ae121314f9d8f7f25e2aaa8f62a",
    "status": "ACTIVE",
    "additionalInfo": [
      {
        "key": "Product",
        "value": "Pencil"
      },
      {
        "key": "Invoice",
        "value": "18476"
      },
      {
        "key": "Order",
        "value": "302"
      }
    ],
    "fee": 50,
    "discount": 0,
    "valueWithDiscount": 350,
    "expiresDate": "2025-12-28T19:51:26.670Z",
    "type": "BOLETO",
    "paymentLinkID": "79a6b6f5-60f7-47b6-9771-26efcab84b1e",
    "createdAt": "2025-11-28T19:51:27.763Z",
    "updatedAt": "2025-11-28T19:51:27.763Z",
    "ensureSameTaxID": false,
    "interestsSettings": {
      "fines": {
        "value": 100
      },
      "interests": {
        "value": 100
      }
    },
    "brCode": "00020101021226870014br.gov.bcb.pix2565qr-h.woovi.digital/qr/v2/cob/9fb5f17d-d687-4337-88cd-2abd98f9d43b52040000530398654043.505802BR5917Teste_Description6009Sao_Paulo622905250514087053ef4559a0c942bd06304A66C",
    "expiresIn": 2592000,
    "pixKey": "78447c87-9961-4eb1-a2de-f60597e849e2",
    "paymentLinkUrl": "undefined/79a6b6f5-60f7-47b6-9771-26efcab84b1e",
    "qrCodeImage": "https://api.woovi.dev/openpix/charge/brcode/image/79a6b6f5-60f7-47b6-9771-26efcab84b1e.png",
    "globalID": "Q2hhcmdlOjY5MjlmZDNmZWEwZmMwM2JmYzgwMjg3Mw==",
    "paymentMethods": {
      "boleto": {
        "method": "BOLETO",
        "correlationID": "80748320",
        "boletoBarcode": "34192863800000100011570000105681500052061000",
        "boletoDigitable": "34191570070010568150600520610007286380000010001",
        "status": "CREATED",
        "value": 350,
        "fee": 50,
        "barcodeImage": "https://api.woovi.dev/api/image/barcode/79a6b6f5-60f7-47b6-9771-26efcab84b1e.png"
      },
      "pix": {
        "method": "PIX_COB",
        "status": "ACTIVE",
        "value": 350,
        "txId": "0514087053ef4559a0c942bd01f65302",
        "fee": 50,
        "brCode": "00020101021226870014br.gov.bcb.pix2565qr-h.woovi.digital/qr/v2/cob/9fb5f17d-d687-4337-88cd-2abd98f9d43b52040000530398654043.505802BR5917Teste_Description6009Sao_Paulo622905250514087053ef4559a0c942bd06304A66C",
        "transactionID": "0514087053ef4559a0c942bd01f65302",
        "identifier": "0514087053ef4559a0c942bd01f65302",
        "qrCodeImage": "https://api.woovi.dev/openpix/charge/brcode/image/79a6b6f5-60f7-47b6-9771-26efcab84b1e.png"
      }
    }
  },
  "correlationID": "9134e286-6f716-427a-bf00-241681624580",
  "brCode": "00020101021226870014br.gov.bcb.pix2565qr-h.woovi.digital/qr/v2/cob/9fb5f17d-d687-4337-88cd-2abd98f9d43b52040000530398654043.505802BR5917Teste_Description6009Sao_Paulo622905250514087053ef4559a0c942bd06304A66C"
}
```

## 3. Campos Importantes na Resposta

Na resposta da API, você encontrará o objeto `interestsSettings` que confirma as configurações de juros e multa aplicadas ao boleto:

```json
"interestsSettings": {
  "fines": {
    "value": 100
  },
  "interests": {
    "value": 100
  }
}
```

Este objeto confirma que os valores de juros e multa foram configurados corretamente. Os valores são retornados em basis points (100 = 1%).

:::caution Isso é a regra, não o valor cobrado
Os percentuais acima definem **como** os encargos são calculados. Quanto o pagador
**efetivamente pagou** de multa e juros só existe depois do pagamento, e vem em
outros campos — veja a seção abaixo.
:::

---

## 4. Como saber quanto o pagador pagou de juros e multa

Quando o boleto é pago depois do vencimento, o banco calcula os encargos e cobra
um valor acima do emitido. A Woovi devolve essa diferença **discriminada**, em
centavos:

| Campo | Descrição |
| --- | --- |
| `finesValue` | Multa que o pagador pagou. |
| `interestsValue` | Juros que o pagador pagou. |

Cada campo é **omitido quando não houve**, então um boleto pago em dia não traz
nenhum dos dois.

### Como os valores se relacionam

- `charge.value` — o valor **emitido** na cobrança
- `boleto.value` — o que o pagador **efetivamente pagou**

```
boleto.value = charge.value + finesValue + interestsValue
```

Exemplo de um boleto emitido por R$ 2.428,98 e pago com atraso:

```json
{
  "charge": { "value": 242898 },
  "boleto": {
    "value": 245000,
    "finesValue": 1902,
    "interestsValue": 200
  }
}
```

R$ 19,02 de multa e R$ 2,00 de juros, somando os R$ 21,02 pagos acima do emitido.

### Onde esses campos aparecem

| Onde | Quando usar |
| --- | --- |
| Webhook **`OPENPIX:CHARGE_COMPLETED`** | No momento do pagamento. Veja **[Webhook de Boleto pago](/docs/boleto/boleto-webhook)**. |
| Webhook **`BOLETO_SETTLED`** | No momento em que o valor é creditado na sua conta. Veja **[Conciliação de liquidação](/docs/boleto/boleto-reconciliation)**. |
| **`GET /api/v1/boleto-transaction`** | Para conciliar um período em lote, ou consultar uma transação pelo `boletoTransactionID`. |

:::note
Os valores são os **cobrados pelo banco**, não um recálculo a partir dos
percentuais que você configurou. Use-os direto na conciliação, sem refazer a conta
a partir da data de pagamento.
:::

---

## Como pagar um boleto via API


## Resumo

Este guia mostra como **pagar um boleto** usando o saldo da sua conta Woovi
através da API (fluxo *Boleto OUT*). O fluxo tem três passos:

1. **Validar** o boleto pelo código de barras (`POST /api/v1/boleto/validate`) —
   confirma o valor, o vencimento e o beneficiário antes de pagar.
2. **Criar o pagamento** (`POST /api/v1/payment`) — gera uma solicitação de
   pagamento (Movement) com status `CREATED`. Enviando `autoApprove: true`
   **nesta mesma chamada**, o pagamento já sai aprovado.
3. **Aprovar** o pagamento (`POST /api/v1/payment/approve`) — só é necessário
   quando você **não** usou `autoApprove` na criação.

:::note Valores em centavos
Todos os valores (`value`, `totalValue`) são expressos em **centavos**
(`300` = R$ 3,00).
:::

---

## Pré-requisitos

- Uma **[API MASTER](../payment/payment-how-to-request-access.md)** (header
  `Authorization: {APP_ID}`).
- A funcionalidade de **pagamentos (PIX OUT)** habilitada na conta. Se ainda não
  tiver, solicite pelo chat da plataforma —
  veja [Como solicitar acesso a pagamentos](../payment/payment-how-to-request-access.md).
- O **pagamento de boletos (Boleto OUT)** habilitado na conta — precisa ser
  solicitado ao suporte. Veja [Ativação](#ativação).
- O escopo **`BOLETO_VALIDATE_POST`** presente na sua aplicação — necessário
  para chamar o endpoint de validação (passo 1).

---

## 1. Validar o boleto

Antes de pagar, valide o código de barras para confirmar valor, vencimento e
beneficiário. Envie **apenas** o `barcode` (com 44, 47 ou 48 dígitos):

:::note Escopo necessário
Este endpoint exige que sua aplicação tenha o escopo **`BOLETO_VALIDATE_POST`**.
Se a validação retornar `403`, confira os escopos da aplicação.
:::

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/boleto/validate \
  --header 'Authorization: {APP_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "barcode": "34195148200000003001095517077320772982609000"
  }'
```

A resposta traz os dados do boleto:

```json
{
  "boleto": {
    "barcode": "34195148200000003001095517077320772982609000",
    "expiresDate": "2026-06-27T02:59:59.999Z",
    "totalValue": 300,
    "issuingEntity": {
      "code": "341",
      "name": "ITAU UNIBANCO S/A"
    },
    "finalBeneficiary": {
      "name": "WOOVI",
      "taxID": "44720743000101"
    }
  }
}
```

| Campo | Descrição |
| --- | --- |
| `barcode` | Código de barras normalizado do boleto |
| `digitable` | Linha digitável (quando o provedor retorna) |
| `expiresDate` | Data de vencimento (ISO 8601) |
| `totalValue` | Valor total a pagar, **em centavos** |
| `issuingEntity` | Instituição emissora (`code`, `name`) |
| `finalBeneficiary` | Beneficiário final (`name`, `taxID`) |

Se o código for inválido, a API responde `400` com o detalhe do erro.

📖 Endpoint completo na **Referência da API — Validar boleto**.

---

## 2. Criar o pagamento

Com o boleto validado, crie o pagamento no endpoint
Create Payment request.
Para pagar um boleto, use `type: "BOLETO"` e informe o **`boletoBarcode`**:

| Campo | Obrigatório | Descrição |
| --- | --- | --- |
| `type` | sim | `"BOLETO"` para pagamento de boleto |
| `boletoBarcode` | sim | Código de barras do boleto (44/47/48 dígitos) |
| `correlationID` | sim | Identificador único **seu** para o pagamento |
| `comment` | não | Comentário livre |
| `sourceAccountId` | não | Conta de origem; se omitido, usa a conta padrão. Veja [Como obter o accountId](../payment/payment-how-to-get-account-id.md) |
| `autoApprove` | não | `true` cria **e aprova** na mesma chamada (veja passo 3) |

:::note O valor vem do boleto validado
Diferente do PIX manual, você **não** envia o `value` nem o beneficiário no corpo
do pagamento de boleto — eles são resolvidos a partir do código de barras
validado. Basta o `boletoBarcode`.
:::

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/payment \
  --header 'Authorization: {APP_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "BOLETO",
    "boletoBarcode": "34195148200000003001095517077320772982609000",
    "comment": "teste boleto out",
    "correlationID": "boleto-out-teste-001"
  }'
```

A resposta traz o pagamento criado com status **`CREATED`** e o objeto `boleto`
com os dados resolvidos na validação:

```json
{
  "payment": {
    "value": 300,
    "status": "CREATED",
    "comment": "teste boleto out",
    "correlationID": "boleto-out-teste-001",
    "sourceAccountId": "6a0382bc2dd3cd1010cbc72d",
    "boleto": {
      "barcode": "34195148200000003001095517077320772982609000",
      "expiresDate": "2026-06-27T02:59:59.999Z",
      "totalValue": 300,
      "finalBeneficiary": {
        "name": "WOOVI",
        "taxID": "44720743000101"
      },
      "issuingEntity": {
        "code": "341",
        "name": "ITAU UNIBANCO S/A"
      }
    }
  }
}
```

O pagamento nasce em `CREATED` e **ainda não foi enviado** — é preciso aprová-lo.

### (Opcional) Criar e aprovar na mesma chamada com `autoApprove`

O `autoApprove` é uma flag **da criação** (`POST /api/v1/payment`). Enviando
`autoApprove: true` no corpo, o pagamento é criado **e aprovado** na mesma
requisição, dispensando o passo 3. Está disponível para todas as contas — basta
enviar a flag.

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/payment \
  --header 'Authorization: {APP_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "BOLETO",
    "boletoBarcode": "34195148200000003001095517077320772982609000",
    "comment": "teste boleto out",
    "correlationID": "boleto-out-teste-001",
    "autoApprove": true
  }'
```

A resposta traz o `payment` com status `APPROVED` e você **não** precisa chamar o
`/payment/approve`.

---

## 3. Aprovar o pagamento

:::note Só quando não usou `autoApprove`
Se você criou o pagamento com `autoApprove: true`, ele já está aprovado — pule
este passo. O endpoint `/api/v1/payment/approve` **não** aceita `autoApprove`; a
aprovação automática é sempre feita na criação.
:::

Quando o pagamento foi criado sem `autoApprove`, ele fica em `CREATED` e você o
aprova em uma segunda chamada, enviando o `correlationID`
(Approve a Payment Request).

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/payment/approve \
  --header 'Authorization: {APP_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "correlationID": "boleto-out-teste-001"
  }'
```

O endpoint rejeita a aprovação se o pagamento já estiver `CONFIRMED`
(`400 "Payment already confirmed"`) ou `DENIED` (`400 "Payment denied"`).

:::warning Saldo insuficiente
Ao aprovar sem saldo suficiente, a chamada retorna `400`:
`{ "error": "You do not have enough balance to make this payment" }`.
:::

---

## Máquina de status do pagamento

```
CREATED ──aprovação──▶ APPROVED ──▶ PROCESSING ──▶ CONFIRMED
                                        │
                                        └──falha──▶ FAILED
```

| `status` | Significado |
| --- | --- |
| `CREATED` | Pagamento criado, aguardando aprovação |
| `APPROVED` | Aprovado; pagamento do boleto disparado ao provedor |
| `PROCESSING` | Em processamento no provedor |
| `CONFIRMED` | Boleto **pago** (estado final) |
| `FAILED` | Falha no processamento (estado final) |

Como o pagamento é processado de forma assíncrona, acompanhe o status final pelo
webhook de movimentação ou consultando
`GET /api/v1/payment/{correlationID}`. Veja
**[Conciliação do pagamento de boleto](/docs/boleto/boleto-out-reconciliation)**.

---

## Ativação

O pagamento de boleto **não é self-service** — precisa ser habilitado na sua
conta pela Woovi.

| Recurso | Para quê | Como obter |
| --- | --- | --- |
| Pagamentos (PIX OUT) | Criar pagamentos via API | [Solicitar acesso a pagamentos](../payment/payment-how-to-request-access.md) |
| Pagamento de boletos (Boleto OUT) | Pagar boletos via API | Solicite ao suporte |

:::info
Para habilitar o pagamento de boletos, entre em contato com o suporte da Woovi
pelo chat da plataforma. Veja também
[Como criar e aprovar um pagamento em uma única chamada](../payment/payment-how-to-auto-approve.md).
:::

---

## Referência da API

Os endpoints usados neste guia, na Referência da API:

| Passo | Endpoint | Referência |
| --- | --- | --- |
| 1. Validar | `POST /api/v1/boleto/validate` | Validar boleto |
| 2. Criar | `POST /api/v1/payment` | Create Payment request |
| 3. Aprovar | `POST /api/v1/payment/approve` | Approve a Payment Request |

---

## Conciliação do pagamento de boleto


## Resumo

Depois de **pagar um boleto** pela API (fluxo *Boleto OUT* — veja
**[Como pagar um boleto via API](/docs/boleto/boleto-out-api)**), o pagamento é
processado de forma **assíncrona**. Este guia mostra as três formas de
**conciliar** e saber que o boleto foi efetivamente pago:

| Forma | Quando usar |
| --- | --- |
| **Webhook `OPENPIX:MOVEMENT_CONFIRMED`** | Você quer ser **avisado** no momento em que o pagamento é confirmado, sem ficar consultando a API. |
| **`GET /api/v1/payment/{id}`** | Você quer **consultar** o estado atual de **um** pagamento pontualmente (polling ou verificação sob demanda). |
| **`GET /api/v1/boleto-transaction`** | Você quer conciliar **em lote**, listando todos os boletos pagos em um período — e precisa da **tarifa** cobrada em cada um. |

Nas duas primeiras formas, a amarração com a sua operação é feita pelo
**`correlationID`** que você definiu na criação do pagamento. A terceira atende
aos dois casos: **listar** as transações de um período ou consultar **uma**
transação específica pelo **`boletoTransactionID`**, o id público da transação.

:::note Valores em centavos
Todos os valores (`value`) são expressos em **centavos** (`300` = R$ 3,00).
:::

---

## Máquina de status do pagamento

```
CREATED ──aprovação──▶ APPROVED ──▶ PROCESSING ──▶ CONFIRMED
                                        │
                                        └──falha──▶ FAILED
```

| `status` | Significado |
| --- | --- |
| `CREATED` | Pagamento criado, aguardando aprovação |
| `APPROVED` | Aprovado; pagamento do boleto disparado ao provedor |
| `PROCESSING` | Em processamento no provedor |
| `CONFIRMED` | Boleto **pago** (estado final) |
| `FAILED` | Falha no processamento (estado final) |

A conciliação acontece nos estados finais: **`CONFIRMED`** (pago) ou **`FAILED`**
(falha).

---

## Forma 1 — Webhook `OPENPIX:MOVEMENT_CONFIRMED`

Quando o pagamento do boleto é confirmado, a Woovi dispara o webhook
**`OPENPIX:MOVEMENT_CONFIRMED`** para a URL configurada na sua conta. É o mesmo
evento de confirmação de PIX OUT, mas no pagamento de boleto o payload traz um
objeto **`boleto`** (com `barcode` e `expiresDate`):

```json
{
  "event": "OPENPIX:MOVEMENT_CONFIRMED",
  "account": {
    "accountId": "6843167bb88789ea9046003f"
  },
  "payment": {
    "value": 300,
    "status": "CONFIRMED",
    "comment": "teste boleto out",
    "correlationID": "boleto-out-teste-006",
    "metadata": {}
  },
  "boleto": {
    "barcode": "34191091725285164077229826090002215000000000300",
    "expiresDate": "2026-07-08T02:59:59.999Z"
  }
}
```

| Campo | Descrição |
| --- | --- |
| `event` | `OPENPIX:MOVEMENT_CONFIRMED` no pagamento confirmado |
| `account.accountId` | Conta de origem que pagou o boleto |
| `payment.value` | Valor pago, **em centavos** |
| `payment.status` | `CONFIRMED` (pago) |
| `payment.correlationID` | O `correlationID` que **você** definiu ao criar o pagamento |
| `payment.metadata` | Metadados que você enviou na criação (se houver) |
| `boleto.barcode` | Código de barras do boleto pago |
| `boleto.expiresDate` | Data de vencimento do boleto (ISO 8601) |

Ao receber o webhook, use o **`payment.correlationID`** para localizar o
pagamento na sua base e marcá-lo como **pago**.

:::info Em caso de falha
Quando o pagamento falha, o evento disparado é **`OPENPIX:MOVEMENT_FAILED`**, com
`payment.status` em `FAILED` e um objeto `error` com o motivo. Veja
**[Payload de Pagamentos](/docs/webhook/examples/webhook-payment-payload)** e a
**[lista de erros de pagamento](/docs/payment/payment-failed-errors)**.
:::

Para receber esse evento, crie um webhook selecionando o evento
**`OPENPIX:MOVEMENT_CONFIRMED`** — veja
**[Tipos de eventos do Webhook](/docs/webhook/webhook-events-type#openpixmovement_confirmed)**.
A criação em si pode ser feita
**[via plataforma](/docs/webhook/platform/webhook-platform-api)** ou
**[via API](/docs/webhook/webhook-api)**; para validar a assinatura, veja
**[Validando o HMAC do webhook](/docs/webhook/seguranca/webhook-hmac)**.

---

## Forma 2 — Consultar o pagamento (`GET /api/v1/payment/{id}`)

Se preferir consultar em vez de receber o webhook, use o endpoint de pagamento
passando o `correlationID` (ou o `id`) do pagamento:

[Get one Payment request](</api#tag/payment-request-access/GET/api/v1/payment/{id}>)

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/payment/boleto-out-teste-006 \
  --header 'Authorization: {APP_ID}'
```

A resposta traz o `payment` com o **`status`** atual:

```json
{
  "payment": {
    "status": "CONFIRMED",
    "value": 300,
    "comment": "teste boleto out",
    "correlationID": "boleto-out-teste-006",
    "sourceAccountId": "6843167bb88789ea9046003f"
  }
}
```

Concilie olhando o campo **`payment.status`**:

- **`CONFIRMED`** → boleto pago (estado final, pode conciliar).
- **`FAILED`** → pagamento falhou (estado final).
- **`CREATED` / `APPROVED` / `PROCESSING`** → ainda em andamento; consulte
  novamente mais tarde.

---

## Forma 3 — Listar as transações de boleto (`GET /api/v1/boleto-transaction`)

As duas formas anteriores respondem sobre **um** pagamento. Quando o que você
precisa é fechar um período — conferir tudo que foi pago entre duas datas, com a
**tarifa** de cada boleto — use a API de transações de boleto.

Filtre por `type=BOLETO_OUT` para trazer apenas os boletos que a **sua empresa
pagou** (sem `BOLETO_OUT`, a listagem também traz os boletos que os seus
pagadores pagaram):

```bash
curl --request GET \
  --url 'https://api.woovi.com/api/v1/boleto-transaction?type=BOLETO_OUT&start=2026-07-01T00:00:00.000Z&end=2026-07-31T23:59:59.000Z' \
  --header 'Authorization: {APP_ID}'
```

```json
{
  "status": "OK",
  "pageInfo": {
    "skip": 0,
    "limit": 100,
    "hasPreviousPage": false,
    "hasNextPage": false
  },
  "boletoTransactions": [
    {
      "boletoTransactionID": "btx_019f6123d8ff7332a4a16de2ed15a3cb",
      "type": "BOLETO_OUT",
      "status": "CONFIRMED",
      "value": 3827,
      "fee": 115,
      "createdAt": "2026-07-14T14:59:27.103Z"
    }
  ]
}
```

Concilie pelo campo **`status`**: **`CONFIRMED`** é o boleto pago. O **`value`** é
o valor que saiu da sua conta e o **`fee`** é a tarifa cobrada pela operação.

Para o detalhe de **uma** transação, consulte pelo `boletoTransactionID` — é o
mesmo id que a listagem devolve e que você pode guardar na sua base para conferir
a transação depois, sem varrer o período de novo:

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/boleto-transaction/btx_019f6123d8ff7332a4a16de2ed15a3cb \
  --header 'Authorization: {APP_ID}'
```

```json
{
  "boletoTransaction": {
    "boletoTransactionID": "btx_019f6123d8ff7332a4a16de2ed15a3cb",
    "type": "BOLETO_OUT",
    "status": "CONFIRMED",
    "value": 3827,
    "fee": 115,
    "createdAt": "2026-07-14T14:59:27.103Z"
  }
}
```

:::note De onde vem o `boletoTransactionID`
No **boleto OUT** o id vem da **listagem**: o webhook `OPENPIX:MOVEMENT_CONFIRMED`
não o inclui — ele identifica o pagamento pelo `payment.correlationID`. Já no
**boleto IN** o id chega direto no webhook `BOLETO_SETTLED`, e aí você consulta a
transação sem listar nada — veja
**[Conciliação de liquidação do Boleto](/docs/boleto/boleto-reconciliation)**.
:::

:::note Escopos da aplicação
A listagem exige o escopo **`BOLETO_TRANSACTION_GET_LIST`** e o detalhe exige
**`BOLETO_TRANSACTION_GET`**. Sem o escopo correspondente a chamada responde
**`403`**.
:::

:::note Boleto OUT não tem `settledAt` nem `charge`
Esses dois campos aparecem só em transações **`BOLETO_IN`** — a liquidação é o
crédito na sua conta de um boleto que o seu pagador pagou. No `BOLETO_OUT` o
estado final é o **`status`** `CONFIRMED`.
:::

Os filtros de data (`start`/`end`) e a paginação (`skip`/`limit`) estão descritos
na **[referência da API](/api#tag/boleto)**.

---

## Fluxo recomendado

1. Crie e aprove o pagamento com um `correlationID` próprio da sua operação
   (veja **[Como pagar um boleto via API](/docs/boleto/boleto-out-api)**).
2. Prefira o **webhook `OPENPIX:MOVEMENT_CONFIRMED`** para ser avisado da
   confirmação sem polling. Amarre pelo `payment.correlationID`.
3. Como alternativa ou reforço, consulte **`GET /api/v1/payment/{correlationID}`**
   e verifique `payment.status` até chegar em `CONFIRMED` (pago) ou `FAILED`
   (falha).
4. No fechamento do dia ou do mês, rode **`GET /api/v1/boleto-transaction?type=BOLETO_OUT`**
   com o período desejado para conferir todos os pagamentos de uma vez e apurar as
   tarifas.

---

## Prazo de confirmação do Boleto


## Resumo

O boleto **não é instantâneo como o Pix**. Depois que o pagador paga, o banco
precisa **processar e confirmar** o pagamento antes de a cobrança mudar de
**pendente** para **paga** — e isso **não acontece na hora**.

:::info Boleto não é Pix
O Pix é confirmado em tempo real. O boleto depende do processamento bancário,
então é normal que a cobrança fique um tempo como **pendente** mesmo já tendo
sido paga. Se o seu cliente enviar o comprovante, **não é preciso reenviar nada
nem abrir chamado** — o status muda sozinho assim que a confirmação chega.
:::

---

## Quanto tempo leva para confirmar?

Não existe um prazo fixo — depende do banco e do meio usado pelo pagador. Como
referência:

| Situação | Prazo típico de confirmação |
| --- | --- |
| Fluxo normal | **1 a 2 dias úteis** |
| Média geral | **1 a 3 dias úteis** |
| Pagamento em lotérica | **no mínimo 1 dia útil** |

A cobrança muda de **pendente** para **paga** **automaticamente** assim que a
confirmação é recebida — sem nenhuma ação da sua parte.

---

## Confirmação ≠ dinheiro na conta

Confirmar o pagamento e ter o valor disponível no saldo são **dois momentos
diferentes**:

1. **Confirmação** — a cobrança muda para paga (status `COMPLETED`). É o prazo
   descrito acima.
2. **Liquidação** — o valor é compensado e **creditado na sua conta** (status
   `SETTLED`). Acontece **depois** da confirmação.

Ou seja, mesmo após o boleto ser confirmado, ainda há um prazo até o dinheiro
cair no saldo. Para entender a liquidação e como conciliar o recebimento, veja
**[Conciliação de liquidação do Boleto](/docs/boleto/boleto-reconciliation)**.

:::tip Precisa de confirmação imediata?
Para recebimento em tempo real, oriente seu cliente a pagar via **Pix**. Nas
cobranças que aceitam boleto e Pix, o cliente escolhe a opção mais rápida.
:::

---

## Conciliação de liquidação do Boleto


## Resumo

Um boleto tem **dois momentos** distintos, e diferenciá-los é essencial para
conciliar corretamente:

| Momento | O que significa | Quando acontece |
| --- | --- | --- |
| **Pagamento** | O banco reconheceu que o boleto foi pago | No ato do pagamento |
| **Liquidação** | O valor foi compensado e **creditado na sua conta** | Em até **3 dias úteis** (≈ D+3) após o pagamento |

O webhook de boleto (**`OPENPIX:CHARGE_COMPLETED`**) é disparado no
**pagamento** — veja **[Webhook de Boleto pago](/docs/boleto/boleto-webhook)**.
Para conferência financeira (bater o valor recebido com a venda) e liberação de
produto, o momento que importa é a **liquidação**.

Para a liquidação você tem três caminhos, do mais recomendado ao de reforço:

| Forma | Quando usar |
| --- | --- |
| **Webhook `BOLETO_SETTLED`** | Você quer ser **avisado** no momento em que o valor é creditado, sem polling. É o caminho recomendado. |
| **`GET /api/v1/boleto-transaction`** | Você quer conciliar **em lote**, listando o que liquidou em um período (filtro por `settledStart`/`settledEnd`). |
| **API de cobrança pelo `correlationID`** (`paymentMethods.boleto.status` = `SETTLED` + `settledAt`) | Você já integra a cobrança e quer verificar **uma** venda pontualmente, pelo mesmo `correlationID` que já usa. |

---

## Máquina de status do boleto

O status fica em `paymentMethods.boleto.status` na cobrança. A transição é:

```
CREATED ──pagamento──▶ COMPLETED ──liquidação (até 3 dias úteis)──▶ SETTLED
   │
   └──expiração/cancelamento──▶ CANCELED
```

| `status` | Significado | Campos relevantes |
| --- | --- | --- |
| `CREATED` | Boleto emitido, aguardando pagamento | — |
| `COMPLETED` | Boleto **pago**, aguardando liquidação | `charge.paidAt` |
| `SETTLED` | Boleto **liquidado** (valor creditado na conta) | `paymentMethods.boleto.settledAt` |
| `CANCELED` | Boleto cancelado | — |

:::warning Pagamento ≠ saldo disponível
Em `COMPLETED` o pagamento foi reconhecido, mas o dinheiro ainda **não** está na
conta. Só concilie o recebimento e libere o produto quando o status chegar em
**`SETTLED`**.
:::

---

## Passo 1 — Identificar a venda no pagamento (webhook)

Quando o boleto é **pago**, você recebe o webhook **`OPENPIX:CHARGE_COMPLETED`**.
O payload traz a cobrança e o objeto `boleto`, com o `correlationID` que você
definiu na criação — é por ele que se amarra o pagamento à sua venda. O formato
completo está em **[Webhook de Boleto pago](/docs/boleto/boleto-webhook)**.

Trecho relevante do payload:

```json
{
  "event": "OPENPIX:CHARGE_COMPLETED",
  "charge": {
    "correlationID": "correlation-id-exemplo",
    "status": "COMPLETED",
    "paidAt": "2026-06-05T09:30:00.000Z",
    "paymentMethods": {
      "boleto": { "status": "COMPLETED", "value": 10000 }
    }
  },
  "boleto": {
    "correlationID": "correlation-id-exemplo",
    "status": "COMPLETED",
    "value": 10000
  }
}
```

Guarde o `correlationID` da charge (`charge.correlationID`) e marque a venda como
**paga** (ainda **não** liquidada).

---

## Passo 2 — Acompanhar a liquidação na API de cobrança

A liquidação ocorre em até 3 dias úteis após o pagamento. Para saber quando o
valor foi creditado, **consulte a cobrança** pelo `correlationID` (ou pelo `id`)
e verifique o método de pagamento `boleto`:

[Consultar cobrança](/api#tag/charge/GET/api/v1/charge/{id})

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/charge/correlation-id-exemplo \
  --header 'Authorization: SUA_APP_ID'
```

Enquanto **não** liquidou, o status segue `COMPLETED`:

```json
{
  "charge": {
    "correlationID": "correlation-id-exemplo",
    "status": "COMPLETED",
    "paidAt": "2026-06-05T09:30:00.000Z",
    "paymentMethods": {
      "boleto": {
        "method": "BOLETO",
        "correlationID": "correlation-id-exemplo",
        "status": "COMPLETED",
        "value": 10000,
        "fee": 100
      }
    }
  }
}
```

Quando liquida, o status vai para **`SETTLED`** e o campo **`settledAt`** passa a
existir com a data da liquidação:

```json
{
  "charge": {
    "correlationID": "correlation-id-exemplo",
    "status": "COMPLETED",
    "paidAt": "2026-06-05T09:30:00.000Z",
    "paymentMethods": {
      "boleto": {
        "method": "BOLETO",
        "correlationID": "correlation-id-exemplo",
        "status": "SETTLED",
        "settledAt": "2026-06-10T13:01:55.000Z",
        "value": 10000,
        "fee": 100
      }
    }
  }
}
```

- **`paymentMethods.boleto.status === "SETTLED"`** → o valor foi liquidado.
- **`paymentMethods.boleto.settledAt`** → data/hora da liquidação (ISO 8601).

Esse é o momento seguro para conciliar o recebimento e liberar o produto.

:::note
Valores monetários (`value`, `fee`) são expressos em **centavos**
(`10000` = R$ 100,00).
:::

---

## Webhook de liquidação — `BOLETO_SETTLED`

Em vez de consultar a cobrança até virar `SETTLED`, você pode receber o webhook
**`BOLETO_SETTLED`**, disparado no momento em que o valor é **creditado na sua
conta**. Ele dispensa o polling do passo anterior.

O corpo repete os blocos `charge` e `boleto` do `OPENPIX:CHARGE_COMPLETED` de
boleto — quem já trata o evento de pagamento reaproveita o mesmo parsing — e
acrescenta o **`boleto.settledAt`**:

```json
{
  "event": "BOLETO_SETTLED",
  "charge": {
    "correlationID": "minha-venda-123",
    "value": 242898,
    "status": "COMPLETED"
  },
  "boleto": {
    "boletoTransactionID": "btx_019fa55beec9775faf8a069d64dcde54",
    "value": 245000,
    "status": "SETTLED",
    "boletoBarcode": "34191120100002428981103069645110772982609000",
    "boletoDigitable": "34191103036964511077129826090002112010000242898",
    "fee": 299,
    "settledAt": "2026-07-27T10:00:00.000Z",
    "finesValue": 1902,
    "interestsValue": 200
  }
}
```

Amarre pelo **`charge.correlationID`**, o mesmo que você já usa no evento de
pagamento.

:::note `boleto.value` pode ser maior que `charge.value`
`charge.value` é o valor **emitido**; `boleto.value` é o que o pagador
**efetivamente pagou**, que fica acima do emitido quando o boleto é pago depois do
vencimento (juros e multa). Concilie o crédito pelo `boleto.value`.

A diferença entre os dois vem discriminada: **`finesValue`** é a multa e
**`interestsValue`** o juros que o pagador pagou, em centavos, como cobrados pelo
banco. No exemplo acima, `245000 - 242898 = 2102 = 1902 + 200`.

Cada campo é **omitido quando não houve** — um boleto pago em dia não traz
nenhum dos dois. Veja
**[Boleto com Juros e Multa](/docs/boleto/boleto-juros-multa)**.
:::

Guarde o **`boletoTransactionID`**: é o id público da transação, e com ele você
consulta o detalhe na API abaixo.

Para configurar a URL e validar a assinatura, veja
**[Webhook](/docs/webhook/webhook-events-type)**.

---

## Conciliação em lote — `GET /api/v1/boleto-transaction`

Para fechar um período, liste as transações filtrando pela **data de liquidação**
(`settledStart` / `settledEnd`) e por `type=BOLETO_IN`:

```bash
curl --request GET \
  --url 'https://api.woovi.com/api/v1/boleto-transaction?type=BOLETO_IN&settledStart=2026-07-01T00:00:00.000Z&settledEnd=2026-07-31T23:59:59.000Z' \
  --header 'Authorization: {APP_ID}'
```

```json
{
  "status": "OK",
  "pageInfo": {
    "skip": 0,
    "limit": 100,
    "hasPreviousPage": false,
    "hasNextPage": false
  },
  "boletoTransactions": [
    {
      "boletoTransactionID": "btx_019fa55beec9775faf8a069d64dcde54",
      "type": "BOLETO_IN",
      "status": "CONFIRMED",
      "value": 245000,
      "fee": 299,
      "createdAt": "2026-07-26T13:04:11.212Z",
      "settledAt": "2026-07-27T10:00:00.000Z",
      "finesValue": 1902,
      "interestsValue": 200,
      "charge": {
        "value": 242898,
        "status": "COMPLETED",
        "boletoBarcode": "34191120100002428981103069645110772982609000",
        "boletoDigitable": "34191103036964511077129826090002112010000242898"
      }
    }
  ]
}
```

Existem **dois intervalos de data independentes**, porque respondem perguntas
diferentes: `start`/`end` filtram por **criação** e `settledStart`/`settledEnd`
por **liquidação**. Para conferência financeira use o de liquidação — as duas datas
voltam em todo item, então dá para bater uma contra a outra.

O detalhe de uma transação sai pelo id recebido no webhook:

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/boleto-transaction/btx_019fa55beec9775faf8a069d64dcde54 \
  --header 'Authorization: {APP_ID}'
```

:::note Escopos da aplicação
A listagem exige **`BOLETO_TRANSACTION_GET_LIST`** e o detalhe exige
**`BOLETO_TRANSACTION_GET`**. Sem o escopo, a chamada responde **`403`**.
:::

---

## Fluxo recomendado

1. Crie a cobrança com um `correlationID` próprio da sua venda.
2. Ao receber `OPENPIX:CHARGE_COMPLETED`, marque a venda como **paga** e guarde o
   `correlationID` da charge (`charge.correlationID`).
3. Assine o webhook **`BOLETO_SETTLED`**. Ao recebê-lo, use `boleto.settledAt` como
   a **data de liquidação**, concilie o recebimento pelo `boleto.value` e libere o
   produto. Guarde o `boleto.boletoTransactionID`.
4. No fechamento do período, rode
   **`GET /api/v1/boleto-transaction?type=BOLETO_IN`** com `settledStart`/`settledEnd`
   para conferir tudo que liquidou de uma vez.
5. Se preferir não depender de webhook, consulte a API de cobrança pelo
   `correlationID` e verifique `paymentMethods.boleto.status`. Quando for
   **`SETTLED`**, use `paymentMethods.boleto.settledAt` como a **data de
   liquidação**, concilie o recebimento e libere o produto.

---

## Perguntas frequentes

**Qual a diferença entre `paidAt` e `settledAt`?**
`paidAt` é quando o pagamento foi reconhecido; `settledAt` é quando o valor foi
efetivamente creditado na sua conta (≈ D+3). Para conciliação, use `settledAt`.

**Posso liberar o produto no `COMPLETED`?**
Só se aceitar o risco de o valor ainda não estar na conta. Para liberar com o
dinheiro garantido, aguarde o `SETTLED`.

---

## Webhook de Boleto pago


## Resumo

Quando um boleto emitido pela Woovi é **pago**, enviamos um webhook para a URL
que você cadastrou. Hoje existe **um único webhook no fluxo de boleto**: o de
**boleto pago**.

:::warning Boleto pago não é o mesmo que saldo disponível
O webhook é disparado no momento em que o **pagamento** do boleto é confirmado.
A **liquidação** — quando o valor de fato entra na sua conta e fica disponível
para saque/transferência — acontece **depois**, tipicamente em **D+3**.

Enquanto não liquida, a transação fica em **Transações a liquidar**. Não trate o
recebimento do webhook como dinheiro disponível; trate como "cobrança quitada".
:::

---

## Qual webhook é disparado

| Item | Valor |
| --- | --- |
| Evento (`event`) | `OPENPIX:CHARGE_COMPLETED` |
| Quando dispara | No pagamento do boleto |
| Método HTTP | `POST` |
| Content-Type | `application/json` |

O boleto usa o **mesmo evento** de uma cobrança Pix concluída
([`OPENPIX:CHARGE_COMPLETED`](/docs/webhook/webhook-events-type)). A diferença
está no corpo: o payload de boleto inclui o objeto **`boleto`** e **não** inclui
o objeto `pix`. Para diferenciar a forma de pagamento, verifique qual desses
objetos está presente, ou olhe `charge.paymentMethods`.

---

## Como cadastrar o webhook

### Pelo aplicativo

1. Acesse a lista de **[API/Plugins → Webhooks](https://app.woovi.com/home/api/list)**.
2. Clique em **[Adicionar webhook](https://app.woovi.com/home/openpix/webhook-create)**.
3. Informe a **URL** do seu endpoint (precisa responder `2xx`).
4. Selecione o evento **`OPENPIX:CHARGE_COMPLETED`**.
5. (Recomendado) Defina uma **HMAC secret key** para validar a assinatura.
6. Salve e mantenha o webhook **ativo**.

### Pela API

Crie o webhook apontando para o seu endpoint. Ele precisa estar **ativo**
(`isActive: true`) e inscrito no evento `OPENPIX:CHARGE_COMPLETED`.

```bash
curl -X POST https://api.woovi.com/api/v1/webhook \
  -H "Authorization: SUA_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "name": "Boleto pago",
      "event": "OPENPIX:CHARGE_COMPLETED",
      "url": "https://seu-dominio.com/webhooks/woovi",
      "authorization": "opcional-token-que-voce-recebe-de-volta",
      "isActive": true
    }
  }'
```

:::tip
O campo `authorization` é devolvido nos cabeçalhos da requisição do webhook
(`Authorization` / `x-openpix-authorization`), permitindo que seu servidor
confirme que a chamada partiu da Woovi.
:::

---

## Payload recebido

O corpo enviado para a sua URL tem o seguinte formato:

```json
{
  "event": "OPENPIX:CHARGE_COMPLETED",
  "charge": {
    "customer": {
      "name": "Dan",
      "taxID": { "taxID": "31324227036", "type": "BR:CPF" },
      "email": "dan@example.com",
      "correlationID": "..."
    },
    "value": 10000,
    "comment": "Pagamento do pedido #123",
    "identifier": "a1b2c3d4...",
    "correlationID": "seu-id-de-correlacao",
    "transactionID": "...",
    "status": "COMPLETED",
    "additionalInfo": [],
    "fee": 100,
    "discount": 0,
    "valueWithDiscount": 10000,
    "expiresDate": "2026-06-10T18:00:00.000Z",
    "createdAt": "2026-06-02T12:00:00.000Z",
    "updatedAt": "2026-06-05T09:30:00.000Z",
    "paidAt": "2026-06-05T09:30:00.000Z",
    "paymentMethods": { "boleto": { "...": "..." } }
  },
  "boleto": {
    "value": 10000,
    "status": "COMPLETED",
    "correlationID": "seu-id-de-correlacao",
    "boletoBarcode": "34191790010104351004791020150008291070026000",
    "boletoDigitable": "34191.79001 01043.510047 91020.150008 2 91070000026000",
    "fee": 100
  },
  "company": {
    "id": "60f...",
    "name": "Sua Empresa LTDA",
    "taxID": "00000000000000"
  }
}
```

### Campos principais

| Campo | Descrição |
| --- | --- |
| `event` | Sempre `OPENPIX:CHARGE_COMPLETED` para este webhook. |
| `charge` | Objeto completo da cobrança (mesmo formato da API de Charge). Use `charge.correlationID` para casar com o seu pedido. |
| `charge.status` | `COMPLETED` quando a cobrança foi quitada. |
| `charge.value` | Valor da cobrança, em **centavos**. |
| `boleto.value` | Valor do boleto, em **centavos**. |
| `boleto.status` | Status do método de pagamento boleto. |
| `boleto.boletoBarcode` | Código de barras do boleto. |
| `boleto.boletoDigitable` | Linha digitável do boleto. |
| `boleto.fee` | Taxa aplicada, em **centavos**. |
| `boleto.finesValue` | Multa que o pagador pagou por atraso, em **centavos**. Ausente quando não houve. |
| `boleto.interestsValue` | Juros que o pagador pagou por atraso, em **centavos**. Ausente quando não houve. |
| `company` | Dados da sua empresa (`id`, `name`, `taxID`). |

:::note
Todos os valores monetários (`value`, `fee`, `valueWithDiscount`, ...) são
expressos em **centavos** (`10000` = R$ 100,00).
:::

:::tip Boleto pago com atraso
No exemplo acima o boleto foi pago em dia, então `charge.value` e `boleto.value`
são iguais e não há multa nem juros. Quando o pagamento é feito depois do
vencimento, `boleto.value` fica acima de `charge.value` e a diferença vem
discriminada:

```json
"boleto": {
  "value": 245000,
  "finesValue": 1902,
  "interestsValue": 200,
  "...": "..."
}
```

Aqui a cobrança foi emitida por `242898` e o pagador pagou `245000`: `1902` de
multa e `200` de juros. Veja
**[Boleto com Juros e Multa](/docs/boleto/boleto-juros-multa)**.
:::

---

## Validando a assinatura

Quando há uma HMAC secret key configurada no webhook, enviamos o cabeçalho
`x-openpix-signature` com a assinatura do corpo da requisição:

- **Algoritmo:** HMAC-SHA1
- **Chave:** a HMAC secret key cadastrada no seu webhook
- **Mensagem:** o corpo **bruto** (raw body) da requisição, exatamente como recebido
- **Encoding:** Base64

Recalcule a assinatura no seu servidor e compare com o cabeçalho recebido. Veja o
passo a passo completo, com exemplos em várias linguagens, em
**[Validando o HMAC do webhook](/docs/webhook/seguranca/webhook-hmac)**.

:::warning
Use o **corpo bruto** (string exata recebida) no cálculo da assinatura. Se você
serializar o JSON novamente após o parse, a assinatura não vai bater.
:::

---

## Boas práticas

- **Responda rápido com `2xx`.** Processe o webhook de forma assíncrona; em caso
  de falha (timeout ou status diferente de `2xx`), reenviamos a notificação.
- **Seja idempotente.** O mesmo evento pode chegar mais de uma vez. Use
  `charge.correlationID` / `charge.identifier` como chave para não processar duas
  vezes.
- **Não conte como saldo.** Este webhook indica **boleto pago**, não **valor
  liquidado/disponível**. A liquidação ocorre depois (≈ D+3).

---

## Resumo rápido

| Pergunta | Resposta |
| --- | --- |
| Qual webhook recebo no boleto? | `OPENPIX:CHARGE_COMPLETED`, no **pagamento** do boleto. |
| O dinheiro já está disponível? | **Não.** Pagamento ≠ liquidação. A liquidação é posterior (≈ D+3). |
| Como diferencio de Pix? | O payload de boleto traz o objeto `boleto` e não traz `pix`. |
| Como cadastro? | Painel (**API/Plugins → Webhooks**) ou via API `POST /api/v1/webhook`. |
| Como valido a origem? | Cabeçalho `x-openpix-signature` (HMAC-SHA1 + Base64 do raw body). |

---

## APIs de Cashback

## Como dar cashback para um cliente via API?

Para dar cashback para um cliente via API, você utiliza o _endpoint_ `/api/v1/cashback-fidelity` da API.

Você pode acessar aqui
a documentação referente a esse _endpoint_.

Os campos obrigatórios para dar um cashback são os sequintes:

- **`value`**: O valor em centavos do cashback.
- **`taxID`**: TaxID (CPF/CNPJ) do client.

```bash
curl 'https://api.woovi.com/api/v1/cashback-fidelity' -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "user-agent: node-fetch" --data-binary '{"taxID":"cpf-cnpj","value":1500}
```

Obs.: O cliente precisa já ter sido criado na plataforma.

## Como verificar o saldo de cashback de cliente via API?

Para verificar o saldo de cashback para um cliente via API, você utiliza o _endpoint_ `/api/v1/cashback-fidelity/balance/:cpf-cnpj` da API.

Você pode acessar aqui
a documentação referente a esse _endpoint_.

[`/api/v1/cashback-fidelity/balance/{taxID}`](/api#tag/cashback-fidelity/GET/api/v1/cashback-fidelity/balance/{taxID})

```bash
curl 'https://api.woovi.com/api/v1/cashback-fidelity/balance/${cpf-cnpj}/balance' -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "user-agent: node-fetch" --data-binary '{"taxID":"cpf-cnpj","value":1500}
```

---

## Como configurar o cashback

Uma vez configurado o cashback siga os passos abaixo para configurar o cashback direto em suas configurações.

- Acesse a aba `Settings` em `Cashback`
- Selecione ativar, a porcentagem a ser gerada de cashback e o valor minimo da cobrança a gerar cashback

| Campo                    | Descrição                                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| ativar/desativar         | ativa a feature                                                                                               |
| porcentagem              | valor da porcentagem a ser gerada em cima do valor pago da charge                                             |
| valor mínimo da cobrança | valor mínimo de uma cobrança para gerar cashback em cima da mesma. O valor mínimo da plataforma é de R$ 50,00 |

---

## Como usar?

Para ativar o Cashback em sua empresa siga os passos abaixo:

## 1. Ativar o Cashback

- Acesse `Cashback` via sidemenu
- ![cashback sidemenu](/img/cashback/cashback-sidemenu.png)

No seu primeiro acesso você irá acessar o Tutorial de Cashback.

![cashback tutorial](/img/cashback/cashback-tutorial.png)

> Caso ja tenha configurado seu cashback e deseja revisar as mesmas [saiba mais aqui](/docs/cashback/cashback-how-to-config)

### 1.1 Configure o Cashback

- Selecione ativar, a porcentagem a ser gerada de cashback e o valor minimo da cobrança a gerar cashback

| Campo                    | Descrição                                                         |
| ------------------------ | ----------------------------------------------------------------- |
| ativar/desativar         | ativa a feature                                                   |
| porcentagem              | valor da porcentagem a ser gerada em cima do valor pago da charge |
| valor mínimo da cobrança | valor mínimo de uma cobrança para gerar cashback em cima da mesma |

Ao ativar a feature de Cashback você será redirecionado para o overview page.

![cashback overview](/img/cashback/cashback-overview.png)

## 2. Gerar Cobrança com Cashback

Uma vez tendo o cashback ativado a cobrança passará a considerar a opção de ativar o mesmo.

Para a opção de cashback ser disponibilizada a cobrança precisa atender ao valor mínimo setado na configuração.

![cashback charge form add](/img/cashback/cashback-charge-create-add-collapsible.png)

Preenchendo o valor mínimo da cobrança clique para criar a mesma. Você será redirecionado para o detalhe da cobrança:
![cashback charge detail](/img/cashback/cashback-charge-detail.png)

---

## O que é Cashback?

Cashback é a possibilidade de receber um valor instantâneo após uma compra via Pix através de uma loja que integra a Woovi.

---

## APIs de Cashback Fidelidade

## Como dar cashback para um cliente via API?

Para dar cashback para um cliente via API, você utiliza o _endpoint_ `/api/v1/cashback-fidelity` da API.

Você pode acessar [aqui](/api#tag/cashback-fidelity/POST/api/v1/cashback-fidelity)
a documentação referente a esse _endpoint_.

Os campos obrigatórios para dar um cashback são os sequintes:

- **`value`**: O valor em centavos do cashback.
- **`taxID`**: TaxID (CPF/CNPJ) do client.

```bash
curl 'https://api.woovi.com/api/v1/cashback-fidelity' -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "user-agent: node-fetch" --data-binary '{"taxID":"cpf-cnpj","value":1500}
```

Obs.: O cliente precisa já ter sido criado na plataforma.

## Como verificar o saldo de cashback de cliente via API?

Para verificar o saldo de cashback para um cliente via API, você utiliza o _endpoint_ `/api/v1/cashback-fidelity/balance/:cpf-cnpj` da API.

Você pode acessar [aqui](/api#tag/cashback-fidelity/GET/api/v1/cashback-fidelity/balance/{taxID})
a documentação referente a esse _endpoint_.

[`/api/v1/cashback-fidelity/balance/{taxID}`](/api#tag/cashback-fidelity/GET/api/v1/cashback-fidelity/balance/{taxID})

```bash
curl 'https://api.woovi.com/api/v1/cashback-fidelity/balance/${cpf-cnpj}/balance' -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "user-agent: node-fetch" --data-binary '{"taxID":"cpf-cnpj","value":1500}
```

---

## Como dar Cashback pra fidelizar o seu cliente pela plataforma?

:::info
- Primeiramente certifique se sua empresa já tem o Cashback Fidelidade ativado. Caso não esteja ativado, você pode seguir esse [passo a passo](/docs/cashback-fidelity/cashback-fidelity-how-to-config.md) para fazer a ativação.
:::

Para fidelizar o seu cliente pela plataforma siga os passos abaixo:

### 1. Acesse `Cashback` via sidemenu

- ![](/img/cashback/cashback-sidemenu.png)

### 2. Clique em `Novo Cashback`

:::info
Importante lembrar que o usuário precisa possuir a permissão de admin na plataforma
:::

- ![](/img/cashback-fidelity/cashback-overview-with-new-cashback-button.png)

### 3. Gere o Cashback Fidelidade

Preencha o formulário com o cliente e o valor que você deseja dar esse Cashback

- ![](/img/cashback-fidelity/cashback-fidelity-create-screen.png)

Agora a próxima cobrança criada para esse cliente, irá constar o Cashback que você deu nessa operação.

---

## Como configurar o Cashback Fidelidade

Uma vez configurado o Cashback Fidelidade siga os passos abaixo para configurar o Cashback Fidelidade direto em suas configurações.

- Acesse a aba `Settings` em `Cashback Fidelidade`
- Selecione ativar, a porcentagem a ser gerada de cashback e o valor minimo da cobrança a gerar cashback

| Campo                    | Descrição                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| ativar/desativar         | ativa a feature                                                                                                                 |
| porcentagem              | valor da porcentagem a ser gerada em cima do valor pago da charge                                                               |
| valor mínimo da cobrança | valor mínimo de uma cobrança para gerar cashback na próxima compra em cima da mesma. O valor mínimo da plataforma é de R$ 50,00 |

![cashback fidelity settings](/img/cashback-fidelity/cashback-fidelity-settings.png)

---

## Como usar?(Cashback-fidelity)

Para ativar o Cashback Fidelidade em sua empresa siga os passos abaixo:

## 1. Ativar o Cashback Fidelidade

- Acesse `Cashback` via sidemenu
- ![cashback fidelity sidemenu](/img/cashback/cashback-sidemenu.png)

No seu primeiro acesso você irá acessar o Tutorial de Cashback Fidelidade.

![cashback fidelity tutorial](/img/cashback/cashback-tutorial.png)

> Caso ja tenha configurado seu cashback e deseja revisar as mesmas [saiba mais aqui](/docs/cashback-fidelity/cashback-fidelity-how-to-config)

### 1.1 Configure o Cashback Fidelidade

- Selecione ativar, a porcentagem a ser gerada de cashback na próxima compra e o valor minimo da cobrança a gerar cashback na próxima compra

| Campo                    | Descrição                                                                           |
| ------------------------ | ----------------------------------------------------------------------------------- |
| ativar/desativar         | ativa a feature                                                                     |
| porcentagem              | valor da porcentagem a ser gerada na próxima compra em cima do valor pago da charge |
| valor mínimo da cobrança | valor mínimo de uma cobrança para gerar cashback na próxima compra em cima da mesma |

Ao ativar a feature de Cashback Fidelidade você será redirecionado para o overview page.

![cashback fidelity overview](/img/cashback-fidelity/cashback-fidelity-overview.png)

## 2. Gerar Cobrança com Cashback Fidelidade

Uma vez tendo o Cashback Fidelidade ativado a cobrança passará a considerar a opção de ativar o mesmo.

Para a opção de Cashback Fidelidade ser disponibilizada a cobrança precisa atender ao valor mínimo setado na configuração.

![cashback fidelity charge form add](/img/cashback-fidelity/cashback-fidelity-charge-create-add-collapsible.png)

Preenchendo o valor mínimo da cobrança clique para criar a mesma. Você será redirecionado para o detalhe da cobrança:
![cashback fidelity charge detail](/img/cashback-fidelity/cashback-fidelity-charge-detail.png)

---

## O que é Cashback Fidelidade?

Cashback Fidelidade é a possibilidade de um cliente receber um valor na próxima compra após comprar via Pix em uma loja que integra a Woovi.

---

## Bloqueando Pagamentos

Este documento irá ajudá-lo a bloquear cobranças para serem pagas somente por 1 pagador.

## Como funciona?

- No endpoint de criação de charge, existe agora um novo campo que pode ser enviado: ensureSameTaxID.
- Esse campo faz com que o pagamento de uma cobrança seja recusado caso o CPF/CNPJ do pagador seja diferente daquele configurado como customer.

- Ao criar uma charge, basta apenas enviar esse campo como “true” e enviar um customer. Exemplo:

```json
curl -X POST "https://api.woovi.com/api/v1/application" \
  -H "Authorization: {APP_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "ensureSameTaxID": "true",
    "customer": {
      "name": "João",
      "email": "joão@gmail.com",
      "taxID": "45784409158",
    }
  }'

```

### Conclusão
Com isso, caso seja realizada uma tentativa de pagamento para essa cobrança, o sistema da Woovi verificará o CPF/CNPJ do pagador e do customer cadastrado; se forem diferentes, o pagamento será recusado.

---

## Como selecionar uma conta na criação de uma cobrança

1 - No formulario de criação da cobrança vá até o step Destino do Pagamento

![charge-creation](/img/charge/charge-creation.png)

2 - Abra o collapsible, clique no campo de conta, o drawer de busca de contas sera aberto, selecione ou busque a conta desejada para criação da cobrança

![charge-account-drawer](/img/charge/charge-account-drawer.png)

:::info
- A seleção de conta só aparece para clientes que possuem mais de uma conta virtual.
- Agora quando essa cobrança for paga, o valor desta cobrança irá constar no extrato da conta selecionada.
:::

---

## Como enviar uma mensagem de cobrança via WhatsApp?

## Como enviar uma mensagem via API oficial de WhatsApp para uma cobrança manualmente?

Se você deseja estar em contato com seus clientes e fidelizá-los, estar em contato com eles via WhatsApp é uma maneira prática e eficiente de fazer.

Para isto, a woovi traz uma solução prática e rápida que garante que seu cliente vá receber sua mensagem utilizando a API oficial de WhatsApp disponibilizada pela Meta.

## Enviando uma mensagem manualmente

Para fazer o envio manual de uma mensagem via WhatsApp para uma cobrança, segue o tutorial abaixo.

### Acesse o detalhe de uma cobrança

Acesse o detalhe de uma cobrança criada.

![Detalhe de uma cobrança](./__assets__/charge-whatsapp-detail-route.png)

### Abrindo o modal de envio

Nas opções do menu a direita, você irá encontrar a opção **Compartilhar via WhatsApp API**. Clique nela.

Ao clicar, você verá este modal aparecendo:

![Cobrança com modal do envio de WhatsApp](./__assets__/charge-whatsapp-send-manually.png)

Você verá as informações como:

- O nome do destinatário;
- O número do WhatsApp que receberá a mensagem;
- O preview da mensagem que será enviado;

### Enviando a mensagem

Para enviar a mensagem, clique no botão **Enviar**. Você verá uma notificação de envio com sucesso e seu cliente
irá receber a mensagem no respectivo número de telefone.

:::info

Caso você queira enviar para todas as cobranças criadas, siga o tutorial [aqui](../whatsapp/whatsapp-how-to-send-charges.md).

:::

## Como ativar o envio do WhatsApp automaticamente para todas as cobranças?

Se você deseja estar habilitando esse fluxo de envio para todas as cobranças que forem criadas, também existe essa possibilidade.

Siga o tutorial a seguir: [Como ativar o WhatsApp](../whatsapp/whatsapp-how-to-activate.md).

---

## Cobrança

Uma Cobrança permite que você receba um pagamento via Pix.

A cobrança possui um valor fixo e só pode ser pago uma única vez.

A cobrança é ideal para conciliar os seus pagamentos.

## Casos de Uso

- Aceitar pagamentos em lojas físicas
- Aceitar pagamentos em ecommerce
- Aceitar pagamentos únicos
- Aceitar pagamentos com juros e multas
- Aceitar pagamentos recorrentes (veja também [Assinaturas/Recorrências](./subscription-recurrence))

## Tipos de cobrança

Dentro de cobranças, temos dois tipos: Cobranças e Cobranças com vencimento.

O tipo da cobrança determina como ela vai se comportar ao chegar na data de expiração.

Em nossas APIs, utilizados a propriedade `type` para representar o tipo de uma cobrança.

### Cobrança (cob)

Uma cobrança (cob), ao passar da data de expiração não pode mais ser paga; Nosso sistema vai alterar o estado da cobrança para `EXPIRED`.

Cobranças em nossas APIs são representadas pelo tipo `DYNAMIC`.

Para mais informações a respeito de como você pode criar uma cobrança usando nossa API, veja [Como usar a API para criar uma cobrança (cob)?](./charge/how-to-create-charge-using-api)

### Cobrança com vencimento (cobv)

Uma cobrança com vencimento (cobv), ao passar de sua data de expiração, ainda pode ser paga; Com a diferença de que haverá incidência de multa e juros.

Cobranças com vencimento em nossas APIs são representadas pelo tipo `OVERDUE`.

Para mais informações a repsieot de como você pode criar uma cobrança com vencimento usando nossa API, veja [Como usar a API para criar uma cobrança com vencimento (cobv)?](./charge/how-to-create-cobv-using-api)

---

## Simulador de desconto, juros e multa

import ChargeDiscountSimulator from '@site/src/components/ChargeDiscountSimulator/ChargeDiscountSimulator';

Ajuste a modalidade, valor, vencimento, desconto, juros e multa para
visualizar — dia a dia — quanto o cliente paga ao longo do ciclo de uma
cobrança Pix com vencimento (`OVERDUE` / COBV). Os cálculos são feitos
**localmente no seu navegador** — nenhuma chamada à API é executada e
nenhuma cobrança é criada.

## Modalidades de desconto

A Woovi expõe seis modalidades, alinhadas ao padrão BACEN COBV:

1. **`FIXED_VALUE_UNTIL_SPECIFIED_DATE`** — desconto em centavos válido
   até uma data específica. Aceita múltiplas faixas (ex.: R$1,00 até 5
   dias antes; R$0,50 até 10 dias antes).
2. **`PERCENTAGE_UNTIL_SPECIFIED_DATE`** — mesma ideia em percentual
   (basis points).
3. **`VALUE_PER_RUNNING_DAY_ADVANCE`** — centavos por dia corrido de
   antecedência ao vencimento.
4. **`VALUE_PER_BUSINESS_DAY_ADVANCE`** — centavos por dia útil
   (pula fins de semana e feriados bancários BR).
5. **`PERCENTAGE_PER_RUNNING_DAY_ADVANCE`** — basis points por dia
   corrido de antecedência.
6. **`PERCENTAGE_PER_BUSINESS_DAY_ADVANCE`** — basis points por dia
   útil de antecedência.

## Como funcionam os cálculos

- **Desconto** (`discountSettings`): aplicado **apenas antes do
  vencimento** (`dayIndex < daysForDueDate`). No dia do vencimento e
  depois o desconto é zero.
- **Juros** (`interests.value`): basis points por **dia corrido**,
  somente após o vencimento. Ex: `100` = 1,00% ao dia.
- **Multa** (`fines.value`): aplicada **uma única vez** após o
  vencimento. `type: 'FIXED'` em centavos; `type: 'PERCENTAGE'` em
  basis points sobre o valor principal.
- **`daysAfterDueDate`**: define a janela de simulação após o
  vencimento. Não confundir com regras de expiração — após esse limite
  a tela apenas para de gerar linhas.

## Convenção de unidades

Para evitar problemas de ponto flutuante, a Woovi (e o BACEN) usam dois
inteiros:

- **Centavos** — `R$1,00 = 100`. Vale para `chargeValue`, `value` das
  modalidades 3/4, entradas de `discountFixedDate` da modalidade 1 e
  multas com `type: 'FIXED'`.
- **Basis points** — `1,00% = 100`. Vale para `value` das modalidades
  5/6, entradas da modalidade 2, `interests.value` e multas com
  `type: 'PERCENTAGE'`.

A tela mostra um *preview* legível ao lado de cada campo (`R$X,XX` ou
`X,XX%`) para que você não precise fazer a conta na cabeça.

## Exportar para a API

- **Copiar JSON** devolve o envelope `{ modality, modalityNumber, input,
  rows }` — mesmo formato emitido pela flag `--out` do script
  `simulateChargeDiscount.ts` no monorepo Woovi.
- **Copiar como cURL** monta um `POST /api/v1/charge` pronto para
  rodar. Substitua `<APP_ID>` pelo seu AppID e `<CORRELATION_ID>` por
  um identificador único antes de executar.

## Modo `daily` × `summary`

Por padrão, a linha do tempo mostra uma linha por dia (`daily`). Ative o
toggle **Modo summary** para ver apenas marcos relevantes: dia de
criação, dias em que o desconto muda de faixa, dia do vencimento,
primeira diária pós-vencimento e o último dia simulado.

Veja também [Como criar uma cobv usando a API](./how-to-create-cobv-using-api.mdx).

---

## Como criar uma cobrança com informações adicionais?

## Plataforma

1. No formulário de cobrança identifique o step de informações adicionais
2. Adiciona as informações que desejar em forma de chave valor

![charge additional info example](./__assets__/charge-add-info.png)

Após a criação da cobrança as informações adicionais estarão disponíveis no link de pagamento da cobrança:

![charge detail with additional info](./__assets__/charge-detail-add-info.png)

## API

1. Envie o campo `additionalInfo` como um array de objeto
2. Cada objeto do array deve conter a seguinte estrutura `{ key: 'teste', value: '123' }`

- Request Body

```json
{
  "correlationID": "123abcde",
  "value": 1000,
  "type": "DYNAMIC",
  "additionalInfo": [
    {
      "key": "test",
      "value": "123"
    }
  ]
}
```

- Payload

```ts
{
    "charge": {
        "value": 1000,
        "identifier": "c8032ec611bd4ab7957ae58c19890a8d",
        "correlationID": "123abcde",
        "paymentLinkID": "ae0672da-d7a5-4599-8ec7-d0887b55a2b2",
        "transactionID": "c8032ec611bd4ab7957ae58c19890a8d",
        "status": "ACTIVE",
        "additionalInfo": [
            {
                "key": "test",
                "value": "123"
            }
        ],
        "discount": 0,
        "valueWithDiscount": 1000,
        "expiresDate": "2023-05-13T20:29:47.869Z",
        "type": "DYNAMIC",
        "createdAt": "2023-05-12T20:29:49.646Z",
        "updatedAt": "2023-05-12T20:29:49.646Z",
        "brCode": "00020101021226990014br.gov.bcb.pix2577pix-h.bpp.com.br/23114447/qrs1/v2/01pMq2ZLBxuiphmfCatLb772nzWZaiYTh9fL2irJewQ520400005303986540510.005802BR5904Finn6009Sao_Paulo62290525c8032ec611bd4ab7957ae58c163047AB5",
        "expiresIn": 86400,
        "pixKey": "cc134114-a533-4876-9a6d-e433a00b2300",
        "paymentLinkUrl": "https://woovi.com/pay/ae0672da-d7a5-4599-8ec7-d0887b55a2b2",
        "qrCodeImage": "https://api.woovi.com/woovi/charge/brcode/image/ae0672da-d7a5-4599-8ec7-d0887b55a2b2.png",
        "globalID": "Q2hhcmdlOjY0NWVhMWJkOTI2NTg5M2UwMjQyNDYyNw=="
    },
    "correlationID": "123abcde",
    "brCode": "00020101021226990014br.gov.bcb.pix2577pix-h.bpp.com.br/23114447/qrs1/v2/01pMq2ZLBxuiphmfCatLb772nzWZaiYTh9fL2irJewQ520400005303986540510.005802BR5904Finn6009Sao_Paulo62290525c8032ec611bd4ab7957ae58c163047AB5"
}
```

---

## Como criar uma cobrança com dados no email de cobrança paga?

1. Crie a cobrança seguindo o tutorial [Como criar uma cobrança com informações adicionais?](/docs/charge/how-charge-additional-info)
2. Ao receber o email de cobrança paga você poderá identificar as informações no mesmo

![charge completed email with additional info](./__assets__/charge-completed-email-additional.png)

---

## Como filtrar cobranças de um cliente em particular

Para filtrar cobranças de um cliente, passe um parâmetro na URL chamado `customer` com o [`correlationID`](../../concepts/correlation-id.md) do cliente.

Por exemplo, caso o `correlationID` do cliente seja `abcd`, filtre as cobranças utilizando a URL `https://api.woovi.com/api/v1/charge?customer=abcd`.

Aqui está um comando cURL de exemplo:

```bash
curl --request GET \
  --url 'https://api.woovi.com/api/v1/charge?customer=correlation-id-do-cliente' \
  --header 'Authorization: seu-app-id'
```

---

## Como redirecionar o usuário para uma URL pós pagar a cobrança via link de pagamento?

## Redirecionando o usuário

Caso você deseja redirecionar o usuário para uma URL em específico após o pagamento de uma
cobrança. É necessário criar a respectiva cobrança daquele link de pagamento com um campo chamado
`redirectUrl` acrescentado.

Utilizando a API de [Charge POST](/api#tag/charge/POST/api/v1/charge),
para criar uma nova cobrança com esse novo campo. No body da requisição deveria ser encaminhado conforme o seguinte
exemplo:

```json
{
  "correlationID": "9134e286-6f71-427a-bf00-241681624587",
  "value": 100,
  "redirectUrl": "https://example.com"
}
```

Nesse cenário, após o pagamento dessa cobrança, o usuário será redirecionado para a
URL do `https://example.com`.

---

## Como bloquear pagamentos de CPF/CNPJ diferente do cliente

# Bloquear pagamento para CPF/CNPJ diferente do cliente

Em algumas operações, especialmente em setores com risco de fraude, é essencial garantir que o pagamento de uma cobrança Pix seja feito exclusivamente pelo CPF ou CNPJ previamente cadastrado como cliente.

Para atender a esse cenário, a Woovi oferece o campo `ensureSameTaxID` no endpoint de criação de cobrança.

## :hammer_and_wrench: Como funciona?

Ao criar uma cobrança (charge) via API, você pode utilizar o campo `ensureSameTaxID`. Esse campo, quando ativado, impede que o pagamento seja aceito caso o CPF/CNPJ do pagador seja diferente do informado no campo `customer`.

## :rocket: Exemplo de uso com curl

```bash
curl -X POST "https://api.woovi.com/api/v1/application" \
-H "Authorization: {APP_ID}" \
-H "Content-Type: application/json" \
-d '{
  "ensureSameTaxID": true,
  "customer": {
    "name": "João",
    "email": "joao@gmail.com",
    "taxID": "45784409158"
  }
}'
```

## :white_check_mark: O que acontece na prática?

Com essa configuração ativada:

- Se o pagador tentar concluir a cobrança com um CPF/CNPJ diferente daquele informado no campo `customer.taxID`, o pagamento será recusado.
- A Woovi valida em tempo real o CPF/CNPJ de quem está tentando pagar com o do cliente registrado.
- Ideal para prevenir fraudes e proteger operações sensíveis.

## :brain: Conclusão

A funcionalidade `ensureSameTaxID` é uma camada adicional de segurança que permite que você valide automaticamente a identidade do pagador e evite recebimentos indevidos. Recomendamos seu uso em operações com alto valor ou maior risco de chargeback via Pix (MEDs).

:blue_book: Consulte nossa [documentação da API de cobrança](/api#tag/charge/POST/api/v1/charge) para mais detalhes sobre todos os campos disponíveis.

---

## Como definir o tempo de expiração de uma cobrança?


A configuração de expiração das cobranças pode ser configurado no menu `Cobranças`

![Menu Charge](./__assets__/charge-menu.png)

Na aba `Ajustes`

![Settings Pix](./__assets__/charge-settings-tab.png)

Identifique o card `Tempo padrão de expiração de cobrança` e configure da forma que desejar com as opções disponíveis ou então customizadas.

![Expiration Time](./__assets__/charge-expiration-options.png)

---

## Como compartilhar uma cobrança?


A melhor forma de compartilhar uma cobrança é enviando o link de pagamento para o seu cliente.

Você pode compartilhar esse link na nossa plataforma das seguintes formas:

#### Enviando o Link de Pagamento através de um e-mail

![Share Link Email](./__assets__/charge-send-email.png)

![Share Link Email Detail](./__assets__/charge-send-email-modal.png)

#### Enviando o Link de Pagamento

![Share Link](./__assets__/charge-pay-link.png)

#### Enviando o Link de Pagamento através do WhatsApp

![Share Link WhatsApp](./__assets__/charge-share-wpp.png)

![Share Link WhatsApp Detail](./__assets__/charge-wpp-detail.png)

---

## Como criar uma cobrança solicitando o cadastro do cliente?

Você pode criar uma cobrança solicitando que o cliente cadastre seus dados antes que ele possa realizar o pagamento da cobrança.

No formulario de criação da cobrança na segunda etapa, selecione a opção "Solicitar cadastro".

![charge-creation](./__assets__/request-customer.png)

Preencha os demais dados e clique em "Criar cobrança".

Com a cobrança criada, será necessário preencher um formulário com os dados do cliente para acessar o QR Code da cobrança.

Você pode copiar o link do pagamento e enviar para o seu cliente.

![customer-registration](./__assets__/customer-registration.png)

Após preencher os dados, o cliente terá acesso à página de pagamento da cobrança.

O cliente é cadastrado na plataforma e vinculado à cobrança automaticamente.

![charge](./__assets__/charge.png)

---

## Como usar a API para criar uma cobrança (cob)?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para criar uma cobrança Pix, você utiliza o _endpoint_ `/api/v1/charge` da API.

Você pode acessar [aqui](/api#tag/charge/POST/api/v1/charge)
a documentação referente a esse _endpoint_.

Os campos obrigatórios para criar uma cobrança Pix são os sequintes:

- **`value`**: O valor em centavos da cobrança Pix a ser criado.
- **`correlationID`**: Um identificador único para a cobrança Pix. [CorrelationID](../concepts/correlation-id)

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "value": 100,
  "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a"
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, retornaremos a cobrança criada.

Retornarmeros a seguinte resposta de exemplo:

```json
{
  "charge": {
    "customer": null,
    "value": 100,
    "identifier": "996ed4b7cc1c...",
    "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
    "paymentLinkID": "86f574fb-73...",
    "transactionID": "996ed4b7cc1c...",
    "status": "ACTIVE",
    "giftbackAppliedValue": 0,
    "discount": 0,
    "valueWithDiscount": 1500,
    "expiresDate": "2023-02-25T20:09:06.141Z",
    "type": "DYNAMIC",
    "createdAt": "2023-02-24T20:09:06.141Z",
    "additionalInfo": [],
    "updatedAt": "2023-02-24T20:09:14.165Z",
    "expiresIn": 86400,
    "pixKey": "d65032a3-c0c...",
    "brCode": "0002010102...",
    "paymentLinkUrl": "http://url.com/pay/...",
    "qrCodeImage": "http://url.com/openpix/charge/brcode/image/...",
    "globalID": "Q2hhcmdlOjYzZjkxOTZhNjA3ODg1..."
  },
  "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
  "brCode": "0002010102..."
}
```

### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/charge' -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      --data-binary '{"correlationID":"c782e0ac-833d-4a89-9e73-9b60b2b41d3a","value":1500}'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/charge', {
  method: 'POST',
  body: JSON.stringify({
    value: 100,
    correlationID: 'c782e0ac-833d-4a89-9e73-9b60b2b41d3a',
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como usar a API para criar uma cobrança com split para Sub Conta?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para criar uma cobrança Pix com split para sub conta, você utiliza o _endpoint_ `/api/v1/charge` da API.

Você pode acessar [aqui](/api#tag/charge/POST/api/v1/charge)
a documentação referente a esse _endpoint_.

Os campos obrigatórios para criar uma cobrança Pix com Split são os seguintes:

- **`value`**: O valor em centavos da cobrança Pix a ser criado.
- **`correlationID`**: Um identificador único para a cobrança Pix. [CorrelationID](../concepts/correlation-id)
- **`splits`**: Um array contendo as configurações de split realizado na hora do recebimento.

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "value": 100,
  "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
  "splits": [
    {
      "pixKey": "destinatario@example.com",
      "value": 15,
      "splitType": "SPLIT_SUB_ACCOUNT"
    }
  ]
}
```

O valor do campo `value` dentro do objeto no array de `splits`, é o valor desejado para a realização do split em **centavos**. O valor do split não será debitado da conta de origem pois transações de split para sub contas são transações virtuais, somente será debitado da conta de origem o valor integral do saldo da sub conta no momento do saque da mesma.

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, além dos campos normais de cobrança criada, retornaremos os seguintes campos:

```json
{
  "charge": {
    ...Charge Payload
    "splits": [
      { "pixKey": "destinatario@example.com", "value": 15, splitType: "SPLIT_SUB_ACCOUNT" },
    ]
  },
  "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
  "brCode": "00020101021226990014br.gov.bcb.pix2577pix-h.bpp.com.br/23114447/qrs1/v2/011Q0PuArnNb5VzolFm8H9X0A7yQb5Ayi6wZ2Koj6RX52040000530398654043.335802BR5911Krusty_Krab6009Sao_Paulo62290525cac964d74db74c479add4eabc63047932"
}
```

### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/charge' -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      --data-binary '{"correlationID":"c782e0ac-833d-4a89-9e73-9b60b2b41d3a","value":100, "splits": [{ "pixKey": "destinatario@example.com", "value": 15, splitType:"SPLIT_SUB_ACCOUNT"  }]}'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/charge', {
  method: 'POST',
  body: JSON.stringify({
    value: 100,
    correlationID: 'c782e0ac-833d-4a89-9e73-9b60b2b41d3a',
    splits: [
      {
        pixKey: 'destinatario@example.com',
        value: 15,
        splitType: 'SPLIT_SUB_ACCOUNT',
      },
    ],
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como usar a API para criar uma cobrança com split?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info
Para a utilização dessa funcionalidade é necessário possuir a funcionalidade Split
:::

## Criar Split via API

Para criar uma cobrança Pix com split, você utiliza o _endpoint_ `/api/v1/charge` da API.

Você pode acessar [aqui](/api#tag/charge/POST/api/v1/charge)
a documentação referente a esse _endpoint_.

Os campos obrigatórios para criar uma cobrança Pix com Split são os seguintes:

- **`value`**: O valor em centavos da cobrança Pix a ser criado.
- **`correlationID`**: Um identificador único para a cobrança Pix. [CorrelationID](../concepts/correlation-id)
- **`splits`**: Um array contendo as configurações de split realizado na hora do recebimento

### Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "value": 100,
  "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
  "splits": [
    { "pixKey": "destinatario@woovi.com.br", "value": 15 },
    { "pixKey": "2a33747b-1715-4f57-8b9d-4cb73c15b19b", "value": 30 }
  ]
}
```

O valor do campo `value` dentro do objeto no array de `splits`, é o valor desejado para a realização do split em **centavos**. O valor restante continuará na conta de origem da cobrança

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, além dos campos normais de cobrança criada, retornaremos os seguintes campos:

```json
{
  "charge": {
    ...Charge Payload
    "splits": [
      { "pixKey": "destinatario@woovi.com.br", "value": 15 },
      { "pixKey": "2a33747b-1715-4f57-8b9d-4cb73c15b19b", "value": 30 }
    ]
  },
  "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
  "brCode": "00020101021226990014br.gov.bcb.pix2577pix-h.bpp.com.br/23114447/qrs1/v2/011Q0PuArnNb5VzolFm8H9X0A7yQb5Ayi6wZ2Koj6RX52040000530398654043.335802BR5911Krusty_Krab6009Sao_Paulo62290525cac964d74db74c479add4eabc63047932"
}
```

### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/charge' -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      --data-binary '{"correlationID":"c782e0ac-833d-4a89-9e73-9b60b2b41d3a","value":100, "splits": [{ "pixKey": "destinatario@woovi.com.br", "value": 15 }, { "pixKey": "2a33747b-1715-4f57-8b9d-4cb73c15b19b", "value": 30 }]}'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/charge', {
  method: 'POST',
  body: JSON.stringify({
    value: 100,
    correlationID: 'c782e0ac-833d-4a89-9e73-9b60b2b41d3a',
    splits: [
      { pixKey: 'destinatario@woovi.com.br', value: 15 },
      { pixKey: '2a33747b-1715-4f57-8b9d-4cb73c15b19b', value: 30 },
    ],
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como usar a API para criar uma cobrança com uma subconta atrelada?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## Criar cobrança com uma subconta atrelada via API

Para criar uma cobrança Pix com uma subconta atrelada, você utiliza o _endpoint_ `/api/v1/charge` da API.

Você pode acessar [aqui](/api#tag/charge/POST/api/v1/charge)
a documentação referente a esse _endpoint_.

Os campos obrigatórios para criar uma cobrança Pix com descontos são os seguintes:

- **`value`**: O valor em centavos da cobrança Pix a ser criado.
- **`correlationID`**: Um identificador único para a cobrança Pix. [CorrelationID](../concepts/correlation-id)
- **`subaccount`**: A chave da subconta que será atrelada à cobrança Pix.

### Exemplo

O body da sua requisição será semelhante a este exemplo:

```js
{
  "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
  "value": 1600,
  "subaccount": "pixkey@pixkey.com" // Aqui estamos usando um email como chave Pix.
}
```

O campo `subaccount` é a chave Pix da subconta que será atrelada à cobrança Pix. Após o pagamento da cobrança, o valor será creditado (já aplicado a tarifa da plataforma) na subconta que você especificou na criação.

:::info
Antes de criar uma cobrança Pix com uma subconta atrelada, você precisa ter uma subconta cadastrada na plataforma woovi. Para saber como criar uma subconta, acesse esta [documentação](/docs/subaccount/how-to-create-a-subbaccount).
:::

### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/charge' -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      --data-binary '{
        "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
        "value": 1600,
        "subaccount": "pixkey@pixkey.com"
      }'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/charge', {
  method: 'POST',
  body: JSON.stringify({
    correlationID: 'c782e0ac-833d-4a89-9e73-9b60b2b41d3a',
    value: 1600,
    subaccount: 'pixkey@pixkey.com',
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como usar a API para criar uma cobrança com woovi Parcelado?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info
Para a ultilização dessa funcionalidade é necessário possuir a funcionalidade woovi Parcelado. Solicite o acesso via chat pela plataforma pelo link.
:::

Para criar uma cobrança Pix com woovi Parcelado, você utiliza o _endpoint_ `/api/v1/charge` da API.

Você pode acessar [aqui](/api#tag/charge/POST/api/v1/charge)
a documentação referente a esse _endpoint_.

Os campos obrigatórios para criar uma cobrança Pix com woovi Parcelado são os seguintes:

- **`value`**: O valor em centavos da cobrança Pix a ser criado.
- **`correlationID`**: Um identificador único para a cobrança Pix. [CorrelationID](../concepts/correlation-id)
- **`type`**: O type da cobrança ser PIX_CREDIT
- **`customer`**: É obrigatório que seja passado um cliente com: nome, cpf/cnpj, email, telefone e endereço completo

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "correlationID": "63c533c0-3bb2-4847-a568-e2270e99aad8",
  "value": 1500,
  "comment": "woovi Parcelado",
  "type": "PIX_CREDIT",
  "customer": {
    "name": "Dan ",
    "taxID": "12345678900",
    "phone": "+5519912345678",
    "email": "test@woovi.com",
    "address": {
      "zipcode": "13142514",
      "street": "Rua woovi",
      "number": "2019",
      "neighborhood": "Casa",
      "city": "Sao Paulo",
      "state": "SP",
      "complement": "Brooklin"
    }
  }
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, além dos campos normais de cobrança criada, com status `ACTIVE_WAITING_PAYMENT_METHOD`.

## Renderizando a cobrança

Para que o fluxo funcione por completo após a crição da cobrança com woovi Parcelado é necessário que a mesma seja renderizada utilizando o link de pagamento da mesma ou o nosso Plugin Js.

### Renderizando a cobrança - Link de Pagamento

Renderizar sua cobrança woovi Parcelado com o link de pagamento é a forma mais simples de executar o fluxo por completo. Basta pegar o campo `paymentLinkUrl` e abrir em uma nova aba no navegador.

### Renderizando a cobrança - Plugin Js

Você encontra as docs sobre como renderiza-la clicando [aqui](/docs/plugin#come%C3%A7ando-com-o-plugin-de-order).

Siga os steps abaixo:

1. Copie o seu correlationID
2. Injete o plugin js conforme o exemplo abaixo passando três campos:

- **appID**: appID da sua loja, importante que o mesmo seja do tipo PLUGIN. Veja como criar um appID do tipo Plugin [aqui](/docs/apis/api-getting-started)
- **correlationID**: correlationID da cobrança
- **node**: o node representa o nó em seu HTML que ira receber nosso plugin injetado. `<div id="woovi-order"></div> <!-- o node nesse caso é "woovi-order" -->`

```html<!DOCTYPE html>
<!DOCTYPE html>
<html lang="pt-BR">

<head>
  <meta charset="UTF-8" />
  <title>Demo woovi Plugin</title>
</head>

<body>
  <div id="woovi-order"></div> <!-- o node nesse caso é "woovi-order" -->
  <script src="https://plugin.woovi.com/v1/woovi.js?appID=appID&correlationID=appID&node=woovi-order"></script>
</body>

</html>
```

### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/charge' -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      --data-binary '{"correlationID":"63c533c0-3bb2-4847-a568-e2270e99aad8","value":1500,"comment":"woovi Parcelado","type":"PIX_CREDIT","customer":{"name":"Dan ","taxID":"12345678900","phone":"+5519912345678","email":"test@woovi.com","address":{"zipcode":"13142514","street":"Rua woovi","number":"2019","neighborhood":"Casa","city":"Sao Paulo","state":"SP","complement":"Brooklin"}}}'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/charge', {
  method: 'POST',
  body: JSON.stringify({
    value: 100,
    correlationID: 'c782e0ac-833d-4a89-9e73-9b60b2b41d3a',
    type: 'PIX_CREDIT',
    customer: {
      name: 'Dan ',
      taxID: '12345678900',
      phone: '+5519912345678',
      email: 'test@woovi.com',
      address: {
        zipcode: '13142514',
        street: 'Rua woovi',
        number: '2019',
        neighborhood: 'Casa',
        city: 'Sao Paulo',
        state: 'SP',
        complement: 'Brooklin',
      },
    },
  }),
  headers: {
    Authorization: 'appID',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como usar a API para criar uma cobrança com vencimento, multa e juros (cobv)?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para criar uma cobrança Pix com vencimento, multa e juros, você utiliza o _endpoint_ `/api/v1/charge` da API.

Você pode acessar [aqui](/api#tag/charge/POST/api/v1/charge)
a documentação referente a esse _endpoint_.

Os campos obrigatórios para criar uma cobrança Pix com vencimento, multa e juros são os sequintes:

- **`value`**: O valor em centavos da cobrança Pix a ser criado.
- **`correlationID`**: Um identificador único para a cobrança Pix. [CorrelationID](../concepts/correlation-id)
- **`type`**: O tipo de cobrança. Especificamente com o valor `OVERDUE`.
- **`customer`**: Um objeto que representa o usuário que vai receber a cobrança.

Dentro de **`customer`** é necessário enviar a o CPF/CNPJ do cliente sendo cobrado.

Se o cliente já estiver cadastrado em nosso banco de dados e tiver um endereço, essas informações bastam.

Entretanto, caso o cliente não esteja cadastrado, ou não tenha endereço cadastrado, é necessário, ou cadastrar o cliente com um endereço, ou enviar essas informações junto com a requisição.

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "value": 100,
  "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
  "type": "OVERDUE",
  "customer": {
    "taxID": "607.681.970-74"
  }
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, retornaremos a assinatura criada.

Uma resposta semelhante à seguinte será retornada:

```json
{
  "charge": {
    "customer": {
      "name": "S...",
      "address": {
        "zipcode": "13...",
        "street": "R...",
        "number": "151",
        "neighborhood": "Centro",
        "city": "S...",
        "state": "SP",
        "complement": "Casa"
      },
      "taxID": { "taxID": "60768197074", "type": "BR:CPF" },
      "correlationID": "b6b1f741-f13f-4923-a14e-b515b245e6a5"
    },
    "value": 1500,
    "identifier": "ec60c...",
    "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
    "paymentLinkID": "98e76...",
    "transactionID": "ec60c...",
    "status": "ACTIVE",
    "giftbackAppliedValue": 0,
    "discount": 0,
    "valueWithDiscount": 1500,
    "expiresDate": "2023-03-04T02:59:59.999Z",
    "type": "OVERDUE",
    "createdAt": "2023-02-24T20:31:35.288Z",
    "additionalInfo": [],
    "updatedAt": "2023-02-24T20:31:43.744Z",
    "interestsSettings": {
      "fines": { "value": 1000 },
      "interests": { "value": 200 }
    },
    "expiresIn": 628104,
    "pixKey": "d65032...",
    "brCode": "0002010...",
    "paymentLinkUrl": "http://url.com/pay/...",
    "qrCodeImage": "http://url.com/openpix/charge/brcode/image/...",
    "globalID": "Q2hhcmdlOjYzZjkxZ..."
  },
  "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
  "brCode": "0002010..."
}
```

### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/charge' -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      --data-binary '{"correlationID":"c782e0ac-833d-4a89-9e73-9b60b2b41d3a","value":1500, "type": "OVERDUE","customer": {"taxID": "607.681.970-74"}}'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/charge', {
  method: 'POST',
  body: JSON.stringify({
    value: 100,
    correlationID: 'c782e0ac-833d-4a89-9e73-9b60b2b41d3a',
    type: 'OVERDUE',
    customer: {
      taxID: '607.681.970-74',
    },
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como usar o Woovi QR por API


## O que é o Woovi QR?

O Woovi QR é uma solução pensada para o checkout físico, onde o cliente realiza o pagamento diretamente no caixa. Com essa abordagem, é necessário apenas um único QR Code para processar quantas cobranças forem necessárias.

O QR Code pode ser impresso e reutilizado por todos os clientes futuros. O que muda a cada cobrança são apenas os dados associados ao pagamento, não a imagem do QR Code em si.

## :rocket: Criando a primeira cobrança

Para criar a primeira cobrança do Woovi QR, utilize o endpoint de criação de cobrança com o campo `fixedLocation` definido como `true`.

```bash
curl -X POST "https://api.woovi.com/api/v1/charge" \
  -H "Authorization: {APP_ID}" \
  -H "Content-Type: application/json" \
  -d '{
  "correlationID": "...",
  "value": 100,
  "comment": "test",
  "fixedLocation": true
}'
```

## :key: Armazenando o paymentLinkID

Após criar a primeira cobrança, a parte mais importante do retorno da API é o `paymentLinkID`, que deverá ser armazenado e enviado em todas as cobranças futuras para o mesmo QR Code:

```json
{
  "charge": {
    "correlationID": "...",
    "value": 100,
    "comment": "test",
    "paymentLinkID": "a57c4739-0382-..."
  }
}
```

## :repeat: Futuras cobranças

Para criar cobranças futuras, utilize o mesmo `paymentLinkID` da primeira cobrança, assim o QR Code será reutilizado:

```bash
curl -X POST "https://api.woovi.com/api/v1/charge" \
  -H "Authorization: {APP_ID}" \
  -H "Content-Type: application/json" \
  -d '{
  "correlationID": "...",
  "value": 100,
  "comment": "test",
  "paymentLinkID": "a57c4739-0382-...",
  "fixedLocation": true
}'
```

## :white_check_mark: Como funciona na prática?

Com esse fluxo, todas as cobranças reutilizam o mesmo QR Code. Dessa forma, a `qrCodeImage` retornada pela API pode ser impressa uma única vez e utilizada permanentemente no caixa para todas as cobranças futuras.

## :brain: Conclusão

O Woovi QR simplifica o processo de checkout físico, eliminando a necessidade de gerar um novo QR Code para cada transação. Basta imprimir o QR Code uma vez e reutilizá-lo para todas as cobranças subsequentes, otimizando o fluxo de pagamento no ponto de venda.

:blue_book: Consulte nossa [documentação da API de cobrança](/api#tag/charge/POST/api/v1/charge) para mais detalhes sobre todos os campos disponíveis.

---

## Exemplo de resposta do webhook de cobrança paga

## Webhook de cobrança paga

Segue abaixo o exemplo dos dados que são enviados numa requisição do webhook de cobrança
paga (`OPENPIX:CHARGE_COMPLETED`). Esse webhook é disparado no momento que um usuário paga uma cobrança.

- `pix`: Objeto com detalhes da transação Pix relacionada ao pagamento da cobrança;
- `company`: Empresa do qual a cobrança pertence;
- `account`: Detalhes da conta que a Transação pertence;
- `charge`: Detalhes da cobrança paga;

## Resposta (JSON) de exemplo

```json
{
  "event": "OPENPIX:CHARGE_COMPLETED",
  "charge": {
    "customer": {
      "name": "John Doe",
      "email": "john@doe.com",
      "phone": "+5511123456789",
      "taxID": {
        "taxID": "07549767000113",
        "type": "BR:CNPJ"
      },
      "correlationID": "cb25ba21-fc5d-40f6-80bc-47079f5bc482"
    },
    "value": 5000,
    "comment": "",
    "identifier": "db85f0c5380c493b8eb3cf6b6780fd98",
    "paymentLinkID": "b982c71a-e9a2-4ff7-8cb0-34a2717fe7ed",
    "transactionID": "db85f0c5380c493b8eb3cf6b6780fd98",
    "status": "COMPLETED",
    "additionalInfo": [],
    "discount": 0,
    "valueWithDiscount": 5000,
    "expiresDate": "2023-11-28T12:30:34.164Z",
    "type": "DYNAMIC",
    "correlationID": "51b3e0ea-abfc-4a7b-999c-847f27c35add",
    "createdAt": "2023-11-28T11:30:34.652Z",
    "updatedAt": "2023-11-28T11:30:40.042Z",
    "paidAt": "2023-11-28T11:30:39.933Z",
    "payer": {
      "name": "QA",
      "taxID": {
        "taxID": "05460236000124",
        "type": "BR:CNPJ"
      },
      "correlationID": "1ba4011d-f670-4e63-9ecf-4b2606501660"
    },
    "brCode": "00020101021226900014br.gov.bcb.pix2568api.woovi.com/api/testaccount/qr/v1/db85f0c5380c493b8eb3cf6b6780fd98520400005303986540550.005802BR5909admin_dev6009Sao_Paulo62290525db85f0c5380c493b8eb3cf6b663046A80",
    "expiresIn": 3599,
    "pixKey": "d94d2ebc-0b3e-4b48-8b96-2eddac9e4f0e",
    "paymentLinkUrl": "https://woovi.com/pay/b982c71a-e9a2-4ff7-8cb0-34a2717fe7ed",
    "qrCodeImage": "https://api.woovi.com/woovi/charge/brcode/image/b982c71a-e9a2-4ff7-8cb0-34a2717fe7ed.png",
    "globalID": "Q2hhcmdlOjY1NjVjZjVhZmIzNDE4Y2EwYTJjMWVlOQ=="
  },
  "pix": {
    "customer": {
      "name": "John Doe",
      "email": "john@doe.com",
      "phone": "+5511123456789",
      "taxID": {
        "taxID": "07549767000113",
        "type": "BR:CNPJ"
      },
      "correlationID": "cb25ba21-fc5d-40f6-80bc-47079f5bc482"
    },
    "payer": {
      "name": "QA",
      "taxID": {
        "taxID": "05460236000124",
        "type": "BR:CNPJ"
      },
      "correlationID": "1ba4011d-f670-4e63-9ecf-4b2606501660"
    },
    "charge": {
      "customer": {
        "name": "John Doe",
        "email": "john@doe.com",
        "phone": "+5511123456789",
        "taxID": {
          "taxID": "07549767000113",
          "type": "BR:CNPJ"
        },
        "correlationID": "cb25ba21-fc5d-40f6-80bc-47079f5bc482"
      },
      "value": 5000,
      "comment": "",
      "identifier": "db85f0c5380c493b8eb3cf6b6780fd98",
      "paymentLinkID": "b982c71a-e9a2-4ff7-8cb0-34a2717fe7ed",
      "transactionID": "db85f0c5380c493b8eb3cf6b6780fd98",
      "status": "COMPLETED",
      "additionalInfo": [],
      "discount": 0,
      "valueWithDiscount": 5000,
      "expiresDate": "2023-11-28T12:30:34.164Z",
      "type": "DYNAMIC",
      "correlationID": "51b3e0ea-abfc-4a7b-999c-847f27c35add",
      "createdAt": "2023-11-28T11:30:34.652Z",
      "updatedAt": "2023-11-28T11:30:40.042Z",
      "paidAt": "2023-11-28T11:30:39.933Z",
      "payer": {
        "name": "QA",
        "taxID": {
          "taxID": "05460236000124",
          "type": "BR:CNPJ"
        },
        "correlationID": "1ba4011d-f670-4e63-9ecf-4b2606501660"
      },
      "brCode": "00020101021226900014br.gov.bcb.pix2568api.woovi.com/api/testaccount/qr/v1/db85f0c5380c493b8eb3cf6b6780fd98520400005303986540550.005802BR5909admin_dev6009Sao_Paulo62290525db85f0c5380c493b8eb3cf6b663046A80",
      "expiresIn": 3599,
      "pixKey": "d94d2ebc-0b3e-4b48-8b96-2eddac9e4f0e",
      "paymentLinkUrl": "https://woovi.com/pay/b982c71a-e9a2-4ff7-8cb0-34a2717fe7ed",
      "qrCodeImage": "https://api.woovi.com/woovi/charge/brcode/image/b982c71a-e9a2-4ff7-8cb0-34a2717fe7ed.png",
      "globalID": "Q2hhcmdlOjY1NjVjZjVhZmIzNDE4Y2EwYTJjMWVlOQ=="
    },
    "value": 5000,
    "time": "2023-11-28T11:30:39.933Z",
    "endToEndId": "E39f22d047934468f89c8347ed4cd80d0",
    "transactionID": "db85f0c5380c493b8eb3cf6b6780fd98",
    "infoPagador": "woovi testing",
    "type": "PAYMENT",
    "createdAt": "2023-11-28T11:30:39.954Z",
    "globalID": "UGl4VHJhbnNhY3Rpb246NjU2NWNmNWZmYjM0MThjYTBhMmMxZjc3"
  },
  "company": {
    "id": "5fa58a32bb2a83003433e506",
    "name": "Admin Dev S/A",
    "taxID": "05460236000124"
  },
  "account": {}
}
```

---

## Exemplo de resposta do webhook de cobrança criada

## Webhook de cobrança criada

Segue abaixo o exemplo dos dados que são enviados numa requisição do webhook de cobrança
paga (`OPENPIX:CHARGE_CREATED`). Esse webhook é disparado no momento em que um usuário cria
uma nova cobrança, seja pela API ou pela plataforma.

- `company`: Empresa do qual a cobrança pertence;
- `account`: Detalhes da conta que a cobrança pertence;
- `charge`: Detalhes da cobrança criada;

## Resposta (JSON) de exemplo

```json
{
  "event": "OPENPIX:CHARGE_CREATED",
  "charge": {
    "customer": {
      "name": "John Doe",
      "email": "john@doe.com",
      "phone": "+5511912345678",
      "address": {
        "zipcode": "48350-370",
        "street": "AVENIDA SANTO AMARO",
        "number": "1234",
        "neighborhood": "BROOKLIN PAULISTA",
        "city": "SAO PAULO",
        "state": "SP",
        "complement": ""
      },
      "taxID": {
        "taxID": "83914717000176",
        "type": "BR:CNPJ"
      },
      "correlationID": "cb5f9107-6158-442d-9884-69b3c5cbcc33"
    },
    "value": 5000,
    "comment": "",
    "identifier": "ab683b8f0e45482fb33154ba80f36354",
    "paymentLinkID": "df9b4d14-31fa-4507-ad02-4d4959a256e5",
    "transactionID": "ab683b8f0e45482fb33154ba80f36354",
    "status": "ACTIVE",
    "additionalInfo": [],
    "discount": 0,
    "valueWithDiscount": 5000,
    "expiresDate": "2023-11-29T12:44:45.489Z",
    "type": "DYNAMIC",
    "correlationID": "12d2d5d9-4c5a-4de1-9892-894da980cd3b",
    "createdAt": "2023-11-28T12:44:45.620Z",
    "updatedAt": "2023-11-28T12:44:45.620Z",
    "brCode": "00020101021226910014br.gov.bcb.pix2569localhost:5001/api/testaccount/qr/v1/ab683b8f0e45482fb33154ba80f36354520400005303986540550.005802BR5904demo6009SAO_PAULO61080455630062290525ab683b8f0e45482fb33154ba863040A26",
    "expiresIn": 86399,
    "pixKey": "9fcd7111-a0a0-451d-916f-91557e899f69",
    "paymentLinkUrl": "http://app.woovi.com/pay/df9b4d14-31fa-4507-ad02-4d4959a256e5",
    "qrCodeImage": "http://app.woovi.com/woovi/charge/brcode/image/df9b4d14-31fa-4507-ad02-4d4959a256e5.png",
    "globalID": "Q2hhcmdlOjY1NjVlMGJkNjliYTEwMjc5ZTQyNDk3OA=="
  },
  "company": {
    "id": "655bbc1b86edb0c8b53d0196",
    "name": "demo",
    "taxID": "75800612000168"
  },
  "account": {}
}
```

---

## Exemplo de resposta de webhook de cobrança expirada

## Webhook de cobrança expirada

Segue abaixo o exemplo dos dados que são enviados numa requisição do webhook de
cobrança expirada (`OPENPIX:CHARGE_EXPIRED`). Esse webhook é disparado no momento
que a cobrança é expirada.

- `event`: O tipo de evento realizado que neste caso seria `OPENPIX:CHARGE_EXPIRED`.
- `charge`: A cobrança que foi expirada.
- `company`: Empresa a que a cobrança pertence.

## Resposta (JSON) de exemplo

```json
{
  "event": "OPENPIX:CHARGE_EXPIRED",
  "charge": {
    "customer": {
      "name": "Antonio Victor",
      "taxID": { "taxID": "12345678976", "type": "BR:CPF" },
      "email": "antoniocliente@example.com",
      "correlationID": "4979ceba-2132-4292-bd90-bee7fb2125e4"
    },
    "value": 123456,
    "comment": "",
    "identifier": "ea83401ed4834b3ea6f1f283b389af29",
    "paymentLinkID": "21516412-4192-409d-ba18-1ac594db4c29",
    "transactionID": "ea83401ed4834b3ea6f1f283b389af29",
    "status": "EXPIRED",
    "additionalInfo": [],
    "discount": 0,
    "valueWithDiscount": 123456,
    "expiresDate": "2023-11-18T18:32:57.679Z",
    "type": "DYNAMIC",
    "correlationID": "0ac9e5a0-04f3-4879-85bf-8be34f16a1fa",
    "createdAt": "2023-11-17T18:32:57.869Z",
    "updatedAt": "2023-11-17T18:35:59.212Z",
    "brCode": "00020101021226910014br.gov.bcb.pix2569localhost:5001/api/testaccount/qr/v1/5b2970f464a740378aa472c6dad0bf8352040000530398654071234.565802BR5905Woovi6009SAO_PAULO610804556300622905255b2970f464a740378aa472c6d63046BA9",
    "expiresIn": 86399,
    "paymentLinkUrl": "https://woovi.com.br/pay/21516412-4192-409d-ba18-1ac594db4c29",
    "qrCodeImage": "https://api.woovi.com.br/woovi/charge/brcode/image/21516412-4192-409d-ba18-1ac594db4c29.png",
    "globalID": "Q2hhcmdlOjY1NTdiMWQ5MmQ4NzYzMjA5ZGU0OWE0NA=="
  },
  "company": {
    "id": "64cab82a485da23384a4e3af",
    "name": "Woovi LTDA",
    "taxID": "75800612000168"
  }
}
```

---

## Configurando o split entre subcontas no Checkout

Com o split de subcontas configurado através do Checkout, você tem a possibilidade de
dividir o valor de uma cobrança paga entre duas ou mais subcontas, de acordo com o valor
que você definir para cada uma delas. Para saber mais sobre subcontas, [clique aqui](../subaccount/split-sub-account-usecases.mdx).

## Pré-requisitos

Caso ainda não tenha ativado o módulo de Subcontas, na aba de `Ajustes`, no detalhe do
chekout em questão, você verá a seguinte mensagem:

![Seção para ativar o módulo de Subcontas no detalhe do Checkout](./__assets__/checkout-settings-activate-split.png)

Clique no botão `Ativar`, e o módulo de Subcontas será ativado para o seu Checkout. Desse modo você poderá configurar o split entre subcontas. É necessário ativar o módulo de Subcontas para que seja possível configurar o split entre subcontas
através do Checkout.

Após ativar, você verá a seguinte seção:

![Seção de formulário da configuração do split entre subcontas no Checkout](./__assets__/checkout-settings-split-form.png)

## Configurando o split entre subcontas

Após realizar a ativação do módulo, você verá a seção de configuração do split entre subcontas
conforme a imagem acima. Você terá dois campos disponíveis para realizar a configuração:

### Status do split

Neste campo, você poderá definir se o split entre subcontas estará ativo ou inativo. Caso esteja
ativo, o valor da cobrança será dividido entre as subcontas configuradas. Caso esteja inativo, o
valor da cobrança será direcionado somente para a conta principal.

### Regra de divisão entre subcontas

Ao ativar o split entre subcontas, você terá uma seção onde poderá inserir as regras de divisão,
contendo os seguintes campos:

- **Chave Pix da Subconta**: chave Pix que irá receber o valor daquela regra de divisão;
- **Valor**: valor fixo que será destinado àquela subconta;

Segue o exemplo da imagem abaixo:

![Formulário de configuração de splits preenchido](./__assets__/checkout-settings-split-form-filled.png)

:::info

Caso queira adicionar novas subcontas na regra de divisão, basta clicar no botão: `Adicionar nova subconta`
e preencher os campos conforme a descrição acima.

:::

Após preencher os campos, clique no botão `Salvar` para que as configurações sejam salvas. Caso todas as informações
forem preenchidas corretamente, você verá uma mensagem de sucesso e estará com o split por subcontas configurado. Suas
próximas cobranças criadas através desse checkout farão o split automaticamente de acordo com as respectivas regras.

:::info

No final da seção do formulário, consta também a informação do montante que será repartido entre subcontas e o restante
que será direcionado para a conta principal.

:::

---

## Como criar um Checkout Pix via plataforma?

## Acessando o formulário

Através do menu lateral, acesse a opção **Checkout** e clique no botão, no canto superior direito,
**Novo Checkout**. Você acessará o [formulário de criação de um novo checkout](https://app.woovi.com.br/home/checkouts/list).

![Formulário de criação de um checkout](./__assets__/checkout-create-form.png)

## Preenchendo o formulário

Após acessar o formulário, preencha os campos obrigatórios:

- **Valor**: valor referente as cobranças criadas por aquele checkout;
- **Descrição**: descrição que será exibido quando acessar aquele checkout.

Após preencher os campos, clique no botão **Criar**. Pronto,
seu checkout foi criado com sucesso!

Após a criação, você será automaticamente redirecionado para a página de detalhe do respectivo checkout.

## Detalhe do checkout

![Detalhe de um checkout](./__assets__/checkout-detail.png)

Na página de detalhe do checkout, você poderá visualizar as informações do checkout criado, como:

- **Valor**: valor referente as cobranças criadas por aquele checkout;
- **Descrição**: descrição que será exibido quando acessar aquele checkout;
- Poderá desativar o checkout, caso desejar.
- Poderá visualizar as cobranças criadas por aquele checkout.
- Poderá acessar o link de pagamento referente àquele checkout.

## Acessando o link de pagamento

Na página de detalhe do checkout, clique no botão **Abrir checkout**.
Você será redirecionado para a página de pagamento do checkout:

![Link de pagamento de um checkout](./__assets__/checkout-payment-link.png)

Esse é o link de pagamento atrelado ao checkout que você criou.
Quando o seu cliente clicar no botão **Pagar**, será gerado uma
cobrança que ele poderá pagar com o respectivo valor e descrição
que você definiu.

---

## Como identificar uma cobrança criada via Checkout com webhook no meu sistema?

## Introdução

:::info

É necessário que você tenha já criado um webhook referente a `Cobrança Criada` ou `Cobrança Paga`,
para que seja possível receber as notificações quando um desses eventos ocorrer.

Caso não tenha criado um webhook ainda, acesse a documentação [instruindo como criá-los](../webhook/platform/webhook-platform-api.mdx).

:::

Caso você deseje identificar uma cobrança criada através de um Checkout em seu
sistema, é possível utilizar os webhooks de cobrança criada ou cobrança paga para
identificar o checkout que originou a cobrança.

## Identificando o Checkout

Quando uma cobrança é criada ou paga via Checkout, através do payload que é enviado no webhook, você verá
um exemplo como este:

```json
{
  "charge": {
    "checkout": {
      "title": "Título do Checkout",
      "paymentLinkID": "ff3e1bjk-9c7d-49eb-933a-8a47423ee928",
      "paymentLinkURL": "https://woovi.com.br/pay/ff3e1bjk-9c7d-49eb-933a-8a47423ee928"
    }
  }
}
```

Neste exemplo, o campo `checkout` dentro do objeto de `charge` contém as informações do checkout que originou a cobrança.

- `title`: Título do checkout, conforme definido na criação do checkout pela plataforma;
- `paymentLinkID`: ID do link de pagamento do checkout, **esse ID é único** e pode ser utilizado para identificar o checkout;
- `paymentLinkURL`: URL do link de pagamento do checkout, que pode ser utilizado para redirecionar o cliente para a página de pagamento.

Com essas informações, você pode identificar o checkout que originou a cobrança e realizar as ações necessárias em seu sistema.

## Exemplo de payload de webhook

Segue abaixo o payload de exemplo de uma cobrança criada (`OPENPIX:CHARGE_CREATED`) via Checkout:

```json
{
  "event": "OPENPIX:CHARGE_CREATED",
  "charge": {
    "customer": null,
    "value": 1200,
    "comment": "Webhook de Evento de Cobrança criada",
    "identifier": "c2cc9e8cd68442b0a41ee26534bef534",
    "paymentLinkID": "429762a4-4bef-4b00-8cc1-f0d3acb676d3",
    "transactionID": "c2cc9e8cd68442b0a41ee26534bef534",
    "status": "ACTIVE",
    "additionalInfo": [],
    "fee": 50,
    "discount": 0,
    "valueWithDiscount": 1200,
    "expiresDate": "2024-03-15T18:00:32.466Z",
    "type": "DYNAMIC",
    "correlationID": "c5820a0a-8abd-46a9-ab9b-ac5a9a68f463",
    "createdAt": "2024-03-14T18:00:34.413Z",
    "updatedAt": "2024-03-14T18:00:34.413Z",
    "brCode": "00020101021226990014br.gov.bcb.pix2577pix-h.bpp.com.br/23114447/qrs1/v2/011sMBpqAGIcbBqf1L8lqJxnJ8gzX6ZGGa22ycXMQ7Q520400005303986540512.005802BR5904demo6009SAO_PAULO61080455630062290525c2cc9e8cd68442b0a41ee265363047835",
    "checkout": {
      "title": "Título do Checkout",
      "paymentLinkID": "ff3e1bjk-9c7d-49eb-933a-8a47423ee928",
      "paymentLinkURL": "https://woovi.com.br/pay/ff3e1bjk-9c7d-49eb-933a-8a47423ee928"
    }
    "expiresIn": 86400,
    "pixKey": "676bd1f8-93cb-4389-b094-5587179d56bf",
    "paymentLinkUrl": "http://woovi.com.br/pay/429762a4-4bef-4b00-8cc1-f0d3acb676d3",
    "qrCodeImage": "http://woovi.com.br/woovi/charge/brcode/image/429762a4-4bef-4b00-8cc1-f0d3acb676d3.png",
    "globalID": "Q2hhcmdlOjY1ZjMzYjQyZmNkYjRlZWMyMmY4YTdjYg=="
  },
  "company": {
    "id": "65ba3d42675443db3debd9f9",
    "name": "Teste",
    "taxID": "75800612000168"
  },
  "account": {
    "clientId": "AE11101E-FBE5-7EC8-130F-D9E6794894F9"
  }
}
```

Para mais informações sobre os campos do payload, acesse a documentação com maiores detalhes:

- [Payload de Cobrança Criada](../charge/webhook/charge-webhook-example-charge-created.md)
- [Payload de Cobrança Paga](../charge/webhook/charge-webhook-example-charge-completed.md)

---

## Começando com o ClickPix

O ClickPix é um tipo de plugin que permite que você crie cobranças com mais facilidade. Para iniciar a utilização do ClickPix, você precisa seguir alguns passos:

## Solicitar a ativação da feature de ClickPix

- O primeiro passo é solicitar a ativação da feature de ClickPix, para isso, você pode solicitar a ativação via o chat de suporte.

## O que é necessário saber antes de utilizar o ClickPix?

- É necessário entender que para utilizar o ClickPix você precisa ter um AppID válido do tipo plugin, veja como criar [aqui](../plugin/app-id).

### Utilizando o Plugin `ClickPix`

A primeira coisa é incluir a tag de script do plugin na parte inferior do arquivo html

```html
<script src="https://plugin.woovi.com.br/v1/woovi.js" async>
```

O script pode ser importado dentro de um arquivo `.html`. Por exemplo, se seu aplicativo for um aplicativo em React, o script do Plugin woovi será importado dentro de `index.html`.

Veja o exemplo abaixo:

```html
<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <title>Demo ClickPix</title>
  </head>
  <body>
    <div id="root"></div>
    <script src="https://plugin.woovi.com.br/v1/woovi.js" async></script>
  </body>
</html>
```

Até este momento, nada deve acontecer, pois o plugin não foi inicializado.
Para confirmar se o plugin foi inicializado corretamente, você pode acessar o console do seu navegador e buscar por esses logs

```
[woovi] connecting, attemp 0
[woovi] connected
```

### Inicializando o plugin `ClickPix`

Após a importação do script, você poderar adicionar as tags para a inicialização dos botões do ClickPix.

```html
<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <title>Demo ClickPix</title>
  </head>
  <body>
    <div id="root">
      <div data-clickpix data-value="888"></div>
    </div>
    <script src="https://plugin.woovi.com.br/v1/woovi.js" async></script>
  </body>
</html>
```

### Customizando o botão ClickPix

É possível customizar o botão ClickPix adicionando atributos no elemento `div` como `data-customer-fields`, `data-additional-info`, e `data-variant`. Note que os paramêtros de `data-clickpix` e `data-value` são obrigatórios.

#### Definindo o valor da cobrança

O valor da cobrança é definido através do atributo `data-value`. O campo `data-value` é obrigatório, e caso não seja informado, o botão não será exibido. O valor enviado deverá ser um número inteiro, sendo o valor da cobrança em centavos.

**Exemplo:**

```html
<div data-clickpix data-value="888"></div>
```

No exemplo acima, o botão sempre gerará uma cobrança no valor de R$ 8,88.

#### Solicitando informações de cliente

Para solicitar informações específicas do cliente, é possível a utilização do atributo `data-customer-fields`. É possível solicitar os seguintes campos:

- Email
- Telefone
- Endereço

Esses dados serão solicitados após a criação da cobrança pelo o botão ClickPix.

**Exemplo:**

```html
<div
  data-clickpix
  data-value="888"
  data-customer-fields="email,phone,address"
></div>
```

No exemplo acima, cobranças criadas pelo o botão sempre solicitarão o email, telefone e endereço do cliente.

#### Adicionando informações adicionais

É possível adicionar informações adicionais em cobranças geradas pelo botão ClickPix, através do atributo `data-additional-info`. Esses dados precisam ser formatados no seguinte formato:

`key1:value1,key2:value2,key3:value3`

Sendo cada `key:value` uma informação adicional diferente.

**Exemplo:**

```html
<div
  data-clickpix
  data-value="888"
  data-additional-info="order:1234,product:123"
></div>
```

No exemplo acima o botão sempre irá gerar uma cobrança com as informações adicionais de `order: 1234` e `product: 123`.

### Definindo a variação do botão ClickPix

É possível definir a variação do botão ClickPix, através do atributo `data-variant`. Essa variação pode ser definida como `default` ou `purple`, `green` ou `gradient`.

Abaixo você encontra todas as variações, ordenadas por `default, purple, green, gradient`.

![ClickPix-variants](./__assets__/clickpix-variants.png)

Caso não seja informado um valor específico, o botão será exibido como `default`.

**Exemplo:**

```html
<div data-clickpix data-value="888" data-variant="purple"></div>
```

No exemplo acima o botão será exibido como um botão `purple`.

---

## Customizando seu próprio botão ClickPix

Leia sobre os passos inicias de como iniciar sua integração com ClickPix

- [Começando com o ClickPix](./click-pix-starting.md)

## Passo a passo da configuração

1) Adicione a tag script do nosso plugin no head da página
```html
<script src="https://plugin.woovi.com.br/v1/woovi.js" async>
```
2) Crie uma div com as propriedades necessárias para o carregamento do seu botão clickpix e defina um `id` para ela, e oculte este botão utilizando CSS adicionando a propriedade `display: none`
> Em nosso exemplo estamos utilizando o id `clickpix-product-1` para este botão, que será usado exclusivamente para buscar o elemento na página
Atributos obrigatórios:
- data-clickpix
- data-appid
- data-value (valor em centavos Ex: 888 = R$ 8,88)
- data-customer-fields (campos que o cliente deve preencher Ex: email,phone)
- data-additional-info (informações adicionais Ex: order:123,product:my-product)
> As informações adicionais devem ser separadas por virgula caso tenha mais de uma. Seguimos um padrão de chave:valor, onde antes dos `:` é o identificador que chamamos de chave para identificar algum dado e depois do `:` é o valor que você deseja atribuir a um identificador

> Em nosso exemplo estou querendo identificar que esse clickpix é um pedido com id `123` e que é um produto chamado `my-product`

```html
<div
  id="clickpix-product-1"
  style="display: none;"
  data-clickpix
  data-appid="YOUR_APPID"
  data-value="888"
  data-customer-fields="email,phone"
  data-additional-info="order:123,product:my-product"
></div>
```
> Para saber se o código do plugin está sendo carregado corretamente, você pode remover a propriedade `style` temporariamente e ver se aparece um botão do `clickpix`, se aparecer é sinal que está sendo carregado
3) Agora você pode criar seu botão customizado e definir um `id` para ele
> Em nosso exemplo este botão está definido com o id `product-1`
```html
  <button class="my-custom-button" id="product-1">Buy here $ 8,88</button>
```
4) Crie uma tag script para colocar o script de busca e gatilho
Para alterar o script, basta você ajustar os valores do `document.querySelector` para os id que você definiu
```html
<script>
  document.addEventListener('DOMContentLoaded', () => {
    // Utilizaremos a função `document.querySelector` para pegar o nosso botão customizado através do atributo id
    const myCustomButton = document.querySelector('#product-1')

    // Criamos um novo evento de click no nosso botão customizado
    myCustomButton.onclick = () => {
      // Agora, fazemos uma busca no nosso botão utilizando o id do botão do clickpix que definimos anteriormente
      // E falamos para a consulta avançar um nível na camada DOM para obter o botão de enviar do clickpix
      const clickpix = document.querySelector('#clickpix-product-1 button')
      // Emitimos um evento de click
      clickpix.click()
    }
  })
</script>
```
5) Pronto! Seguindo esses passos seu botão clickpix estará customizado e pronto para ser utilizado

:::info
Evite usar o atributo `hidden` do javascript no nosso botão clickpix para garantir que ele carregue corretamente
:::

> Resumo: use seu botão personalizado como um gatilho para o botão clickpix e oculte o botão clickpix usando CSS com `display: none`

## Exemplos
Aqui você poderá ver um exemplo completo de como você pode fazer a integração do seu próprio botão utilizando o clickpix
Você precisará apenas criar um `index.html`, copiar nosso exemplo e trocar `YOUR_APPID` pelo seu appID de teste (caso queira testar) ou de produção

### Usando único botão customizado
```html
<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <title>Demo ClickPix</title>
    <style>
      /* Your custom css */
      .my-custom-button {
        text-transform: uppercase;
        text-decoration: none;
        padding: 15px 40px;
        display: inline-block;
        border-radius: 100px;
        background-color: #03d69d;
        border: none;
        color: #fff;
        cursor: pointer;
        font-weight: 800;
      }
    </style>

    <!-- Plugin Script -->
    <script src="https://plugin.woovi.com.br/v1/woovi.js" async></script>
  </head>
  <body>
    <div id="root">
      <!-- Your custom button -->
      <button class="my-custom-button" id="product-1">Buy here $ 8,88</button>

      <!-- ClickPix button -->
      <div
        id="clickpix-product-1"
        style="display: none;"
        data-clickpix
        data-appid="YOUR_APPID"
        data-value="888"
        data-customer-fields="email,phone"
        data-additional-info="order:123,product:my-product"
      ></div>
    </div>

    <script>
      // trigger clickpix button when custom button is clicked
      document.addEventListener('DOMContentLoaded', () => {
        // the # is important for you reference to querySelector that you get a element using a id
        const myCustomButton = document.querySelector('#product-1')

        myCustomButton.onclick = () => {
          const clickPixDivContainer = document.querySelector('#clickpix-product-1')
          const clickPixSubmitButton = clickPixDivContainer.querySelector('button')
          clickPixSubmitButton.click()
        }
      })
    </script>
  </body>
</html>
```

## Usando múltiplos botões com clickpix

```html
<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <title>Demo ClickPix</title>
    <style>
      /* Your custom css */
      .my-custom-button {
        text-transform: uppercase;
        text-decoration: none;
        padding: 15px 40px;
        display: inline-block;
        border-radius: 100px;
        background-color: #03d69d;
        border: none;
        color: #fff;
        cursor: pointer;
        font-weight: 800;
      }

      #root {
        display: flex;
        justify-content: center;
        align-items: center;
        gap: 20px;
        height: 100vh;
      }
    </style>

    <!-- Plugin Script -->
    <script src="https://plugin.woovi.com.br/v1/woovi.js" async></script>
  </head>
  <body>
    <div id="root">
      <!-- Your wrapper for buttons -->
      <div class="clickpix-button" id="product-1">
        <!-- Your custom button -->
        <button class="my-custom-button">Buy here R$ 8,88</button>

        <!-- ClickPix button -->
        <div
          class="button-action"
          style="display: none;"
          data-clickpix
          data-appid="YOUR_APPID"
          data-value="888"
          data-customer-fields="email,phone"
          data-additional-info="order:123,product:my-product"
        ></div>
      </div>

      <!-- Your wrapper for buttons -->
      <div class="clickpix-button" id="product-2">
        <!-- Your custom button -->
        <button class="my-custom-button">Buy here R$ 18,88</button>

        <!-- ClickPix button -->
        <div
          class="button-action"
          style="display: none;"
          data-clickpix
          data-appid="YOUR_APPID"
          data-value="1888"
          data-customer-fields="email,phone"
          data-additional-info="order:123,product:my-product" 
        ></div>
      </div>

      <!-- Your wrapper for buttons -->
      <div class="clickpix-button" id="product-3">
        <!-- Your custom button -->
        <button class="my-custom-button">Buy here R$ 28,88</button>

        <!-- ClickPix button -->
        <div
          class="button-action"
          style="display: none;"
          data-clickpix
          data-appid="YOUR_APPID"
          data-value="2888"
          data-customer-fields="email,phone"
          data-additional-info="order:123,product:my-product"
        ></div>
      </div>
    </div>
    <script>
      document.addEventListener('DOMContentLoaded', () => {
        // get all clickpix buttons
        const clickpixButtons = document.querySelectorAll('.clickpix-button')

        clickpixButtons.forEach((clickpixButton) => {
          // get you custom button
          const customButton = clickpixButton.querySelector('button.my-custom-button')

          // set a trigger event in your custom button
          customButton.onclick = () => {
            // get our clickpix button container
            const clickpixDivContainer = clickpixButton.querySelector('.button-action')
            // get our clickpix submit button
            const clickpixSubmitButton = clickpixDivContainer.querySelector('button')
            // emit click event
            clickpixSubmitButton.click()
          }
        })
      })
    </script>
  </body>
</html>
```

---

## Basis Points (bips)

## Basis Points

`Basis points`, `bips` ou somente `bps` é uma unidade de medida usada frequentemente por instituições financeiras para representar porcentagens.

`1 bps` é igual a `0.01%`.

Basis points são usados principalmente para melhorar a clareza da comunicação, dizer que uma porcentagem mudou pode ser ambíguo, como na seguinte situação hipotética:

`A taxa de juros de crédito é de 10%`

Dizer: `A taxa vai aumentar em 5%`

Não é claro a respeito de se a nova taxa vai ser 5% maior do que era, ou seja, a nova taxa é `10,5%`, ou se aumentou em 5% e agora é `15%`.

Agora, dizer `A taxa de juros aumentou em 50 basis points` trás clareza e um leitor poderia facilmente saber que a nova taxa é de `10,5%`

### Referências externas

Calculadora de basis points: [https://www.omnicalculator.com/finance/basis-point](https://www.omnicalculator.com/finance/basis-point)

[https://www.suno.com.br/artigos/basis-points/](https://www.suno.com.br/artigos/basis-points/)

[https://www.investopedia.com/ask/answers/what-basis-point-bps](https://www.investopedia.com/ask/answers/what-basis-point-bps)

---

## Cobrança(Concepts)


Uma Cobrança representa uma soliticação de pagamento.

Uma Cobrança precisa ter um valor.

Uma Cobrança permite que ao receber um pagamento, ele seja automaticamente reconciliado.

Uma Cobrança aceita somente 1 pagamento.

Uma Cobrança possui um prazo de vencimento.

Casos de uso: criar uma cobrança para um pedido, criar uma cobrança para um serviço, criar uma cobrança para um produto.

---

## Correlation ID

Ao lidar com a comunicação entre sistemas distribuídos e serviços em uma aplicação, um aspecto crítico é a identificação e o rastreamento de transações específicas. O Correlation ID (ID de Correlação) desempenha um papel fundamental nesse processo. Vamos explorar a formatação adequada do Correlation ID e fornecer um exemplo prático para ilustrar sua implementação.

## O que é um Correlation ID?

Um Correlation ID é um identificador exclusivo associado a uma transação ou solicitação específica que percorre todo o ciclo de vida da operação, desde a entrada até a saída do sistema. Isso é essencial para rastrear e correlacionar eventos e logs relacionados a uma determinada transação, facilitando a depuração e o monitoramento de sistemas complexos.

Na plataforma da Woovi, o `correlationID` é também a **chave de idempotência** das nossas APIs: ele garante que uma cobrança ou um pagamento seja criado uma única vez, mesmo que a requisição seja reenviada. Para pagamentos (Pix Out), isso significa **reusar o mesmo `correlationID` em todas as tentativas até o pagamento chegar a um estado terminal** — gerar um ID novo para o mesmo pagamento cria uma duplicata. Veja [Idempotência](./idempotence.md) para os detalhes e exemplos.

## Formato Recomendado

O formato do Correlation ID deve ser consistente e fácil de gerar, interpretar e comparar. Recomenda-se o uso de uma sequência alfanumérica única, como um UUID (Universally Unique Identifier) ou um GUID (Globally Unique Identifier). Esses formatos geralmente possuem uma estrutura semelhante a:

Exemplos:
123e4567-e89b-12d3-a456-426655440000

Onde cada caractere é uma representação hexadecimal.

## Exemplo Prático

Vamos considerar um cenário em que estamos desenvolvendo um serviço de pagamento em um ambiente de microserviços, onde várias solicitações são processadas simultaneamente. Ao receber uma solicitação de pagamento, geramos um Correlation ID único para essa transação. Aqui está um exemplo de implementação em Python:

```python
import uuid

def process_payment(request):
    correlation_id = str(uuid.uuid4())
    # Restante do processamento da solicitação com o uso do Correlation ID
```

Neste exemplo, a biblioteca UUID do Python é usada para criar um ID de Correlação único sempre que uma solicitação de pagamento é recebida. Esse ID pode ser incluído em registros de log, cabeçalhos de solicitação e respostas, permitindo o rastreamento da transação em todo o sistema.

## Conclusão

O Correlation ID desempenha um papel crucial na rastreabilidade e no monitoramento de sistemas distribuídos. Ao adotar um formato consistente, como UUID ou GUID, os desenvolvedores podem garantir a eficácia do rastreamento de transações na plataforma da Woovi, simplificando a depuração e melhorando a visibilidade operacional. Certifique-se de seguir as melhores práticas ao implementar o Correlation ID em sua aplicação.

---

## Client

## Cliente

Um Cliente representa um cliente do seu e-commerce ou loja física.

Ao cadastrar os seus clientes você consegue descobrir quem são seus melhores clientes e enviar ofertas personalizadas.

---

## Idempotência


Idempotência, no contexto de desenvolvimento, significa que chamar uma determinada função uma vez ou várias vezes deve ter o mesmo efeito no estado do sistema.

Uma função ser idempotente não significa que o retorno é sempre igual, mas que essa função, caso ela tenha alterado o estado do sistema, não faça nenhuma nova alteração, caso ela seja chamada logo em seguida com os mesmos parâmetros.

Então, por exemplo, uma função que retorna o saldo de uma conta é idempotente, mesmo que ela retorne valores diferentes (porque outras funções podem ter alterado o estado do sistema entre uma chamada e outra.)

### Idempotência nas nossas APIs

Ao utilizar nossas APIs, para garantir idempotência nas chamadas, nós usamos o padrão conhecido como Idempotence-Key, o que significa que ao fazer uma chamada para nossa API, é importante especificar um ID que o seu sistema entenda como correspondente à operação.

Ex.:

> Você quer usar nossa API para criar uma cobrança
>
> No seu sistema, você deve ter uma tabela/coleção que representa a criação da cobrança, criar um documento e pegar o ID dele
>
> Na chamada para a nossa API, adicione uma propriedade `correlationID` com esse ID.

Ao utilizar nossos webhooks, é necessário garantir que a rota que lida com os webhooks seja idempotente, pois é prática comum reenviar webhooks para garantir que pelo menos um deles chegou e foi processado. No final desse documento, tem exemplos de como você pode fazer essa implementação.

Para pagamentos (Pix Out), o `correlationID` também é a chave de idempotência: reuse o mesmo `correlationID` em retries até o pagamento chegar a um estado terminal. Veja [Idempotência em Pagamentos](../payment/payment-idempotency.md) para os detalhes e exemplos.

### Por que idempotência é relevante?

Um problema recorrente em sistemas orientados a eventos, é duplicação de eventos, isso pode ocorrer por diversas razões, como falhas de comunicação, invocações paralelas das funções que geram os eventos, etc.

Sistemas resilientes são construídos considerando que esses problemas podem e vão frequentemente acontecer, e se preparando de maneira adequada para que falhas de comunicação não causem um estado interno ruim.

Então, a principal importância da idempotência é fazer que seu sistema seja resiliente e confiável.

### Quando uma função deve ser idempotente?

Como tudo no desenvolvimento, depende fortemente do objetivo do projeto e das regras de negócio.

Entretanto, existem alguns padrões:

#### REST APIs

##### Rotas PUT

Todas as rotas com o verbo PUT, que fazem alterações em entidades.

Ex.: Uma rota que serve para mudar o endereço de um cliente.

Enquanto o novo endereço for o mesmo, não deve fazer diferença para o estado do sistema quantas vezes essa rota for chamada.

##### Rotas GET

Todas as rotas com o verbo GET, que servem para ler informações.

Ex.: Uma rota que serve para ler o saldo atual de uma conta bancária.

Mesmo que o saldo mude com o passar do tempo, é seguro chamar essa rota várias vezes, sem que ela cause alterações no estado do sistema.

##### Rotas DELETE

Todas as rotas com o verbo DELETE, que servem para apagar entidades.

Ex.: Uma rota que sirva para deletar uma cobrança.

Uma vez chamada, a função vai apagar a conta bancária, chamadas subsequentes não devem apagar outras contas, mas retornar alguma mensagem dizendo que essa conta já foi deletada.

##### Rotas POST públicas

Nem toda rota POST precisa ser idempotente.

É interessante considerar que se servidores externos vão chamar sua API (em oposição à servidores/aplicações que você controla), pois se for o caso, os mesmos problemas de conexão associados à webhooks surgirão, e essas rotas também devem ser idempotentes.

#### WebHooks e sistemas orientados a eventos

É normal que rotas que lidam com webhooks ou que lidam com eventos sejam invocadas várias vezes.

Isso acontece para resolver problemas de insegurança na comunicação entre os servidor que originou o evento com o receptor da mensagem.

Por conta disso, rotas que lidam com webhooks precisam ser idempotentes.

### Como implementar idempotência?

Esses são alguns padrões de como implementar idempotência>

#### Padrão getOrCreate

A ideia dessa padrão é verificar se a entidade que a função está tentando criar já não tem um equivalente criado no banco de dados.

Supondo essa função:

```js
const createCustomerBankAccount = function(customer, params){

    // Validações do modelo
    ...

    // Criando a conta no banco de dados
    db.customerBankAccount.create({ ...params, customer: customer.id })
}
```

Aplicando este padrão, ela pode ser rescrita da seguinte forma:

```js
const getOrCreateCustomerBankAccount = function(customer, params){

    // Antes de fazer validações para criação, podemos procurar pelos parâmetros mais importantes no nosso banco de dados e retornar uma conta já existente
    const existingCustomerBankAccount = db.customerBankAccount.get({
        customer: customer.id,
        bankId: params.bankId
    })

    if (existingCustomerBankAccount){
        return existingCustomerBankAccount;
    }

    // Validações do modelo
    ...

    // Criando a conta no banco de dados
    db.customerBankAccount.create({ ...params, customer: customer.id })
}
```

#### Padrão histórico de chamadas

A ideia desse padrão é salvar todas as chamadas feitas para a rota que lida com os eventos e ao receber uma nova chamada, verificar se não existe uma chamada igual que foi feita anteriormente.

Supondo essa função:

```js
const createCustomerBankAccount = function(customer, params){

    // Validações do modelo
    ...

    // Criando a conta no banco de dados
    db.customerBankAccount.create({ ...params, customer: customer.id })
}
```

Aplicando este padrão, ela pode ser rescrita da seguinte forma:

```js
const createCustomerBankAccount = function(customer, params){

    const newRequest = { customer, ...params }

    const existingRequest = db.events.get(newRequest);

    if (existingRequest){
        return;
    }

    // Validações do modelo
    ...

    // Criando a conta no banco de dados
    db.customerBankAccount.create({ ...params, customer: customer.id })

    db.events.create({...newRequest})
}
```

Ou ainda, usando hashing para poupar armazenamento:

```js
const createCustomerBankAccount = function(customer, params){

    const newRequestHash = MD5(JSON.stringify({ customer, ...params }));

    const existingRequest = db.events.get(hash: newRequestHash);

    if (existingRequest){
        return;
    }

    // Validações do modelo
    ...

    // Criando a conta no banco de dados
    db.customerBankAccount.create({ ...params, customer: customer.id })

    db.events.create({ hash: newRequestHash})
}
```

#### Padrão Idempotence-Key

A ideia desse padrão é usar uma chave para representar uma operação, e ao receber uma chave duplicada, não repetir a operação.

Nós utliziamos um padrão semelhante a este em nossas APIs através da propriedade `correlationID`.

Supondo essa função:

```js
const createCustomerBankAccount = function(customer, params){

    // Validações do modelo
    ...

    // Criando a conta no banco de dados
    db.customerBankAccount.create({ ...params, customer: customer.id });
}
```

Aplicando este padrão, ela pode ser rescrita da seguinte forma:

```js
const createCustomerBankAccount = function(customer, params){

    const { idempotenceKey } = params;

    // Checamos se o usuário enviou uma chave de idempotência
    if (idempotenceKey){

        const existingBankAccount = db.customerBankAccount.get({
            idempotenceKey
        })

        // Checamos se alguma conta já foi cadastrada por essa operação e retornamos caso já tenha acontecido
        if (existingBankAccount){
            return existingBankAccount;
        }

    }

    // Validações do modelo
    ...

    // Criando a conta no banco de dados
    db.customerBankAccount.create({ ...params, customer: customer.id });
}
```

---

## Reembolso


Reembolso é uma transação que reverte um pagamento recebido.

O Reembolso pode ser total ou parcial.

---

## Máquina de Estado

## O que é Máquina de Estado

Máquina de Estado é o sistema que controla o estado de um item. Ela é responsável por garantir que as mudanças sempre serão as previsiveis e serão baseadas no estado atual.

Um exemplo do mundo real seria um sinal de trânsito, onde você possui mudanças previsíveis de estado, sendo que o próximo estado é sempre baseado no estado atual.

```
Vermelho --> Verde
Verde --> Amarelo
Amarelo --> Vermelho
```

---

## Transação


Uma Transação representa um pagamento recebido.

---

## Clientes

A plataforma permite cadastrar os seus clientes.

Um cliente representa alguém que pague por alguns dos seus produtos ou serviços.

Cadastrar clientes permite você descobrir quais são os seus melhores clientes.

Também é possível enviar notificações e campanhas de marketing para vender mais com os seus clientes existentes.

## Casos de Uso

- Descobrir o perfil dos seus clientes
- Engajar clientes existentes com promoções
- Descobrir quais são os seus melhores clientes

---

## Como criar clientes em lote?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para criar clientes em lote acesse o menu de [Clientes](/docs/payment/payment-how-to-request-access) 
na plataforma e clique no opção de **Cliente em Lote**, presente no canto direito superior.

Você será redirecionado para a página de [Cliente em Lote](https://app.woovi.com/home/crm/create-batch), onde encontrará os passos
para criar clientes em lote.

No primeiro passo você encontra os campos para preencher na planilha para importação. Você pode tambem baixar o nosso **modelo do excel**, 
uma planilha excel que ja possui os campos em ordem para facilitar o preenchimento dos dados.

Após ter a planilha com os dados preenchidos, você pode enviar ele no campo de upload, selecionando o arquivo ou arrastando e soltando para dentro da área selecionável.

Após isso, basta clicar em `Avançar` para ir pro próximo passo.

![area-for-upload-file](./__assets__/area-for-upload-file.png)

Após avançar pro próximo passo você poderá verificar os dados enviados em uma tabela, onde poderá editá-los dando um clique duplo no campo desejado. 

Caso algum campo esteja com um formato diferente do correto, um erro sobre a linha poderá ser encontrado, basta clicar para expandir para ter mais informações sobre o erro.

![batch-with-error](./__assets__/batch-with-error.png)

Após validar e corrigir (caso necessário) todos os dados, clique em **Registrar XX Clientes**.

Os clientes serão registrados e o resultado aparecerá na sua tela.

Você encontrará os clientes registrados, e poderá navegar até a lista de clientes clicando no botão **Ver Clientes**.

![go-to-customer-list](./__assets__/go-to-customer-list.png)

---

## Como usar a API para criar um cliente?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para criar um cliente, você utiliza o _endpoint_ `/api/v1/customer` da API.

Você pode acessar [aqui](/api#tag/customer/POST/api/v1/customer)
a documentação referente a esse _endpoint_.

Os campos obrigatórios para criar um cliente são os sequintes:

- **`name`**: Nome do cliente.

E além do nome é necessário enviar um desses três dados:

- **`taxID`**: CPF ou CNPJ do cliente.
- **`email`**: Email do cliente.
- **`phone`**: Celular do cliente. (començando com 55 e código de área)

### Exemplo

O body da sua requisição será semelhante a um destes exemplos:

#### Exemplo com taxID

```json
{
  "name": "Dan",
  "taxID": "360.***.***-72"
}
```

#### Exemplo com email

```json
{
  "name": "Dan",
  "email": "dan@gmail.com"
}
```

#### Exemplo com telefone

```json
{
  "name": "Dan",
  "phone": "554899..."
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, retornaremos o cliente criado.

Retornarmeros a seguinte resposta de exemplo:

```json
{
  "customer": {
    "name": "NOME DO CLIENTE",
    "taxID": { "taxID": "360...", "type": "BR:CPF" },
    "correlationID": "d1d46bbd-b010-4beb-b59e-cecf824efb43"
  }
}
```

#### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/customer' -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      --data-binary '{ "name": "Dan", "email": "dan@gmail.com" }'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/customer', {
  method: 'POST',
  body: JSON.stringify({ name: 'Dan', email: 'dan@gmail.com' }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

  

## Como usar a API para criar um cliente com endereço?

Ao criar um cliente, é possível também adicionar um endereço.

:::info

Para criar cobranças que tenham vencimento, multa e juros, é necessário que o cliente sendo cobrado tenha um endereço cadastrado, assim como seu taxID (CPF/CNPJ), eu vou assumir este caso de uso para o exemplo a seguir.

:::

Então, os campos obrigatórios são:

- **`name`**: Nome do cliente.
- **`taxID`**: CPF ou CNPJ do cliente.
- **`address`**: Endereço do cliente.

Você pode encontrar documentação a respeito da modelagem do objeto de endereço [aqui](/api#tag/customer/POST/api/v1/customer).

### Exemplo

O body da requisição, com os dados de endereço adicionados fica semelhante à esta:

```json
{
  "name": "Ana",
  "taxID": "672.***.***-51",
  "address": {
    "zipcode": "137...",
    "street": "R...",
    "number": "15",
    "neighborhood": "Centro",
    "city": "S...",
    "state": "SP",
    "complement": "Casa"
  }
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, retornaremos o cliente criado.

Retornarmeros a seguinte resposta de exemplo:

```json
{
  "customer": {
    "name": "ana",
    "correlationID": "6ffa...",
    "address": {
      "zipcode": "137...",
      "street": "R...",
      "number": "15",
      "neighborhood": "Centro",
      "city": "S...",
      "state": "SP",
      "complement": "Casa"
    },
    "taxID": { "taxID": "67...", "type": "BR:CPF" }
  }
}
```

#### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/customer' -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      --data-binary '{"name": "Ana", "taxID": "672.***.***-51", "address": {
        "zipcode": "137...", "street": "R...", "number": "15",
        "neighborhood": "Centro", "city": "S...", "state": "SP",
        "complement": "Casa" } }'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/customer', {
  method: 'POST',
  body: JSON.stringify({
    name: 'Ana',
    taxID: '672.***.***-51',
    address: {
      zipcode: '137...',
      street: 'R...',
      number: '15',
      neighborhood: 'Centro',
      city: 'S...',
      state: 'SP',
      complement: 'Casa',
    },
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como atualizar os dados de um cliente

É possível alterar o dados de um cliente, tanto via api, quanto via plataforma e o objetivo dessa documentação é mostrar como fazer isso.

:::info
Alguns dados sensíveis na documentação estarão mascarados por questões de segurança.
:::

## Via Plataforma

Para alterar os dados de um cliente via plataforma você precisa

### 1. Acessar a aba de Clientes

![1 Select Customers Tab](__assets__/customerUpdate/1-select-customers-tab.png)

### 2. Selecionar o cliente que deseja alterar

![2 Select Customer](__assets__/customerUpdate/2-select-customer.png)

### 3. Clicar em qual campo você desejar alterar

![3 Edit And Save](__assets__/customerUpdate/3-edit-and-save.png)
Ao editar o campo não esqueça de clicar em salvar em cada campo.

## Via API

Para alterar os dados de um cliente via API, você utiliza o _endpoint_ `/api/v1/customer/{id}` da API utilizando o método `PATCH`.

Para editar o cliente você precisa chamar a API informando o correlationID do cliente em que deseja alterar na URL, e no corpo da requisição você pode informar os campos `name`, `email`, `phone`, `address` and `taxID`.

:::info
O campo taxID é um campo que não pode ser editado do usuário, caso já possua valor. Ou seja, se o cliente já possuir um taxID cadastrado, não será possível alterá-lo. Caso precise editar o taxID de um usuário de qualquer maneira, o ideal é criar um novo cliente com o novo taxID.
:::

### Exemplo

No body da requisição, você precisa informar **somente** os campos que deseja alterar, caso não informe um campo, ele não será alterado.

#### Exemplo com taxID

```json
{
  "name": "Eduardo",
  "taxID: "360.***.***-72"
}
```

#### Exemplo com email

```json
{
  "name": "Dan",
  "email": "dan@gmail.com"
}
```

#### Exemplo com telefone

```json
{
  "name": "Dan",
  "phone": "+554899..."
}
```

#### Exemplo com endereço

```json
{
  "address": {
    "zipcode": "137...",
    "street": "R...",
    "number": "15",
    "neighborhood": "Centro",
    "city": "S...",
    "state": "SP",
    "complement": "Casa"
  }
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, retornaremos o cliente criado.

Retornarmeros a seguinte resposta de exemplo:

```json
{
  "customer": {
    "name": "NOME DO CLIENTE",
    "taxID": { "taxID": "360...", "type": "BR:CPF" },
    "correlationID": "d1d46bbd-b010-4beb-b59e-cecf824efb43",
    "address": {
      "zipcode": "137...",
      "street": "R...",
      "number": "15",
      "neighborhood": "Centro",
      "city": "S...",
      "state": "SP",
      "complement": "Casa"
    }
  }
}
```

Consulte a documentação da API para mais informações sobre os campos e a resposta da requisição aqui: [API](/api#tag/customer/PATCH/api/v1/customer/{id})

---

## Payload GET de Disputa

## Buscar Disputa (GET)

O endpoint GET de `Disputa` retorna um objeto com os seguintes campos:

- `dispute`: Detalhes da disputa

### Campos do objeto `dispute`:

- `type`: Tipo da disputa (`MED` ou `CHARGEBACK`)
- `status`: Status da disputa
- `endToEndId`: Identificador end-to-end da transação
- `id`: ID único da disputa
- `name`: Nome do cliente que abriu a disputa (apenas para `type: CHARGEBACK`)
- `email`: Email do cliente (apenas para `type: CHARGEBACK`)
- `phoneNumber`: Telefone do cliente (apenas para `type: CHARGEBACK`)
- `value`: Valor da disputa em centavos (apenas para `type: CHARGEBACK`)
- `disputeReason`: Motivo da disputa (apenas para `type: CHARGEBACK`)

### Tipos de disputa:

- `MED`: Mecanismo Especial de Devolução - Retorna campos básicos da disputa
- `CHARGEBACK`: Contestação de pagamento na Woovi - Retorna campos detalhados incluindo dados do cliente

## Exemplos de Resposta

### Disputa do tipo MED

```json
{
  "dispute": {
    "type": "MED",
    "status": "REJECTED",
    "endToEndId": "E31680151202503252045C0MHIPSJI6S",
    "id": "67e3170b38e62d5935ed4faf"
  }
}
```

### Disputa do tipo CHARGEBACK

```json
{
  "dispute": {
    "status": "ACCEPTED",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phoneNumber": "+5511999999999",
    "value": 10000,
    "disputeReason": "Product not received",
    "endToEndId": "Ea9c291526ae54b4cb41d9909bdf6d792",
    "type": "CHARGEBACK"
  }
}
```

---

## O que é uma disputa?

Com a popularização das transações digitais, as Disputas financeiras também têm aumentado. Felizmente, a woovi/Woovi oferece aos seus clientes uma forma segura e eficiente de lidar com possíveis casos de fraude/golpe em transações Pix, disponibilizando a disputa, como forma de denúncia.

## Casos de Uso

- Fraude ou golpe
- Serviço não foi entregue

---

## Como adicionar uma nova evidência em uma disputa?

Quando se está respondendo ou iniciando uma disputa, é possível enviar documentos que serão usados como evidências e provas de que o seu argumento é válido e coerente, serve tanto para defesa quanto para quem contesta.

Para enviar evidências para uma disputa, basta seguir os seguintes passos:

### 1. Obter o id da disputa
  * Entre na plataforma e crie um webhook para o evento "OPENPIX:DISPUTE_CREATED".
  * No payload do evento, obtém-se o id da disputa.
 ```JSON
{
  "event": "OPENPIX:DISPUTE_CREATED",
  "dispute": {
    "status": "<status>",
    "endToEndId": "<endToEndId>",
    "id": "<IdDisputa>"
  }
}
 ```

### 2. Fazer upload do documento

Você tem duas formas de enviar o documento, e cada uma alimenta um campo diferente no passo 3. Envie **`url` ou `fileId`, nunca os dois** no mesmo documento.

| Forma | Campo no passo 3 | Quando usar |
| --- | --- | --- |
| [Endpoint de arquivos da Woovi](../arquivos/upload-de-arquivo.md), com `purpose` `DISPUTE_EVIDENCE` | `fileId` (o `file.id` do retorno) | Recomendado. Você não precisa hospedar o arquivo nem expor uma URL pública. Exige a feature `DISPUTE_EVIDENCE_FILE_ID` na sua conta. |
| Provedor de arquivos de sua preferência | `url` | Quando você já tem uma URL pública de onde a Woovi consegue baixar o documento. |

### 3. Fazer requisição para envio de evidencia
  * Utilize a chave de API para autenticar a requisição.
  * Faça a requisição.

Enviando por `fileId`:

 ```JSON
    curl -X POST "https://api.woovi.com/api/v1/dispute/:IdDisputa/evidence \
      -H "Authorization: <apiKey>" \
      -H "Content-Type: application/json" 
        --data-raw '
{
    "documents": [
      {
        "fileId": "<idDoArquivo>",
        "description": "<discription>",
        "correlationID": "<correlationID>"
      }
    ]
}'
 ```

Enviando por `url`:

 ```JSON
    curl -X POST "https://api.woovi.com/api/v1/dispute/:IdDisputa/evidence \
      -H "Authorization: <apiKey>" \
      -H "Content-Type: application/json" 
        --data-raw '
{
    "documents": [
      {
        "url": "<urlDocumento>",
        "description": "<discription>",
        "correlationID": "<correlationID>"
      }
    ]
}'
 ```

### 4. Entendendo o retorno
  * Caso tudo ocorra corretamente, um código 200 será retornado.
  * No corpo da resposta terá:
 ```JSON
{
    "documents": [
      {
        "url": "<urlParaVisualizarDocumento>",
        "fileId": "<idDoArquivo>",
        "description": "<discription>",
        "correlationID": "<correlationID>"
        "createdAt": "<now>"
      }
    ]
}'
 ```

O `fileId` só volta no retorno quando o documento foi enviado por `fileId`.

OBS: ao finalizar o processamento da requisição, é gerada uma nova url para download, isso se deve ao fato de usarmos a url presente no corpo da requisição para fazer o download dos seus documentos e imediatamente em seguida é realizado o upload novamente em um servidor próprio, nós disponibilizamos essa url no payload do response, logo se tudo der certo, a url que é enviada no corpo da request é diferente da url que é obtida no response.

### Erro ao enviar por `fileId`

Se a sua conta não tem a feature `DISPUTE_EVIDENCE_FILE_ID`, a requisição responde `403`:

 ```JSON
{
  "error": "Your account does not have the permission to send a evidence by fileId",
  "errorCode": "DISPUTE_EVIDENCE_FILE_ID_NOT_ALLOWED"
}
 ```

Nesse caso, envie o documento por `url` ou fale com o suporte para liberar a feature.

## Casos de Uso

- Resposta de Disputa

---

## Como criar uma disputa?

### Formulário

Você pode criar uma disputa de forma fácil atráves do link: https://woovi.com/disputa.

E então preencher os dados sobre a transação com suspeita de fraude.

![dispute-form](./__assets__/dispute-form.png)

Após isso voce será redirecionado para uma página onde será possível ver o status da disputa, esse link também será enviado para o email do pagador.

![dispute-page](./__assets__/dispute-page.png)

### Análise da disputa

E então faremos uma análise da disputa, durante esse tempo o saldo relacionado a transação será bloqueado no saldo da empresa. Isso garante que o dinheiro possa ser devolvido, caso a disputa seja aceita.

### Envio de evidências e provas

Ambas as partes envolvidas na disputa - a empresa e o destinatário da transação - devem enviar evidências e provas para a equipe de suporte da woovi/Woovi. Isso inclui informações como descrições detalhadas da transação, conversas com o destinatário, comprovantes de pagamento, notas fiscais, entre outros.

---

## Webhooks da disputa

## Webhooks

Voce deve ir em API/Plugins e selecionar a opção `Novo webhook` para criar um webhook de disputa

![api/plugins](./__assets__/plugins.png)

![new webhhok](./__assets__/new-webhook.png)

![webhook-panel](./__assets__/dispute-webhook.png)

Após selecionar a URl todo evento de disputa selecionado será enviado para essa URL

## Exemplo

Esse é o webhook que será enviado quando uma disputa for criada

```json
{
  "event": "OPENPIX:DISPUTE_CREATED",
  "dispute": {
    "status": "OPENED",
    "endToEndId": "E3524a995bbd54034b6d07c1c36014557",
    "name": "Seu jorge",
    "email": "test@email.com.br",
    "phoneNumber": "+5519989673846",
    "value": 1000,
    "disputeReason": "Golpe"
  }
}
```

Veja mais exemplos de webhooks [aqui](/docs/webhook/examples/webhook-created-payload)

---

## Como integrar o Pix em sua loja EasyDigitalDownloads

import Embed from 'react-embed';

Converta mais utilizando woovi na sua loja que utilize o plugin WordPress EasyDigitalDownloads.

## Como instalar

:::caution Pré-requisitos

- Instalação WordPress
- Plugin EasyDigitalDownloads
  :::

Acesse a página de [lançamentos](https://github.com/Open-Pix/openpix-easy-digital-downloads/releases/latest) no GitHub e baixe o arquivo ZIP `openpix-easy-digital-downloads.zip` da última versão.

Em seu painel de administração, acesse a página de "Adicionar plugin" e clique em enviar plugin. Aperte o botão de escolher arquivo e selecione o arquivo ZIP:

![Enviando um plugin](./__assets__/edd-wp-add-plugin.png)

Prossiga para a página de plugins em "Plugins instalados" e ative o plugin "woovi EasyDigitalDownloads"

## Como configurar

### Como criar a integração com API

Acesse a página de configurações do plugin EasyDigitalDownloads em Downloads > Settings (Configurações).

Vá na aba Pagamentos > woovi.

Nesta página é necessário informar seu [AppID](../plugin/app-id) da woovi. Veja [como criar uma nova integração do tipo plugin](../apis/getting-started-api).

Tendo seu App ID, cole ele no campo "App ID" e clique em Salvar alterações:

![Página de configurações](./__assets__/edd-configure.png)

Veja que a URL de webhook está informada nesta página.

### Como criar o webhook

Para que os status dos pedidos sejam atualizados e o download seja liberado ao efetuar o pagamento PIX, é necessário configurar o webhook na plataforma da woovi.

Vá até a plataforma e acesse [API/Plugins > Novo Webhook](https://app.woovi.com/home/applications/webhook/create):

![Página de criação de webhooks](./__assets__/edd-woovi-create-webhook.png)

Informe o nome do webhook, selecione o evento "Cobrança paga - OPENPIX:CHARGE_COMPLETED" e insira a URL do seu webhook de acordo com o que foi informado na página de configurações do plugin seguindo o formato `https://<url-do-seu-site>/wp-json/edd-woovi-gateway-webhook/v1/callback`.

Salve o webhook e sua configuração estará pronta.

## Como fazer uma compra

Realize a compra de um produto e na página de checkout selecione o método de pagamento woovi:

![Página de checkout](./__assets__/edd-checkout.png)

Na tela de confirmação irá aparecer o QRCode da woovi:

![Página de confirmação](./__assets__/edd-confirmation.png)

Após efetuar o pagamento o download será liberado para o cliente:

![Página de download](./__assets__/edd-download-open.png)

## Vídeo demonstrativo

---

## Magento1 Changelog

<details>
  <summary>Change Log</summary>

#### 2.1.0 - 12/08/2023

- Implemented 1click v2, a button that redirects the user to our platform with the webhook URL and AppID already prepared.

#### 2.0.1 - 24/08/2023

- Removed giftback, which was causing bugs.
- Rename Pix Parcelado to Woovi Parcelado.
- Implemented OneClick configuration.

#### 1.3.0 - 31/07/2023

- Implementation of Woovi Parcelado Feature

#### 1.2.9 - 13/03/2022

- Initial Version

</details>

---

## Magento1 Download

import Magento1Changelog from './magento1-changelog.mdx'

Faça o download da versão .zip do plugin pelo link abaixo:
![Banner](/img/ecommerce/magento1/magento1-banner.png)
[Download Woovi Magento1 Plugin - versão 2.1.0](pathname:///magento1/woovi_pix.2.1.0.zip) - Versão Atual

Extraia o conteúdo do arquivo .zip e cole dentro da pasta `root` da sua loja Magento1.
Geralmente a loja root é nomeada como `src` que faz referência à source. Caso sua loja seja diferente, procure pela pasta que contenha outras pastas como:

- app
- js
- lib
- skin
- var

Assim como no exemplo abaixo:

![magento1-src-folder](/img/ecommerce/magento1/magento1-folder-structure.png)

Encontrando a pasta que contenha essas citadas basta realizar o seguinte:

- Copiar os arquivos extraídos do .zip;
- Colar dentro dessa pasta

---

## Integrando a Woovi com Magento1 Em Um Clique

## Plugin Pix para Magento1

## Resumo

Este documento detalha passos necessários para conectar a sua plataforma de e-Commerce, baseada no Magento1, na Woovi.

:::caution Atenção
- Este documento espera que você já tenha um ambiente Magento1 ativo, e uma conta criada na Woovi.
:::

:::tip Dica
Para utilizar este tutorial é necessário ter uma versão acima da 1.4.0
:::

## Configurando o Plugin Magento1

### Instale o Plugin Woovi na sua instância Magento1

Faça o download da versão .zip do plugin pelo link abaixo:
![Banner](/img/ecommerce/magento1/magento1-banner.png)
[Download Woovi Magento1 Plugin - versão 2.1.0](pathname:///magento1/woovi_pix.2.1.0.zip) - Versão Atual

Extraia o conteúdo do arquivo .zip e cole dentro da pasta `root` da sua loja Magento1.
Geralmente a loja root é nomeada como `src` que faz referência à source. Caso sua loja seja diferente, procure pela pasta que contenha outras pastas como:

- app
- js
- lib
- skin
- var

Assim como no exemplo abaixo:

![magento1-src-folder](/img/ecommerce/magento1/magento1-folder-structure.png)

Encontrando a pasta que contenha essas citadas basta realizar o seguinte:

- Copiar os arquivos extraídos do .zip;
- Colar dentro dessa pasta

### Autenticação

Após a instalação, é necessário autenticar o plugin com a nossa plataforma. Isso pode ser realizado por meio do nosso botão de um clique ou ao lidar com a URL do webhook.

#### Através do botão de um clique (preferencialmente)

Na página de configurações do plugin em `Vendas > Formas de pagamento` (`Sales > Payment methods`), clique no botão "Conectar a extensão" (_Connect the extension_):

![Página de configurações com o botão de conectar a extensão](/img/ecommerce/magento1/magento1-admin-1click-button.png)

Ao pressionar este botão, uma nova página será aberta em nossa plataforma, onde você poderá configurar rapidamente uma nova integração com o Magento 1.

Na plataforma, a URL do seu e-commerce será configurada automaticamente; você só precisará clicar em "Salvar":

![Página de integração com Magento1 em nossa plataforma](/img/ecommerce/magento1/magento1-save-integration-platform.png)

Ao salvar, será possível criar novos pedidos com Pix e Woovi Parcelado, e o webhook já estará configurado para atualizar o status de seus pedidos em tempo real.

#### Através da URL do e-commerce

Outra alternativa para autenticar o seu plugin seria acessar diretamente a plataforma e inserir a URL do seu e-commerce.

Entre na plataforma da Woovi e [clique aqui](https://app.woovi.com/home/applications/magento1/add/oneclick) ou vá em `API/Plugins` > `Magento1` > `Adicionar`:

![Tutorial-box](/img/ecommerce/magento1/magento1-tutorial-box.png)

Coloque a URL do seu site no campo "Site":

![Oneclick-Input](/img/ecommerce/magento1/magento1-oneclick-input.png)

Clique no botão de salvar, e assim que tiver sucesso na sua integração você verá a seguinte mensagem:

![Oneclick-Success](/img/ecommerce/magento1/magento1-oneclick-success.png)

## Configurações Avançadas

### Configurando CPF/CNPJ para o Customer (opcional)

Para salvar o cpf/cnpj do customer da order na sua cobrança Woovi é necessário que seja ativado o campo `TaxVat` em sua loja Magento.

Entre em Magento1 Admin -> System > Configuration > Customers (side menu) > Customer Configuration

![magento1-customer-sidemenu](/img/ecommerce/magento1/magento1-customer-sidemenu.png)

Em `Show Tax/VAT Number` selecione o valor required:

![magento1-customer-taxvat](/img/ecommerce/magento1/magento1-customer-taxvat.png)

A partir de agora os clientes terão que preencher esse campo com o CPF ou CNPJ e o mesmo será usado para salvar o cliente na plataforma Woovi.

### Crie o Webhook dentro da Plataforma Woovi

Registre o Webhook que será responsável para atualizar sua loja Magento1 quando uma cobrança Pix for paga.

Para realizar o registro de um novo Webhook siga os passos abaixo:

- Va até a plataforma Woovi e acesse: Admin -> API/Plugins -> Novo Webhook
- Utilize a mesma senha cadastrada em sua loja Magento1. O Webhook é necessário para atualizar o status dos Pedidos em tempo real quando a cobrança Pix é paga.
- A URL de Callback que deve ser utilizada no cadastro se encontra logo abaixo ao campo em que se registra a senha do webhook dentro da sua loja Magento1. O padrão é: `https://yourstore/woovi/webhook`

![Webhook](/img/ecommerce/magento1/magento1-woovi-webhook.png)

### Realizar Pedido com Pix

Escolha a opção de pagar o pedido usando Pix

![Pay Pix](/img/ecommerce/magento1/magento1-checkout-cart.png)

Pague o Pix usando o app do seu banco.

![Checkout Success](/img/ecommerce/magento1/successPayment.png)

Valide que o status do Pedido mudou após o pagamento

### Expiração

A Woovi ira cuidar da expiração da cobrança Pix. Entretanto, é preciso que seja configurado em sua loja magento a expiração da order pois o mesmo cuidará de todo o processo.

Entretanto, o magento1 nao possui uma solução nativa para a mesma.

Indicamos que a expiração/cancelamento da order no magento1 seja feito utilizando uma lib terceira para ajuda.

Uma vez tendo a lib terceira indicamos que seja seguido uma configuração semelhante abaixo:

- tempo de expiração da cobrança Woovi: 15 minutos
- coloque os mesmos 15 minutos dentro da sua loja Magento.

:::info
No magento você pode utilizar a lib abaixo ou alguma de sua preferência:

- [https://meetanshi.com/magento-auto-cancel-order.html](https://meetanshi.com/magento-auto-cancel-order.html)
:::

### Atualizando o plugin

Indicamos aos clientes Woovi estar sempre atualizados com a última versão do plugin. Você pode identificar a mesma no step de instalação.

Caso seu plugin esteja desatualizado basta seguir os passos do mesmo step de instalação e atualizar os arquivos do plugin em seu ecommerce.

### Debug

Para debugar o plugin Woovi temos dois arquivos e você encontra ambos dentro de `var/log`:

- `woovi_exception.log`: arquivo que concentra logs referentes ao processo de criação de um novo pedido Magento e consequentemente a charge no lado da Woovi
- `woovi_webhooks.log`: arquivo que concentra logs referentes ao processo de pagamento de um pedido. O webhook é chamado quando identificamos um novo Pix em sua conta e o mesmo trata de atualizar o status da order em sua loja Magento.

## Woovi Parcelado

### Configuração do Woovi Parcelado

1. É necessário que você tenha o plugin do Magento1 configurado. [Siga a documentação](#configurando-o-plugin-magento1).

2. Vá até a seção de configurações do plugin Openpix.

3. O que você pode fazer?
 - Habilitar ou desativar o método de pagamento.
 - Customizar o título do método de pagamento Woovi Parcelado dentro da sua loja.
 - Alterar qual deve ser o status inicial dos pedidos ao realizar uma compra.

![Configurações Woovi Parcelado](/img/ecommerce/magento1/magento1-parcelado-settings.png)

### Configurações do CPF/CNPJ e do endereço

Para criar uma cobrança com Woovi Parcelado, é necessário o cliente informar o seu CPF/CNPJ e os dados do endereço.

Para configurar o CPF/CNPJ, [veja a nossa documentação](#configurando-cpfcnpj-para-o-customer-opcional).

Em relação ao endereço, é necessário que ele tenha 4 linhas:
  - rua
  - número
  - complemento
  - bairro

Para configurar a quantidade de linhas em cada endereço, acesse Magento1 Admin -> System > Configuration > Customers:

![magento1-customer-sidemenu](/img/ecommerce/magento1/magento1-customer-sidemenu.png)

Na seção `Name and Address options`, altere o campo _Number of Lines in a Street Address_ (Número de linhas em um endereço) para o valor 4:

![magento1-address-options](/img/ecommerce/magento1/magento1-address-options.png)

### Como criar um pedido com Woovi Parcelado

Escolha a opção de pagar o pedido usando Pix parcelado:

![Pay with Pix Parcelado](/img/ecommerce/magento1/magento1-pay-with-pix-parcelado.png)

Pague o Pix usando o app do seu banco.

![Checkout Success - Part1](/img/ecommerce/magento1/successPaymentPixParceladoPart1.png)
![Checkout Success - Part2](/img/ecommerce/magento1/successPaymentPixParceladoPart2.png)

Ao selecionar pagamento no Pix à vista pague o QR Code.

Ao selecionar Pix + cartão de crédito insira os dados do cartão, pague o pix e o valor será capturado no cartão.

![Pagando com Woovi Parcelado - Parte 1](/img/ecommerce/magento1/woovi-parcelado-paying-part-1.png)
![Pagando com Woovi Parcelado - Parte 2](/img/ecommerce/magento1/woovi-parcelado-paying-part-2.png)

Valide que o status do Pedido mudou após o pagamento.

### Visualizando um pedido com Woovi Parcelado

Seu cliente poderá visualizar a cobrança Pix dentro do detalhes do pedido.

Basta acessar a página de detalhes do pedido e visualizar em _Payment method_ (método de pagamento).

![Visualizando um pedido](/img/ecommerce/magento1/woovi-parcelado-order-view.png)

---

## Integrando a Woovi com Magento1

### Plugin Pix para Magento1

## Resumo

Este documento detalha passos necessários para conectar a sua plataforma de e-Commerce, baseada no Magento1, na Woovi. A plataforma Woovi efetua em tempo real a conciliação entre seu Banco e seu e-Commerce.
Após conectar a sua conta na Woovi é possível cobrar clientes em tempo real com QrCodes Pix, enviar Links de Pagamento, gerenciar cobranças incluindo extornos.

> _Nota: Este documento espera que você já tenha um ambiente Magento1 ativo._

## 1. Instale o Plugin Woovi na sua instância Magento1

Faça o download da versão .zip do plugin pelo link abaixo:
![Banner](/img/ecommerce/magento1/magento1-banner.png)
[Download Woovi Magento1 Plugin - versão 2.1.0](pathname:///magento1/woovi_pix.2.1.0.zip) - Versão Atual

Extraia o conteúdo do arquivo .zip e cole dentro da pasta `root` da sua loja Magento1.
Geralmente a loja root é nomeada como `src` que faz referência à source. Caso sua loja seja diferente, procure pela pasta que contenha outras pastas como:

- app
- js
- lib
- skin
- var

Assim como no exemplo abaixo:

![magento1-src-folder](/img/ecommerce/magento1/magento1-folder-structure.png)

Encontrando a pasta que contenha essas citadas basta realizar o seguinte:

- Copiar os arquivos extraídos do .zip;
- Colar dentro dessa pasta

Extraia o conteúdo do arquivo .zip e cole dentro da pasta root da sua loja Magento1. Geralmente a loja root é nomeada como `src` que faz referência à source. Caso sua loja seja diferente, procure pela pasta que contenha outras pastas como:

- app
- js
- lib
- skin
- var

Assim como no exemplo abaixo:

![magento1-src-folder](/img/ecommerce/magento1/magento1-src-folder.png)

Encontrando a pasta que contenha essas citadas basta realizar o seguinte:

- Copiar os arquivos extraídos do .zip;
- Colar dentro dessa pasta

## 2. Configurando o Plugin Magento1

Entre em Magento1 Admin -> System > Configuration > Sales (side menu) > Payment Methods

![sales_pay_method.png](/img/ecommerce/magento1/sales_pay_method.png)

Ao acessar `Payment Methods` você irá notar o Collapsible `Woovi - Pix`

![woovi_pay_tab.png](/img/ecommerce/magento1/woovi_pay_tab.png)

- **App ID** Insira o AppID ou Cadastre um AppID do tipo Plugin. Crie um appID [aqui](../../apis/api-getting-started.md)
- **Webhook Authorization** Crie uma senha para a integração do Webhook. O Webhook é necessário para atualizar o status dos Pedidos em tempo real quando a cobrança Pix é paga.
  - Lembre-se: A URL a ser utilizada no webhook deverá ser: `https://yourstore/woovi/webhook` no momento em que cadastrá-lo na plataforma Woovi
  - Lembre-se: A chave que você utilizar aqui deverá ser a mesma no momento em que cadastrá-la na plataforma Woovi.
  - Crie um Webhook [aqui](#3-crie-o-webhook-dentro-da-plataforma-woovi).
- **Enabled** Ativar/Desativar o plugin como método de pagamento
- **Title** Título do método de pagamento em sua loja Magento1

### 2.2 Configurando CPF/CNPJ para o Customer (opcional)

Para salvar o cpf/cnpj do customer da order na sua cobrança Woovi é necessário que seja ativado o campo `TaxVat` em sua loja Magento.

Entre em Magento1 Admin -> System > Configuration > Customers (side menu) > Customer Configuration

![magento1-customer-sidemenu](/img/ecommerce/magento1/magento1-customer-sidemenu.png)

Em `Show Tax/VAT Number` selecione o valor required:

![magento1-customer-taxvat](/img/ecommerce/magento1/magento1-customer-taxvat.png)

A partir de agora os clientes terão que preencher esse campo com o CPF ou CNPJ e o mesmo será usado para salvar o cliente na plataforma Woovi.

## 3. Crie o Webhook dentro da Plataforma Woovi

Registre o Webhook que será responsável para atualizar sua loja Magento1 quando uma cobrança Pix for paga.

Para realizar o registro de um novo Webhook siga os passos abaixo:

- Va até a plataforma Woovi e acesse: Admin -> API/Plugins -> Novo Webhook
- Utilize a mesma senha cadastrada em sua loja Magento1. O Webhook é necessário para atualizar o status dos Pedidos em tempo real quando a cobrança Pix é paga.
- A URL de Callback que deve ser utilizada no cadastro se encontra logo abaixo ao campo em que se registra a senha do webhook dentro da sua loja Magento1. O padrão é: `https://yourstore/woovi/webhook`

![Webhook](/img/ecommerce/magento1/magento1-woovi-webhook.png)

## 4. Realizar Pedido com Pix

Escolha a opção de pagar o pedido usando Pix

![Pay Pix](/img/ecommerce/magento1/magento1-checkout-cart.png)

Pague o Pix usando o app do seu banco.

![Checkout Success](/img/ecommerce/magento1/successPayment.png)

Valide que o status do Pedido mudou após o pagamento

## Expiração

A Woovi ira cuidar da expiração da cobrança Pix. Entretanto, é preciso que seja configurado em sua loja magento a expiração da order pois o mesmo cuidará de todo o processo.

Entretanto, o magento1 nao possui uma solução nativa para a mesma.

Indicamos que a expiração/cancelamento da order no magento1 seja feito utilizando uma lib terceira para ajuda.

Uma vez tendo a lib terceira indicamos que seja seguido uma configuração semelhante abaixo:

- tempo de expiração da cobrança Woovi: 15 minutos
- coloque os mesmos 15 minutos dentro da sua loja Magento.

:::info
No magento você pode utilizar a lib abaixo ou alguma de sua preferência:

- [https://meetanshi.com/magento-auto-cancel-order.html](https://meetanshi.com/magento-auto-cancel-order.html)
:::

## Atualizando o plugin

Indicamos aos clientes Woovi estar sempre atualizados com a última versão do plugin. Você pode identificar a mesma no step de instalação.

Caso seu plugin esteja desatualizado basta seguir os passos do mesmo step de instalação e atualizar os arquivos do plugin em seu ecommerce.

## Debug

Para debugar o plugin Woovi temos dois arquivos e você encontra ambos dentro de `var/log`:

- `woovi_exception.log`: arquivo que concentra logs referentes ao processo de criação de um novo pedido Magento e consequentemente a charge no lado da Woovi
- `woovi_webhooks.log`: arquivo que concentra logs referentes ao processo de pagamento de um pedido. O webhook é chamado quando identificamos um novo Pix em sua conta e o mesmo trata de atualizar o status da order em sua loja Magento.

## Woovi Parcelado

### Configuração do Woovi Parcelado

1. É necessário que você tenha o plugin do Magento1 configurado. [Siga a documentação](#configurando-o-plugin-magento1).

2. Vá até a seção de configurações do plugin Openpix.

3. O que você pode fazer?
 - Habilitar ou desativar o método de pagamento.
 - Customizar o título do método de pagamento Woovi Parcelado dentro da sua loja.
 - Alterar qual deve ser o status inicial dos pedidos ao realizar uma compra.

![Configurações Woovi Parcelado](/img/ecommerce/magento1/woovi-parcelado-settings.png)

### Configurações do CPF/CNPJ e do endereço

Para criar uma cobrança com Woovi Parcelado, é necessário o cliente informar o seu CPF/CNPJ e os dados do endereço.

Para configurar o CPF/CNPJ, [veja a nossa documentação](#configurando-cpfcnpj-para-o-customer-opcional).

Em relação ao endereço, é necessário que ele tenha 4 linhas:
  - rua
  - número
  - complemento
  - bairro

Para configurar a quantidade de linhas em cada endereço, acesse Magento1 Admin -> System > Configuration > Customers:

![magento1-customer-sidemenu](/img/ecommerce/magento1/magento1-customer-sidemenu.png)

Na seção `Name and Address options`, altere o campo _Number of Lines in a Street Address_ (Número de linhas em um endereço) para o valor 4:

![magento1-address-options](/img/ecommerce/magento1/magento1-address-options.png)

### Como criar um pedido com Woovi Parcelado

Escolha a opção de pagar o pedido usando Pix parcelado:

![Pay with Pix Parcelado](/img/ecommerce/magento1/magento1-pay-with-pix-parcelado.png)

Pague o Pix usando o app do seu banco.

![Checkout Success - Part1](/img/ecommerce/magento1/successPaymentPixParceladoPart1.png)
![Checkout Success - Part2](/img/ecommerce/magento1/successPaymentPixParceladoPart2.png)

Ao selecionar pagamento no Pix à vista pague o QR Code.

Ao selecionar Pix + cartão de crédito insira os dados do cartão, pague o pix e o valor será capturado no cartão.

![Pagando com Woovi Parcelado - Parte 1](/img/ecommerce/magento1/woovi-parcelado-paying-part-1.png)
![Pagando com Woovi Parcelado - Parte 2](/img/ecommerce/magento1/woovi-parcelado-paying-part-2.png)

Valide que o status do Pedido mudou após o pagamento.

### Visualizando um pedido com Woovi Parcelado

Seu cliente poderá visualizar a cobrança Pix dentro do detalhes do pedido.

Basta acessar a página de detalhes do pedido e visualizar em _Payment method_ (método de pagamento).

![Visualizando um pedido](/img/ecommerce/magento1/woovi-parcelado-order-view.png)

---

## Magento2 Install

[Woovi Pix For Magento2](https://commercemarketplace.adobe.com/woovi-pix.html)

![Banner](../__assets__/magento2-banner.png)
![Install](../__assets__/magento2-marketplace-search.png)

[Download OpenPix Magento2 Plugin - versão 3.0.0](pathname:///magento2/openpix_pix.3.0.0.zip) - Versão Atual

#### Instalação com Composer

É possível instalar o nosso plugin utilizando o [Composer](https://getcomposer.org).

Realize os seguintes passos:

1. Acessar Magento Marketplace
2. Buscar pelo Plugin Woovi
3. Realizar a compra grátis do mesmo
4. Clicar em instalar
5. Em "Meus Downloads" siga as instruções a direita

![Instructions](../__assets__/composer-instructions.png)

6. Não se esqueça de atualizar o arquivo `auth.json` seguindo as instruções do Magento acima. Exemplo de arquivo `auth.json`:

```json
{
  "http-basic": {
    "repo.magento.com": {
      "username": "CHAVE PÚBLICA",
      "password": "CHAVE PRIVADA"
    }
  }
}
```

- A chave pública/privada pode ser obtida na página de access keys do Magento.

7. Um exemplo de comando para instalar o nosso plugin é `composer require woovi/pix`. Acesse também a [documentação do Magento2](https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/tutorials/extensions.html) para mais detalhes.

---

## Magento 2: Perguntas Frequentes

## Meus pedidos no Magento 2 não estão sendo atualizados

Se caso os seus pedidos gerados a partir da sua loja Magent 2 não estão
atualizando o status conforme o pagamento é efetuado, pode ser que o webhook
da integração tenha sido configurado de forma incorreta.

Para verificar isso, acesse a [lista das suas integrações criadas](https://app.woovi.com/home/applications/tab/list) e,
na lista de webhooks, encontre o webhook relacionado a sua integração.
Você pode encontrá-lo a partir do nome dele: `Magento2 Webhook`. Após achá-lo, acesse o detalhe
do mesmo clicando na sua respectiva linha na tabela.

Na seção de `Ação`, abra ela e confira o campo `Url`. Conforme a [documentação de integração da woovi com Magento2](./magento2-oneclick-plugin.mdx) mostra, o webhook deve estar apontando pro seguinte endpoint: `/woovi/index/webhook`.]
Segue um exemplo: `https://minhalojamagento2.com/woovi/index/webhook`.

---

## Como criar webhook de cobrança expirada

### Plugin Pix para Magento2

## Resumo

Este documento detalha passos necessários para criar um webhook do tipo `CHARGE_EXPIRED` para sua integração magento2 começar a escutar por cobranças expiradas.

:::caution Atenção
Este documento espera que você já tenha um ambiente Magento2 ativo,uma conta criada na woovi, e já possua uma inegração magento2 com um webhook ativo do `CHARGE_PAID`
:::

:::tip Dica
Para utilizar este tutorial é necessário ter uma versão acima da 2.3.0
:::

## Criando um novo webhook

1) Na lateral esquerda, vá em "API/Plugins" -> e clique no botão "Novo Webhook"
![](./__assets__/magento2-webhook-configuring.png)

2) Preencha os campos com as informações necessárias, e clique em salvar

- Nome: com o nome que você gostaria de dar para seu Webhook
- Mantenha o webhoook com status ativo
- Evento: com tipo do evento do webhook novo que será "Cobrança Expirada"
- URL: use o mesmo endereço de webhook aplicado no webhook de "Cobrança Paga", em nosso exemplo estou usando https://magento.test/woovi/index/webhook
- Vincular a uma Aplicação: localize uma aplicação com o nome "Magento2 API", selecione-a para que todas as cobranças expiradas que foram criadas com o `appID` dessa aplicação sejam enviadas para a URL de webhook do magento2

:::tip Dica
É importante que você substitua `magento.test` pelo dominio que seu seu ecommerce está implantado
:::

![](./__assets__/magento2-webhook-configuration-2.png)

3) Após salvar, você poderá ver seu novo webhook criado na lista de webhooks

![](./__assets__/magento2-webhook-configured-2.png)

---

## Como reembolsar um pedido no Magento2?

Nessa documentação falaremos como você pode realizar um reembolso 

## 1. Abra a lista de pedidos

No menu lateral, clique em **Sales** > **Orders**:

![Menu de pedidos](./__assets__/magento2-orders-menu.png)

## 2. Abra os detalhes de um pedido

Selecione uma order já processada pelo Plugin e clique no botão **View**:

![Detalhes do pedido](./__assets__/magento2-order-view.png)

## 3. Abra a fatura do pedido

No menu lateral do pedido, selecione **Invoices** e abra a fatura clicando no botão **View**:

![Detalhes da fatura](./__assets__/magento2-invoice-detail.png)

## 4. Crie uma nota de crédito

Na parte superior da fatura, clique em **Credit memo** para criar uma nova nota de crédito:

![Nota de crédito da fatura](./__assets__/magento2-invoice-credit-memo.png)

## 5. Preencha as informações do reembolso

Nesta parte você poderá ajustar como será feito o reembolso:

- No campo **Qty to refund** defina a quantidade de itens que serão reembolsados. Ao inserir a quantidade, clique em **Update Qty's** para atualizar.
- Selecione **Return to stock** se deseja que os itens voltem ao estoque.
- Em **Refund shipping** você poderá definir o valor da taxa de entrega que será reembolsado. O padrão é a taxa total.

Ao completar as informações, clique no botão **Refund** para realizar o reembolso.

![Nota de crédito](./__assets__/magento2-credit-memo.png)

## 6. Ver reembolsos da cobrança dentro da plataforma

Nos detalhes da cobrança, abra a aba **Transações** e selecione a transação de pagamento da cobrança:

![Transações da cobrança](./__assets__/magento2-charge-transactions.png)

Nos detalhes da transação você poderá visualizar todos os reembolsos:

![Reembolsos da transação](./__assets__/magento2-transaction-refunds.png)

---

## Integrando a Woovi com Magento2 Em Um Clique

### Plugin Pix para Magento2

## Resumo

Este documento detalha passos necessários para conectar a sua plataforma de e-Commerce, baseada no Magento2, na Woovi.

:::caution Atenção
Este documento espera que você já tenha um ambiente Magento2 ativo, e uma conta criada na Woovi
:::

:::tip Dica
Para utilizar este tutorial é necessário ter uma versão acima da 2.3.0
:::

## Configurando o Plugin Magento2

### 1. Instale o Plugin Woovi na sua instância Magento2

[Woovi Pix For Magento2](https://commercemarketplace.adobe.com/woovi-pix.html)

![Banner](../__assets__/magento2-banner.png)
![Install](../__assets__/magento2-marketplace-search.png)

[Download OpenPix Magento2 Plugin - versão 3.0.0](pathname:///magento2/openpix_pix.3.0.0.zip) - Versão Atual

#### Instalação com Composer

É possível instalar o nosso plugin utilizando o [Composer](https://getcomposer.org).

Realize os seguintes passos:

1. Acessar Magento Marketplace
2. Buscar pelo Plugin Woovi
3. Realizar a compra grátis do mesmo
4. Clicar em instalar
5. Em "Meus Downloads" siga as instruções a direita

![Instructions](../__assets__/composer-instructions.png)

6. Não se esqueça de atualizar o arquivo `auth.json` seguindo as instruções do Magento acima. Exemplo de arquivo `auth.json`:

```json
{
  "http-basic": {
    "repo.magento.com": {
      "username": "CHAVE PÚBLICA",
      "password": "CHAVE PRIVADA"
    }
  }
}
```

- A chave pública/privada pode ser obtida na página de access keys do Magento.

7. Um exemplo de comando para instalar o nosso plugin é `composer require woovi/pix`. Acesse também a [documentação do Magento2](https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/tutorials/extensions.html) para mais detalhes.

### 2. Autenticação

Após a instalação, é necessário autenticar o plugin com a nossa plataforma. Isso pode ser realizado por meio do nosso botão de um clique ou ao lidar com a URL do webhook.

### 2.1. Autenticação com um clique (preferencialmente)

Na página de configurações do plugin em `Vendas > Formas de pagamento` (`Sales > Payment Methods`), clique no botão "Conectar a extensão" (_Connect the extension_):

![Configurações da extensão com o botão de um clique](./__assets__/magento2-admin-1click.png)

Ao pressionar este botão, uma nova página será aberta em nossa plataforma, onde você poderá configurar rapidamente uma nova integração com o Magento 2.

Na plataforma, a URL do seu e-commerce será configurada automaticamente; você só precisará clicar em "Salvar":

![Nova integração Magento 2 na plataforma](./__assets__/magento2-save-platform-integration.png)

Ao salvar, será possível criar novos pedidos com Pix e OpenPix Parcelado, e o webhook já estará configurado para atualizar o status de seus pedidos em tempo real.

### 2.2. Autenticação com a URL do e-commerce

Outra alternativa para autenticar o seu plugin seria acessar diretamente a plataforma e inserir a URL do seu e-commerce.

Entre na plataforma da Woovi e [clique aqui](https://app.woovi.com/home/applications/magento2/add/oneclick) ou vá em `API/Plugins` > `Magento2` > `Adicionar`:

![Tutorial-box](./__assets__/magento2-tutorial-box.png)

Coloque a URL do seu site no campo "Site":

![Oneclick-Input](./__assets__/magento2-oneclick-input.png)

Clique no botão de salvar, e assim que tiver sucesso na sua integração você verá a seguinte mensagem:

![Oneclick-Success](./__assets__/magento2-oneclick-success.png)

## Configurações Avançadas

### 1. Configurando CPF/CNPJ para o Customer (opcional)

Para salvar o cpf/cnpj do customer da order na sua cobrança Woovi é necessário que seja ativado o campo `TaxVat` em sua loja Magento.

__Obs: Caso você siga sem a configuração deste campo suas cobranças serão salvas sem o cliente da mesma.__

Entre em Magento2 Admin -> Stores > Configuration -> Customers -> Customer Configuration

![customer-sidemenu](./__assets__/magento2-customer-sidemenu.png)

Primeiro ative o campo `Show VAT Number on Storefront` em `Create New Account Options`:

![magento2-customer-create-new-account-options](./__assets__/magento2-customer-create-new-account-options.png)

Em seguida em `Name and Address Options` ative o campo `Show Tax/VAT Number`:

![magento2-customer-name-address-options.png](./__assets__/magento2-customer-name-address-options.png)

A partir de agora os clientes terão que preencher esse campo com o CPF ou CNPJ e o mesmo será usado para salvar o cliente na plataforma Woovi.

### 2. Crie o Webhook dentro da Plataforma Woovi

Ao configurar a Store volte para a Plataforma Woovi e registre o Webhook que será responsável para atualizar sua Store Magento2 quando uma cobrança Pix for paga.

Para realizar o registro de um novo Webhook siga os passos abaixo:

- Va até a plataforma Woovi e acesse: Admin -> API/Plugins -> Novo Webhook
- Utilize a mesma senha cadastrada em sua store Magento2. O Webhook é necessário para atualizar o status dos Pedidos em tempo real quando a cobrança Pix é paga.
- A URL de Callback que deve ser utilizada no cadastro se encontra logo abaixo ao campo em que se registra a senha do webhook dentro da sua Store Magento2. O padrão é: [https://youstore.com.br/openpix/index/webhook](https://youstore.com.br/openpix/index/webhook)

![Webhook](./__assets__/magento2-webhook-configuration.png)

### 3. Realizar Pedido com Pix

Escolha a opção de pagar o pedido usando Pix

![Pay Pix](./__assets__/magento2-checkout-cart.png)

Pague o Pix usando o app do seu banco.

![Order](./__assets__/magento2-order.png)

Valide que o status do Pedido mudou após o pagamento

### 4. Visualizar Pedido com Pix

Seu cliente poderá visualizar o pedido realizado via Pix dentro do detalhes do pedido. Basta clicar no botão que irá aparecer dentro da pagina de detalhe do pedido "Clique aqui para ver seu QRCode"

![Order information](./__assets__/magento2-order-info.png)
![Order](./__assets__/magento2-order-detail.png)

### 5. Expiração do pedido Magento2

A Woovi ira cuidar da expiração da cobrança Pix. Entretanto, é preciso que seja configurado em sua loja magento a expiração da order pois o mesmo cuidará de todo o processo.

Indicamos que a expiração/cancelamento da order no magento possua um tempo semelhante ao tempo configurado na Woovi. Exemplo:

- tempo de expiração da cobrança Woovi: 15 minutos
- coloque os mesmos 15 minutos dentro da sua loja Magento.

:::info
No magento você pode utilizar o lifetime order seguindo a doc abaixo:

- [https://docs.magento.com/user-guide/v2.3/sales/order-pending-payment-lifetime.html](https://docs.magento.com/user-guide/v2.3/sales/order-pending-payment-lifetime.html)
:::

### 6. Atualizando o plugin do Magento2

Indicamos aos clientes Woovi estar sempre atualizados com a última versão do plugin. Você pode identificar a mesma no step de instalação.

Caso seu plugin esteja desatualizado basta seguir os passos do mesmo step de instalação e atualizar os arquivos do plugin em seu ecommerce.

### 7. Debug logs Magento2

Para debugar o plugin Woovi temos o arquivo de log e você encontra dentro de `var/log`:

- `openpix.log`: arquivo que concentra logs referentes ao processo de criação de um novo pedido Magento e consequentemente a charge no lado da Woovi e o processo de atualização da Order quando paga.

---

## Integrando Woovi Parcelado com Magento2

### Plugin Woovi Parcelado para Magento2

## Resumo

Este documento detalha passos necessários para conectar a sua plataforma de e-Commerce, baseada no Magento2, na Woovi. A plataforma Woovi efetua em tempo real a conciliação entre seu Banco e seu e-Commerce.
Após conectar a sua conta na Woovi é possível cobrar clientes em tempo real com QrCodes Pix, enviar Links de Pagamento, gerenciar cobranças incluindo extornos.

> *Nota: Este documento espera que você já tenha um ambiente Magento2 ativo.*

> *Nota: O plugin é disponibilizado sob o nome **OpenPix** no Magento Marketplace, porém trata-se do mesmo plugin da Woovi.*

## 1. Instale o Plugin Woovi Parcelado na sua instância Magento2

[OpenPix For Magento2](https://commercemarketplace.adobe.com/openpix-pix.html)

![Banner](./__assets__/magento2-banner.png)
![Install](./__assets__/magento2-marketplace-search.png)

[Download OpenPix Magento2 Plugin - versão 3.0.1](pathname:///magento2/openpix_pix.3.0.1.zip) - Versão Atual

## 2. Configurando o Plugin Magento2

1. Configure o plugin Magento2 com apenas 1 clique seguindo a documentação [Magento2 OneClick](/docs/ecommerce/magento2/magento2-oneclick)

2. Ative o plugin clicando em `Payment via Woovi Parcelado` no Plugin Woovi.

- [ ] Ative ou Desative o Plugin
- [ ] Customize o título do pagamento dentro da sua Store

![Customize](./__assets__/magento2-woovi-parcelado-settings.png)

### 2.2 Configurando CPF/CNPJ para o Customer (required)

É obrigatório o envio do cliente com nome, cpf/cnpj, telefone e endereço com pleto. Para disponibilizar o cpf/cnpj do customer da order na sua cobrança Woovi é necessário que seja ativado o campo `TaxVat` em sua loja Magento.

Entre em Magento2 Admin -> Stores > Configuration -> Customers -> Customer Configuration

![customer-sidemenu](./__assets__/magento2-customer-sidemenu.png)

Primeiro ative o campo `Show VAT Number on Storefront` em `Create New Account Options`:

![magento2-customer-create-new-account-options](./__assets__/magento2-customer-create-new-account-options.png)

Em seguida em `Name and Address Options` ative o campo `Show Tax/VAT Number`:

![magento2-customer-name-address-options.png](./__assets__/magento2-customer-name-address-options.png)

Para finalizar modifique o endereço para que ele seja disponibilizado em 4 linhas

![magento2-customer-address-4-lines.png](./__assets__/magento2-woovi-parcelado-address.png)

A partir de agora os clientes terão que preencher esse campo com o CPF ou CNPJ e o mesmo será usado para salvar o cliente na plataforma Woovi.

## 5. Realizar Pedido com Pix

Escolha a opção de pagar o pedido à vista ou com Pix + Cartão de crédito

![Pay Pix](./__assets__/magento2-cart.png)

Pague o Pix usando o app do seu banco.
![Order](./__assets__/magento2-order.png)

Ao selecionar pagamento no pix à vista pague o qrcode.

Ao selecionar pix + cartão de crédito insira os dados do cartão, pague o pix e o valor sera captura no cartão.

![Order](./__assets__/magento2-order-2.png)

Valide que o status do Pedido mudou após o pagamento

## 5. Visualizar Pedido com Pix

Seu cliente poderá visualizar o pedido realizado via Pix dentro do detalhes do pedido. Basta clicar no botão que irá aparecer dentro da pagina de detalhe do pedido "Clique aqui para ver seu QRCode"

![Order](./__assets__/magento2-detail.png)
## Expiração

A Woovi ira cuidar da expiração da cobrança Pix. Entretanto, é preciso que seja configurado em sua loja magento a expiração da order pois o mesmo cuidará de todo o processo.

Indicamos que a expiração/cancelamento da order no magento possua um tempo semelhante ao tempo configurado na Woovi. Exemplo:
- tempo de expiração da cobrança Woovi: 15 minutos
- coloque os mesmos 15 minutos dentro da sua loja Magento.

:::info
No magento você pode utilizar o lifetime order seguindo a doc abaixo:
- [https://docs.magento.com/user-guide/v2.3/sales/order-pending-payment-lifetime.html](https://docs.magento.com/user-guide/v2.3/sales/order-pending-payment-lifetime.html)
  :::

## Atualizando o plugin
Indicamos aos clientes Woovi estar sempre atualizados com a última versão do plugin. Você pode identificar a mesma no step de instalação.

Caso seu plugin esteja desatualizado basta seguir os passos do mesmo step de instalação e atualizar os arquivos do plugin em seu ecommerce.

## Debug

Para debugar o plugin Woovi temos o arquivo de log e você encontra dentro de `var/log`:

- `woovi.log`: arquivo que concentra logs referentes ao processo de criação de um novo pedido Magento e consequentemente a charge no lado da Woovi e o processo de atualização da Order quando paga.

---

## Integrando a Woovi com Magento2

### Plugin Pix para Magento2

## Resumo

Este documento detalha passos necessários para conectar a sua plataforma de e-Commerce, baseada no Magento2, na Woovi. A plataforma Woovi efetua em tempo real a conciliação entre seu Banco e seu e-Commerce.
Após conectar a sua conta na Woovi é possível cobrar clientes em tempo real com QrCodes Pix, enviar Links de Pagamento, gerenciar cobranças incluindo extornos.

> _Nota: Este documento espera que você já tenha um ambiente Magento2 ativo._

> _Nota: O plugin é disponibilizado sob o nome **OpenPix** no Magento Marketplace, porém trata-se do mesmo plugin da Woovi._

## 1. Instale o Plugin Woovi na sua instância Magento2

[OpenPix For Magento2](https://commercemarketplace.adobe.com/openpix-pix.html)

![Banner](./__assets__/magento2-banner.png)
![Install](./__assets__/magento2-marketplace-search.png)

[Download OpenPix Magento2 Plugin - versão 3.0.1](pathname:///magento2/openpix_pix.3.0.1.zip) - Versão Atual

## 2. Configurando o Plugin Magento2

1. Configure o plugin Magento2 com apenas 1 clique seguindo a documentação [Magento2 OneClick](/docs/ecommerce/magento2/magento2-oneclick)

2. Ative o plugin clicando em `Payment via Pix` no Plugin Woovi.

- [ ] Ative ou Desative o Plugin
- [ ] Customize o título do pagamento dentro da sua Store

![Customize](./__assets__/magento2-customize.png)

### 2.2 Configurando CPF/CNPJ para o Customer (opcional)

Para salvar o cpf/cnpj do customer da order na sua cobrança Woovi é necessário que seja ativado o campo `TaxVat` em sua loja Magento.

**Obs: Caso você siga sem a configuração deste campo suas cobranças serão salvas sem o cliente da mesma.**

Entre em Magento2 Admin -> Stores > Configuration -> Customers -> Customer Configuration

![customer-sidemenu](./__assets__/magento2-customer-sidemenu.png)

Primeiro ative o campo `Show VAT Number on Storefront` em `Create New Account Options`:

![magento2-customer-create-new-account-options](./__assets__/magento2-customer-create-new-account-options.png)

Em seguida em `Name and Address Options` ative o campo `Show Tax/VAT Number`:

![magento2-customer-name-address-options.png](./__assets__/magento2-customer-name-address-options.png)

A partir de agora os clientes terão que preencher esse campo com o CPF ou CNPJ e o mesmo será usado para salvar o cliente na plataforma Woovi.

## 3. Crie o Webhook dentro da Plataforma Woovi

Ao configurar a Store volte para a Plataforma Woovi e registre o Webhook que será responsável para atualizar sua Store Magento2 quando uma cobrança Pix for paga.

Para realizar o registro de um novo Webhook siga os passos abaixo:

- Va até a plataforma Woovi e acesse: Admin -> API/Plugins -> Novo Webhook
- Utilize a mesma senha cadastrada em sua store Magento2. O Webhook é necessário para atualizar o status dos Pedidos em tempo real quando a cobrança Pix é paga.
- A URL de Callback que deve ser utilizada no cadastro se encontra logo abaixo ao campo em que se registra a senha do webhook dentro da sua Store Magento2. O padrão é: [https://youstore.com.br/woovi/index/webhook](https://youstore.com.br/woovi/index/webhook)

![Webhook](./__assets__/magento2-webhook-configuration.png)

## 4. Realizar Pedido com Pix

Escolha a opção de pagar o pedido usando Woovi Parcelado

![Pay Pix](./__assets__/magento2-cart.png)

Pague o Pix usando o app do seu banco.

![Order](./__assets__/magento2-order.png)

Valide que o status do Pedido mudou após o pagamento

## 5. Visualizar Pedido com Pix

Seu cliente poderá visualizar o pedido realizado via Pix dentro do detalhes do pedido. Basta clicar no botão que irá aparecer dentro da pagina de detalhe do pedido "Clique aqui para ver seu QRCode"

![Order information](./__assets__/magento2-order-info.png)
![Order](./__assets__/magento2-order-detail.png)

## Expiração

A Woovi ira cuidar da expiração da cobrança Pix. Entretanto, é preciso que seja configurado em sua loja magento a expiração da order pois o mesmo cuidará de todo o processo.

Indicamos que a expiração/cancelamento da order no magento possua um tempo semelhante ao tempo configurado na Woovi. Exemplo:

- tempo de expiração da cobrança Woovi: 15 minutos
- coloque os mesmos 15 minutos dentro da sua loja Magento.

:::info
No magento você pode utilizar o lifetime order seguindo a doc abaixo:

- [https://docs.magento.com/user-guide/v2.3/sales/order-pending-payment-lifetime.html](https://docs.magento.com/user-guide/v2.3/sales/order-pending-payment-lifetime.html)
  :::

## Atualizando o plugin

Indicamos aos clientes Woovi estar sempre atualizados com a última versão do plugin. Você pode identificar a mesma no step de instalação.

Caso seu plugin esteja desatualizado basta seguir os passos do mesmo step de instalação e atualizar os arquivos do plugin em seu ecommerce.

## Debug

Para debugar o plugin Woovi temos o arquivo de log e você encontra dentro de `var/log`:

- `woovi.log`: arquivo que concentra logs referentes ao processo de criação de um novo pedido Magento e consequentemente a charge no lado da Woovi e o processo de atualização da Order quando paga.

---

## Integrando Nuvemshop na woovi

:::caution Atenção
Este documento espera que você já tenha um ecommerce na Nuvemshop, e uma conta criada na woovi
:::

## Plugin Pix para Nuvemshop

### 1. Acesse a configuração da Nuvemshop

Entre na plataforma da woovi e [clique aqui](https://app.woovi.com/home/applications/nuvemshop/add) ou vá em `API/Plugins` > `Plugin Nuvemshop` > `Adicionar`

![tutorial-box](./__assets__/nuvemshop-tutorial-box.png)

### 2. Informe a URL do seu ecommerce

![1](./__assets__/how-to-install-nuvemshop-plugin-1.png)

- OBS: Após informar a URL do seu ecommerce, você será redirecionado para a página de autorização da Nuvemshop.

### 3. Autorize o Aplicativo dentro da Nuvemshop

![2](./__assets__/how-to-install-nuvemshop-plugin-2.png)

- OBS: Após você autorizar o nosso plugin no seu ecommerce, você será redirecionado novamente para plataforma para efetuar o
cadastro da aplicação Nuvemshop dentro da woovi.

### 4. Crie uma nova aplicação

![3](./__assets__/how-to-install-nuvemshop-plugin-3.png)

![4](./__assets__/how-to-install-nuvemshop-plugin-4.png)

---

## Como integrar o Pix em sua loja OpenCart 3

A Woovi disponibiliza uma extensão para o OpenCart 3 que permite a integração do Pix em seu checkout, com suporte à atualização automática do status de seus pedidos e logs.

A plataforma efetua em tempo real a conciliação entre seu Banco e sua loja. Após conectar a sua conta na Woovi é possível cobrar clientes em tempo real com QrCodes Pix, enviar links de pagamento e gerenciar cobranças incluindo extornos.

Veja como é fácil aumentar suas vendas integrando o Pix em sua loja:

## Pré-requisitos

:::caution Preste atenção
- Uma loja com o OpenCart 3 instalado.
:::

## Instalação

Antes de instalar a extensão, é importante garantir que ela esteja disponível na sua loja. Isso pode ser feito de duas maneiras: através do marketplace ou fazendo o upload do arquivo da extensão.

### Marketplace

A maneira mais conveniente de baixar a extensão em sua loja é acessando o [marketplace oficial](https://www.opencart.com/index.php?route=marketplace/extension/info&extension_id=45252&filter_search=woovi) do OpenCart. Lá, você encontrará a extensão pronta para ser baixada e instalada com facilidade.

Veja como você pode baixar utilizando o marketplace:

#### 1) Acesse o painel de administração

Para acessar o marketplace e carregar a extensão na sua loja, siga estes passos simples:

1. No painel de administração da sua loja, localize a barra lateral e clique na opção _Extensions_.

2. Em seguida, no submenu que é exibido, clique na opção _Marketplace_:

   ![Acesso ao submenu com o marketplace como opção](./__assets__/opencart3/marketplace-access.png)

Ao seguir essas etapas, você será direcionado para o marketplace oficial do OpenCart.

#### 2) Pesquise a extensão

Ao acessar o marketplace, pesquise pela extensão _woovi_:

![Listagem do marketplace com a extensão](./__assets__/opencart3/marketplace-search.png)

#### 3) Carregue a extensão

Desça um pouco a página até localizar a seção de _Download_ e identifique a versão mais recente da extensão em _Available installs_. Ao lado desta versão, haverá um botão marcado como _Install_. Clique nesse botão para carregar a extensão.

![Página da extensão com o botão de Install](./__assets__/opencart3/extension-download-page.png)

### Upload do arquivo

Além do marketplace, você também tem a opção de carregar manualmente o arquivo da extensão. Para isso, acesse a página de downloads no [marketplace oficial](https://www.opencart.com/index.php?route=marketplace/extension/info&extension_id=45252&filter_search=woovi) e baixe primeiramente o arquivo mais recente da extensão compatível com OpenCart 3:

![Página da extensão no marketplace indicando o botão de acesso aos downloads](./__assets__/opencart3/marketplace-download-button.png)

![Página de downloads no marketplace](./__assets__/opencart3/marketplace-downloads-page.png)

:::caution Preste atenção
Assegure-se de que o nome do arquivo da extensão seja _woovi.ocmod.zip_ ao fazer o upload, porque o OpenCart considera o nome do arquivo como um "identificador" da extensão, que precisa ser _woovi_.
:::

Após isso, acesse a página do instalador de extensões, localizado na opção _Installer_ no menu _Extensions_ do OpenCart:

![Opção do instalador de extensões no menu do OpenCart](./__assets__/opencart3/extension-installer-menu-option.png)

Ao acessar a página do instalador de extensões, localize o botão de _Upload_ azul:

![Página de upload](./__assets__/opencart3/extension-installer-page.png)

Clique nesse botão e selecione o arquivo da extensão que deseja carregar.

### Instalando o método de pagamento Woovi Pix

Até o momento, você conseguiu instalar os arquivos da extensão do seu site. Agora, é necessário instalar o método de pagamento _Woovi Pix_ em sua loja.

Para fazer isso, acesse a página de extensões através da sub-opção _Extensions_ dentro da opção _Extensions_ localizada na barra lateral do painel de administração:

![Sub-opção "Extensions" selecionada](./__assets__/opencart3/extensions-menu-option.png)

Na página de extensões, utilize a opção de filtro para selecionar extensões do tipo _Payment_:

![Filtro pelo tipo _Payment_ habilitado](./__assets__/opencart3/extension-list-filtered-by-payment-type.png)

Role um pouco para baixo na página e clique no botão verde com o símbolo "+" na extensão _Woovi Pix_ para que o método de pagamento seja instalado com sucesso:

![Instalação da extensão Woovi Pix como método de pagamento](./__assets__/opencart3/install-payment-method.png)

Após isso, clique no botão azul com o ícone de um lápis para acessar a página de configuração da extensão.

### Instalando o método de pagamento Woovi Parcelado

Para instalar o método de pagamento Woovi Parcelado, siga os mesmos passos utilizados na instalação do Woovi Pix, porém aplicados ao Woovi Parcelado:

![Instalando Woovi Parcelado como método de pagamento](./__assets__/opencart3/install-woovi-parcelado-payment-method.png)

## Configuração dos métodos de pagamento

A nossa extensão oferece dois métodos de pagamento para a sua loja: Woovi Pix e Woovi Parcelado.

Ambos os métodos de pagamento possuem as mesmas possibilidades de configuração.

Após acessar a página de configurações da extensão, é necessário ativar o método de pagamento desejado no checkout, selecionando a opção "Enabled" (habilitado) no campo "Status" da seção "Edit Pix Settings" (editar configurações do Pix) ou "Edit Woovi Parcelado" (editar configurações do Woovi Parcelado):

![Página de configurações com o botão _Status_](./__assets__/opencart3/admin-settings-status.png)

Tendo habilitado o botão Status, o método de pagamento desejado deverá aparecer como método de pagamento no checkout.

## Autenticação

É necessário integrar a extensão com a plataforma Woovi e isto pode ser feito adicionando a url de _webhook_ na plataforma ou utilizando o botão de um clique.

### 1 clique

Na página de configurações, clique no botão "Conectar a extensão" (_Connect the extension_):

![Botão que configura a extensão em 1 clique](./__assets__/opencart3/admin-1click-v2-button.png)

Ao pressionar esse botão, você será redirecionado para nossa plataforma, onde poderá configurar rapidamente uma nova integração com o OpenCart3.

Na plataforma, a URL do seu e-commerce será configurada automaticamente; você só precisará clicar em "Salvar":

![Salvando a integração na plataforma](./__assets__/opencart3/platform-new-opencart3-integration.png)

Salvando a integração, seu _App ID_ deve estar em seu painel:

![Página de configurações com o AppID adicionado](./__assets__/opencart3/admin-settings-appid.png)

### URL de webhook

Para obter essa URL, vá até a página de configurações e copie ela:

![Página de configurações com a url de webhook](./__assets__/opencart3/admin-settings-webhook.png)

Entre na plataforma da Woovi e [clique aqui](https://app.woovi.com/home/applications/opencart/add) ou vá em `API/Plugins` > `OpenCart` > `Adicionar`:

![Botão de adicionar um plugin na plataforma Woovi](./__assets__/opencart3/woovi-plugin-card.png)

Cole a URL de webhook no campo _Preencha a url do seu site_ e pressione o botão _Salvar_:

![Formulário para adicionar uma integração na plataforma Woovi](./__assets__/opencart3/woovi-add-plugin-form.png)

Após isto, verifique se o _AppID_, um código que identifica sua loja, se encontra na página de configurações:

![Página de configurações com o AppID adicionado](./__assets__/opencart3/admin-settings-appid.png)

Pronto, agora vamos aprender como utilizar o Pix ou Woovi Parcelado no seu checkout.

## Como utilizar o Pix ou Woovi Parcelado no checkout

Ao realizar uma compra em sua loja OpenCart, o cliente será redirecionado para a página de checkout.

Nesta página, o cliente deve inserir informações como CPF/CNPJ e o endereço dele, que será utilizado para a criação da cobrança.

![Formulário de checkout com campos adicionais](./__assets__/opencart3/checkout-form.png)

Após isso, o cliente deve selecionar o método de pagamento desejado: Pix ou Woovi Parcelado.

![Selecionando o método de pagamento](./__assets__/opencart3/checkout-payment-method-selector.png)

Ao confirmar a compra utilizando o método de pagamento _Pix_, o QR Code do Pix será exibido na página de sucesso, pronto para ser escaneado pelo seu cliente:

![Página de sucesso do checkout](./__assets__/opencart3/checkout-success-js-plugin.png)
![QrCode do Pix na página de sucesso do checkout](./__assets__/opencart3/checkout-success-js-plugin-part2.png)

Ao escolher o Woovi Parcelado como método de pagamento, um menu será exibido para possibilitar o pagamento por meio de Pix e/ou cartão de crédito:

![Página de sucesso do checkout com Woovi Parcelado](./__assets__/opencart3/checkout-success-js-plugin-parcelado.png)
![Menu de pagamento Woovi Parcelado na página de sucesso do checkout](./__assets__/opencart3/checkout-success-js-plugin-part2-parcelado.png)

## Campos adicionais

A extensão necessita dos seguintes campos adicionais:

- CPF/CNPJ para ambos métodos de pagamento.
- Rua, número, complemento e bairro para o método de pagamento Woovi Parcelado.

Cada campo adicional é obtido de duas maneiras:

- Através dos _custom fields_ (campos personalizados) do OpenCart.
- Ou diretamente durante o checkout.

Durante a instalação, a extensão configura automaticamente os custom fields necessários para que os clientes possam inserir seu CPF/CNPJ e endereço durante o checkout:

![Custom fields durante o registro](./__assets__/opencart3/checkout-form.png)

Caso deseje, é possível alterar o custom field utilizado ou até mesmo desativar essa configuração no painel de administração, selecionando a opção _None_ (Nenhum) em _Edit custom fields settings_:

![Configuração ou desativação do custom field](./__assets__/opencart3/admin-settings-custom-fields.png)

Se a extensão não puder encontrar um custom field, no checkout irá aparecer diretamente campos adicionais para que o cliente possa inserir seu CPF/CNPJ ou endereço, logo acima do botão de confirmação do pedido:

![Campos adicionais durante o checkout](./__assets__/opencart3/checkout-additional-fields.png)

## Como configurar os status dos pedidos

As configurações dos status de cada pedido podem ser encontradas na página de configurações:

![Configurações dos status dos pedidos](./__assets__/opencart3/admin-settings-order-status.png)

### Quando um pedido for criado

Por padrão, quando a cobrança da Woovi é criada, o status do pedido é alterado para _Pending_ (pendente). No entanto, é possível configurá-lo para qualquer status desejado:

![Configuração do status quando um pedido for criado](./__assets__/opencart3/admin-settings-order-status-when-waiting.png)

Veja um exemplo de pedido que acabou de ser criado:

![Pedido de exemplo com o status pendente](./__assets__/opencart3/example-order-pending-status.png)

### Quando o pedido for pago

Por padrão, quando a cobrança da Woovi é paga, o status do pedido é alterado para _Processing_ (processando). No entanto, é possível configurá-lo para qualquer status desejado:

![Configuração do status quando um pedido for pago](./__assets__/opencart3/admin-settings-order-status-when-paid.png)

Veja um exemplo de pedido que acabou de ser pago:

![Pedido de exemplo com o status processando](./__assets__/opencart3/example-order-processing-status.png)

## Como configurar o título do método de pagamento

Para modificar o título a ser empregado para o método de pagamento via Pix ou Woovi Parcelado durante o processo de checkout, dirija-se à página de configurações da extensão.

Configure o título do método de pagamento no campo _Payment method title_ (Título do Método de Pagamento) na seção de configurações do Pix ou Woovi Parcelado:

![Configuração do título do método de pagamento Pix](./__assets__/opencart3/admin-settings-payment-method-title.png)

Observe o novo título do método de pagamento durante o processo de checkout.

![Novo título do método de pagamento durante o checkout](./__assets__/opencart3/checkout-new-pix-payment-method-title.png)

## Como visualizar os logs da sua loja

Você pode acessar os logs da sua loja acessando a página localizada na barra lateral do seu painel de administração, em _System_ (Sistema) > _Maintenance_ (Manutenção) > _Error logs_ (Registro de erros):

![Opção de log na barra lateral do painel](./__assets__/opencart3/admin-sidebar-log-option.png)

Nessa página de logs, deve aparecer os erros registrados da sua loja:

![Página de logs](./__assets__/opencart3/admin-logs-page.png)

---

## Como integrar o Pix em sua loja OpenCart 4

A Woovi disponibiliza uma extensão para o OpenCart 4 que permite a integração do Pix em seu checkout, com suporte à atualização automática do status de seus pedidos e logs.

A plataforma efetua em tempo real a conciliação entre seu Banco e sua loja. Após conectar a sua conta na Woovi é possível cobrar clientes em tempo real com QrCodes Pix, enviar links de pagamento e gerenciar cobranças incluindo extornos.

Veja como é fácil aumentar suas vendas integrando o Pix em sua loja:

## Pré-requisitos

:::caution Preste atenção
- Uma loja com o OpenCart 4 instalado.
:::

## Instalação

Antes de instalar a extensão, é importante garantir que ela esteja disponível na sua loja. Isso pode ser feito de duas maneiras: através do marketplace ou fazendo o upload do arquivo da extensão.

### Marketplace

A maneira mais conveniente de baixar a extensão em sua loja é acessando o [marketplace oficial](https://www.opencart.com/index.php?route=marketplace/extension/info&extension_id=45252&filter_search=woovi) do OpenCart. Lá, você encontrará a extensão pronta para ser baixada e instalada com facilidade.

Veja como você pode baixar utilizando o marketplace:

#### 1) Acesse o painel de administração

Para acessar o marketplace e carregar a extensão na sua loja, siga estes passos simples:

1. No painel de administração da sua loja, localize a barra lateral e clique na opção _Extensions_.

2. Em seguida, no submenu que é exibido, clique na opção _Marketplace_:
![Acesso ao submenu com o marketplace como opção](./__assets__/opencart4/marketplace-access.png)

Ao seguir essas etapas, você será direcionado para o marketplace oficial do OpenCart.

#### 2) Pesquise a extensão

Ao acessar o marketplace, pesquise pela extensão _woovi_:

![Listagem do marketplace com a extensão](./__assets__/opencart4/marketplace-search.png)

#### 3) Inicie o download

Role um pouco a página até encontrar a seção _Download_. Clique nessa seção e em seguida no botão _Download_ para carregar a nossa extensão na sua loja:

![Página da extensão com o botão de Download](./__assets__/opencart4/extension-download-page.png)

### Upload do arquivo

Além do marketplace, você também tem a opção de carregar manualmente o arquivo da extensão. Para isso, acesse a página de downloads no [marketplace oficial](https://www.opencart.com/index.php?route=marketplace/extension/info&extension_id=45252&filter_search=woovi) e baixe primeiramente o arquivo da extensão:

![Página da extensão no marketplace indicando o botão de acesso aos downloads](./__assets__/opencart4/marketplace-download-button.png)
![Página de downloads no marketplace](./__assets__/opencart4/marketplace-downloads-page.png)

:::caution Preste atenção
Assegure-se de que o nome do arquivo da extensão seja _woovi.ocmod.zip_ ao fazer o upload, porque o OpenCart considera o nome do arquivo como um "identificador" da extensão, que precisa ser _woovi_.
:::

Após isso, acesse a página do instalador de extensões, localizado na opção _Installer_ no menu _Extensions_ do OpenCart:

![Opção do instalador de extensões no menu do OpenCart](./__assets__/opencart4/extension-installer-menu-option.png)

Ao acessar a página do instalador de extensões, localize o botão de upload azul localizado no canto superior direito do seu painel. Clique nesse botão e selecione o arquivo da extensão que deseja carregar:

![Seleção do arquivo](./__assets__/opencart4/extension-file-selection.png)

### Instalando a extensão

Após baixar a extensão, seja através do marketplace ou por upload, você encontrará a extensão na página do instalador de extensões. Nessa página, localize a extensão _Woovi_ e clique no botão verde com o símbolo "+" para dar continuidade à instalação:

![Botão para instalar a extensão](./__assets__/opencart4/install-extension-button.png)

### Instalando o método de pagamento

Acesse a página de extensões por meio da sub-opção _Extensions_ dentro da outra opção _Extensions_:

![Sub-opção "Extensions" selecionada](./__assets__/opencart4/extensions-menu-option.png)

Na página de extensões, utilize a opção de filtro para selecionar extensões do tipo _Payment_:

![Filtro pelo tipo _Payment_ habilitado](./__assets__/opencart4/extension-list-filtered-by-payment-type.png)

Para instalar _definitivamente_ nossa extensão como um método de pagamento, role um pouco para baixo na página e clique no botão verde com o símbolo "+" na extensão Woovi:

![Instalação da extensão Woovi como método de pagamento](./__assets__/opencart4/install-payment-method.png)

Após isso, clique no botão azul com o ícone de um lápis para acessar a página de configuração da extensão.

## Configuração

Após acessar a página de configurações da extensão, é necessário ativar a extensão no checkout pressionando o botão _Status_: 

![Página de configurações com o botão _Status_](./__assets__/opencart4/admin-settings-status.png)

Tendo habilitado o botão Status, _Pix_ deverá aparecer como método de pagamento no checkout.

No entanto, é necessário integrar a extensão com a plataforma Woovi e isto pode ser feito adicionando a url de _webhook_ na plataforma.

Para obter essa URL, vá até a página de configurações e copie ela:

![Página de configurações com a url de webhook](./__assets__/opencart4/admin-settings-webhook.png)

Entre na plataforma da Woovi e [clique aqui](https://app.woovi.com/home/applications/opencart/add/oneclick) ou vá em `API/Plugins` > `OpenCart` > `Adicionar`:

![Botão de adicionar um plugin na plataforma Woovi](./__assets__/opencart4/woovi-plugin-card.png)

Cole a URL de webhook no campo _Preencha a url do seu site_ e pressione o botão _Salvar_:

![Formulário para adicionar uma integração na plataforma Woovi](./__assets__/opencart4/woovi-add-plugin-form.png)

Após isto, verifique se o _AppID_, um código que identifica sua loja, se encontra na página de configurações:

![Página de configurações com o AppID adicionado](./__assets__/opencart4/admin-settings-appid.png)

Pronto, agora vamos aprender como utilizar o Pix no seu checkout.

## Como utilizar o Pix no checkout

Ao realizar uma compra em sua loja OpenCart, o cliente será redirecionado para a página de checkout.

Nesta página, o cliente deverá inserir seu CPF ou CNPJ, que será utilizado para a cobrança Pix:

![Formulário de checkout com o CPF/CNPJ](./__assets__/opencart4/checkout-form-with-tax-id.png)

Após isso, o cliente deve selecionar _Pix_ como método de pagamento (_Payment Method_):

![Selecionando Pix como método de pagamento](./__assets__/opencart4/checkout-payment-method-selector.png)

Ao confirmar a compra, o QR Code do Pix será exibido na página de sucesso, pronto para ser escaneado pelo seu cliente:

![Página de sucesso do checkout](./__assets__/opencart4/checkout-success-js-plugin.png)
![QrCode do Pix na página de sucesso do checkout](./__assets__/opencart4/checkout-success-js-plugin-part2.png)

## CPF/CNPJ

O CPF/CNPJ utilizado nas cobranças do Pix pode ser obtido de duas formas:

- Através dos _custom fields_ (campos personalizados) do OpenCart.
- Ou diretamente durante o checkout.

Os custom fields são uma funcionalidade do OpenCart que permitem adicionar campos adicionais nos dados dos clientes.

Durante a instalação, a extensão configura automaticamente o custom field necessário para que os clientes possam inserir seu CPF/CNPJ durante o registro:

![CPF/CNPJ durante o registro](./__assets__/opencart4/account-register-with-taxid.png)

Caso deseje, é possível alterar o custom field utilizado ou até mesmo desativar essa configuração no painel de administração, selecionando a opção _None_ (Nenhum):

![Configuração ou desativação do custom field](./__assets__/opencart4/admin-settings-custom-field.png)

Se a extensão não puder encontrar um custom field, no checkout irá aparecer diretamente um campo para que o cliente possa inserir seu CPF ou CNPJ, logo acima do botão de confirmação do pedido:

![Campo CPF/CNPJ durante o checkout](./__assets__/opencart4/checkout-custom-field.png)

## Como configurar os status dos pedidos

As configurações dos status de cada pedido podem ser encontradas na página de configurações:

![Configurações dos status dos pedidos](./__assets__/opencart4/admin-settings-order-status.png)

### Quando um pedido for criado

Por padrão, quando a cobrança da Woovi é criada, o status do pedido é alterado para _Pending_ (pendente). No entanto, é possível configurá-lo para qualquer status desejado:

![Configuração do status quando um pedido for criado](./__assets__/opencart4/admin-settings-order-status-when-waiting.png)

Veja um exemplo de pedido que acabou de ser criado:

![Pedido de exemplo com o status pendente](./__assets__/opencart4/example-order-pending-status.png)

### Quando o pedido for pago

Por padrão, quando a cobrança da Woovi é paga, o status do pedido é alterado para _Processing_ (processando). No entanto, é possível configurá-lo para qualquer status desejado:

![Configuração do status quando um pedido for pago](./__assets__/opencart4/admin-settings-order-status-when-paid.png)

Veja um exemplo de pedido que acabou de ser pago:

![Pedido de exemplo com o status processando](./__assets__/opencart4/example-order-processing-status.png)

## Como visualizar os logs da sua loja

Você pode acessar os logs da sua loja acessando a página localizada na barra lateral do seu painel de administração, em _System_ (Sistema) > _Maintenance_ (Manutenção) > _Error logs_ (Registro de erros):

![Opção de log na barra lateral do painel](./__assets__/opencart4/admin-sidebar-log-option.png)

Na página de logs, clique no botão "woovi.log" para acessar a página com os logs da extensão:

![Página de logs da extensão](./__assets__/opencart4/admin-logs-page.png)

---

## Oracle Commerce Cloud - Começando

![Banner](/img/ecommerce/woocommerce-banner.png)

## Guia de Introdução

Para começar a usar o Woovi basta seguir os seguintes passos:

1. Cadastre-se para uma nova conta em [Cadastre-se](https://woovi.com/register/?src=occ) ou [Fale com Vendas](https://woovi.com/join/?src=occ)
2. Crie um API appID do tipo Oracle Commerce Cloud [aqui](/docs/apis/api-getting-started)
3. Siga o [guia de integração](/docs/ecommerce/oracle/occ-integrating) para começar a trabalhar.

---

## Integrando Oracle Commerce Cloud na Woovi

### Plugin Pix para OCC - Oracle Commerce Cloud

## Resumo

Este documento detalha passos necessários para conectar a sua plataforma de e-Commerce, baseada em Oracle Commerce Cloud, na Woovi. A plataforma Woovi efetua em tempo real a conciliação entre seu Banco e seu e-Commerce.
Após conectar a sua conta na Woovi é possível cobrar clientes em tempo real com QrCodes Pix, enviar Links de Pagamento, gerenciar cobranças incluindo extornos.

> *Nota: Este documento espera que você já tenha um ambiente Oracle Commerce Cloud ativo.*

## 1. Crie um Registered Applications na OCC

Entre em `<ambiente>.occa.ocs.oraclecloud.com/occs-admin/#/settings/webAPI` e crie uma nova aplicação para a Woovi

## 2. Crie uma nova Aplicação do tipo Oracle na Woovi

![App](/img/ecommerce/occ-app.png)

Escolhe o tipo Oracle para a Aplicação Woovi. Cadastre o Application ID, o Application Secret e a url da sua instância Oracle Commerce Cloud.
Ao salvar será automaticamente registrado os Webhooks de Generic Payments.

## 3. Instale o Plugin Woovi na sua instância Oracle Commerce Cloud

Converse com o integrador para adicionar as extensoes e widgtes da Woovi na sua Storefront

#### Requisitos de sistema

- Oracle Commerce Cloud 18D e acima 
- Ser cliente ativo Woovi.

---

## Integrando a woovi na Prestashop


Este documento detalha os passos necessários para conectar sua plataforma de e-commernce Prestashop na woovi. 

## 1. Faça o download do plugin

Plugin disponível no link abaixo:

[Woovi (Prestashop)](https://github.com/jefersoneiji/woovi-prestashop/releases/download/v0.0.1/woovi.zip)

## 2. Encontre o arquivo .zip salvo no computador

![Encontre o arquivo .zip salvo no computador](./__assets__/prestashop-step-5.png "step 4")

## 3. Entre como administrador no Back-Office do seu e-commerce

Em seguida, selecione o menu **Módulos > Gerenciador de módulos > Enviar um módulo**.

Siga as instruções da tela que aparecerá. 

![As a loggged user open your prestashop back-office](./__assets__/prestashop-step-6.png "step 5")

## 4. Depois da instalação completa, clique em "Configurar"

![As a loggged user open your prestashop back-office](./__assets__/prestashop-step-7.png "step 6")

## 5. Para os próximos passos, seguem as documentações abaixo

- (etapa obrigatória) Como configurar seu [AppID](./plugin-set-up.md)
- Como configurar seu [Webhook](./webhook-set-up.md)

---

## Integrando o AppID na Prestashop

# Como configurar seu AppID na Prestashop

Este documento detalha os passos necessários para conectar sua plataforma Prestashop na woovi. 

## 1. Copie seu AppID na plataforma da Woovi

Para encontrá-lo, acesse o seguinte menu **API/Plugins**.

Caso ele ainda não exista, clique neste botão **Nova API/Plugin > Tipo API REST > Salvar > AppID**.

![Getting appID in woovi's platform](./__assets__/prestashop-set-up-step-1.png "step 1")

## 2. Após a instalação do módulo, selecione o botão "Configurar"

![Opening plugin's set up page](./__assets__/prestashop-set-up-step-1-pt-br.png "step 2")

## 3. No campo de texto "AppID woovi" digite o AppID copiado

Em seguida, aperte o botão "Guardar". Pronto, AppID configurado.

![Saving appID in prestashop](./__assets__/prestashop-set-up-step-2-pt-br.png "step 3")

---

## Integrando o webhook na Prestashop

# Configuração do Webhook

Esta seção demonstra como configurar webhooks com seu e-commerce Prestashop. 

## 1. Registre o link do seu webhook na Woovi

Para encontrá-lo, acesso o seguinte menu **API/Plugins**.

Na sequência clique no botão **Novo Webhook**.

A tela abaixo deverá aparecer. 

O link a ser cadastrado será parecido com esse: 
```
https://seuwebsiteaqui.com.br/woovi/webhook
```

Ele deverá ser digitado no campo  **URL**:

![Registering webhook endpoint in woovi](./__assets__/prestashop-webhook-set-up-step-1.png "step 1")

Pronto! Webhook cadastrado.

## 2. Agora, os pedidos já podem ser atualizados pela Woovi

Depois da confirmação do pagamento, o status do pedido será alterado para **Pagamento Aceito**.

![Order status updated in prestashop after webhook endpoint is triggered](./__assets__/prestashop-webhook-set-up-step-2-pt-br.png "step 2")

---

## Integrando VTEX na woovi

:::caution Atenção
Este documento espera que você já tenha um ambiente VTEX, e uma conta criada na woovi
:::

## Plugin Pix para VTEX

### 1. Acesse a configuração da VTEX

Entre na plataforma da woovi e [clique aqui](https://app.woovi.com/home/applications/vtex/add) ou vá em `API/Plugins` > `Plugin VTEX` > `Adicionar`

![tutorial-box](./__assets__/vtex-tutorial-box.png)

### 2.2. Clique em salvar

![vtex-save](./__assets__/vtex-detail-save.png)

### 2.3. Copie o App ID gerado

![vtex-save](./__assets__/copy-app-id.png)

### 3. Acesse as configurações de pagamento

Acesse as configurações de pagamento no ADMIN da seu ecommerce VTEX.

![1-vtex-admin-panel](./__assets__/1-admin-panel.png)
![2-vtex-admin-panel](./__assets__/2-admin-panel.png)

### 3.1 Acesse a aba `Afiliações de Gateways`

Nesta aba clique no botão `+`.

![vtex-add-new-gateway](./__assets__/add-new-gateway.png)

### 3.2 Selecione o gateway `WooviConnector`

![vtex-woovi-gateway](./__assets__/gateway-woovi.png)

### 4. Configure o gateway

Cole seu `Application Key`, `Application Token` e o `App ID` que você já havia copiado, e clique em `Salvar`.

![vtex-woovi-gateway](./__assets__/woovi-connector-detail.png)

Caso você não tenha o `Application Key` e `Application Token`, você pode seguir a [documentação](https://help.vtex.com/pt/tutorial/chaves-de-aplicacao--2iffYzlvvz4BDMr6WGUtet) oficial da VTEX para fazer a geração.

### 5. Adicionando `Condição de pagamento` da Woovi

Logo depois de adicionar a nova afiliação de gateway, vá na aba `Condições de pagamentos` e clique em `+`.

![vtex-add-new-payment-condition](./__assets__/add-new-payment-condition.png)

### 5.1 Selecione a condição de pagamento `Woovi`

![vtex-woovi-payment-condition](./__assets__/payment-condition-woovi.png)

### 5.2 Configure a condição de pagamento

Selecione o gateway da Woovi que você acabou de criar, logo em seguida clique em `Salvar`.

![woovi-payment-condition-detail](./__assets__/woovi-payment-condition-detail.png)

Pronto, agora o método de pagamento da Woovi já aparecerá no seu checkout.

---

## Integrando Wake na woovi

:::caution Atenção
Este documento espera que você já tenha um ambiente Wake, e uma conta criada na woovi
:::

## Plugin Pix para Wake

### 1. Acesse a configuração da Wake

Entre na plataforma da woovi e [clique aqui](https://app.woovi.com/home/applications/wake/add) ou vá em `API/Plugins` > `Plugin Wake` > `Adicionar`

![1](./__assets__/wake-integrating-1.png)

### 2. Acesse a configuração da Wake na woovi

![2](./__assets__/wake-integrating-2.png)

### 2.1. Copie o App ID gerado

![3](./__assets__/wake-integrating-3.png)

### 3. Acesse o dashboard do seu ADMIN dentro da Wake

![4](./__assets__/wake-integrating-4.png)

### 4. Vá até `Pagamentos > Conectores de Pagamento F-Gateway`

![5](./__assets__/wake-integrating-5.png)

### 5. Procure a opção Custom

### 6. Clique em `Adicionar configuração`

![6](./__assets__/wake-integrating-6.png)

### 7. Preencha com as seguintes informações

![7](./__assets__/wake-integrating-7.png)

Depois de preencher, adicione a configuração.

### 8. Vá para a configuração que você acabou de criar e preencha as seguintes informações:

- Configuração do Endpoint de Pagamento: https://api.woovi.com/api/wake
- Versão: Completa
- Headers:
  - paymentType: pix
  - appID: Coloque o AppID que você gerou na etapa [2.1](#21-copie-o-app-id-gerado)

![8](./__assets__/wake-integrating-8.png)

### 9. Vá até `Pagamentos > Grupos e Parcelamentos`

![9](./__assets__/wake-integrating-9.png)

### 10. Crie um novo grupo

![10](./__assets__/wake-integrating-10.png)

### 11. Preencha com as seguintes informações

![11](./__assets__/wake-integrating-11.png)

### 12. Após salvar, volte em `Pagamentos > Grupos e Parcelamentos`

### 13. Vincule a forma de pagamento que você criou anteriormente

![12](./__assets__/wake-integrating-12.png)

![13](./__assets__/wake-integrating-13.png)

![14](./__assets__/wake-integrating-14.png)

![15](./__assets__/wake-integrating-15.png)

### 14. Vá `Pagamentos > Estrutura de pagamentos`

![16](./__assets__/wake-integrating-16.png)

### 15. Crie uma nova estrutura

![17](./__assets__/wake-integrating-17.png)

![18](./__assets__/wake-integrating-18.png)

### 16. Configure o grupo de pagamento que você acabou de criar nessa nova estrutura

![19](./__assets__/wake-integrating-19.png)

### 17. Salve a estrutura

![20](./__assets__/wake-integrating-20.png)

Pronto, o método de pagamento Pix da woovi está configurado na sua Wake!

---

## Woocommerce Advanced Settings

## 1. Customer Salvar CPF/CNPJ

Para salvar o customer da order na sua cobrança woovi é necessário que seja ativado um plugin que possibilite que o cliente informe o CPF/CNPJ no momento da compra.

Indicamos o uso do plugin [woocommerce-extra-checkout-fields-for-brazil](https://wordpress.org/plugins/woocommerce-extra-checkout-fields-for-brazil/) para este caso. Uma vez ativado o plugin passará a salvar os clientes que informarem o CPF/CNPJ no momento da compra.

**Obs: O uso não é obrigatório. Caso você siga sem a configuração do mesmo, suas cobranças serão salvas sem o cliente da mesma.**

## 2. Realizar Pedido com Pix no WooCommerce

Escolha a opção de pagar o pedido usando Pix

![Pay Pix](/img/ecommerce/woocommerce-pay-pix.png)

Pague o Pix usando o app do seu banco.

![Order](/img/ecommerce/woocommerce-order.png)

Valide que o status do Pedido mudou após o pagamento

## 3. Como configurar a expiração do pedido Woocommerce

A cobrança da woovi tem um valor de expiração padrão que equivale a 1 dia, já a configuração de expiração padrão do Woocommerce é de 60 minutos

Para saber mais sobre Como configurar o tempo de expiração da woovi Charge [Clique aqui](/docs/flows/flow-edit-default-expiration).

![Woocommerce Pedido](/img/ecommerce/woo-pedido.png)

Para alterar e igualar esse tempo de expiração para a woovi e para Woocommerce você deve procurar no menu admin:

`Woocommerce` > `Settings` > `Products` > `Inventory`

Por último, alterar o valor do Hold stock para 1440 minutos equivalente a 1 dia

![Woocommerce Expiracao](/img/ecommerce/woo-expiracao.png)

## 4. Como selecionar qual deverá ser o status quando um novo pedido for gerado

Por padrão quando a cobrança da woovi é criada, o status do pedido é alterado para `Pending payment`, porém é possível configurar para qualquer status que você queira.

![Woocommerce Status do Pedido Criado](/img/ecommerce/woocommerce-status-when-create-default.png)

Basta clicar e selecionar qual status você quer que seja colocado no pedido quando a cobrança da woovi for criada.

Após esta alteração os novos pedidos quando forem criados irão receber o valor desse campo em seu status.

## 5. Como selecionar qual deverá ser o status quando um pedido for pago

Por padrão quando a cobrança da woovi é paga, o status do pedido é alterado para `Processing`, porém é possível configurar para qualquer status que você queira.

![Woocommerce Status do Pedido Pago](/img/ecommerce/woocommerce-status-when-paid-default.png)

Basta clicar e selecionar qual status você quer que seja colocado no pedido quando a transação Pix for paga.

Após esta alteração os novos pedidos quando forem pagos irão receber o valor desse campo em seu status.

## 6. Como ver meus logs woovi em minha loja WooCommerce/Wordpress

Você pode visualizar os logs woovi em sua loja através dos seguintes passos:

- 1. Tenha acesso aos arquivos da loja
- 2. Acesse o seguinte path: `/wp-content/uploads/wc-logs`
- 3. Dentro de `wc-logs` você irá encontrar os arquivos de logs da woovi com o seguinte padrão de nome `woocommerce_woovi-2023-01-13-7d609d821235742dd8162bbb0ef84862`

## 7. Como verificar se o HPOS está habilitado?

HPOS (High Performance Order Storage) é uma nova forma de armazenamento de pedidos no WooCommerce, sendo a opção padrão para novas lojas, o que possibilitará um aumento de desempenho em sua loja.

Gradualmente, cada loja deve migrar para utilizar o HPOS, e cada plugin deve adicionar compatibilidade.

Para verificar se esta opção está ativa em sua loja Woocommerce, vá até a aba de "Recursos", acessando "Woocommerce" > "Configurações" > "Avançado" > "Recursos" e verificando se a opção _High-performance order storage (recommended)_ está ativada:

![Opção para ativar ou desativar HPOS](../__assets__/woo-hpos-settings.png)

---

## Woocommerce Oneclick

import Embed from 'react-embed';

## Veja o vídeo ou siga os passos abaixo

### 1. Instale a woovi na sua instância WooCommerce

[woovi For WooCommerce](https://wordpress.org/plugins/woovi-for-woocommerce/)

![Banner](/img/ecommerce/woocommerce-banner.png)
![Install](/img/ecommerce/woocommerce-plugin-install.png)

### 2. Configurando o Plugin WooCommerce

Após a instalação, é necessário integrar o plugin com a nossa plataforma. Isso pode ser realizado por meio do nosso botão de um clique ou inserindo a URL do seu ecommerce diretamente em nossa plataforma.

Ao configurar uma nova integração, será possível criar novos pedidos com Pix e woovi Parcelado, e o webhook já estará configurado para atualizar o status de seus pedidos em tempo real.

Antes de tudo, vá até a página de configurações do seu plugin, clicando em "Settings", para configurar o plugin:

![Configuracoes](/img/ecommerce/woocommerce/woocommerce-plugin-settings.png)

### 2.1. Configurando com um clique (recomendado)

Na página de configurações do plugin, clique no botão "Configure now with one click":

![Configurações do plugin com o botão de um clique](../__assets__/woocommerce-admin-1click.png)

Ao pressionar este botão, uma nova página será aberta em nossa plataforma, onde você poderá configurar rapidamente uma nova integração com sua loja WooCommerce.

Na plataforma, a URL do seu e-commerce será configurada automaticamente; você só precisará clicar em "Salvar":

![Nova integração WooCommerce na plataforma](../__assets__/woocommerce-save-platform-integration.png)

### 2.2. Configurando através da URL de seu ecommerce

Outra alternativa para autenticar o seu plugin seria acessar diretamente a plataforma e inserir a URL do seu e-commerce.

Na página de configurações do plugin, copie a URL de Webhook da sua loja WooCommerce:

![Webhook URL](/img/ecommerce/woocommerce/woocommerce-plugin-webhook.png)

Entre na plataforma da woovi e [clique aqui](https://app.woovi.com/home/applications/woocommerce/add/oneclick) ou vá em `API/Plugins` > `WooCommerce` > `Adicionar`:

![Webhook URL](/img/ecommerce/woocommerce/woocommerce-plugin-tutorial-card.png)

Cole a URL de Webhook que você copiou no campo "Site":

![Webhook URL](/img/ecommerce/woocommerce/woocommerce-plugin-tutorial.png)

---

## Número máximo de parcelas no plugin woovi Crediário

Para configurar o número máximo de parcelas ao criar um pedido em sua loja WooCommerce, acesse a plataforma woovi. Vá até a página de ajustes de cobrança, através de _Cobranças > Ajustes_, e clique na opção "Pix Crediário" na seção de "Métodos de pagamento":

![Configuração do número máximo de parcelas padrão](./__assets__/woocommerce-pix-crediary-platform-max-installment-number-setting.png)

Não se esqueça de clicar no botão "Salvar".

[Crie um novo pedido em seu Woocommerce](woocommerce-crediary.mdx).

Observe que o número máximo de parcelas será aquele configurado na página de ajustes de cobrança:

![Checkout com o número máximo de parcelas](./__assets__/woocommerce-pix-crediary-plugin-checkout-max-installment-number.png)

---

## Como configurar o plugin woovi Crediário com WooCommerce

:::caution Atenção
Este documento espera que você já tenha um ambiente WooCommerce ativo, e uma conta criada na woovi
Caso não tenha acesso à plataforma registre-se [aqui](https://app.woovi.com/register?src=wordpress-docs)
:::

## Instale o Plugin woovi na sua instância WooCommerce

Este documento detalha passos necessários para conectar a sua plataforma de e-Commerce, baseada no WooCommerce, na woovi.

### 1. Instale a woovi na sua instância WooCommerce

[woovi For WooCommerce](https://wordpress.org/plugins/woovi-for-woocommerce/)

![Banner](/img/ecommerce/woocommerce-banner.png)
![Install](/img/ecommerce/woocommerce-plugin-install.png)

### 2. Configurando o Plugin WooCommerce

Ao configurar uma nova integração, será possível criar novos pedidos com woovi Crediário.

É necessário ter um [AppID](../../plugin/app-id.md) do tipo _Plugin_ para que seja possível a integração.

Para tanto, entre na plataforma e crie uma nova aplicação na página de [_Nova API/Plugin_](https://app.woovi.com/home/applications/add) em _API/Plugins > Nova API/Plugin_:

![Criando uma nova aplicação na plataforma](./__assets__/woocommerce-pix-crediary-platform-new-application.png)

Ao ser redirecionado para a página de visualizar uma aplicação, copie o _App ID_:

![Copiando o identificador da aplicação](./__assets__/woocommerce-pix-crediary-platform-application-id.png)

Vá até a página de configurações do seu plugin, clicando em _Settings Pix Crediary_, para configurar o plugin:

![Configurações Settings Crediário](./__assets__/woocommerce-plugin-settings-v2100.png)

Cole o _App ID_ copiado no campo _AppID woovi_:

![Colando o identificador da aplicação](./__assets__/woocommerce-pix-crediary-plugin-settings-app-id.png)

### 3. Ativando Plugin Brazilian Market

Para utilizar o woovi Crediário e salvar o customer da order na sua cobrança woovi é necessário que seja ativado um plugin que possibilite que o cliente informe os campos abaixo no momento da compra.

- Nome
- Cpf/Cnpj
- Email
- Telefone
- Endereço

Indicamos o uso do plugin [woocommerce-extra-checkout-fields-for-brazil](https://wordpress.org/plugins/woocommerce-extra-checkout-fields-for-brazil/) para este caso. Uma vez ativado o plugin passará a salvar os clientes que informarem o CPF/CNPJ no momento da compra.

### 4. Configurações do Plugin no WooCommerce

Ao acessar as configurações do plugin após os passos anteriores note que o AppID woovi ja estará preenchido e você poderá editar o título, descrição e label do botão de compra do plugin.

Para o tutorial iremos seguir com o titulo **Pagar com woovi Crediário** como no print abaixo:

![Configurações do Pix Crediário](./__assets__/woocommerce-pix-crediary-plugin-settings.png)

### 4.1. Como configurar o número máximo de parcelas

[Veja como configurar o número máximo de parcelas quando se faz um pedido no Woocommerce](./woocommerce-crediary-max-installment-number.md).

## 5. Realizar Pedido com Pix Crediário no WooCommerce

Escolha a opção de pagar o pedido usando woovi Crediário ou o nome que você escolheu no momento da configuração do plugin.

![Woocommerce Checkout Crediário](./__assets__/woocommerce-pix-crediary-checkout.png)

Selecione a opção de pagamento:

![Selecionando a opção de pagamento](./__assets__/woocommerce-pix-crediary-selecting-payment-option.png)

Pague a entrada via Pix usando o app do seu banco:

![Pague o QR Code](./__assets__/woocommerce-pix-crediary-payment.png)

## 4. Como ver meus logs woovi em minha loja WooCommerce/Wordpress

Você pode visualizar os logs woovi em sua loja através dos seguintes passos:

- 1. Tenha acesso aos arquivos da loja
- 2. Acesse o seguinte path: `/wp-content/uploads/wc-logs`
- 3. Dentro de `wc-logs` você irá encontrar os arquivos de logs da woovi com o seguinte padrão de nome `woocommerce_woovi-2023-01-13-7d609d821235742dd8162bbb0ef84862`

---

## Como aplicar desconto por método de pagamento Pix em minha loja Woocommerce?

Para aplicar descontos por método de pagamento Pix em sua loja Woocommerce, siga os seguintes passos:

## 1 - Instale o plugin WooCommerce Discounts Per Payment Method

O primeiro passo é instalar o plugin [WooCommerce Discounts Per Payment Method](https://br.wordpress.org/plugins/woo-payment-discounts/) em sua loja Woocommerce. Esse plugin é responsável por adicionar a opção de desconto por método de pagamento em sua loja.

## 2 - No menu Woocommerce, selecione a opção: Desconto por Método de Pagamento

Depois de instalar o plugin, vá até o painel administrativo de sua loja e selecione a opção "Desconto por Método de Pagamento". Essa opção deve estar disponível no menu do plugin instalado.

## 3 - Configure as regras de desconto conforme os métodos de pagamento disponíveis

Por fim, configure as regras de desconto conforme os métodos de pagamento disponíveis em sua loja. Para aplicar desconto para pagamentos via Pix, selecione a opção "Pix" e defina a porcentagem de desconto que deseja oferecer para os clientes que escolherem essa forma de pagamento.

![image](https://user-images.githubusercontent.com/67057187/226739290-cae6960f-b83f-40bd-a7cb-144ec8cef982.png)

Lembre-se de salvar as configurações antes de sair da página. Com esses passos simples, você poderá aplicar descontos por método de pagamento Pix em sua loja Woocommerce e oferecer uma experiência diferenciada aos seus clientes.

---

## Como trocar entre ambiente Sandbox e Produção

## Trocando ambiente 

1. Acesse o painel admin do seu wordpress  
2. No menu lateral acesse -> Plugins -> Plugins Instalados  
3. Localize o nosso plugin "woovi for Woocommerce"  
4. Clique em "Settings Pix"  
![](./__assets__/settings-pix.png)

5. Localize input de seleção "Ambiente" e troque para qual ambiente deseja integrar o plugin  
- Sandbox  
- Production  
![](./__assets__/choose-environment.png)

6. Gera um appID em nossa plataforma  
Você pode seguir [essa documentação](/docs/ecommerce/woocommerce/woocommerce-plugin) para criar um appID e usar os links abaixo para acessar nossos ambientes  
Produção: https://app.woovi.com  
Sanbox: https://app.woovi-sandbox.com  

7. Feito isso, volte para tela de configuração do plugin no seu painel admin do wordpress, role até o final e clique em salvar alterações
![](./__assets__/save-changes.png)

---

## Como reembolsar um pedido no WooCommerce

## 1. Abra os detalhes do pedido

No menu lateral, abra a lista de pedidos e então clique em um pedido já pago:

![Pedidos no WooCommerce](./__assets__/woocommerce-orders.png)

## 2. Click the refund button

Um pouco abaixo na página você verá uma seção com detalhes do pedido, clique no botão **Reembolsar**:

![Botão de reembolso no WooCommerce](./__assets__/woocommerce-refund.png)

## 3. Preencha as informações e confirme o pedido

Neste passo você poderá configurar como o reembolso será feito:

- No campo **Qtd**, você decide a quantidade de items que serão reembolsados
- Selecione **Repor os itens reembolsados** se deseja que os itens voltem ao estoque
- Em **Total** você poderá definir o valor total do reembolso. Ele poderá ser menos que o valor total do pedido, resultando em um reembolso parcial.
- Também poderá definir o comentário do reembolso no campo **Razão do reembolso**.

Ao completar as informações, clique no botão **Reembolsar R$ XX,XX por woovi**:

![Confirmar o reembolso no WooCommerce](./__assets__/woocommerce-refund-confirm.png)

## 4. Ver reembolsos da cobrança dentro da plataforma

Nos detalhes da cobrança dentro da plataforma você poderá ver o status do reembolso e os eventos:

![Cobrança reembolsada](./__assets__/woocommerce-refund-charge.png)

Também é possível visualizar a lista de reembolsos:

abra a aba **Transações** e selecione a transação de pagamento da cobrança:

![Transações da cobrança](./__assets__/woocommerce-charge-transactions.png)

Nos detalhes da transação você poderá visualizar todos os reembolsos:

![Reembolsos da transação](./__assets__/woocommerce-transaction-refunds.png)

---

## Configurando o WooCommerce Openpix com a NextMove

## Integrando a Woovi com o NextMove

1. Instale o Plugin Woovi na sua instância WooCommerce
2. Configure o Plugin WooCommerce [aqui](./woocommerce-plugin.mdx)
3. Dentro do plugin do NextMove, vá em `Configurações` > `Edit/rules` da página `Thank You`

![NextMove-settings](/img/ecommerce/woocommerce/woocommerce-nextmove-settings.png)

4. Dentro da pagina de edição clique em `Manage Components`

5. Dentro da página de edição de componentes clique em `HTML` e coloque o seguinte código

```html
<div id='openpix-order' style='margin-bottom: 40px'></div>
```

![NextMove-settings](/img/ecommerce/woocommerce/woocommerce-nextmove-html-settings.png)

6. Crie uma cobrança utilizando a Woovi, e confirme se o qrcode é exibido

---

## Integrando a woovi com WooCommerce

:::caution Atenção
Este documento espera que você já tenha um ambiente WooCommerce ativo, e uma conta criada na woovi
Caso não tenha acesso à plataforma registre-se [aqui](https://app.woovi.com/register?src=wordpress-docs)
:::

## Instale o Plugin woovi na sua instância WooCommerce utilizando o 1-Click

Este documento detalha passos necessários para conectar a sua plataforma de e-Commerce, baseada no WooCommerce, na woovi.

## Veja o vídeo ou siga os passos abaixo

### 1. Instale a woovi na sua instância WooCommerce

[woovi For WooCommerce](https://wordpress.org/plugins/woovi-for-woocommerce/)

![Banner](/img/ecommerce/woocommerce-banner.png)
![Install](/img/ecommerce/woocommerce-plugin-install.png)

### 2. Configurando o Plugin WooCommerce

Após a instalação, é necessário integrar o plugin com a nossa plataforma. Isso pode ser realizado por meio do nosso botão de um clique ou inserindo a URL do seu ecommerce diretamente em nossa plataforma.

Ao configurar uma nova integração, será possível criar novos pedidos com Pix e woovi Parcelado, e o webhook já estará configurado para atualizar o status de seus pedidos em tempo real.

Antes de tudo, vá até a página de configurações do seu plugin, clicando em "Settings", para configurar o plugin:

![Configuracoes](/img/ecommerce/woocommerce/woocommerce-plugin-settings.png)

### 2.1. Configurando com um clique (recomendado)

Na página de configurações do plugin, clique no botão "Configure now with one click":

![Configurações do plugin com o botão de um clique](../__assets__/woocommerce-admin-1click.png)

Ao pressionar este botão, uma nova página será aberta em nossa plataforma, onde você poderá configurar rapidamente uma nova integração com sua loja WooCommerce.

Na plataforma, a URL do seu e-commerce será configurada automaticamente; você só precisará clicar em "Salvar":

![Nova integração WooCommerce na plataforma](../__assets__/woocommerce-save-platform-integration.png)

### 2.2. Configurando através da URL de seu ecommerce

Outra alternativa para autenticar o seu plugin seria acessar diretamente a plataforma e inserir a URL do seu e-commerce.

Na página de configurações do plugin, copie a URL de Webhook da sua loja WooCommerce:

![Webhook URL](/img/ecommerce/woocommerce/woocommerce-plugin-webhook.png)

Entre na plataforma da woovi e [clique aqui](https://app.woovi.com/home/applications/woocommerce/add/oneclick) ou vá em `API/Plugins` > `WooCommerce` > `Adicionar`:

![Webhook URL](/img/ecommerce/woocommerce/woocommerce-plugin-tutorial-card.png)

Cole a URL de Webhook que você copiou no campo "Site":

![Webhook URL](/img/ecommerce/woocommerce/woocommerce-plugin-tutorial.png)

## Configurações avançadas WooCommerce

## 1. Customer Salvar CPF/CNPJ

Para salvar o customer da order na sua cobrança woovi é necessário que seja ativado um plugin que possibilite que o cliente informe o CPF/CNPJ no momento da compra.

Indicamos o uso do plugin [woocommerce-extra-checkout-fields-for-brazil](https://wordpress.org/plugins/woocommerce-extra-checkout-fields-for-brazil/) para este caso. Uma vez ativado o plugin passará a salvar os clientes que informarem o CPF/CNPJ no momento da compra.

**Obs: O uso não é obrigatório. Caso você siga sem a configuração do mesmo, suas cobranças serão salvas sem o cliente da mesma.**

## 2. Realizar Pedido com Pix no WooCommerce

Escolha a opção de pagar o pedido usando Pix

![Pay Pix](/img/ecommerce/woocommerce-pay-pix.png)

Pague o Pix usando o app do seu banco.

![Order](/img/ecommerce/woocommerce-order.png)

Valide que o status do Pedido mudou após o pagamento

## 3. Como configurar a expiração do pedido Woocommerce

A cobrança da woovi tem um valor de expiração padrão que equivale a 1 dia, já a configuração de expiração padrão do Woocommerce é de 60 minutos

Para saber mais sobre Como configurar o tempo de expiração da woovi Charge [Clique aqui](/docs/flows/flow-edit-default-expiration).

![Woocommerce Pedido](/img/ecommerce/woo-pedido.png)

Para alterar e igualar esse tempo de expiração para a woovi e para Woocommerce você deve procurar no menu admin:

`Woocommerce` > `Settings` > `Products` > `Inventory`

Por último, alterar o valor do Hold stock para 1440 minutos equivalente a 1 dia

![Woocommerce Expiracao](/img/ecommerce/woo-expiracao.png)

## 4. Como selecionar qual deverá ser o status quando um novo pedido for gerado

Por padrão quando a cobrança da woovi é criada, o status do pedido é alterado para `Pending payment`, porém é possível configurar para qualquer status que você queira.

![Woocommerce Status do Pedido Criado](/img/ecommerce/woocommerce-status-when-create-default.png)

Basta clicar e selecionar qual status você quer que seja colocado no pedido quando a cobrança da woovi for criada.

Após esta alteração os novos pedidos quando forem criados irão receber o valor desse campo em seu status.

## 5. Como selecionar qual deverá ser o status quando um pedido for pago

Por padrão quando a cobrança da woovi é paga, o status do pedido é alterado para `Processing`, porém é possível configurar para qualquer status que você queira.

![Woocommerce Status do Pedido Pago](/img/ecommerce/woocommerce-status-when-paid-default.png)

Basta clicar e selecionar qual status você quer que seja colocado no pedido quando a transação Pix for paga.

Após esta alteração os novos pedidos quando forem pagos irão receber o valor desse campo em seu status.

## 6. Como ver meus logs woovi em minha loja WooCommerce/Wordpress

Você pode visualizar os logs woovi em sua loja através dos seguintes passos:

- 1. Tenha acesso aos arquivos da loja
- 2. Acesse o seguinte path: `/wp-content/uploads/wc-logs`
- 3. Dentro de `wc-logs` você irá encontrar os arquivos de logs da woovi com o seguinte padrão de nome `woocommerce_woovi-2023-01-13-7d609d821235742dd8162bbb0ef84862`

## 7. Como verificar se o HPOS está habilitado?

HPOS (High Performance Order Storage) é uma nova forma de armazenamento de pedidos no WooCommerce, sendo a opção padrão para novas lojas, o que possibilitará um aumento de desempenho em sua loja.

Gradualmente, cada loja deve migrar para utilizar o HPOS, e cada plugin deve adicionar compatibilidade.

Para verificar se esta opção está ativa em sua loja Woocommerce, vá até a aba de "Recursos", acessando "Woocommerce" > "Configurações" > "Avançado" > "Recursos" e verificando se a opção _High-performance order storage (recommended)_ está ativada:

![Opção para ativar ou desativar HPOS](../__assets__/woo-hpos-settings.png)

---

## Como configurar o plugin woovi Parcelado com WooCommerce

:::caution Atenção
Este documento espera que você já tenha um ambiente WooCommerce ativo, e uma conta criada na woovi
Caso não tenha acesso à plataforma registre-se [aqui](https://app.woovi.com/register?src=wordpress-docs)
:::

## Instale o Plugin woovi na sua instância WooCommerce utilizando o 1-Click

Este documento detalha passos necessários para conectar a sua plataforma de e-Commerce, baseada no WooCommerce, na woovi.

### 1. Instale a woovi na sua instância WooCommerce

[woovi For WooCommerce](https://wordpress.org/plugins/woovi-for-woocommerce/)

![Banner](/img/ecommerce/woocommerce-banner.png)
![Install](/img/ecommerce/woocommerce-plugin-install.png)

### 2. Configurando o Plugin WooCommerce

Após a instalação, é necessário integrar o plugin com a nossa plataforma. Isso pode ser realizado por meio do nosso botão de um clique ou inserindo a URL do seu ecommerce diretamente em nossa plataforma.

Ao configurar uma nova integração, será possível criar novos pedidos com Pix e woovi Parcelado, e o webhook já estará configurado para atualizar o status de seus pedidos em tempo real.

Antes de tudo, vá até a página de configurações do seu plugin, clicando em "Settings Parcelado", para configurar o plugin:

![Configurações Settings Parcelado](./__assets__/woocommerce-plugin-settings-v261.png)

### 2.1. Configurando com um clique (recomendado)

Na página de configurações do plugin, clique no botão "Configure now with one click":

![Configurações do plugin com o botão de um clique](./__assets__/woocommerce-parcelado-admin-1click.png)

Ao pressionar este botão, uma nova página será aberta em nossa plataforma, onde você poderá configurar rapidamente uma nova integração com sua loja WooCommerce.

Na plataforma, a URL do seu e-commerce será configurada automaticamente; você só precisará clicar em "Salvar":

![Nova integração WooCommerce na plataforma](./__assets__/woocommerce-save-platform-parcelado-integration.png)

Após salvo, sua integração ja estará configurada. Você pode ir para o passo de [ativar as configurações dos clientes](#3-ativando-plugin-brazilian-market).

### 2.2. Configurando através da URL de seu ecommerce

Outra alternativa para configurar o plugin seria acessar diretamente a plataforma e inserir a URL do seu e-commerce.

Primeiramente, copie a URL de Webhook da sua loja WooCommerce:

![Webhook URL Parcelado](./__assets__/woocommerce-plugin-webhook-parcelado.png)

Entre na plataforma da woovi e [clique aqui](https://app.woovi.com/home/applications/woocommerce-pix-credit-card/add/oneclick) ou vá em `API/Plugins` > `Plugin WooCommerce Parcelado` > `Adicionar`:

![Integration Box](./__assets__/woocommerce-integration-box-parcelado.png)

Cole a URL de Webhook que você copiou no campo "Site":

![Webhook URL](./__assets__/woocommerce-plugin-tutorial.png)

### 3. Ativando Plugin Brazilian Market

Para utilizar o woovi Parcelado e salvar o customer da order na sua cobrança woovi é necessário que seja ativado um plugin que possibilite que o cliente informe os campos abaixo no momento da compra.

- Nome
- Cpf/Cnpj
- Email
- Telefone
- Endereço

Indicamos o uso do plugin [woocommerce-extra-checkout-fields-for-brazil](https://wordpress.org/plugins/woocommerce-extra-checkout-fields-for-brazil/) para este caso. Uma vez ativado o plugin passará a salvar os clientes que informarem o CPF/CNPJ no momento da compra.

### 4. Configurações do Plugin no WooCommerce
Ao acessar as configurações do plugin após os passos anteriores note que o AppID woovi ja estará preenchido e confirme que o campo seja **Configured**.

Você também pode editar o titulo, descrição e label do botão de compra do plugin.

Para o tutorial iremos seguir com o titulo **Pagar com woovi Parcelado** como no print abaixo:

![Parcelado Settings](./__assets__/woo-settings-parcelado.png)

## 5. Realizar Pedido com Pix no WooCommerce

Escolha a opção de pagar o pedido usando woovi Parcelado ou o nome que você escolheu no momento da configuração do Plugin

![Woocommerce Checkout Parcelado](./__assets__/woo-checkout-parcelado.png)

Selecione a opção de pagamento:

![Woocommerce Opções do Pedido](./__assets__/woo-pedido-1.png)

Preencha os dados do cartão:

![Woocommerce Dados do Cartao do Pedido](./__assets__/woo-pedido-cartao.png)

Será gerado o pix da entrada e ao ser pago será capturada a transação no cartão de crédito e por fim completerá a venda!

![Woocommerce Entrada](./__assets__/woo-parcelado-entrada.png)

Valide que o status do Pedido mudou após o pagamento

![Woocommerce Pedido Sucesso](./__assets__/woo-pedido-sucesso.png)

## Configurações avançadas WooCommerce

## 1. Como configurar a expiração do pedido Woocommerce

A cobrança da woovi irá seguir o padrão selecionado dentro da plataforma para cobranças parceladas. Configure o tempo de expiração no woocommerce semelhante ao da plataforma para o funcionamento ideal.

Para saber mais sobre Como configurar o tempo de expiração da woovi Charge [Clique aqui](/docs/flows/flow-edit-default-expiration).

O prazo de pagamento representa o tempo selecionado de expiração.
![Woocommerce Opções do Pedido](./__assets__/woo-parcelado-payment-term.png)

Para alterar e igualar esse tempo de expiração para a woovi e para Woocommerce você deve procurar no menu admin:

`Woocommerce` > `Settings` > `Products` > `Inventory`

Por último, alterar o valor do Hold stock para 1440 minutos equivalente a 1 dia

![Woocommerce Expiracao](/img/ecommerce/woo-expiracao.png)

## 2. Como selecionar qual deverá ser o status quando um novo pedido for gerado

Por padrão quando a cobrança da woovi é criada, o status do pedido é alterado para `Pending payment`, porém é possível configurar para qualquer status que você queira.

![Woocommerce Status do Pedido Criado](/img/ecommerce/woocommerce-status-when-create-default.png)

Basta clicar e selecionar qual status você quer que seja colocado no pedido quando a cobrança da woovi for criada.

Após esta alteração os novos pedidos quando forem criados irão receber o valor desse campo em seu status.

## 3. Como selecionar qual deverá ser o status quando um pedido for pago

Por padrão quando a cobrança da woovi é paga, o status do pedido é alterado para `Processing`, porém é possível configurar para qualquer status que você queira.

![Woocommerce Status do Pedido Pago](/img/ecommerce/woocommerce-status-when-paid-default.png)

Basta clicar e selecionar qual status você quer que seja colocado no pedido quando a transação Pix for paga.

Após esta alteração os novos pedidos quando forem pagos irão receber o valor desse campo em seu status.

## 4. Como ver meus logs woovi em minha loja WooCommerce/Wordpress

Você pode visualizar os logs woovi em sua loja através dos seguintes passos:

- 1. Tenha acesso aos arquivos da loja
- 2. Acesse o seguinte path: `/wp-content/uploads/wc-logs`
- 3. Dentro de `wc-logs` você irá encontrar os arquivos de logs da woovi com o seguinte padrão de nome `woocommerce_woovi-2023-01-13-7d609d821235742dd8162bbb0ef84862`

---

## Woocommerce Postname Permalink

## Problema

Ao tentar cadastrar o webhook do Woocommerce, o mesmo retorna o erro 404.

## Solução

Acesse o painel do WordPress e vá em Configurações > Links permanentes.

Altere a opção para Nome do Post.

Exemplo:

![Woocommerce Postname Permalink](/img/ecommerce/woocommerce/woocommerce-postname.png)

---

## Integrando a Woovi com WooCommerce(Woocommerce)

:::caution Atenção
Este documento espera que você já tenha um ambiente WooCommerce ativo, e uma conta criada na woovi
Caso não tenha acesso à plataforma registre-se [aqui](https://app.woovi.com/register?src=wordpress-docs)
:::

## Resumo

Este documento detalha passos necessários para conectar a sua plataforma de e-Commerce, baseada no WooCommerce, na Woovi. A plataforma Woovi efetua em tempo real a conciliação entre seu Banco e seu e-Commerce.
Após conectar a sua conta na Woovi é possível cobrar clientes em tempo real com QrCodes Pix, enviar Links de Pagamento, gerenciar cobranças incluindo extornos.

## 1. Instale o Plugin Woovi na sua instância WooCommerce

### Download Direto do Plugin

Você pode baixar o plugin diretamente pelo link abaixo:

[woocommerce-openpix-v2.13.4.zip](https://github.com/Open-Pix/woocommerce-openpix/releases/download/v2.13.4/woocommerce-openpix-prod-v2.13.4-2026-01-27.13.36.zip)

Para instalar o plugin baixado:
1. Acesse o painel do WordPress
2. Vá em Plugins > Adicionar Novo
3. Clique em "Enviar plugin" no topo da página
4. Selecione o arquivo .zip baixado
5. Ative o plugin

### Instalação via Repositório WordPress

[Woovi For WooCommerce](https://wordpress.org/plugins/openpix-for-woocommerce/)

![Banner](/img/ecommerce/woocommerce-banner.png)
![Install](/img/ecommerce/woocommerce-plugin-install.png)

## 2. Configurando o Plugin WooCommerce

Entre em WooCommerce -> Settings > Payments.

![Payments](/img/ecommerce/woocommerce-payments.png)

### Clique em `Manage` no Plugin Woovi

- [ ] Cadastre um AppID do tipo API. Crie um appID [aqui](../../apis/api-getting-started.md)
- [ ] Customize o Título, Descrição e Texto de Botão de Pedido

![Setup](/img/ecommerce/woocommerce-setup.png)

### Após adicionar o seu appID, clique em `Configure now with one click` para configurarmos ou criar seu Webhook

- [ ] Ao clicar os campos, `Webhook Authorization` e `Webhook HMAC Secret Key` irão atualizar automaticamente e mostrar o status em `Webhook Status`.

### Caso não configure você pode acessar a plataforma, criar um webhook manualmente. Para isso:

- [ ] Crie uma senha para a integração do Webhook. O Webhook é necessário para atualizar o status dos Pedidos em tempo real quando a cobrança Pix é paga.
- [ ] Cadastre a URL de Callback do WooCommerce na Woovi. Exemplo: [https://meusite.com.br/wc-api/WC_Woovi_Pix_Gateway](https://meusite.com.br/wc-api/WC_Woovi_Pix_Gateway)
- [ ] Clique em `Configure now with one click` novamente, para configurar o Webhook com esses novos dados criados.

![Webhook](/img/ecommerce/woocommerce-gatilho.png)

### 2.1 Configuração Automática com Um Clique

## Veja o vídeo ou siga os passos abaixo

### 1. Instale a woovi na sua instância WooCommerce

[woovi For WooCommerce](https://wordpress.org/plugins/woovi-for-woocommerce/)

![Banner](/img/ecommerce/woocommerce-banner.png)
![Install](/img/ecommerce/woocommerce-plugin-install.png)

### 2. Configurando o Plugin WooCommerce

Após a instalação, é necessário integrar o plugin com a nossa plataforma. Isso pode ser realizado por meio do nosso botão de um clique ou inserindo a URL do seu ecommerce diretamente em nossa plataforma.

Ao configurar uma nova integração, será possível criar novos pedidos com Pix e woovi Parcelado, e o webhook já estará configurado para atualizar o status de seus pedidos em tempo real.

Antes de tudo, vá até a página de configurações do seu plugin, clicando em "Settings", para configurar o plugin:

![Configuracoes](/img/ecommerce/woocommerce/woocommerce-plugin-settings.png)

### 2.1. Configurando com um clique (recomendado)

Na página de configurações do plugin, clique no botão "Configure now with one click":

![Configurações do plugin com o botão de um clique](../__assets__/woocommerce-admin-1click.png)

Ao pressionar este botão, uma nova página será aberta em nossa plataforma, onde você poderá configurar rapidamente uma nova integração com sua loja WooCommerce.

Na plataforma, a URL do seu e-commerce será configurada automaticamente; você só precisará clicar em "Salvar":

![Nova integração WooCommerce na plataforma](../__assets__/woocommerce-save-platform-integration.png)

### 2.2. Configurando através da URL de seu ecommerce

Outra alternativa para autenticar o seu plugin seria acessar diretamente a plataforma e inserir a URL do seu e-commerce.

Na página de configurações do plugin, copie a URL de Webhook da sua loja WooCommerce:

![Webhook URL](/img/ecommerce/woocommerce/woocommerce-plugin-webhook.png)

Entre na plataforma da woovi e [clique aqui](https://app.woovi.com/home/applications/woocommerce/add/oneclick) ou vá em `API/Plugins` > `WooCommerce` > `Adicionar`:

![Webhook URL](/img/ecommerce/woocommerce/woocommerce-plugin-tutorial-card.png)

Cole a URL de Webhook que você copiou no campo "Site":

![Webhook URL](/img/ecommerce/woocommerce/woocommerce-plugin-tutorial.png)

### 2.2 Customer

Para salvar o customer da order na sua cobrança Woovi é necessário que seja ativado um plugin que possibilite que o cliente informe o CPF/CNPJ no momento da compra.

Indicamos o uso do plugin [woocommerce-extra-checkout-fields-for-brazil](https://wordpress.org/plugins/woocommerce-extra-checkout-fields-for-brazil/) para este caso. Uma vez ativado o plugin passará a salvar os clientes que informarem o CPF/CNPJ no momento da compra.

**Obs: O uso não é obrigatório. Caso você siga sem a configuração do mesmo, suas cobranças serão salvas sem o cliente da mesma.**

## 3. Realizar Pedido com Pix

Escolha a opção de pagar o pedido usando Pix

![Pay Pix](/img/ecommerce/woocommerce-pay-pix.png)

Pague o Pix usando o app do seu banco.

![Order](/img/ecommerce/woocommerce-order.png)

Valide que o status do Pedido mudou após o pagamento

## 4. Como configurar a expiração do pedido Woocommerce

A cobrança da Woovi tem um valor de expiração padrão que equivale a 1 dia, já a configuração de expiração padrão do Woocommerce é de 60 minutos

Para saber mais sobre Como configurar o tempo de expiração da Woovi Charge [Clique aqui](/docs/flows/flow-edit-default-expiration).

![Woocommerce Pedido](/img/ecommerce/woo-pedido.png)

Para alterar e igualar esse tempo de expiração para a Woovi e para Woocommerce você deve procurar no menu admin:

`Woocommerce` > `Settings` > `Products` > `Inventory`

Por último, alterar o valor do Hold stock para 1440 minutos equivalente a 1 dia

![Woocommerce Expiracao](/img/ecommerce/woo-expiracao.png)

## 5. Como selecionar qual deverá ser o status quando um novo pedido for gerado

Por padrão quando a cobrança da Woovi é criada, o status do pedido é alterado para `Pending payment`, porém é possível configurar para qualquer status que você queira.

![Woocommerce Status do Pedido Criado](/img/ecommerce/woocommerce-status-when-create-default.png)

Basta clicar e selecionar qual status você quer que seja colocado no pedido quando a cobrança da Woovi for criada.

Após esta alteração os novos pedidos quando forem criados irão receber o valor desse campo em seu status.

## 6. Como selecionar qual deverá ser o status quando um pedido for pago

Por padrão quando a cobrança da Woovi é paga, o status do pedido é alterado para `Processing`, porém é possível configurar para qualquer status que você queira.

![Woocommerce Status do Pedido Pago](/img/ecommerce/woocommerce-status-when-paid-default.png)

Basta clicar e selecionar qual status você quer que seja colocado no pedido quando a transação Pix for paga.

Após esta alteração os novos pedidos quando forem pagos irão receber o valor desse campo em seu status.

## 7. Como ver meus logs Woovi em minha loja WooCommerce/Wordpress

Você pode visualizar os logs Woovi em sua loja através dos seguintes passos:

- 1. Tenha acesso aos arquivos da loja
- 2. Acesse o seguinte path: `/wp-content/uploads/wc_logs`
- 3. Dentro de `wc_logs` você irá encontrar os arquivos de logs da woovi.com o seguinte padrão de nome `woocommerce_openpix-2023-01-13-7d609d821235742dd8162bbb0ef84862`

---

## Redirecionando o usuário no plugin WooCommerce

Quando um usuário efetua o pagamento de uma cobrança durante a finalização do pedido, é possível redirecioná-lo para outra página.

Para fazer isso, acesse as configurações do plugin e altere a URL de redirecionamento.

![Configurações da URL de redirecionamento](/img/ecommerce/woocommerce/woocommerce-redirect-url-setting.png)

Após o usuário efetuar o pagamento da cobrança, ele será redirecionado para a URL configurada.

A URL irá conter os seguintes parâmetros:

- `order_id`: Identificação do pedido do WooCommerce.
- `correlationID`: Ao utilizar esta variável, será colocado no lugar o [CorrelationID](../../concepts/correlation-id.md) da cobrança será passado na URL e, com esse identificador, você poderá manipular qual é a cobrança em questão utilizando nossas [APIs](/api).
- `key`: Chave do pedido (_order key_) do WooCommerce.

Por exemplo, se você configurou a URL de redirecionamento como `https://example.com/thank-you`, a URL final será `https://example.com/thank-you?order_id=identificacao-do-pedido&key=chave-do-pedido&correlationID=correlationID-do-pedido`.

Para obter uma cobrança usando o `correlationID`, você pode utilizar a nossa [API](/api#tag/charge/GET/api/v1/charge/{id}) de cobranças.

---

## Integrando a Woovi com WooCommerce Subscriptions

## Resumo

Este documento detalha os passos necessários para utilizar a Woovi junto ao plugin WooCommerce Subscriptions em sua plataforma de e-Commerce, baseada no WooCommerce. A plataforma Woovi efetua em tempo real a conciliação entre seu Banco e seu e-Commerce.

Após configurar o plugin Woovi, será possível cobrar clientes recorrentemente com QrCodes Pix, enviar Links de Pagamento, gerenciar cobranças incluindo extornos.

> _Nota: Este documento espera que você já tenha um ambiente WooCommerce ativo e já possua o WooCommerce Subscriptions instalado._

## 1. Instale e configure o Plugin Woovi

Siga nossa documentação para instalar e configurar o Plugin Woovi: [Integrando a Woovi com WooCommerce](./woocommerce-plugin.mdx)

## 2. Ative o plugin WooCommerce Subscriptions

Entre em **Plugins** na barra lateral, procure pelo plugin WooCommerce Subscriptions e clique em **Ativar**.

![Ativando o plugin](/img/ecommerce/woocommerce/woocommerce-subscriptions-activation.png)

_Plugins -> WooCommerce Subscriptions -> Ativar_

## 3. Configure o WooCommerce Subscriptions para aceitar pagamentos com Pix

### 3.1. Abrindo as configurações

Na mesma tela, clique em **Configurações** no plugin WooCommerce Subscriptions ou, na barra lateral, vá até **WooCommerce**, clique em **Configurações** e vá até **Assinaturas** no menu superior.

![Botão de configurações no plugin](/img/ecommerce/woocommerce/woocommerce-subscriptions-plugin-settings.png)

![Configurações do plugin](/img/ecommerce/woocommerce/woocommerce-subscriptions-settings.png)

_WooCommerce -> Configurações -> Assinaturas_

### 3.2. Ativando as renovações manuais

No menu **Assinaturas**, desça até a seção de **Renovações** e ative a opção **Aceitar renovações manuais**

![Ativando as renovações manuais](/img/ecommerce/woocommerce/woocommerce-subscriptions-manual-renewals.png)

_Assinaturas -> Renovações -> Aceitar renovações manuais_

## 4. Crie uma nova assinatura

Para criar uma nova assinatura, vá em **Produtos**, na barra lateral, e clique em **Adicionar novo**.

Adicione as informações sobre a assinatura e então desça até a seção **Dados do produto** e selecione **Assinatura simples**.

![Criando uma nova assinatura](/img/ecommerce/woocommerce/woocommerce-subscriptions-product.png)

_Produtos -> Adicionar novo -> Dados do produto -> Assinatura simples_

---

## Intro

A plataforma woovi oferece diversos relatórios para serem baixados e auxiliar em suas tarefas. Veja abaixo como acessar seus relatórios.

## Como acessar meus relatórios baixados
1. Para acessar seu export acesse `Minha Conta` clicando em seu nome no header no lado direito
![export my account button](./__assets__/export-my-account.png)
2. Em minha conta acesse a **Tab** `Exportações`
3. Faça Download das Exportações desejadas
   ![exports tabs](./__assets__/export-tab.png)

---

## Bancos

### Meu banco não consegue ler o QR Code

Alguns bancos podem apresentar instabilidades para realizar pagamentos Pix pelo QR Code.

Caso isso ocorra recomendamos que o cliente acione o suporte do seu banco.

---

## Cobranças

### O que é uma cobrança?

Uma cobrança é uma solicitação de pagamento pelo Pix. Você pode configurar uma nova cobrança com as informações de `Cliente`, `Valor`, `Comentário` e outras informações de identificação.

### Como criar uma cobrança?

Para criar uma nova cobrança, acesse o menu `Cobranças`

![Menu Charge](/img/FAQ/charge-menu.png)

Clique em `Nova cobrança`

![New Charge](/img/FAQ/new-charge.png)

Você pode configurar a cobrança da forma que precisa.

![Charge](/img/FAQ/charge.png)

### Como definir o tempo de expiração de uma cobrança?

A configuração de expiração das cobranças pode ser configurado no menu `Ajustes`

![Menu Settings](/img/FAQ/settings-menu.png)

Na aba `Pix`

![Settings Pix](/img/FAQ/settings-pix.png)

Identifique o card `Tempo de Expiração` e configure da forma que deseja.

![Expiration Time](/img/FAQ/expiration-time.png)

### Como compartilhar uma cobrança?

A melhor forma de compartilhar uma cobrança é enviando o link de pagamento para o seu cliente.

Você pode compartilhar esse link na nossa plataforma das seguintes formas:

#### Enviando o Link de Pagamento através de um e-mail

![Share Link Email](/img/FAQ/paymentLink-email.png)

![Share Link Email Detail](/img/FAQ/charge-email.png)

#### Enviando o Link de Pagamento

![Share Link](/img/FAQ/paymentLink.png)

#### Enviando o Link de Pagamento através do WhatsApp

![Share Link WhatsApp](/img/FAQ/paymentLink-wpp.png)

![Share Link WhatsApp Detail](/img/FAQ/charge-wpp.png)

### Como pagar uma cobrança?

Você pode pagar de várias maneiras uma cobrança em nossa plataforma, como:

- Copiando o código do QR Code da cobrança e realizando o pagamento via Pix copia e cola

![QR Code Copy Paste](/img/FAQ/charge-copy-paste.png)

Exemplo de um código de QR Code:

    00020101021226990014br.gov.bcb.pix2577pix-h.bpp.com.br/23114447/qrs1/v2/01PFfypmDzCtFVaRhbq7l3DFonudYpTCNT48PBM6uOS520400005303986540510.005802BR5909User_Pix6009Sao_Paulo62290505e51a840039e14d8cabbed01be64052EFA

- Enviando o link de pagamento para o seu cliente como vimos no tópico anterior

### O que é um link de pagamento e como funciona?

O link de pagamento como o nome diz é um endereço de pagamento que você pode usar para enviar uma cobrança aos seus determinados clientes e realizar o pagamento do mesmo.

![Payment Lik](/img/FAQ/payment-link.png)

- Para realizar o pagamento, você pode escanear o QR code usando o seu aplicativo de pagamento preferido.
- Ou copiar o QR Code e colar no seu aplicativo de pagamento preferido.

---

## CloudFlare

### Não estou conseguindo cadastrar meu Webhook ?

- Crie uma regra de excessão de firewall
- Se a regra não funcionar, desative a proteção antibots

## Regra de excessão de firewall

Exemplo de regra de excessão de firewall:

![CloudFlare Regra de firewall](/img/cloudflare/cloudflare_regra_firewall.png)

## Desabilitar Cloudflare Bot

A solução de antibot da Cloudflare pode bloquear os requests de Webhooks. 

Para desabilitar a proteção antibot siga os passos abaixo:

1. clique no seu dominio
2. Na Sidebar lateral procure por Security e clique, em seguida escolha o item Bots no menu:

![cloudflare sidebar security example](./__assets__/cloudflare-sidebar.png)

4. Em Bots clique em `Configure Super Bot Fight Mode`

![cloudflare bots home](./__assets__/cloudflare-bots.png)

5. Procure por Definitely Automated e Verified Bots, atualize os valores de ambos para Allow

![cloudflare bots options](./__assets__/cloudflare-bots-options.png)

6. Realize um teste e veja se esta funcionando normalmente

[https://www.cloudflare.com/products/bot-management/](https://www.cloudflare.com/products/bot-management/)

---

## Flagship

### O que é a Flagship?

Flagship é a nossa instituição financeira parceira. Por meio da Flagship podemos ter acesso a criação de contas virtuais e a rede de pagamentos Pix.

A Flagship é devidamente autorizada pelo Banco Central, e segue todas as regras de segurança do sistema bancário brasileiro.

**FLAGSHIP INSTITUIÇÃO DE PAGAMENTOS LTDA**

**CNPJ: 23.114.447/0001-97**

Para pesquisar sobre a Flagship direto no site do Banco Central, acesse: https://www.bcb.gov.br/estabilidadefinanceira/encontreinstituicao

---

## Políticas gerais

### Por que não posso abrir uma conta?

Não aceitamos empresas ou instituições envolvidas com as seguintes atividade:

- Rifas, apostas e jogos de azar;
- Drogas ilícitas;
- Armas de fogo;
- Produtos falsificados;
- Pornografia e conteúdo adulto;
- Violação de direitos autorais e ou propriedade intelectual.

Caso o seu pedido de abertura de conta tenha sido reprovado e você acredita que a sua empresa atua em norma com as nossas políticas entre em contato com o suporte.

---

## QrCode-Magento1

### O QR Code não aparece no checkout Magento1

Caso você possua um checkout personalizado em sua loja Magento, pode ser que o QR Code não apareça no checkout. Isso por que nossos arquivos ficam nas pastas padrões do Magento e o checkout personalizado em outra.

Para corrigir isso, você precisa copiar os arquivos da pasta
`app/design/frontend/base/default/template/openpix/*` e da pasta `app/design/frontend/base/default/layout/openpix/*` para a pasta em que está o seu checkout personalizado ex: `app/design/frontend/layout-personalizado/template/openpix/*` e `app/design/frontend/layout-personalizado/layout/openpix/*`.

---

## Pix QRCode Estático

### O que é um Pix QRCode estático?

O QR Code estático permite que você receba diversos pagamentos via Pix no mesmo QR Code. Ideal para utilização em LIVES e ambientes físicos.

Você pode configurar esse QR Code com um valor de pagamento pré-definido ou deixar livre para o cliente preencher o valor.

### Como criar um QR Code estático?

1. No menu, acesse a opção `QR Code`

![Menu QRCode](/img/FAQ/QrCode-menu.png)

2. E clique em `Criar QR Code`

![Create QRCode](/img/FAQ/QrCode-btn.png)

3. Defina o nome do QR Code

![Name QRCode](/img/FAQ/QrCode-name.png)

4. Defina se o QrCode será estático tendo sempre o mesmo valor ou então Impresso, podendo ter seu valor alterado de acordo com o valor do Pix

![Static QRCode](/img/FAQ/QrCode-static.png)

5. Configure as definições de valor

![Value QRCode](/img/FAQ/QrCode-value.png)

6. Caso deseje, adicione um comentário ao QR Code, exemplo: data de validade, campanha de vendas, etc.

![Value Comment](/img/FAQ/QrCode-comment.png)

Após a configuração clique em `Salvar`.

---

## Planos de preço da plataforma

## Quais são os planos disponíveis?

A plataforma oferece dois planos principais: o Plano Essencial e o Plano Integrado.

O Plano Essencial cobra uma taxa fixa por transação.
O Plano Integrado cobra uma taxa percentual sobre a transação.

Você pode ver os valores de cada plano [nessa página.](https://woovi.com.br/pricing/)

## Como são cobradas as taxas?

Sempre que você recebe um pagamento, as taxas do plano escolhido são automaticamente descontadas. Ao final do mês, enviamos a nota fiscal com o total das taxas cobradas.

As demais taxas da plataforma também seguem essa mesma mecânica: são cobradas conforme o uso.

## Como posso alterar o plano da minha empresa?

Para visualizar detalhes e valores de cada plano, visite a página "[Planos](https://woovi.com.br/pricing/)".

Para fazer a alteração do seu plano na plataforma, siga o passo a passo:

- Acesse o menu "Ajustes".
- Escolha "Meu Plano".
- Selecione o plano de sua preferência.

Ao alterar o plano, as novas taxas serão aplicadas nas futuras cobranças e afetarão todas as contas da empresa.

---

## SSL/TLS

## Versão do SSL/TLS

As APIs da Woovi usam HTTPS seguindo os critérios de segurança.

Para que sua aplicação ou e-commerce consiga consumir as APIs da Woovi, ela precisa suportar no mínimo TLS 1.2, sendo o recomenado o TLS 1.3

## Onde eu verifico qual versão meu site está usando?

Para verificar a versão do seu site, você pode usar o site [SSL Labs](https://www.ssllabs.com/ssltest/analyze.html)

![TLS](/img/tls.png)

---

## Transações

### O que é uma transação?

Uma transação representa qualquer movimentação financeira via pix na plataforma.

Para acessá-las, selecione o menu `Transações`.

![Menu Transactions](/img/FAQ/transactions-menu.png)

### O que é um Pix avulso?

É uma transação enviada diretamente para a sua chave Pix sem uma cobrança ou um qrcode estático previamente veiculado.

Exemplo: um cliente transfere um valor para a chave Pix da sua empresa, ao invés de ler o QR code da cobrança.

### Pix avulso é cobrado?

Sim, caso o cliente realize um Pix avulso para a chave aleatória da sua conta virtual Woovi haverá cobrança da taxa de R$ 0,50.

### Como localizar uma transação?

A melhor forma de localizar uma transação Pix é pelo endToEndId.

Basta pesquisar em `Transações` o endToEndId da transação que deseja encontrar.

![endToEndId](/img/FAQ/endToEndId.png)

O cliente final pode encontrar essa informação no comprovante de pagamento.

### O que é um endToEndId?

É um código identificador único que toda transação Pix possui. Normalmente essa informação está presente no comprovante de pagamento disponibilizado por todos os bancos.

Ele é gerado automaticamente pelo Pix(Bacen) e é único para cada transação.

Exemplo de um endToEndId que é mostrado no detalhe de uma transação:

![endToEndId Detail](/img/FAQ/endToEndId-detail.png)

### Onde encontrar o endToEndId no comprovante do banco?

Exemplo de um endToEndId que é mostrado no comprovante de pagamento:

![endToEndId Pag](/img/FAQ/pag-endToEndId.png)

Geralmente o endToEndId inicia com a letra maiscula `E`.

### Posso reembolsar uma transação?

Sim, você pode reembolsar totalmente uma transação dentro da plataforma em até 90 dias.

Basta ir em `Transações`

![Menu Transactions](/img/FAQ/transactions-menu.png)

Buscar pela transação que deseja reembolsar

![Transactions](/img/FAQ/transactions.png)

E clicar no botão `Reembolsar`

![Transactions detail](/img/FAQ/transaction-detail.png)

Depois confirmar o endToEndId da transação digitando os últimos 4 caracteres do endToEndId.

![Refund transactions](/img/FAQ/refund.png)

Lembre-se, após a conclusão o reembolso não pode ser desfeito.

### Como reprocessar os webhooks de uma transação?
Você pode reprocessar os webhooks de uma transação indo até o detalhe da mesma e disparando via o botão `Reenviar Webhook`. 

Você encontrará o botão logo abaixo da tabela `Webhooks` conforme imagem abaixo.

![Webhooks transactions](/img/FAQ/transaction_webhooks.png)

### Como ver os logs de um webhook de uma transação?
Clicando em cima de uma linha da tabela de webhooks você pode ver os logs do especifico webhook selecionado.

![Webhooks transactions log](/img/FAQ/transaction_webhooks_log.png)

### O que é o `type` de uma transação?

O valor do `type` serve para indicar qual é o tipo daquela transação. Assim
sendo, atualmente ela pode conter um dos respectivos tipos:

- `PAYMENT`: Indica que a transação é um pagamento.
- `WITHDRAW`: Indica que a transação é um saque.

---

## Usuários

A Woovi possui todas as ferramentas necessárias para gerenciar os usuários dentro da sua plataforma. Aqui você pode encontrar as principais dúvidas referente ao assunto.

## Permissões
Permissões possibilitam o gerenciamento de usuários em relação as atividades dentro da Woovi.

### Como gerenciar as permissões dos usuários
Os usuários dentro da plataforma Woovi podem possuir permissões individuais ou grupos de permissões. Permitindo assim o fácil gerenciamento tanto particular quanto em grupo dos mesmos.

Para editar as permissões de um usuário basta:

- Clicar em Permissões no menu lateral ![Permission Sidebar](/img/FAQ/users/users_permission_sidebar.png)
- Será exibida a lista de usuários. Clique no que deseja editar as permissões
  ![Users List](/img/FAQ/users/users_list.png)
- Dentro do detalhe do usuário possuirá as abas: permissões e grupo de permissões
  ![Users Detail](/img/FAQ/users/users_detail.png)
- Para setar uma permissão especifica para o usuário basta acessar a aba `Permissões`
- Para setar um grupo de permissão basta acessar a aba Grupo de Permissões

---

## Conta Virtual

### O que é a conta virtual?

A conta virtual funciona como uma conta transacional, ela facilita a criação de cobranças, a liquidação de Pix e as integrações da plataforma.

Por meio dessa conta virtual geramos uma chave Pix aleatória em nome da sua empresa, essa chave é utilizada em todas as cobranças da plataforma.

### Por que preciso ativar uma conta virtual?

Os grandes bancos e fintechs possuem diferentes formas de processamento das cobranças dinâmicas do Pix, para normalizar e facilitar todo o processo de cobranças criamos a nossa própria conta virtual.

Todo o saldo gerado pela conta virtual é direcionado para a chave Pix CNPJ da sua empresa, e por consequência para a conta bancária que essa chave Pix está veiculada.

### Como abrir uma conta virtual?

Na plataforma, acesse o menu `Contas`

![Menu Accounts](/img/FAQ/accounts-menu.png)

Clique em `Criar Conta Agora`.

![Active Account](/img/FAQ/activate-account.png)

Você será redirecionado para página de ativação da conta virtual.

![Active Account](/img/FAQ/active-account.png)

Basta aceitar os Termos e Condições da conta virtual e clicar em `Solicitar a ativação`.

![Active Account Step 2](/img/FAQ/active-account-2.png)

Em até 48h iremos verificar a os seus dados e realizar a abertura da conta virtual.

### Qual a taxa da conta virtual?

#### Plano Integrado:

| Item              | Valor                                                                  |
| ----------------- | ---------------------------------------------------------------------- |
| Pix Comum         | 0,8% - Por Pix recebido (tarifa mínima de R$ 0,50 e máxima de R$ 5,00) |
| Saque             | R$ 1,00 - Por Saque (Saques a partir de R$ 500,00 são gratuitos.)      |
| Mensalidade       | Grátis                                                                 |
| Reembolso         | Grátis                                                                 |
| Reembolso Parcial | Grátis                                                                 |

#### Plano Avançado:

Caso sua operação possua um grande volume de transações entre em contato com nosso time para a definição de um plano personalizado.

### Onde posso consultar as taxas da minha conta virtual?

Na plataforma, acesse o menu `Contas`

![Menu Accounts](/img/FAQ/accounts-menu.png)

Selecione a Conta Woovi.

![Openix Account](/img/FAQ/account-list.png)

Dentro da página de `Detalhes da Conta` você pode acompanhar as `Taxas` aplicadas na sua conta.

![Account Details](/img/FAQ/account-detail.png)

---

## Saques

### O que é um saque?

Os saques são transações de depósitos realizadas entre a conta virtual e a sua chave Pix CNPJ.

Após realizar um saque você pode movimentar livremente o dinheiro da sua empresa na conta bancária vinculada a sua chave Pix CNPJ.

### Quanto tempo leva para concluir um saque?

Os saques da plataforma são instantâneos pelo Pix. 24 horas por dia, 7 dias por semana.

### Como fazer um saque?

1 - Na plataforma, clique no menu `Contas`;

![Menu Accounts](/img/FAQ/accounts-menu.png)

2 - Selecionar a conta virtual Woovi;

![Openix Account](/img/FAQ/account-openpix.png)

3- Clique no botão `Sacar`;

![Withdraw](/img/FAQ/withdraw-modal.png)

Todo saldo gerado pelas cobranças é depositado de maneira automática, todos os dias às 19h, na conta bancária vinculada a Chave Pix do seu CNPJ.

Você pode solicitar o saque manual a qualquer momento, nesse caso, se a solicitação de saque for inferior a R$ 1.000,00 será cobrada uma taxa de R$ 1,00 por saque.

### Saque automático

![Saque automatico config exemplo](https://github.com/Open-Pix/openpix-developers/assets/19939822/570639e4-a5b3-41b2-9986-249a1d0f8104)

O saque automático é grátis para valores iguais ou maiores do que R$ 500 e é realizado todo dia as 19h.

:::info
O valor mínimo de saque é configurado nos ajustes da conta transactional dentro da plataforma. Por padrão esse valor é de R$ 500,00. Saques acima R$ 500,00 são gratuitos.
:::

### Quais os limites de saque?

- Saque mínimo: R$ 1,01
- Saque máximo: Sem limite

Os saques da plataforma são instantâneos pelo Pix. 24 horas por dia, 7 dias por semana.

### Posso mudar a minha chave Pix de saque?

Não, por razões de segurança os saques só podem ser realizados na chave Pix do seu CNPJ, por consequência os valores são depositados na conta bancária que a sua chave Pix CNPJ está vinculada.

### Realizei o saque mas o valor não está na minha conta bancária?

Toda solicitação de saque é depositada na chave Pix CNPJ da sua empresa, e por consequência na conta bancária que essa chave está veiculada.

Verifique se a conta bancária que você consultou é a conta que possui o registro da sua chave Pix CNPJ.

Você, ou alguém da sua empresa pode ter solicitado a mudança e o valor foi depositado em outra conta.

Se esse não for o caso, entre em contato com o nosso suporte.

### Reserva de Segurança

Conforme as normas do Banco Central precisamos manter uma porcentagem do saldo total como reserva de segurança para reembolsos em casos de fraude. Clique aqui [https://www.bcb.gov.br/detalhenoticia/17417/nota](https://www.bcb.gov.br/detalhenoticia/17417/nota) e saiba mais.

---

## Começando Campanha Usando Chave Pix(Flows)

### Como começar uma nova campanha?
- Crie uma nova conta bancária usando o AppID da conta principal.
- Armazene o accountId retornado pela requisição de criação de conta bancária.
- Crie uma nova aplicação utilizando o accountId retornado na última requisição.
- Armazene o AppID relacionado a essa conta. Você usará ele para pegar o saldo de uma campanha.
- Crie uma nova chave pix utilizando o AppID da conta que deseja.
- Cada conta bancária tem um saldo, então é recomendado que crie uma nova conta bancária para cada campanha.

### 1. Criando uma conta bancária

- Utilize o endpoint de criação de conta bancária para criar uma nova conta.
- Utilize o AppID da conta principal, o criado no slide 7.
- Faça a requisição.

```json
curl -X POST "https://api.woovi.com/api/v1/account" \
  -H "Authorization: {APP_ID}" \
  -H "Content-Type: application/json" 
```
- Caso tudo ocorra corretamente, um código 200 será retornado.
- No corpo da resposta terá:

```json
{
  "account": {
    "accountId": "6840aeca23c0d1fe48c856a3",
    "taxId": "12.345.678/0001-90",
    "isDefault": true,
    "balance": {
      "total": 0,
      "blocked": 0,
      "available": 0
    }
  }
}
```

### 2. Criando uma Aplicação

- Utilize o endpoint de criação de aplicação.
- A aplicação será a chave que será utilizada para acessar os dados de uma conta bancária específica.
- Utilize o AppID retornado pelo último endpoint, para relacioná-lo com a nova conta bancária.

```json
curl -X POST "https://api.woovi.com/api/v1/application" \
  -H "Authorization: {{BANK_ACCOUNT_APP_ID}}" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "{{ACCOUNT_ID}}",
    "application": {
      "name": "My Test Application",
      "type": "API"
    }
  }'
```

- O retorno do endpoint de criação de uma aplicação, se tudo ocorrer bem, será um código 201.
- No corpo da resposta conterá:
```json
{
  "application": {
    "name": "My Test Application",
    "isActive": true,
    "type": "API",
    "clientId": "client_123abc",
    "clientSecret": "secret_456def",
    "appID": {{APPLICATION_APP_ID}},
    "companyBankAccount": "{{ACCOUNT_ID}}"
  }
}
```

### 3. Criando uma Chave Pix

- Utilize o endpoint de criação de chave pix.
- Utilize o AppID retornado pelo último endpoint, para criar a chave pix naquela conta específica.

```json
curl -X POST "https://api.woovi.com/api/v1/pix-keys" \
  -H "Authorization: {{APPLICATION_APP_ID}}" \
  -H "Content-Type: application/json" \
  -d '{
    "pixKey": "campanha@woovi.com",
    "type": "EMAIL"
  }'
```

- Se tudo ocorrer bem, o código de retorno será 201.
- O retorno serão os dados daquela chave pix criada.
```json
{
  "pixKey": {
    "key": "campanha@woovi.com",
    "type": "EMAIL"
  }
}
```
- Com esse fluxo, já será possível criar novas campanhas com suas respectivas chaves pix.
- Ainda temos endpoints que permitem a visualização do saldo, as informações de uma conta e as chaves pix atreladas a ela.

### 4. Consultando Chaves Pix

- Utilize o AppID da conta bancária que você quer consultar.
```json
curl -X GET "https://api.woovi.com/api/v1/pix-keys" \
  -H "Authorization: {{APPLICATION_APP_ID}}"
```

- O retorno terá status 200.
- O corpo da resposta será:
```json
{
  "pixKeys": [
    {
      "key": "teste-woovi@woovi.com",
      "type": "EMAIL"
    },
    {
      "key": "random-evp-key",
      "type": "EVP"
    }
  ],
  "account": {
    "accountId": "6840aeca23c0d1fe48c856a3",
    "isDefault": true,
    "balance": {
      "total": 100000,
      "blocked": 0,
      "available": 100000
    }
  }
}
```

### 5. Deletando Chaves Pix
- Caso uma campanha chegue ao fim, apagar a chave pix garantirá que nenhum dinheiro seja mandado a ela novamente.
- Existe um endpoint que permite que uma chave pix seja deletada.
- Utilize o AppID da conta que está atrelada a chave pix.
- O retorno será um código 204, se tudo ocorrer bem.

```json
curl -X DELETE "https://api.woovi.com/api/v1/pix-keys/{{PIX_KEY_VALUE}}" \
  -H "Authorization: {{APPLICATION_APP_ID}}"
```

---

## Máquina de estado de uma Cobrança

## Diagrama de estados da cobrança

- Veja abaixo o diagrama de estados de uma cobrança:

![Charge Diagram](/img/flows/charge-flow.png)

## Status da cobrança

- `ACTIVE`: A cobrança está ativa e ainda não foi paga.
- `COMPLETED`: A cobrança foi paga.
- `EXPIRED`: O tempo de pagamento da cobrança expirou.

---

## Códigos de Erro de Pagamento PIX


Quando um pagamento PIX falha, o webhook `MOVEMENT_FAILED` retorna informações sobre o erro através dos campos `providerRejectedReason` e `providerErrorCode`. Abaixo estão todos os possíveis códigos de erro que podem ser retornados, com suas descrições detalhadas e informações sobre qual participante gera cada erro.

## Tabela Completa de Códigos de Erro

| Código | Nome do Erro | Descrição Detalhada | Participante que Gera o Erro |
|--------|--------------|---------------------|------------------------------|
| AB03 | Liquidação Abortada por Timeout | Liquidação da transação interrompida devido a timeout no SPI | Sistema de Pagamentos Instantâneos (SPI) |
| AB09 | Erro no Agente Credor | Transação interrompida devido a erro no participante do usuário recebedor | Banco recebedor (Woovi) |
| AB11 | Timeout do Agente Devedor | Timeout do participante emissor da ordem de pagamento | Sistema de Pagamentos Instantâneos (SPI) |
| AC03 | Número da Conta do Credor Inválido | Número da agência e/ou conta transacional do usuário recebedor inexistente ou inválido | Banco recebedor (Woovi) |
| AC06 | Conta Bloqueada | Conta transacional do usuário recebedor encontra-se bloqueada | Banco recebedor (Woovi) |
| AC07 | Conta do Credor Encerrada | Número da conta transacional do usuário recebedor encerrada | Banco recebedor (Woovi) |
| AC14 | Tipo de Conta do Credor Inválido | Tipo incorreto para a conta transacional do usuário recebedor | Banco recebedor (Woovi) |
| AG03 | Transação Não Suportada | Tipo de transação não é suportado/autorizado na conta transacional do usuário recebedor. Exemplo: transferência para conta salário | Banco recebedor (Woovi) |
| AG12 | Transferência Interna Não Permitida | Não é permitida ordem de pagamento/devolução no SPI cujos recursos sejam transferidos de uma conta transacional para outra em uma mesma instituição participante ou entre participantes que utilizem o serviço de liquidação de um mesmo participante liquidante no SPI (booktransfer) | Sistema de Pagamentos Instantâneos (SPI) |
| AG13 | Devolução de Retorno Proibida | Não é permitido devolver a devolução de um pagamento instantâneo | Sistema de Pagamentos Instantâneos (SPI) |
| AGNT | Agente Incorreto | Participante direto não é liquidante do participante do usuário pagador | Sistema de Pagamentos Instantâneos (SPI) |
| AM01 | Valor Zero | Ordem de pagamento instantâneo com valor zero | Sistema de Pagamentos Instantâneos (SPI) |
| AM02 | Valor Não Permitido | Ordem de pagamento/devolução em valor que faz superar o limite permitido para o tipo de conta transacional creditada | Banco recebedor (Woovi) |
| AM04 | Fundos Insuficientes | Saldo insuficiente na conta PI do participante do usuário pagador | Sistema de Pagamentos Instantâneos (SPI) |
| AM09 | Valor Incorreto | Devolução de pagamento em valor que faz superar o valor da ordem de pagamento instantâneo correspondente | Banco recebedor (Woovi) |
| AM12 | Valor Inválido | Divergência entre a somatória dos valores do bloco valorDoDinheiroOuCompra e o campo valor | Sistema de Pagamentos Instantâneos (SPI) |
| AM18 | Número de Transações Inválido | Quantidade de transações inválida | Sistema de Pagamentos Instantâneos (SPI) |
| BE01 | Inconsistência com Cliente Final | CPF/CNPJ do usuário recebedor não é consistente com o titular da conta transacional especificada | Banco recebedor (Woovi) |
| BE05 | Parte Iniciadora Não Reconhecida | CNPJ do iniciador de pagamento não se encontra cadastrado no arranjo Pix | Sistema de Pagamentos Instantâneos (SPI) |
| BE15 | Código de Identificação Inválido | Preenchimento incorreto do campo idConciliacaoRecebedor | Banco recebedor (Woovi) |
| BE17 | Código de Identificação do Credor Inválido | QR Code rejeitado pelo participante do usuário recebedor | Banco recebedor (Woovi) |
| CH11 | Identificador do Credor Incorreto | CPF/CNPJ do usuário recebedor incorreto | Banco recebedor (Woovi) |
| CH16 | Conteúdo Formalmente Incorreto | Preenchimento do conteúdo da mensagem incorreto ou incompatível com as regras de negócio | Sistema de Pagamentos Instantâneos (SPI) |
| CN01 | Autorização Cancelada | Agendamento de pagamento recorrente cancelado com statusDoCancelamento igual a "ACCR (confirmado)" | Banco recebedor (Woovi) |
| DS04 | Ordem Rejeitada | Ordem rejeitada pelo participante do usuário recebedor | Banco recebedor (Woovi) |
| DS0G | Pagamento Não Permitido | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada. No caso em que o participante que assinou a mensagem não é o titular da conta PI debitada nem é o liquidante no SPI do participante do usuário pagador | Sistema de Pagamentos Instantâneos (SPI) |
| DS27 | Usuário Ainda Não Ativado | Participante não se encontra cadastrado ou ainda não iniciou a operação no SPI | Sistema de Pagamentos Instantâneos (SPI) |
| DT02 | Data de Criação Inválida | Data e Hora do envio da mensagem inválida | Sistema de Pagamentos Instantâneos (SPI) |
| DT05 | Data de Corte Inválida | Transação extrapola o prazo máximo para devolução de pagamento instantâneo regulamentado pelo arranjo Pix | Sistema de Pagamentos Instantâneos (SPI) |
| DUPL | Pagamento Duplicado | Pagamento efetuado em duplicidade nos casos em que as ordens de pagamento possuem IdConciliacaoDoRecebedor iguais para um mesmo usuário recebedor. É permitido que duas cobranças tenham o mesmo IdConciliacaoDoRecebedor desde que correspondam a usuários recebedores diferentes | Banco recebedor (Woovi) |
| ED05 | Falha na Liquidação | Erro no processamento do pagamento instantâneo (erro genérico) | Sistema de Pagamentos Instantâneos (SPI) / Banco recebedor (Woovi) |
| FF07 | Finalidade Inválida | Inconsistência entre a finalidade da transação e o preenchimento do bloco elementos Structured `<Strd>` | Sistema de Pagamentos Instantâneos (SPI) |
| FF08 | EndToEndId Inválido | Identificador da operação mal formatado | Sistema de Pagamentos Instantâneos (SPI) |
| FRAD | Origem Fraudulenta | Ordem de pagamento rejeitada por fundada suspeita de fraude | Banco recebedor (Woovi) |
| MD01 | Sem Mandato | ISPB do participante facilitador de serviço Pix Saque ou Pix Troco inexistente | Sistema de Pagamentos Instantâneos (SPI) |
| RC09 | Identificador do Membro Devedor Inválido | ISPB do participante do usuário pagador inválido ou inexistente | Sistema de Pagamentos Instantâneos (SPI) |
| RC10 | Identificador do Membro Credor Inválido | ISPB do participante do usuário recebedor inválido ou inexistente | Sistema de Pagamentos Instantâneos (SPI) |
| RR04 | Motivo Regulatório | Ordem de pagamento em que o usuário pagador é sancionado por resolução do Conselho de Segurança das Nações Unidas (CSNU). Nos casos em que o usuário recebedor for o sancionado, a ordem de pagamento não deve ser rejeitada | Banco recebedor (Woovi) |
| SL02 | Serviço Específico do Agente Credor | A transação referenciada na mensagem de devolução (pacs.004) original não está relacionada aos serviços de Pix Saque ou Pix Troco | Banco recebedor (Woovi) |
| UPAY | Pagamento Indevido | Pagamento é indevido por ausência de recorrência válida/ativa | Banco recebedor (Woovi) |
## Categorias de Erro

### Erros de Liquidação (AB)
- **AB03**: Timeout durante a liquidação
- **AB09**: Erro no participante recebedor  
- **AB11**: Timeout no participante pagador

### Erros de Conta (AC)
- **AC03**: Conta inexistente ou inválida
- **AC06**: Conta bloqueada
- **AC07**: Conta encerrada
- **AC14**: Tipo de conta inválido

### Erros de Autorização (AG)
- **AG03**: Transação não suportada/autorizada
- **AG12**: Transferência não permitida (booktransfer)
- **AG13**: Devolução de devolução não permitida
- **AGNT**: Agente incorreto no fluxo

### Erros de Valor (AM)
- **AM01**: Valor zero
- **AM02**: Valor acima do limite
- **AM04**: Saldo insuficiente
- **AM09**: Valor incorreto
- **AM12**: Valor inválido
- **AM18**: Número de transações inválido

### Erros de Identificação (BE/CH)
- **BE01**: CPF/CNPJ inconsistente
- **BE05**: Iniciador não reconhecido
- **BE15**: Código de identificação inválido
- **BE17**: QR Code rejeitado
- **CH11**: CPF/CNPJ incorreto
- **CH16**: Conteúdo incorreto

### Erros de Processamento (CN/DS/DT)
- **CN01**: Autorização cancelada
- **DS04**: Ordem rejeitada
- **DS0G**: Operação não autorizada
- **DS27**: Usuário não ativado
- **DT02**: Data de criação inválida
- **DT05**: Prazo expirado

### Erros Específicos
- **DUPL**: Pagamento duplicado
- **ED05**: Falha na liquidação (genérico)
- **FF07**: Finalidade inválida
- **FF08**: EndToEndId inválido
- **FRAD**: Suspeita de fraude
- **MD01**: Mandato inexistente
- **RC09/RC10**: ISPB inválido
- **RR04**: Motivo regulatório
- **SL02**: Serviço específico
- **UPAY**: Pagamento indevido

## Exemplo de Webhook com Código de Erro Detalhado

```json
{
  "event": "OPENPIX:MOVEMENT_FAILED",
  "payment": {
    "value": 1,
    "status": "FAILED",
    "correlationID": "manual-payment-0009"
  },
  "transaction": {
    "value": 1,
    "endToEndId": "E54811417202507081527dYr4Cp2gfAp",
    "time": "2025-07-08T15:27:19.687Z",
    "providerRejectedReason": "BE17 - QR Code rejeitado pelo banco recebedor",
    "providerErrorCode": "BE17"
  }
}
```

## Observações Importantes

### Participantes que Geram Erros
- **Sistema de Pagamentos Instantâneos (SPI)**: Sistema central do Banco Central
- **Banco recebedor (Woovi)**: Instituição financeira que recebe o pagamento
- **Participante do usuário pagador**: Instituição financeira que envia o pagamento

### Campos de Retorno
- **`providerErrorCode`**: Contém apenas o código (ex: "BE17")
- **`providerRejectedReason`**: Contém o código e a descrição detalhada (ex: "BE17 - QR Code rejeitado pelo banco recebedor")

---

## Criando uma Cobrança usando API

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Você pode gerar novas Cobranças Pix usando a API Woovi em seu backend ou frontend

```jsx
curl --location --request POST 'https://api.woovi.com/api/openpix/v1/charge' \
--header 'Content-Type: application/json' \
--header 'Authorization: <appID>' \
--data-raw '{
    "correlationID": "8a4a4168-a877-4494-9d8d-eba2d4435e97",
    "value": "1",
    "comment": "my first pix charge",
    "customer": {
        "name": "Bob",
        "email": "bob@woovi.com",
        "phone": "5511940468888",
        "taxID": "471.737.080-52"
    }
}'
```

```jsx
const createCharge = async () => {
  const payload = {
    correlationID: '8a4a4168-a877-4494-9d8d-eba2d4435e97', // our system id
    value: 1, // 1 cent
    comment: 'my first pix',
    customer: {
      name: 'Bob',
      email: 'bob@woovi.com',
      taxID: '471.737.080-52',
      phone: '5511940468888'
    }
  }

  const response = await fetch('https://api.woovi.com/api/openpix/v1/charge', {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      'Content-Type': 'application/json',
      Authorization: 'appID',
    },
    body: JSON.stringify(payload),
  });
  const data = await response.json();
  console.log({
    data,
  });
}
```

## Descrição do Paylod

- **correlationID**: seu ID para controlar a cobrança
- **value**: valor da cobrança em centavos
- **comment**: comentário a ser mostrado no QRCode enquanto o cliente está pagando a cobrança
- **customer**: o cliente dessa cobrança
- **customer.name**: nome do cliente
- **customer.email**: email do cliente
- **customer.taxID**: CPF/CNPJ do cliente
- **customer.phone**: telefone do cliente

---

## Como configurar o tempo de expiração da Woovi Charge

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

A cobrança da Woovi tem um valor de expiração padrão equivalente a 1 mês, mas você pode alterar esse tempo de expiração ao seu caso de uso

Procure no menu Admin por `Settings` > `Pix`

![Woovi Expiracao](/img/flows/default_expiration.png)

Depois modifique o tempo de expiração da cobrança para seu caso de uso

![Woovi Edit Expiracao](/img/flows/edit-default-expiration.png)

---

## Estatísticas de Fraude da Chave PIX

# Estatísticas de Fraude da Chave PIX ou CPF

A API de Estatísticas de Fraude da Chave PIX permite consultar estatísticas abrangentes de fraude e indicadores de risco para chaves PIX. Este endpoint fornece informações detalhadas sobre marcadores de fraude, relatórios de infração e padrões de transação associados tanto ao proprietário da chave quanto à chave PIX específica.

## Visão Geral

Esta API retorna estatísticas de fraude e indicadores de risco que ajudam instituições financeiras a avaliar o nível de risco das chaves PIX antes de processar transações. A resposta inclui duas seções principais:

- **Estatísticas do Proprietário**: Informações relacionadas ao proprietário da chave consultada
- **Estatísticas da Chave**: Informações específicas da chave PIX em si

## API Endpoint

validação de estatística de fraude por chave pix

```
GET /api/v1/fraud-validation/pix-key/{pix-key}
```

Validação de estatística de fraude por CPF/CNPJ

```
GET /api/v1/fraud-validation/taxId/{taxId}
```

**📖 [Ver documentação completa da API](/api#tag/fraudValidation)**

## Parâmetros da Requisição

| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-----------|
| `pixkey` | string | Sim | A chave PIX a ser consultada (CPF, CNPJ, email, telefone ou chave aleatória) |

## Estrutura da resposta

A resposta da API contém estatísticas abrangentes de fraude organizadas em duas seções principais:

### Estatísticas do Proprietário (`ownerStatistics`)

Informações relacionadas ao proprietário da chave PIX consultada.

#### SPI (Sistema de Pagamentos Instantâneos)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `watermark` | string | Data da última atualização dos dados |
| `settlements` | object | Liquidações/transações realizadas em diferentes períodos |
| `settlements.d90` | string | Últimos 90 dias |
| `settlements.m12` | string | Últimos 12 meses |
| `settlements.m60` | string | Últimos 60 meses (5 anos) |

#### Marcadores de Fraude (`fraudMarkers`)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `watermark` | string | Data da última atualização dos dados de fraude |
| `applicationFrauds` | object | Fraudes em aplicações/cadastros por período |
| `muleAccounts` | object | Contas identificadas como "mulas" (intermediárias para movimentação de recursos ilícitos) |
| `scammerAccounts` | object | Contas identificadas como de golpistas |
| `otherFrauds` | object | Outros tipos de fraudes não categorizadas |
| `unknownFrauds` | object | Fraudes de natureza desconhecida ou não classificada |
| `totalFraudTransactionAmount` | object | Valor total das transações fraudulentas por período |
| `distinctFraudReporters` | object | Número de diferentes instituições que reportaram fraudes |

#### Relatórios de Infração (`infractionReports`)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `watermark` | string | Data da última atualização dos dados de infração |
| `openReports` | string | Número de relatórios de infração em aberto |
| `openReportsDistinctReporters` | string | Número de diferentes instituições que têm relatórios abertos |
| `rejectedReports` | object | Relatórios rejeitados nos períodos especificados |

#### Entradas (`entries`)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `watermark` | string | Data da última atualização dos dados de entrada |
| `registeredAccounts` | string | Número de contas registradas associadas à chave |

### Estatísticas da Chave (`keyStatistics`)

Informações específicas sobre a chave consultada.

#### SPI (Sistema de Pagamentos Instantâneos)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `watermark` | string | Data da última atualização dos dados |
| `settlements` | object | Liquidações/transações realizadas em diferentes períodos |
| `settlements.d90` | string | Últimos 90 dias |
| `settlements.m12` | string | Últimos 12 meses |
| `settlements.m60` | string | Últimos 60 meses (5 anos) |

#### Marcadores de Fraude (`fraudMarkers`)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `watermark` | string | Data da última atualização dos dados de fraude |
| `applicationFrauds` | object | Fraudes em aplicações/cadastros por período |
| `muleAccounts` | object | Contas identificadas como "mulas" |
| `scammerAccounts` | object | Contas identificadas como de golpistas |
| `otherFrauds` | object | Outros tipos de fraudes não categorizadas |
| `unknownFrauds` | object | Fraudes de natureza desconhecida |
| `totalFraudTransactionAmount` | object | Valor total das transações fraudulentas por período |
| `distinctFraudReporters` | object | Número de diferentes instituições que reportaram fraudes |

#### Relatórios de Infração (`infractionReports`)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `watermark` | string | Data da última atualização dos dados de infração |
| `openReports` | string | Número de relatórios de infração em aberto |
| `openReportsDistinctReporters` | string | Número de diferentes instituições que têm relatórios abertos |
| `rejectedReports` | object | Relatórios rejeitados nos períodos especificados |

#### Entradas (`entries`)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `watermark` | string | Data da última atualização dos dados de entrada |
| `distinctAccounts` | object | Número de contas distintas associadas à chave por período |

## Períodos de Tempo

A API utiliza os seguintes indicadores de período:

- **d90**: Últimos 90 dias
- **m12**: Últimos 12 meses
- **m60**: Últimos 60 meses (5 anos)

## Exemplo de Requisição

### cURL
```bash
curl -X GET "https://api.woovi.com/api/v1/pix-keys/12345678901/fraud-validation" \
  -H "Authorization: SEU_APP_ID_AQUI"
```

## Exemplo de Resposta

```json
{
  "success": true,
  "data": {
    "ownerStatistics": {
      "spi": {
        "watermark": "2025-04-08T10:19:11.308Z",
        "settlements": {
          "d90": "0",
          "m12": "9",
          "m60": "9"
        }
      },
      "fraudMarkers": {
        "watermark": "1970-01-01T00:00:00Z",
        "applicationFrauds": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "muleAccounts": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "scammerAccounts": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "otherFrauds": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "unknownFrauds": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "totalFraudTransactionAmount": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "distinctFraudReporters": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        }
      },
      "infractionReports": {
        "watermark": "1970-01-01T00:00:00Z",
        "openReports": "0",
        "openReportsDistinctReporters": "0",
        "rejectedReports": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        }
      },
      "entries": {
        "watermark": "2025-05-24T19:38:15.063Z",
        "registeredAccounts": "1"
      }
    },
    "keyStatistics": {
      "spi": {
        "watermark": "1970-01-01T00:00:00Z",
        "settlements": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        }
      },
      "fraudMarkers": {
        "watermark": "1970-01-01T00:00:00Z",
        "applicationFrauds": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "muleAccounts": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "scammerAccounts": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "otherFrauds": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "unknownFrauds": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "totalFraudTransactionAmount": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "distinctFraudReporters": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        }
      },
      "infractionReports": {
        "watermark": "1970-01-01T00:00:00Z",
        "openReports": "0",
        "openReportsDistinctReporters": "0",
        "rejectedReports": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        }
      },
      "entries": {
        "watermark": "2025-05-24T19:38:15.063Z",
        "distinctAccounts": {
          "d90": "0",
          "m12": "1",
          "m60": "1"
        }
      }
    }
  }
}
```

## Entendendo a Resposta

### Valores Zero
Todos os valores que mostram "0" indicam que não há registros de fraudes, infrações ou problemas associados à chave consultada.

### Datas Watermark
- **Datas recentes** (ex: "2025-04-08T10:19:11.308Z") indicam atualizações recentes de dados
- **Datas epoch** (ex: "1970-01-01T00:00:00Z") indicam que não há dados disponíveis para essa categoria

### Significado Prático
Este relatório serve como uma ferramenta de verificação de segurança e histórico financeiro para instituições financeiras avaliarem riscos antes de processar transações. Os marcadores temporais (d90, m12, m60) permitem avaliar tanto o comportamento recente quanto os padrões históricos.

## Casos de Uso

- **Avaliação de Risco**: Avaliar o nível de risco das chaves PIX antes de processar transações
- **Conformidade**: Atender aos requisitos regulatórios para prevenção de fraude
- **Due Diligence**: Realizar verificações de antecedentes dos proprietários de chaves PIX
- **Prevenção de Fraude**: Identificar chaves potencialmente arriscadas antes que causem perdas

## Tratamento de Erros

A API retornará respostas de erro apropriadas para requisições inválidas ou quando a chave PIX não for encontrada. Cenários de erro comuns incluem:

- Formato de chave PIX inválido
- Chave PIX não encontrada
- Erros de autenticação/autorização
- rate limit

---

## Validação de KYC (CPF/CNPJ)


A API de Validação de KYC recebe um CPF ou CNPJ, consulta os sinais de risco disponíveis e devolve um **veredito** — aprovado ou reprovado, com o nível de risco e os sinais que levaram à decisão.

A diferença em relação às [Estatísticas de Pessoa](/docs/flows/person-statistic) é o que você recebe: lá vêm os números crus do DICT para você interpretar; aqui vem a decisão já tomada, com os sinais agregados numa taxonomia estável.

## Visão Geral

A consulta é **assíncrona**: a criação responde `201` com `status: PROCESSING` e o veredito fica pronto em seguida (normalmente em menos de um segundo). Você lê o resultado de duas formas:

- consultando `GET /api/v1/kyc-validation/{correlationID}`; ou
- assinando os webhooks `KYC_VALIDATION_COMPLETED` e `KYC_VALIDATION_FAILED`.

Cada validação é **cobrada** como `KYC_VALIDATION_FEE`, com o valor configurado na sua conta. A cobrança acontece **antes** de a consulta ser enfileirada: se a chamada respondeu `201`, ela já foi cobrada.

## API Endpoints

Criar uma validação:

```
POST /api/v1/kyc-validation/taxid
```

Consultar o resultado:

```
GET /api/v1/kyc-validation/{correlationID}
```

**📖 [Ver documentação completa da API](https://developers.woovi.com/en/api#tag/kyc)**

## Pré-requisitos

| Requisito | Onde |
|-----------|------|
| Feature `KYC_VALIDATION` habilitada | na sua empresa (fale com o time Woovi) |
| Escopos `KYC_VALIDATION_POST` e `KYC_VALIDATION_GET` | na sua aplicação |
| Conta bancária aberta vinculada à aplicação | é ela que paga a validação |
| Taxa configurada | `kycValidationFeeSettings` na conta |

## Parâmetros da Requisição

| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-----------|
| `taxId` | string | Sim | CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita máscara — tudo que não é dígito é descartado |
| `correlationID` | string | Sim | Seu identificador único da validação (1 a 128 caracteres). É a chave de idempotência e é por ele que você lê o resultado |

## Idempotência e cobrança

O `correlationID` é a chave de idempotência:

- **`correlationID` novo** → nova validação, `201`, **cobrada**.
- **`correlationID` já usado** → devolve a validação original, `200`, **sem cobrar de novo**.

Uma tentativa depois de um `FAILED` exige um `correlationID` novo — e é uma nova cobrança.

## Estrutura da Resposta

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `correlationID` | string | O identificador que você enviou |
| `taxId` | string | O CPF/CNPJ consultado, só dígitos |
| `status` | string | `PROCESSING`, `COMPLETED` ou `FAILED` |
| `result` | string \| null | `APPROVED` ou `REJECTED`. Null enquanto `PROCESSING` e quando `FAILED` |
| `riskLevel` | string \| null | `NONE`, `LOW`, `MEDIUM` ou `HIGH`. Null enquanto `PROCESSING` e quando `FAILED` |
| `reasons` | array | Sinais que sustentam o veredito. Vazio enquanto `PROCESSING`, e vazio num `APPROVED` sem nenhum sinal |
| `createdAt` | string | Data de criação da validação |
| `completedAt` | string \| null | Data da conclusão. Null enquanto `PROCESSING` |

### Status

| Status | Significado |
|--------|-------------|
| `PROCESSING` | Aceita e enfileirada. Já foi cobrada |
| `COMPLETED` | Consulta concluída, `result` e `riskLevel` preenchidos |
| `FAILED` | Todas as fontes estavam indisponíveis, então não houve veredito. A validação **foi cobrada**; para tentar de novo use um `correlationID` novo |

### Sinais (`reasons`)

Os sinais descrevem **o que** foi observado, nunca **onde** — a lista é estável mesmo que as fontes mudem.

| Sinal | Significado |
|-------|-------------|
| `FRAUD_HISTORY` | Marcações de fraude confirmadas contra o CPF/CNPJ por outras instituições |
| `DISPUTE_HISTORY` | Disputas e reclamações abertas contra o CPF/CNPJ, ponderadas pelo volume dele |
| `SANCTIONS` | Presença em listas de sanções |
| `PEP` | Pessoa politicamente exposta |
| `CRIMINAL_LAWSUITS` | Processos criminais, com peso maior para assuntos de fraude financeira |
| `EXCESSIVE_LAWSUITS` | Número ou valor de processos civis fora do normal |

## Exemplo de Requisição

### Criar a validação

```bash
curl -X POST "https://api.woovi.com/api/v1/kyc-validation/taxid" \
  -H "Authorization: SEU_APP_ID_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "02.916.265/0001-60",
    "correlationID": "my-unique-id"
  }'
```

```json
{
  "correlationID": "my-unique-id",
  "taxId": "02916265000160",
  "status": "PROCESSING",
  "result": null,
  "riskLevel": null,
  "reasons": [],
  "createdAt": "2026-08-24T14:00:06.386Z",
  "completedAt": null
}
```

### Ler o resultado

```bash
curl -X GET "https://api.woovi.com/api/v1/kyc-validation/my-unique-id" \
  -H "Authorization: SEU_APP_ID_AQUI"
```

```json
{
  "correlationID": "my-unique-id",
  "taxId": "02916265000160",
  "status": "COMPLETED",
  "result": "REJECTED",
  "riskLevel": "HIGH",
  "reasons": ["FRAUD_HISTORY", "DISPUTE_HISTORY"],
  "createdAt": "2026-08-24T14:00:06.386Z",
  "completedAt": "2026-08-24T14:00:06.462Z"
}
```

Uma validação sem sinal nenhum:

```json
{
  "correlationID": "my-other-id",
  "taxId": "00000000191",
  "status": "COMPLETED",
  "result": "APPROVED",
  "riskLevel": "LOW",
  "reasons": [],
  "createdAt": "2026-08-24T14:00:41.447Z",
  "completedAt": "2026-08-24T14:00:41.489Z"
}
```

## Webhooks

Em vez de ficar consultando o `GET`, assine os eventos:

| Evento | Quando dispara |
|--------|----------------|
| `KYC_VALIDATION_COMPLETED` | A validação concluiu com veredito |
| `KYC_VALIDATION_FAILED` | Nenhuma fonte respondeu, sem veredito |

O corpo do webhook traz o mesmo objeto `kycValidation` da resposta do `GET`.

## Tratamento de Erros

| HTTP | `errorCode` | O que aconteceu |
|------|-------------|-----------------|
| 400 | `KYC_VALIDATION_INVALID_BODY` | `taxId` sem 11 ou 14 dígitos, ou campo obrigatório ausente |
| 400 | `KYC_VALIDATION_BILLING_FAILED` | A taxa não pôde ser cobrada (taxa não configurada, saldo insuficiente). Nada foi consultado nem cobrado |
| 401 | — | `Authorization` ausente ou inválido (resposta: `{"data":null,"errors":[{"message":"Invalid appID"}]}`) |
| 403 | `KYC_VALIDATION_FEATURE_NOT_ENABLED` | A empresa não tem a feature `KYC_VALIDATION` |
| 403 | `KYC_VALIDATION_ACCOUNT_NOT_AVAILABLE` | A aplicação não está ligada a uma conta aberta, então não há como cobrar |
| 404 | `KYC_VALIDATION_NOT_FOUND` | Não existe validação com esse `correlationID` na sua empresa |
| 502 | `KYC_VALIDATION_BILLING_UNAVAILABLE` | O serviço de cobrança não respondeu. Nada foi cobrado — tente de novo com o **mesmo** `correlationID` |

## Casos de Uso

- **Onboarding**: reprovar ou mandar para análise manual um cadastro cujo CPF/CNPJ já carrega histórico de fraude
- **Antes de liberar limite**: checar o CNPJ do cliente antes de aumentar limite ou liberar um produto novo
- **Contraparte**: avaliar quem vai receber, e não só quem paga
- **Conformidade**: registrar a consulta e o veredito como parte do processo de KYC/PLD

## Diferença entre Validação de KYC e Estatísticas de Fraude

| Aspecto | Validação de KYC | [Estatísticas de Pessoa](/docs/flows/person-statistic) / [de Chave PIX](/docs/flows/fraud-statistic) |
|---------|------------------|------------------------------------------------|
| O que devolve | Veredito (`APPROVED`/`REJECTED`) + nível de risco + sinais | Números crus (liquidações, marcações, notificações) |
| Quem decide | Woovi, com limiares versionados | Você, a partir dos números |
| Fontes | Fraude, disputa, sanções, PEP e processos | DICT |
| Forma | Assíncrona (`POST` + `GET`/webhook) | Síncrona (`GET`) |
| Identificador | CPF ou CNPJ | CPF/CNPJ ou chave PIX |
| Idempotência | Por `correlationID` | Não se aplica |

---

## Estatísticas de Pessoa (CPF/CNPJ)


A API de Estatísticas de Pessoa permite consultar dados estatísticos de fraude e indicadores de risco associados a uma pessoa física (CPF) ou jurídica (CNPJ). Este endpoint fornece informações sobre liquidações, marcadores de fraude, relatórios de infração e vínculos com chaves PIX.

## Visão Geral

Esta API retorna estatísticas associadas ao proprietário (pessoa) identificado pelo CPF ou CNPJ, incluindo:

- **SPI**: Liquidações como recebedor no Sistema de Pagamentos Instantâneos
- **Marcadores de Fraude**: Histórico de fraudes associadas à pessoa
- **Relatórios de Infração**: Notificações de infração abertas e rejeitadas
- **Entradas**: Contas associadas a chaves PIX registradas

## API Endpoint

Consultar estatísticas por CPF/CNPJ:

```
GET /api/v1/fraud-validation/taxId/{taxId}
```

**📖 [Ver documentação completa da API](/api#tag/fraudValidation)**

## Parâmetros da Requisição

| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-----------|
| `taxId` | string | Sim | CPF (11 dígitos) ou CNPJ (14 dígitos) da pessoa a ser consultada |

## Estrutura da Resposta

### SPI (Sistema de Pagamentos Instantâneos)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `watermark` | string | Data da última atualização dos dados |
| `settlements` | object | Número de liquidações como recebedor no SPI |
| `settlements.d90` | string | Últimos 90 dias |
| `settlements.m12` | string | Últimos 12 meses |
| `settlements.m60` | string | Últimos 60 meses (5 anos) |

### Marcadores de Fraude (`fraudMarkers`)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `watermark` | string | Data da última atualização dos dados de fraude |
| `applicationFrauds` | object | Marcações de fraude do tipo APPLICATION_FRAUD por período |
| `muleAccounts` | object | Marcações de fraude do tipo MULE_ACCOUNT (contas intermediárias para recursos ilícitos) |
| `scammerAccounts` | object | Marcações de fraude do tipo SCAMMER_ACCOUNT (contas de golpistas) |
| `otherFrauds` | object | Marcações de fraude do tipo OTHER |
| `unknownFrauds` | object | Marcações de fraude sem classificação de tipo, criadas na API v1 |
| `totalFraudTransactionAmount` | object | Valor total das transações liquidadas no SPI associadas a marcações de fraude (exclui APPLICATION_FRAUD e UNKNOWN) |
| `distinctFraudReporters` | object | Número de participantes distintos que geraram marcações de fraude (exclui tipo UNKNOWN) |

### Relatórios de Infração (`infractionReports`)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `watermark` | string | Data da última atualização dos dados de infração |
| `openReports` | string | Número de notificações de infração ainda não concluídas nem canceladas |
| `openReportsDistinctReporters` | string | Número de participantes distintos criadores de notificações abertas |
| `rejectedReports` | object | Número de notificações de infração concluídas com rejeição por período |

### Entradas (`entries`)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `watermark` | string | Data da última atualização dos dados de entrada |
| `registeredAccounts` | string | Número de contas da pessoa associadas a chaves atualmente registradas |

## Períodos de Tempo

A API utiliza os seguintes indicadores de período:

- **d90**: Últimos 90 dias
- **m12**: Últimos 12 meses
- **m60**: Últimos 60 meses (5 anos)

## Exemplo de Requisição

### cURL
```bash
curl -X GET "https://api.woovi.com/api/v1/fraud-validation/taxId/12345678901" \
  -H "Authorization: SEU_APP_ID_AQUI"
```

## Exemplo de Resposta

```json
{
  "success": true,
  "data": {
    "personStatistics": {
      "spi": {
        "watermark": "2025-04-08T10:19:11.308Z",
        "settlements": {
          "d90": "0",
          "m12": "9",
          "m60": "9"
        }
      },
      "fraudMarkers": {
        "watermark": "1970-01-01T00:00:00Z",
        "applicationFrauds": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "muleAccounts": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "scammerAccounts": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "otherFrauds": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "unknownFrauds": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "totalFraudTransactionAmount": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        },
        "distinctFraudReporters": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        }
      },
      "infractionReports": {
        "watermark": "1970-01-01T00:00:00Z",
        "openReports": "0",
        "openReportsDistinctReporters": "0",
        "rejectedReports": {
          "d90": "0",
          "m12": "0",
          "m60": "0"
        }
      },
      "entries": {
        "watermark": "2025-05-24T19:38:15.063Z",
        "registeredAccounts": "1"
      }
    }
  }
}
```

## Entendendo a Resposta

### Valores Zero
Todos os valores que mostram "0" indicam que não há registros de fraudes, infrações ou problemas associados à pessoa consultada.

### Datas Watermark
- **Datas recentes** (ex: "2025-04-08T10:19:11.308Z") indicam atualizações recentes de dados
- **Datas epoch** (ex: "1970-01-01T00:00:00Z") indicam que não há dados disponíveis para essa categoria

### Diferença entre Estatísticas de Pessoa e de Chave PIX

| Aspecto | Estatísticas de Pessoa | Estatísticas de Chave PIX |
|---------|----------------------|---------------------------|
| Identificador | CPF ou CNPJ | Chave PIX (CPF, CNPJ, email, telefone, aleatória) |
| Escopo | Todas as chaves e contas da pessoa | Chave PIX específica |
| Entradas | `registeredAccounts` (contas registradas) | `distinctAccounts` (contas distintas por período) |
| Endpoint | `/fraud-validation/taxId/{taxId}` | `/fraud-validation/pix-key/{pix-key}` |

## Casos de Uso

- **KYC (Know Your Customer)**: Verificar o histórico de fraude de uma pessoa antes de aprovar cadastro
- **Avaliação de Risco**: Avaliar o nível de risco de transações com base no histórico do destinatário
- **Conformidade Regulatória**: Atender aos requisitos do Banco Central para prevenção de fraude
- **Monitoramento**: Acompanhar indicadores de fraude de contrapartes em transações PIX

## Tratamento de Erros

A API retornará respostas de erro apropriadas para requisições inválidas. Cenários de erro comuns incluem:

- Formato de CPF/CNPJ inválido
- CPF/CNPJ não encontrado
- Erros de autenticação/autorização
- Rate limit

---

## Simulação de Erros no Sandbox para pagamentos por agência e conta

## Simulação de Erros no Sandbox

No ambiente de sandbox, é possível simular diferentes cenários de erro utilizando números de conta específicos. Quando um pagamento PIX é feito para uma dessas contas especiais, o sistema retorna automaticamente um webhook `MOVEMENT_FAILED` com o erro correspondente, permitindo testar o tratamento de erros na sua aplicação.

## Como Funciona

1. **Crie um pagamento PIX** usando uma das contas de simulação listadas abaixo
2. **Receba o webhook** `MOVEMENT_FAILED` com o erro simulado
3. **Teste o tratamento** de erro na sua aplicação

## Contas de Simulação de Erro

### Erros de Provedor Padrão

| Conta | Código de Erro | Descrição | Mensagem |
|-------|----------------|-----------|----------|
| `1111111` | `ACCOUNT_NOT_FOUND` | Conta não encontrada | Account not found |
| `2222222` | `NOT_ENOUGH_BALANCE` | Saldo insuficiente | Not enough balance |
| `3333333` | `ACCOUNT_TRANSACTION_BLOCKED_BY_MED` | Conta bloqueada | Account blocked |
| `4444444` | `INVALID_PIX_KEY` | Chave PIX inválida | Invalid Pix key |
| `5555555` | `REACH_TRANSFER_LIMIT` | Limite de transferência atingido | Transfer limit reached |
| `6666666` | `SAME_ACCOUNT_TRANSFER` | Transferência mesma conta | Same account transfer not allowed |
| `7777777` | `TRANSACTION_NOT_FOUND` | Transação não encontrada | Transaction not found |
| `8888888` | `ACCOUNT_LIMIT_ERROR` | Limite da conta excedido | Account limit exceeded |
| `9999999` | `PAY_PIX_KEY_ERROR` | Erro genérico de pagamento | Generic payment error |

### Erros PIX SPI (Sistema de Pagamentos Instantâneos)

| Conta | Código PIX | Descrição Detalhada | Motivo |
|-------|------------|---------------------|--------|
| `1010101` | `AC06` | Conta bloqueada | Conta transacional do usuário recebedor encontra-se bloqueada |
| `1010102` | `AM04` | Saldo insuficiente | Saldo insuficiente na conta PI do participante do usuário pagador |
| `1010103` | `AC03` | Pagamento rejeitado pelo PSP do recebedor | Número da agência e/ou conta transacional do usuário recebedor inexistente ou inválido |
| `1010104` | `FF08` | EndToEndId inválido | Identificador da operação mal formatado |
| `1010105` | `DS04` | Transação rejeitada pelo PSP | Ordem rejeitada pelo participante do usuário recebedor |
| `1010106` | `RR04` | Motivo regulatório | Usuário pagador é sancionado por resolução do Conselho de Segurança das Nações Unidas |
| `1010107` | `AM12` | Valor inválido | Divergência entre a somatória dos valores do bloco valorDoDinheiroOuCompra e o campo valor |
| `1010108` | `FRAD` | Origem fraudulenta | Ordem de pagamento rejeitada por fundada suspeita de fraude |
| `1010109` | `DUPL` | Pagamento duplicado | Pagamento efetuado em duplicidade |
| `1010110` | `AG03` | Transação não suportada | Tipo de transação não é suportado/autorizado na conta transacional do usuário recebedor |
| `1010111` | `AC07` | Conta do recebedor encerrada | Número da conta transacional do usuário recebedor encerrada |
| `1010112` | `AM01` | Valor zero não permitido | Ordem de pagamento instantâneo com valor zero |
| `1010113` | `BE01` | Cliente final inconsistente | CPF/CNPJ do usuário recebedor não é consistente com o titular da conta |
| `1010114` | `CH11` | Identificador do recebedor incorreto | CPF/CNPJ do usuário recebedor incorreto |
| `1010115` | `AB03` | Timeout na liquidação | Liquidação da transação interrompida devido a timeout no SPI |

## Exemplo de Webhook de Erro

### Webhook de Resposta - Erro AM12

Este é o webhook que você receberá ao usar a conta `1010107` no exemplo acima:

```json
{
  "event": "OPENPIX:MOVEMENT_FAILED",
  "payment": {
    "value": 1,
    "status": "FAILED",
    "correlationID": "cor2re3l3122034a339513340w34333311io343331ee33n3200233133333333333343112310",
    "metadata": {}
  },
  "transaction": {
    "value": 1,
    "endToEndId": "E54811417202507211653RZX3fRvHb56",
    "time": "2025-07-21T16:53:22.212Z",
    "providerRejectedReason": "AM12 - Valor inválido"
  },
  "error": {
    "code": "PIX_OUT_NOT_AUTHORIZED",
    "description": "Ocorreu um erro. Tente novamente"
  }
}
```

## Como Testar

### 1. Crie um Pagamento PIX

Exemplo usando a conta de simulação `1010107` que simula o erro **AM12 - Valor inválido**:

```bash
curl -X POST https://api.woovi-sandbox.com/api/v1/payment \
  -H "Authorization: YOUR_SANDBOX_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "correlationID": "manual-payment-001",
    "value": 1,
    "psp": {
      "id": "077",
      "name": "Banco INTER"
    },
    "holder": {
      "name": "Ponte Company LTDA",
      "taxID": {
        "type": "BR:CNPJ",
        "taxID": "2**389250**175"
      }
    },
    "account": {
      "account": "1010107",
      "branch": "0001",
      "accountType": "TRAN"
    }
  }'
```

## Estrutura dos Campos de Erro

### Campo `error`
- **`code`**: Código do erro interno da woovi
- **`description`**: Descrição legível do erro

### Campo `transaction.providerRejectedReason`
- **Formato**: `CÓDIGO - Descrição detalhada`
- **Exemplo**: `"AM04 - Saldo insuficiente"`
- **Presente apenas**: Em erros PIX SPI

## Cenários de Teste Recomendados

### Teste Básico de Erros
1. **Saldo Insuficiente** (`2222222`) - Teste o fluxo quando o usuário não tem saldo
2. **Conta Não Encontrada** (`1111111`) - Teste quando os dados estão incorretos
3. **Conta Bloqueada** (`3333333`) - Teste quando a conta está bloqueada

### Teste de Erros PIX Específicos
1. **Fraude** (`1010108`) - Teste o tratamento de suspeita de fraude
2. **Duplicação** (`1010109`) - Teste pagamentos duplicados
3. **Timeout** (`1010115`) - Teste problemas de conectividade

### Teste de Integração
1. Configure diferentes contas de erro
2. Teste a recepção dos webhooks
3. Verifique se os logs estão sendo gerados corretamente
4. Valide o tratamento adequado para cada tipo de erro

Para mais informações sobre códigos de erro PIX, consulte a [documentação completa de códigos de erro](./error-codes-payment.md).

---

## Como validar Dados bancários Usando agência e conta

Este documento irá ajudá-lo a validar os dados bancários de um beneficiário (agência e conta) sem precisar de uma chave Pix.

A validação é feita iniciando um pagamento de 1 centavo para a conta informada. Quando o pagamento é aprovado, é gerado um payload com os dados do titular daquela conta, confirmando a quem ela pertence.

> **Pré-requisitos:** ter uma [API MASTER](../apis/api-master.md) e o **PIX OUT habilitado** na conta. Caso não tenha o Pix Out, solicite seguindo o artigo [Como ativar o Pix Out (pagamento externo)](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/como-ativar-o-pix-out-pagamento-externo).

## Sequência da integração

![sequencial](./__assets__/payment-flow.png)

## 1. Crie o pagamento

Crie o pagamento informando os dados bancários do beneficiário, seguindo os parâmetros do endpoint Create Payment request.

### Campos do pagamento manual

#### holder (dados do beneficiário)

Representa a pessoa ou empresa que vai receber o pagamento.

| Campo       | Descrição                             |
| ----------- | ------------------------------------- |
| name        | Nome completo do beneficiário         |
| taxID.type  | Tipo do documento (BR:CNPJ ou BR:CPF) |
| taxID.taxID | Número do documento                   |

#### account (dados bancários)

Representa os dados da conta bancária do beneficiário.

| Campo       | Descrição                                             |
| ----------- | ----------------------------------------------------- |
| branch      | Número da agência bancária, **exatamente 4 dígitos** (ex: "0001") |
| account     | Número da conta bancária (ex: "00000000000000000981") |
| accountType | Tipo da conta (ex: "TRAN" para conta corrente)        |

#### Tipos de conta (accountType)

| Código | Descrição                                |
| ------ | ---------------------------------------- |
| CACC   | Current Account (Conta Corrente)         |
| SLRY   | Salary Account (Conta Salário)           |
| SVGS   | Savings Account (Conta Poupança)         |
| TRAN   | Transacting Account (Conta Transacional) |

#### psp (provedor de serviço de pagamento)

Representa a instituição financeira que processará o pagamento.

| Campo | Descrição                                       |
| ----- | ----------------------------------------------- |
| id    | Identificador único do PSP (código ISPB)        |
| name  | Nome da instituição financeira (ex: "WOOVI IP") |

Para descobrir o `id` do PSP, consulte o endpoint PSPs e use o ISPB no campo `psp.id`.

```bash
curl --location 'https://api.woovi.com/api/v1/payment' \
  --header 'Authorization: {APP_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "value": 1,
    "correlationID": "c0938e0c-a613-48a9-982a-672c062d0001",
    "holder": {
      "name": "teste",
      "taxID": {
        "type": "BR:CNPJ",
        "taxID": "202********158"
      }
    },
    "psp": {
      "id": "54811417",
      "name": "WOOVI IP LTDA"
    },
    "account": {
      "account": "000********0981",
      "branch": "00**",
      "accountType": "TRAN"
    }
  }'
```

![creat](./__assets__/request.png)

## 2. Aprove o pagamento e obtenha os dados

Após o pagamento ser aprovado, os dados bancários do titular da conta ficam disponíveis. Há **duas formas** de aprovar o pagamento:

### Opção 1: Aprovação automática (`autoApprove`) — chamada única

Enviando `autoApprove: true` no corpo da requisição do `/api/v1/payment` (a mesma da etapa anterior), o pagamento é criado **e aprovado na mesma chamada**, dispensando o `/api/v1/payment/approve`. A resposta imediata traz o `payment` com status `APPROVED` (sem o `destination` — veja [O que é retornado](#o-que-é-retornado-)).

> **Atenção:** o uso do `autoApprove` requer permissão especial na sua conta. Entre em contato com o suporte para ativar. Veja mais em [Como criar e aprovar um pagamento em uma única chamada?](../payment/payment-how-to-auto-approve.md).

```bash
curl --location 'https://api.woovi.com/api/v1/payment' \
  --header 'Authorization: {APP_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "value": 1,
    "correlationID": "c0938e0c-a613-48a9-982a-672c062d0001",
    "autoApprove": true,
    "holder": {
      "name": "teste",
      "taxID": {
        "type": "BR:CNPJ",
        "taxID": "202********158"
      }
    },
    "psp": {
      "id": "54811417",
      "name": "WOOVI IP LTDA"
    },
    "account": {
      "account": "000********0981",
      "branch": "00**",
      "accountType": "TRAN"
    }
  }'
```

### Opção 2: Aprovação em dois passos (`/payment/approve`)

Sem o `autoApprove`, o pagamento é criado com status `CREATED` e você precisa aprová-lo em uma segunda chamada, seguindo o endpoint Approve a Payment Request.

```bash
curl --location 'https://api.woovi.com/api/v1/payment/approve' \
  --header 'Authorization: {APP_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "correlationID": "c0938e0c-a613-48a9-982a-672c062d0001"
  }'
```

![confirm](./__assets__/confirm-payment.png)

### O que é retornado ?

Os dados do titular da conta vêm no campo `destination`. Como o Pix é enviado de forma assíncrona, esse campo **não** está na resposta imediata do `autoApprove` nem nos webhooks — o webhook [`OPENPIX:MOVEMENT_CONFIRMED`](#3-webhooks) avisa apenas que o pagamento foi confirmado, sem trazer os dados do titular.

Para obter o `destination`, consulte o endpoint `GET /api/v1/transaction` após a confirmação do pagamento, filtrando pela transação correspondente (por exemplo, pelo `endToEndId` recebido no webhook).

```json
{
  "payment": { },
  "transaction": { },
  "destination": {
    "name": "Luc— – —--ar",
    "taxID": "07*******61",
    "bank": "NU PAGAMENTOS - IP",
    "branch": "0001",
    "account": "76******03"
  }
}
```

- `name` — nome do titular da conta.
- `taxID` — documento do titular (CPF parcialmente mascarado / CNPJ).
- `bank` — instituição financeira da conta.
- `branch` e `account` — agência e conta confirmadas.

> No fluxo por agência e conta, o `destination` **não** retorna o campo `pixKey` (esse campo só existe na validação [por chave Pix](./validate-bank-data.md)).

## 3. Webhooks

Após a criação e confirmação do pagamento, você receberá webhooks com o status da transação. Aqui estão exemplos dos possíveis webhooks:

### Webhook de falha (`MOVEMENT_FAILED`)

```json
{
  "event": "OPENPIX:MOVEMENT_FAILED",
  "payment": {
    "value": 1,
    "status": "FAILED",
    "correlationID": "manual-payment-0009"
  },
  "transaction": {
    "value": 1,
    "endToEndId": "E54811417202507081527dYr4Cp2gfAp",
    "time": "2025-07-08T15:27:19.687Z",
    "providerRejectedReason": "AC03 - Pagamento rejeitado pelo PSP do recebedor"
  }
}
```

### Webhook de confirmação (`MOVEMENT_CONFIRMED`)

```json
{
  "event": "OPENPIX:MOVEMENT_CONFIRMED",
  "payment": {
    "status": "APPROVED",
    "value": 1,
    "correlationID": "manual-payment-0009",
    "sourceAccountId": "6823414a524ed520d3518dd6"
  },
  "transaction": {
    "value": 1,
    "time": "2025-07-08T15:27:19.687Z",
    "endToEndId": "E54811417202507081527dYr4Cp2gfAp"
  }
}
```

> Este webhook **não** traz os dados do titular da conta (`destination`). Para obtê-los, consulte o endpoint `GET /api/v1/transaction` — veja [O que é retornado](#o-que-é-retornado-).

Se não souber como configurar o webhook, acesse: [Criando um webhook para interceptar um Pix e chamar uma API](/docs/webhook/platform/webhook-platform-api).

## Prompt para IA

Copie o trecho abaixo numa IA de coding (Claude / Cursor / Gemini / ChatGPT) pra implementar a integração no seu app:

> Implemente uma função `validateBankData({ holder, account, psp })` que valida os dados bancários de um beneficiário (agência e conta) via Woovi, iniciando um pagamento de 1 centavo e devolvendo os dados do titular confirmados pelo Banco Central.
>
> **Endpoint**: `POST https://api.woovi.com/api/v1/payment`
> **Header**: `Authorization: <APP_ID_MASTER>` e `Content-Type: application/json`
> **Pré-requisito**: a conta precisa ter PIX OUT habilitado.
>
> **Body** (envie `autoApprove: true` para criar e aprovar numa única chamada, sem precisar do `/payment/approve`):
> ```json
> {
>   "value": 1,
>   "correlationID": "<uuid único>",
>   "autoApprove": true,
>   "holder": {
>     "name": "<nome do beneficiário>",
>     "taxID": { "type": "BR:CNPJ" | "BR:CPF", "taxID": "<documento>" }
>   },
>   "psp": { "id": "", "name": "<nome do banco>" },
>   "account": {
>     "branch": "<agência>",
>     "account": "<conta>",
>     "accountType": "CACC" | "SLRY" | "SVGS" | "TRAN"
>   }
> }
> ```
>
> **Resposta de sucesso (200)**: confirma que o pagamento foi criado/aprovado, mas **não** traz os dados do titular (`destination`) — nem os webhooks trazem. Para obtê-los, consulte `GET /api/v1/transaction` após a confirmação, filtrando pela transação correspondente.
>
> **Detalhes importantes**:
> - `autoApprove: true` exige permissão especial na conta; sem ela, crie o pagamento e aprove depois com `POST /api/v1/payment/approve` enviando o `correlationID`.
> - O `psp.id` é o código ISPB (8 dígitos) do banco — consulte `GET /api/v1/psp` para descobrir.
> - Trate os webhooks `OPENPIX:MOVEMENT_CONFIRMED` (aprovado) e `OPENPIX:MOVEMENT_FAILED` (rejeitado) para o status final da validação — os dados do titular (`destination`) vêm de `GET /api/v1/transaction`, não do webhook.

---

## Como validar Dados bancários Usando Chave Pix

Este documento irá ajudá-lo a validar os dados bancários de um beneficiário a partir de uma **chave Pix** (CPF, CNPJ, e-mail, telefone ou chave aleatória).

A validação é feita enviando um pagamento de 1 centavo para a chave informada. O banco do recebedor resolve a chave e confirma a quem ela pertence — esses dados voltam na consulta do próprio pagamento, depois que ele é confirmado.

:::info Pré-requisitos

- Um **AppID** com os escopos `PAYMENT_POST` (criar pagamento) e `PAYMENT_GET` (consultar pagamento). Você cria o AppID no app, em **Integrações → API**.
- **Pix Out habilitado** na sua empresa **e** na conta que vai pagar. A liberação da conta é feita por você mesmo, seguindo o artigo [Como ativar o Pix Out (pagamento externo)](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/como-ativar-o-pix-out-pagamento-externo).
- Saldo na conta de origem — o Pix de 1 centavo é real e a tarifa de pagamento é cobrada normalmente.

:::

## 1. Crie e aprove o pagamento

Crie o pagamento informando a chave Pix do beneficiário, seguindo os parâmetros do endpoint Create Payment request.

### Campos do pagamento por chave Pix

| Campo | Descrição |
| --- | --- |
| value | Valor em centavos — use `1` para validar |
| correlationID | Identificador único seu, usado depois para consultar o pagamento |
| destinationAlias | Valor da chave Pix do beneficiário |
| destinationAliasType | Tipo da chave — ver tabela abaixo |
| autoApprove | `true` cria e aprova o pagamento na mesma chamada |

#### Tipos de chave (destinationAliasType)

| Código | Descrição |
| --- | --- |
| CPF | CPF do titular |
| CNPJ | CNPJ do titular |
| EMAIL | Chave de e-mail |
| PHONE | Chave de telefone |
| RANDOM | Chave aleatória (EVP) |

### Opção 1: chamada única (`autoApprove`)

Enviando `autoApprove: true`, o pagamento é criado **e aprovado na mesma chamada**, dispensando o `/api/v1/payment/approve`.

```bash
curl --location 'https://api.woovi.com/api/v1/payment' \
  --header 'Authorization: {APP_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "value": 1,
    "correlationID": "c0938e0c-a613-48a9-982a-672c062d0001",
    "comment": "request user information",
    "autoApprove": true,
    "destinationAlias": "12345678909",
    "destinationAliasType": "CPF"
  }'
```

```json
{
  "payment": {
    "status": "APPROVED",
    "value": 1,
    "destinationAlias": "12345678909",
    "comment": "request user information",
    "correlationID": "c0938e0c-a613-48a9-982a-672c062d0001",
    "sourceAccountId": "6823414a524ed520d3518dd6"
  }
}
```

:::caution Atenção

O `autoApprove` requer permissão específica na sua conta. Se a resposta vier `403` com `Your company does not have access to autoApprove payments via API`, use a Opção 2. Veja mais em [Como criar e aprovar um pagamento em uma única chamada?](../payment/payment-how-to-auto-approve.md).

:::

### Opção 2: aprovação em dois passos

Sem o `autoApprove`, o mesmo `POST /api/v1/payment` cria o pagamento com status `CREATED`, sem enviar o Pix:

```json
{
  "payment": {
    "value": 1,
    "status": "CREATED",
    "destinationAlias": "12345678909",
    "destinationAliasType": "CPF",
    "comment": "request user information",
    "correlationID": "c0938e0c-a613-48a9-982a-672c062d0001",
    "sourceAccountId": "6823414a524ed520d3518dd6"
  }
}
```

Aprove em uma segunda chamada, seguindo o endpoint Approve a Payment Request. Essa chamada exige o escopo `PAYMENT_APPROVE_POST` no AppID e envia apenas o `correlationID`.

```bash
curl --location 'https://api.woovi.com/api/v1/payment/approve' \
  --header 'Authorization: {APP_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "correlationID": "c0938e0c-a613-48a9-982a-672c062d0001"
  }'
```

```json
{
  "payment": {
    "status": "APPROVED",
    "value": 1,
    "destinationAlias": "12345678909",
    "comment": "request user information",
    "correlationID": "c0938e0c-a613-48a9-982a-672c062d0001",
    "sourceAccountId": "6823414a524ed520d3518dd6"
  }
}
```

:::note

A criação **não** valida a chave: um pagamento para uma chave inexistente é criado normalmente e só falha depois de aprovado. E nenhuma das duas chamadas retorna os dados do titular — o Pix é liquidado de forma assíncrona, então esse dado só existe depois da confirmação. Para obtê-lo, consulte o pagamento (próximo passo).

:::

## 2. Consulte o pagamento para obter os dados do titular

Consulte `GET /api/v1/payment/{id}` usando o `correlationID` que você enviou. Depois que o pagamento fica `CONFIRMED`, a resposta traz os dados do titular da chave no bloco **`destination`** (e os mesmos dados, completos, em `transaction.creditParty`).

```bash
curl --location 'https://api.woovi.com/api/v1/payment/c0938e0c-a613-48a9-982a-672c062d0001' \
  --header 'Authorization: {APP_ID}'
```

```json
{
  "payment": {
    "status": "CONFIRMED",
    "value": 1,
    "destinationAlias": "12345678909",
    "comment": "request user information",
    "correlationID": "c0938e0c-a613-48a9-982a-672c062d0001",
    "sourceAccountId": "6823414a524ed520d3518dd6"
  },
  "transaction": {
    "value": 1,
    "time": "2026-01-01T12:00:00.000Z",
    "endToEndId": "E54811417202601011200abcdefghijk",
    "creditParty": {
      "pixKey": {
        "pixKey": "12345678909",
        "type": "CPF"
      },
      "account": {
        "branch": "0001",
        "account": "1234567890",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "12345678",
        "name": "BANCO EXEMPLO S.A."
      },
      "holder": {
        "name": "Fulano de Tal",
        "nameFriendly": "Fulano de Tal",
        "taxID": {
          "taxID": "12345678909",
          "type": "BR:CPF"
        }
      }
    }
  },
  "destination": {
    "name": "Fulano de Tal",
    "taxID": "12345678909",
    "pixKey": "12345678909",
    "bank": "BANCO EXEMPLO S.A.",
    "branch": "0001",
    "account": "1234567890"
  }
}
```

- `destination.name` / `destination.taxID` — nome e documento do titular da chave, resolvidos pelo banco do recebedor no momento da liquidação. Diferente de uma validação em que você mesmo informa o nome, aqui o nome vem **do banco**, não do que você enviou. Não vêm mascarados.
- `destination.pixKey` — a chave Pix usada (`destinationAlias`).
- `destination.bank` / `branch` / `account` — instituição financeira, agência e conta vinculadas à chave.
- `transaction.endToEndId` — identificador do Pix no Banco Central, útil para conciliação.

:::note

O bloco `destination` só aparece com o pagamento `CONFIRMED`. Enquanto o status for `CREATED` ou `APPROVED`, a resposta traz apenas o `payment` — a confirmação costuma levar poucos segundos.

:::

## 3. Erros possíveis

Se a chave não estiver cadastrada em nenhum banco, ou o PSP do recebedor rejeitar o Pix, o pagamento vai para `FAILED`, **sem** `transaction` e **sem** `destination`, e o motivo vem no bloco `error`. Nesse caso o dinheiro não sai da conta.

```json
{
  "payment": {
    "status": "FAILED",
    "value": 1,
    "destinationAlias": "12345678909",
    "correlationID": "c0938e0c-a613-48a9-982a-672c062d0001",
    "sourceAccountId": "6823414a524ed520d3518dd6"
  },
  "error": {
    "code": "PIX_KEY_INFO_NOT_FOUND",
    "description": "A chave pix não esta cadastrada em um banco"
  }
}
```

- `PIX_KEY_INFO_NOT_FOUND` — chave válida mas não cadastrada no DICT
- `403 External payments not enabled for your company` — Pix Out não habilitado na empresa
- `400 External payments not enabled for this account` — Pix Out não habilitado na conta de origem
- `403 Your company does not have access to autoApprove payments via API` — use a aprovação em dois passos
- `400 destinationAliasType must be one of the following values` — tipo de chave fora do enum

Quando a rejeição vem do banco do recebedor, o código também aparece em `transaction.providerRejectedReason` — veja a lista em [Error codes - Payment](./error-codes-payment.md).

## 4. Webhooks

Para não ficar consultando o pagamento em intervalos, configure um webhook e reaja ao evento de confirmação ou de falha. Nenhum dos dois traz os dados do titular — use o `correlationID` deles para consultar o pagamento (passo 2).

### Webhook de confirmação (`MOVEMENT_CONFIRMED`)

```json
{
  "event": "OPENPIX:MOVEMENT_CONFIRMED",
  "payment": {
    "status": "APPROVED",
    "value": 1,
    "correlationID": "c0938e0c-a613-48a9-982a-672c062d0001",
    "sourceAccountId": "6823414a524ed520d3518dd6"
  },
  "transaction": {
    "value": 1,
    "time": "2026-01-01T12:00:00.000Z",
    "endToEndId": "E54811417202601011200abcdefghijk"
  }
}
```

### Webhook de falha (`MOVEMENT_FAILED`)

```json
{
  "event": "OPENPIX:MOVEMENT_FAILED",
  "payment": {
    "value": 1,
    "status": "FAILED",
    "correlationID": "c0938e0c-a613-48a9-982a-672c062d0001"
  },
  "transaction": {
    "value": 1,
    "endToEndId": "E54811417202601011200abcdefghijk",
    "time": "2026-01-01T12:00:00.000Z",
    "providerRejectedReason": "AC03 - Pagamento rejeitado pelo PSP do recebedor"
  }
}
```

Se não souber como configurar o webhook, acesse: [Criando um webhook para interceptar um Pix e chamar uma API](/docs/webhook/platform/webhook-platform-api).

## Prompt para IA

Copie o trecho abaixo numa IA de coding (Claude / Cursor / Gemini / ChatGPT) pra implementar a integração no seu app:

> Implemente uma função `validateBankDataByPixKey({ destinationAlias, destinationAliasType })` que valida os dados bancários vinculados a uma chave Pix via Woovi, enviando um pagamento de 1 centavo e devolvendo os dados do titular resolvidos pelo banco pra essa chave.
>
> **Passo 1 — criar e aprovar o pagamento**:
> `POST https://api.woovi.com/api/v1/payment`
> Header: `Authorization: <APP_ID>`, `Content-Type: application/json`
> Pré-requisito: AppID com os escopos `PAYMENT_POST` e `PAYMENT_GET`, e Pix Out habilitado na empresa e na conta de origem.
> ```json
> {
>   "value": 1,
>   "correlationID": "<uuid único>",
>   "autoApprove": true,
>   "destinationAlias": "<chave Pix>",
>   "destinationAliasType": "CPF" | "CNPJ" | "EMAIL" | "PHONE" | "RANDOM"
> }
> ```
> (`autoApprove: true` exige permissão específica na conta; sem ela, crie o pagamento e aprove depois com `POST /api/v1/payment/approve` enviando o `correlationID`, com o escopo `PAYMENT_APPROVE_POST`.)
>
> **A resposta do passo 1 NÃO traz os dados do titular** — traz só o status do pagamento. O Pix é liquidado de forma assíncrona.
>
> **Passo 2 — buscar os dados do titular**: `GET https://api.woovi.com/api/v1/payment/{correlationID}`. Quando `payment.status` for `CONFIRMED`, os dados do titular vêm no bloco `destination` (`name`, `taxID`, `pixKey`, `bank`, `branch`, `account`) e, completos, em `transaction.creditParty`. Enquanto o status for `CREATED`/`APPROVED`, o `destination` ainda não existe — faça polling com backoff ou, melhor, trate os webhooks `OPENPIX:MOVEMENT_CONFIRMED` e `OPENPIX:MOVEMENT_FAILED` e consulte o pagamento ao receber o evento.
>
> **Passo 3 — tratar falha**: se `payment.status` for `FAILED`, não há `transaction` nem `destination`; o motivo vem em `error.code` / `error.description` (ex.: `PIX_KEY_INFO_NOT_FOUND` = chave não cadastrada em nenhum banco) e, quando a rejeição é do banco do recebedor, em `transaction.providerRejectedReason`.

---

## Como cancelar uma recuperação de fundos (MED) usando a API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para cancelar uma recuperação de fundos (MED) usando a API, você deverá fazer uma chamada POST para o _endpoint_ `/api/v1/funds-recovery/{id}/cancel`, usando o `dictId` retornado na [criação](./funds-recovery-create-api.mdx).

A requisição não precisa de `BODY`.

:::caution
Só é possível cancelar recuperações de fundos **abertas pela sua conta** e que ainda não atingiram um status final (`COMPLETED` ou `CANCELLED`).
:::

## Exemplo

Se tudo ocorreu bem, o _status code_ da requisição será `200` e no `body` da resposta retornaremos a recuperação de fundos cancelada:

```json
{
  "rootTransactionId": "E31680151202606101530AbCdEf12345",
  "situationType": "SCAM",
  "reportDetails": "Pagamento realizado para um falso vendedor. Após o pagamento, o vendedor parou de responder e não entregou o produto.",
  "dictId": "3e760cd5-39b2-45da-8ab6-b212cf205568",
  "status": "CANCELLED",
  "direction": "SENT",
  "reporterParticipant": "31680151",
  "creationTime": "2026-06-11T00:30:00.000Z",
  "lastModified": "2026-06-11T01:10:00.000Z",
  "createdAt": "2026-06-11T00:30:00.000Z",
  "updatedAt": "2026-06-11T01:10:00.000Z"
}
```

## Possíveis erros

| Status | Motivo                                                                                          |
| ------ | ------------------------------------------------------------------------------------------------ |
| `400`  | O `id` informado não é um UUID válido                                                             |
| `401`  | `AppID` inválido ou ausente                                                                       |
| `403`  | Sua conta não possui a funcionalidade MED API ou o AppID não possui o escopo necessário           |
| `404`  | Recuperação de fundos não encontrada para a sua conta                                             |
| `422`  | A recuperação de fundos já está em um status final ou o cancelamento foi recusado pelo Banco Central |

Em caso de erro, o body da resposta terá o formato:

```json
{
  "error": "Cannot cancel: FundsRecovery is already in terminal status COMPLETED"
}
```

### Exemplos em código

  

```sh
curl --request POST \
    --url https://api.woovi.com/api/v1/funds-recovery/3e760cd5-39b2-45da-8ab6-b212cf205568/cancel \
    --header 'Authorization: AUTHORIZATION'
```

  
  

```js
fetch(
  'https://api.woovi.com/api/v1/funds-recovery/3e760cd5-39b2-45da-8ab6-b212cf205568/cancel',
  {
    method: 'POST',
    headers: {
      Authorization: 'AUTHORIZATION',
    },
  },
).then((res) => res.json());
```

---

## Como abrir uma recuperação de fundos (MED) usando a API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para abrir uma recuperação de fundos (MED) usando a API, você deverá fazer uma chamada POST para o _endpoint_ `/api/v1/funds-recovery`, autenticando com o seu `AppID` no header `Authorization`.

Como parte do `BODY` da requisição, esperamos o envio dos seguintes itens:

- **`transactionEndToEndId`**: O `endToEndId` da transação Pix enviada pela sua conta que você deseja recuperar.
- **`situationType`**: O tipo de situação que motivou a recuperação de fundos. Os valores possíveis são:
  - `SCAM`: golpe (ex: falsa venda, falso boleto, engenharia social)
  - `ACCOUNT_TAKEOVER`: invasão de conta
  - `COERCION`: coação (ex: sequestro, extorsão)
  - `FRAUDULENT_ACCESS`: acesso fraudulento às credenciais
  - `OTHER`: outro tipo de fraude
  - `UNKNOWN`: tipo de fraude desconhecido
- **`details`**: A descrição detalhada do ocorrido. Quanto mais contexto, melhor para a análise.

:::caution
Só é possível abrir **uma** recuperação de fundos por transação. A transação precisa ter sido enviada pela sua conta e não pode ter sido rejeitada.
:::

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "transactionEndToEndId": "E31680151202606101530AbCdEf12345",
  "situationType": "SCAM",
  "details": "Pagamento realizado para um falso vendedor. Após o pagamento, o vendedor parou de responder e não entregou o produto."
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `201` e no `body` da resposta retornaremos a recuperação de fundos criada:

```json
{
  "rootTransactionId": "E31680151202606101530AbCdEf12345",
  "situationType": "SCAM",
  "reportDetails": "Pagamento realizado para um falso vendedor. Após o pagamento, o vendedor parou de responder e não entregou o produto.",
  "dictId": "3e760cd5-39b2-45da-8ab6-b212cf205568",
  "status": "CREATED",
  "direction": "SENT",
  "reporterParticipant": "31680151",
  "creationTime": "2026-06-11T00:30:00.000Z",
  "lastModified": "2026-06-11T00:30:00.000Z",
  "events": [],
  "createdAt": "2026-06-11T00:30:00.000Z",
  "updatedAt": "2026-06-11T00:30:00.000Z"
}
```

:::tip
Guarde o campo **`dictId`** — ele é o identificador da recuperação de fundos e será usado nos endpoints de [consulta](./funds-recovery-get-api.mdx) e [cancelamento](./funds-recovery-cancel-api.mdx).
:::

## Possíveis erros

| Status | Motivo                                                                                  |
| ------ | ---------------------------------------------------------------------------------------- |
| `400`  | Body inválido (campo faltando ou `situationType` fora dos valores aceitos)               |
| `401`  | `AppID` inválido ou ausente                                                               |
| `403`  | Sua conta não possui a funcionalidade MED API ou o AppID não possui o escopo necessário   |
| `404`  | Transação não encontrada para a sua conta                                                 |
| `422`  | Já existe uma recuperação de fundos para a transação, a transação foi rejeitada ou o pedido foi recusado pelo Banco Central |

Em caso de erro, o body da resposta terá o formato:

```json
{
  "error": "FundsRecovery already exists for transaction E31680151202606101530AbCdEf12345"
}
```

### Exemplos em código

  

```sh
curl --request POST \
    --url https://api.woovi.com/api/v1/funds-recovery \
    --header 'Authorization: AUTHORIZATION' \
    --header 'content-type: application/json' \
    --data '{"transactionEndToEndId": "E31680151202606101530AbCdEf12345", "situationType": "SCAM", "details": "Pagamento realizado para um falso vendedor."}'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/funds-recovery', {
  method: 'POST',
  body: JSON.stringify({
    transactionEndToEndId: 'E31680151202606101530AbCdEf12345',
    situationType: 'SCAM',
    details: 'Pagamento realizado para um falso vendedor.',
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como consultar as disputas relacionadas a uma recuperação de fundos (MED)?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Uma recuperação de fundos também pode chegar até a sua conta pelo outro lado: quando **um pagamento que você recebeu** é apontado como parte do caminho do dinheiro de uma fraude, a Woovi abre uma **disputa** (MED recebido) na sua conta para que você apresente evidências ou aceite a devolução.

Para consultar as disputas da sua conta relacionadas a uma recuperação de fundos, faça uma chamada GET para o _endpoint_ `/api/v1/funds-recovery/{id}/disputes`, usando como `{id}` o `dictId` da recuperação **ou** o `endToEndId` da transação Pix que a originou.

## Exemplo

Se tudo ocorreu bem, o _status code_ da requisição será `200` e no `body` da resposta retornaremos a lista de disputas da sua conta:

```json
[
  {
    "type": "MED",
    "status": "IN_REVIEW",
    "sentOrReceived": "RECEIVED",
    "situationType": "SCAM",
    "value": 50000,
    "endToEndId": "E31680151202606101530AbCdEf12345",
    "fundsRecoveryId": "3e760cd5-39b2-45da-8ab6-b212cf205568",
    "disputeReason": "Pagamento apontado como parte de um golpe pela instituição do pagador.",
    "createdAt": "2026-06-11T00:35:00.000Z",
    "updatedAt": "2026-06-11T00:35:00.000Z"
  }
]
```

### Campos principais

| Campo            | Descrição                                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`           | `MED`, `DISPUTE` ou `CHARGEBACK`.                                                                                                                 |
| `status`         | `IN_REVIEW`, `OPENED`, `PENDING`, `PENDING_DOCUMENTATION`, `ACCEPTED`, `REJECTED`, `CANCELED`, `ACKNOWLEDGED` ou `CLOSED`.                        |
| `sentOrReceived` | `RECEIVED` quando a disputa foi aberta contra um pagamento que a sua conta recebeu; `SENT` quando a sua conta é a pagadora.                       |
| `value`          | Valor em disputa, em centavos.                                                                                                                    |
| `endToEndId`     | `endToEndId` da transação Pix em disputa.                                                                                                         |

:::info
Este endpoint retorna apenas as disputas **da sua conta**. Uma mesma recuperação de fundos no Banco Central pode envolver várias contas, e cada uma enxerga somente as suas próprias disputas.
:::

## Possíveis erros

| Status | Motivo                                                                                  |
| ------ | --------------------------------------------------------------------------------------- |
| `401`  | `AppID` inválido ou ausente                                                              |
| `403`  | Sua conta não possui a funcionalidade MED API ou o AppID não possui o escopo necessário |
| `404`  | Recuperação de fundos não encontrada para a sua conta                                   |

### Exemplos em código

  

```sh
curl --request GET \
    --url https://api.woovi.com/api/v1/funds-recovery/3e760cd5-39b2-45da-8ab6-b212cf205568/disputes \
    --header 'Authorization: AUTHORIZATION'
```

  
  

```js
fetch(
  'https://api.woovi.com/api/v1/funds-recovery/3e760cd5-39b2-45da-8ab6-b212cf205568/disputes',
  {
    method: 'GET',
    headers: {
      Authorization: 'AUTHORIZATION',
    },
  },
).then((res) => res.json());
```

---

## Como consultar uma recuperação de fundos (MED) usando a API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para consultar uma recuperação de fundos (MED) usando a API, você deverá fazer uma chamada GET para o _endpoint_ `/api/v1/funds-recovery/{id}`, usando como `{id}` o `dictId` retornado na [criação](./funds-recovery-create-api.mdx) **ou** o `endToEndId` da transação Pix que originou a recuperação.

Use este endpoint para acompanhar o andamento da recuperação de fundos através do campo `status` — veja o [ciclo de vida](./funds-recovery.md#ciclo-de-vida) completo.

## Exemplo

Se tudo ocorreu bem, o _status code_ da requisição será `200` e no `body` da resposta retornaremos a recuperação de fundos:

```json
{
  "rootTransactionId": "E31680151202606101530AbCdEf12345",
  "situationType": "SCAM",
  "reportDetails": "Pagamento realizado para um falso vendedor. Após o pagamento, o vendedor parou de responder e não entregou o produto.",
  "dictId": "3e760cd5-39b2-45da-8ab6-b212cf205568",
  "status": "AWAITING_ANALYSIS",
  "direction": "SENT",
  "reporterParticipant": "31680151",
  "creationTime": "2026-06-11T00:30:00.000Z",
  "lastModified": "2026-06-11T00:35:00.000Z",
  "events": [
    {
      "id": "f3a1c9d2-8b47-4e6a-9c21-5d7e0a4b8f13",
      "event": "AWAITING_ANALYSIS",
      "timestamp": "2026-06-11T00:35:00.000Z"
    }
  ],
  "createdAt": "2026-06-11T00:30:00.000Z",
  "updatedAt": "2026-06-11T00:35:00.000Z"
}
```

O campo `events` traz o histórico de eventos da recuperação de fundos, em ordem cronológica.

## Possíveis erros

| Status | Motivo                                                                                |
| ------ | -------------------------------------------------------------------------------------- |
| `401`  | `AppID` inválido ou ausente                                                             |
| `403`  | Sua conta não possui a funcionalidade MED API ou o AppID não possui o escopo necessário |
| `404`  | Recuperação de fundos não encontrada para a sua conta                                   |

### Exemplos em código

  

```sh
curl --request GET \
    --url https://api.woovi.com/api/v1/funds-recovery/3e760cd5-39b2-45da-8ab6-b212cf205568 \
    --header 'Authorization: AUTHORIZATION'
```

  
  

```js
fetch(
  'https://api.woovi.com/api/v1/funds-recovery/3e760cd5-39b2-45da-8ab6-b212cf205568',
  {
    method: 'GET',
    headers: {
      Authorization: 'AUTHORIZATION',
    },
  },
).then((res) => res.json());
```

  

O mesmo _endpoint_ aceita o `endToEndId` da transação no lugar do `dictId`, retornando a mesma recuperação de fundos:

```sh
curl --request GET \
    --url https://api.woovi.com/api/v1/funds-recovery/E31680151202606101530AbCdEf12345 \
    --header 'Authorization: AUTHORIZATION'
```

---

## Como consultar as notificações de infração de uma recuperação de fundos (MED)?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Uma **notificação de infração** (_infraction report_) é o registro de fraude que uma instituição envia ao Banco Central sobre uma transação Pix. Ao abrir uma recuperação de fundos, a Woovi registra a notificação de infração da transação original; a instituição do recebedor deve reconhecê-la e responder se concorda ou não com o relato.

Para consultar as notificações de infração ligadas a uma recuperação de fundos, faça uma chamada GET para o _endpoint_ `/api/v1/funds-recovery/{id}/infraction-reports`, usando como `{id}` o `dictId` retornado na [criação](./funds-recovery-create-api.mdx) **ou** o `endToEndId` da transação Pix que originou a recuperação.

## Exemplo

Se tudo ocorreu bem, o _status code_ da requisição será `200` e no `body` da resposta retornaremos a lista de notificações de infração da sua conta relacionadas à recuperação de fundos:

```json
[
  {
    "bacenInfractionReportId": "7c2e4b1a-3d5f-4a6b-9c8d-0e1f2a3b4c5d",
    "fundsRecoveryId": "3e760cd5-39b2-45da-8ab6-b212cf205568",
    "transactionId": "E31680151202606101530AbCdEf12345",
    "reason": "REFUND_REQUEST",
    "situationType": "SCAM",
    "reportDetails": "Pagamento realizado para um falso vendedor. Após o pagamento, o vendedor parou de responder e não entregou o produto.",
    "status": "CLOSED",
    "analysisResult": "AGREED",
    "analysisDetails": "Conta do recebedor bloqueada após verificação.",
    "reporterParticipant": "31680151",
    "counterpartyParticipant": "12345678",
    "infractionAmount": 50000,
    "contactInformation": {
      "email": "suporte@woovi.com",
      "phone": "+5511999999999"
    },
    "creationTime": "2026-06-11T00:30:00.000Z",
    "lastModified": "2026-06-11T12:00:00.000Z",
    "createdAt": "2026-06-11T00:30:00.000Z",
    "updatedAt": "2026-06-11T12:00:00.000Z"
  }
]
```

### Campos principais

| Campo                     | Descrição                                                                                                       |
| ------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `status`                  | `OPEN` ao ser registrada, `ACKNOWLEDGED` quando a outra instituição a reconhece, `CLOSED` após a análise, `CANCELLED` se cancelada. |
| `reason`                  | `REFUND_REQUEST` para um pedido de devolução; `REFUND_CANCELLED` quando a devolução foi cancelada.               |
| `situationType`           | A situação relatada: `SCAM`, `ACCOUNT_TAKEOVER`, `COERCION`, `FRAUDULENT_ACCESS`, `OTHER` ou `UNKNOWN`.          |
| `analysisResult`          | Resposta da outra instituição após a análise: `AGREED` ou `DISAGREED`.                                          |
| `reporterParticipant`     | ISPB da instituição que registrou a notificação.                                                                 |
| `counterpartyParticipant` | ISPB da instituição da contraparte.                                                                              |
| `infractionAmount`        | Valor da transação reportada, em centavos.                                                                       |

## Possíveis erros

| Status | Motivo                                                                                  |
| ------ | --------------------------------------------------------------------------------------- |
| `401`  | `AppID` inválido ou ausente                                                              |
| `403`  | Sua conta não possui a funcionalidade MED API ou o AppID não possui o escopo necessário |
| `404`  | Recuperação de fundos não encontrada para a sua conta                                   |

### Exemplos em código

  

```sh
curl --request GET \
    --url https://api.woovi.com/api/v1/funds-recovery/3e760cd5-39b2-45da-8ab6-b212cf205568/infraction-reports \
    --header 'Authorization: AUTHORIZATION'
```

  
  

```js
fetch(
  'https://api.woovi.com/api/v1/funds-recovery/3e760cd5-39b2-45da-8ab6-b212cf205568/infraction-reports',
  {
    method: 'GET',
    headers: {
      Authorization: 'AUTHORIZATION',
    },
  },
).then((res) => res.json());
```

---

## Como consultar as solicitações de devolução de uma recuperação de fundos (MED)?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Quando o Banco Central conclui a análise de uma recuperação de fundos, ele abre uma **solicitação de devolução** em cada conta por onde o dinheiro passou. Cada solicitação é analisada pela instituição que guarda os fundos e pode ser aceita total ou parcialmente, ou rejeitada.

Para consultar as solicitações de devolução de uma recuperação de fundos, faça uma chamada GET para o _endpoint_ `/api/v1/funds-recovery/{id}/refund-solicitations`, usando como `{id}` o `dictId` retornado na [criação](./funds-recovery-create-api.mdx) **ou** o `endToEndId` da transação Pix que originou a recuperação.

Use este endpoint para saber, por perna do rastreamento, **quanto foi solicitado**, **quanto foi efetivamente devolvido** e **qual transação Pix trouxe o dinheiro de volta**.

## Exemplo

Se tudo ocorreu bem, o _status code_ da requisição será `200` e no `body` da resposta retornaremos a lista de solicitações de devolução:

```json
[
  {
    "bacenRefundId": "9d1f2c3a-1b2c-4d5e-8f90-1a2b3c4d5e6f",
    "fundsRecoveryId": "3e760cd5-39b2-45da-8ab6-b212cf205568",
    "endToEndId": "E31680151202606101530AbCdEf12345",
    "refundReason": "FRAUD",
    "refundAmount": 50000,
    "EffectiveRefundedAmount": 32000,
    "status": "CLOSED",
    "analysisResult": "PARTIALLY_ACCEPTED",
    "rejectionReason": "NO_BALANCE",
    "contestedParticipant": "12345678",
    "requestingParticipant": "31680151",
    "refundTransactionId": "D31680151202606120000AbCdEf67890",
    "refundedAt": "2026-06-12T00:00:00.000Z",
    "refundTransaction": {
      "endToEndId": "D31680151202606120000AbCdEf67890",
      "value": 32000,
      "date": "2026-06-12T00:00:00.000Z"
    },
    "creationTime": "2026-06-11T00:35:00.000Z",
    "lastModified": "2026-06-12T00:00:00.000Z",
    "createdAt": "2026-06-11T00:35:00.000Z",
    "updatedAt": "2026-06-12T00:00:00.000Z"
  }
]
```

### Campos principais

| Campo                     | Descrição                                                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `status`                  | `OPEN` enquanto a instituição analisa a solicitação; `CLOSED` ou `CANCELLED` são finais.                                       |
| `refundAmount`            | Valor solicitado nesta perna, em centavos.                                                                                     |
| `EffectiveRefundedAmount` | Valor efetivamente devolvido nesta perna, em centavos. Pode ser menor que `refundAmount` em uma devolução parcial.             |
| `analysisResult`          | Resultado da análise: `TOTALLY_ACCEPTED`, `PARTIALLY_ACCEPTED` ou `REJECTED`.                                                  |
| `rejectionReason`         | Motivo quando a devolução não foi totalmente aceita: `NO_BALANCE`, `ACCOUNT_CLOSURE`, `CANNOT_REFUND` ou `OTHER`.              |
| `refundTransaction`       | A transação Pix de devolução que liquidou esta solicitação, com `endToEndId`, `value` (centavos) e `date`. `null` enquanto nada foi devolvido. |

:::tip
Somando o `refundTransaction.value` de todas as solicitações você obtém o total recuperado até o momento. Cada `refundTransaction.endToEndId` é uma transação Pix recebida na sua conta, que também aparece no seu extrato.
:::

## Possíveis erros

| Status | Motivo                                                                                  |
| ------ | --------------------------------------------------------------------------------------- |
| `401`  | `AppID` inválido ou ausente                                                              |
| `403`  | Sua conta não possui a funcionalidade MED API ou o AppID não possui o escopo necessário |
| `404`  | Recuperação de fundos não encontrada para a sua conta                                   |

### Exemplos em código

  

```sh
curl --request GET \
    --url https://api.woovi.com/api/v1/funds-recovery/3e760cd5-39b2-45da-8ab6-b212cf205568/refund-solicitations \
    --header 'Authorization: AUTHORIZATION'
```

  
  

```js
fetch(
  'https://api.woovi.com/api/v1/funds-recovery/3e760cd5-39b2-45da-8ab6-b212cf205568/refund-solicitations',
  {
    method: 'GET',
    headers: {
      Authorization: 'AUTHORIZATION',
    },
  },
).then((res) => res.json());
```

---

## O que é a Recuperação de fundos (MED)?

A **Recuperação de fundos** (_Funds Recovery_) é a implementação do **MED** (Mecanismo Especial de Devolução) do Banco Central. Ela permite que você solicite a devolução de uma transação Pix enviada pela sua conta em casos de **golpe ou fraude**.

Ao abrir uma recuperação de fundos, o Banco Central rastreia o caminho do dinheiro entre as instituições participantes do Pix e abre solicitações de devolução nas contas por onde os fundos passaram. Os valores localizados são bloqueados nas contas de destino e devolvidos para a sua conta.

## Pré-requisitos

Para usar a API de recuperação de fundos você precisa:

- Ter a funcionalidade **MED API** habilitada na sua conta. Caso ainda não tenha, entre em contato com o nosso suporte.
- Um [AppID](../apis/api-getting-started.md) para autenticar as requisições, enviado no header `Authorization`.

## Endpoints

| Endpoint                                                                       | Método | Descrição                                |
| ------------------------------------------------------------------------------ | ------ | ---------------------------------------- |
| [`/api/v1/funds-recovery`](./funds-recovery-create-api.mdx)                     | POST   | Abrir uma recuperação de fundos           |
| [`/api/v1/funds-recovery/{id}`](./funds-recovery-get-api.mdx)                   | GET    | Consultar uma recuperação de fundos       |
| [`/api/v1/funds-recovery/{id}/cancel`](./funds-recovery-cancel-api.mdx)         | POST   | Cancelar uma recuperação de fundos        |
| [`/api/v1/funds-recovery/{id}/refund-solicitations`](./funds-recovery-refund-solicitations-api.mdx) | GET | Consultar as solicitações de devolução e o que já foi devolvido |
| [`/api/v1/funds-recovery/{id}/infraction-reports`](./funds-recovery-infraction-reports-api.mdx) | GET | Consultar as notificações de infração |
| [`/api/v1/funds-recovery/{id}/disputes`](./funds-recovery-disputes-api.mdx) | GET | Consultar as disputas da sua conta relacionadas |

## Ciclo de vida

Uma recuperação de fundos passa pelos seguintes status:

- **`CREATED`**: a recuperação de fundos foi registrada no Banco Central.
- **`TRACKED`**: o rastreamento do caminho do dinheiro foi concluído.
- **`AWAITING_ANALYSIS`**: aguardando a análise do Banco Central.
- **`ANALYSED`**: análise concluída; as solicitações de devolução são abertas nas instituições por onde os fundos passaram.
- **`REFUNDING`**: devoluções em andamento.
- **`COMPLETED`**: processo concluído. Os valores recuperados foram devolvidos.
- **`CANCELLED`**: a recuperação de fundos foi cancelada.

`COMPLETED` e `CANCELLED` são status finais — após atingi-los a recuperação de fundos não pode mais ser alterada.

A partir de `ANALYSED`, acompanhe o dinheiro de volta pelas [solicitações de devolução](./funds-recovery-refund-solicitations-api.mdx): cada uma informa o valor devolvido e a transação Pix que o trouxe para a sua conta.

:::info
O valor devolvido depende do saldo encontrado nas contas rastreadas. A recuperação pode ser **total**, **parcial** ou pode não haver fundos disponíveis para devolução.
:::

---

## Visão Geral - Pix Indireto

# Visão geral - Pix Indireto

Cada participante indireto da Woovi terá uma URL diferente para acessar nossos serviços, que consiste em:

|     |     |
| --- | --- |
| Homologação | &lt;nome&gt;.indireto.dev.woovi.cloud |
| Produção | &lt;nome&gt;.indireto.woovi.cloud |

Essa URL será compartilhada com o indireto quando os serviços forem ativados e puderem ser acessados.

## DICT

O mais importante desses serviços é o DICT, que vai seguir a mesmas rotas e documentação definidas [aqui](https://www.bcb.gov.br/content/estabilidadefinanceira/pix/API-DICT.html).

Então se você quer criar uma nova chave pix, por exemplo, deverá usar a URL:

- &lt;nome&gt;.woovi.cloud/dict/api/v2/entries

Todas as mensagens do DICT são por meio de JSON, e vão seguir o mesmo padrão do DICT API. Por exemplo:

No endpoint de verificar existência de chaves, o request consiste de um XML com os seguintes campos:

```
<CheckKeysRequest>
    <Keys>
        <Key>mail@mail.com</Key>
        <Key>mail2@mail.com</Key>
        <Key>+5561999999999</Key>
        <Key>+5561888888888</Key>
        <Key>99999999999</Key>
        <Key>99999999999999</Key>
    </Keys>
</CheckKeysRequest>
```

Para a Woovi no seu endpoint de DICT só é necessário mandar:

```
{
  "CheckKeysRequest": {
    "Keys": {
      "Key": [
        "mail@mail.com",
        "mail2@mail.com",
        "+5561999999999",
        "+5561888888888",
        "99999999999",
        "99999999999999"
      ]
    }
  }
}
```

E a resposta será da seguinte forma:

```
{
  "CheckKeysResponse": {
    "ResponseTime": "2020-01-10T10:00:00.000Z",
    "CorrelationId": "a9f13566e19f5ca51329479a5bae60c5",
    "Keys": {
      "Key": [
        {
          "hasEntry": "true",
          "value": "mail@mail.com"
        },
        {
          "hasEntry": "false",
          "value": "mail2@mail.com"
        },
        {
          "hasEntry": "true",
          "value": "+5561999999999"
        },
        {
          "hasEntry": "false",
          "value": "+5561888888888"
        },
        {
          "hasEntry": "false",
          "value": "99999999999"
        },
        {
          "hasEntry": "true",
          "value": "99999999999999"
        }
      ]
    }
  }
}
```

Com isso o acesso ao DICT já será possível.

## Mensagens do SPI

Toda a comunicação entre participantes diretos e indiretos é feita por meio de mensagens, as mais conhecidas e utilizadas são a PACS002 e PACS008. A PACS008 representa o início de um Pix e a PACS002 representa a confirmação da chegada da mensagem.

As mensagens do SPI seguem o mesmo padrão, serão recebidas em formato JSON saindo de sua fila e serão mandadas por sua fila para você em formato JSON. Exemplo de mensagem:

```
{
  "Fr": {
    "FIId": {
      "FinInstnId": {
        "Othr": {
          "Id": "31985422"
        }
      }
    }
  },
  "To": {
    "FIId": {
      "FinInstnId": {
        "Othr": {
          "Id": "54811417"
        }
      }
    }
  },
  "BizMsgIdr": "M000381660M80LWKPP10W4YJSKTMJGIR",
  "MsgDefIdr": "pacs.002.spi.1.11",
  "CreDt": "2025-03-08T19:37:40.583Z",
  "FIToFIPmtStsRpt": {
    "GrpHdr": {
      "MsgId": "M000381660M80LWKPP10W4YJSKTMJGIR",
      "CreDtTm": "2025-03-08T19:37:40.583Z"
    },
    "TxInfAndSts": [
      {
        "OrgnlInstrId": "E13935893202503081937u9uwdcxH7FB",
        "OrgnlEndToEndId": "E13935893202503081937u9uwdcxH7FB",
        "TxSts": "ACCC",
        "FctvIntrBkSttlmDt": {
          "DtTm": "2025-03-08T19:37:40.515Z"
        },
        "OrgnlTxRef": {
          "IntrBkSttlmDt": "2025-03-10"
        }
      }
    ]
  }
}
```

A mensagem segue a mesma estrutura dos catálogos definidos [aqui](https://www.bcb.gov.br/estabilidadefinanceira/comunicacaodados).

## Cobrança e Location

Como a Woovi disponibiliza seu endpoint de QrCodes para participantes indiretos, é necessário criar uma nova cobrança e uma nova location sempre que um novo QrCode for gerado.

Por isso, na URL de serviços voltada para indiretos, estão disponíveis dois endpoints fundamentais:

- `<nome>.woovi.cloud/charge`: responsável pela criação da cobrança, incluindo informações como valor, devedor, chave Pix e o tipo de cobrança.
- `<nome>.woovi.cloud/location`: responsável por gerar a URL que os demais participantes utilizarão para acessar os dados da cobrança.

Esses dois serviços são indispensáveis para viabilizar e simplificar pagamentos via QrCode.

## Conta Liquidation

Antes de realizar qualquer operação de **PixOut**, é fundamental verificar se a conta **Liquidation** da sua instituição na Woovi possui saldo suficiente para cobrir o valor da transação.

A conta Liquidation representa o saldo agregado dos seus clientes, refletindo todo o dinheiro disponível para a sua instituição dentro do fluxo do Pix. Ela é essencial para garantir a liquidez e a segurança das operações.

Para acessar os serviços relacionados a essa conta, utilize a URL:

- `<nome>.woovi.cloud/liquidation`

Os principais endpoints disponíveis são:

- `GET <nome>.woovi.cloud/liquidation/api/v1/balance`  
    Retorna o saldo atual da conta Liquidation, permitindo a verificação em tempo real antes de qualquer movimentação.
- `GET <nome>.woovi.cloud/liquidation/api/v1/statements`  
    Fornece o extrato completo da conta, detalhando todas as entradas e saídas realizadas ao longo do tempo.

**Importante:** qualquer tentativa de operação que exceda o saldo disponível na conta Liquidation será automaticamente bloqueada pela Woovi, como medida de segurança e controle financeiro. Portanto, é responsabilidade da instituição acompanhar e gerenciar esse saldo continuamente.

---

## Integrando Woovi com AWS Lambda

### Configurando a AWS CLI

Precisamos ter a `aws` CLI configurada também. É necessário, pois ela quem irá controlar toda
a questão de acesso para a sua conta e o script que vai fazer o _deploy_ da sua aplicação, via CDK.

Neste [link](https://aws.amazon.com/cli/), contém a instalação para a CLI de acordo com o seu
sistema operacional.

Depois disso será necessário que você configure a CLI a partir do comando: `aws configure`. Ele irá
pedir alguns valores como: `AWS Access Key ID`, `AWS Secret Access Key`, etc. Para entender como de
fato conseguir tais valores, sugerimos ver a documentação da própria [AWS](https://docs.aws.amazon.com/pt_br/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds), ela vai instruir o
passo a passo completo a respeito.

#### Referências

- [Instalação rápida da nova configuração](https://docs.aws.amazon.com/pt_br/cli/latest/userguide/getting-started-quickstart.html#getting-started-quickstart-new)

### Configurando o CDK

Primeiro de tudo, é necessário instalar o CDK. Para isso, como pré-requisito é necessário ter o 
[npm](https://www.npmjs.com/) instalado na sua máquina também (se preferir, pode usar o Yarn).

Após instalação do NPM, você irá instalar o toolkit da AWS CDK da seguinte forma:

```
npm install --global aws-cdk
```

Após finalizar, valide que tudo ocorreu da forma correta com:

```
cdk --version
```

#### Referências

- [Começando com o CDK](https://docs.aws.amazon.com/pt_br/cdk/v2/guide/getting_started.html#getting_started_install)

### Repositório de boilerplate para CDK + AWS Lambda

Para os próximos passos, temos um repositório com _boilerplate_. Caso for do seu
interesse para continuar as próximas etapas, você pode acessá-lo por [aqui](https://github.com/Open-Pix/aws-cdk-rest-lambda-boilerplate).

### Fazendo o _bootstrap_ do CDK

Por debaixo dos panos, o CDK utiliza outros recursos como os _buckets_ do S3, etc. Precisamos criar eles
para assegurar que todo o fluxo ocorra da forma correta. Para isso, execute:

```
cdk boostrap aws://ACCOUNT-NUMBER/REGION
```

Para você pegar tanto o `ACCOUNT-NUMBER` quanto a `REGION` desejada, caso não tenha em mãos,
via a AWS CLI que já utilizou anteriormente, execute o comando:

```
aws sts get-caller identity
```

Com isso você vai ver algumas informações a respeito da sua conta,incluindo `REGION`
e o `ACCOUNT-NUMBER`.

### Fazendo o deploy da minha stack CDK

Após configurar corretamente A CLI do CDK, precisamos fazer mais dois passos para, por fim, termos
nossa stack rodando na AWS:

Primeiro de tudo, vamos "sintetizar" a nossa aplicação, para ficar de acordo com o esperado pelo
CloudFormation, isto é, um serviço que é usado pela CDK, por debaixo dos panos, para lidar com
toda a responsabilidade de deployment, etc.

Para sintetizarmos, precisamos executar esse comando:

```
cdk synth
```

Isso vai fazer com que toda a sua aplicação converta para um formato YML amigável que será lido
pelo AWS CloudFormation.

---

Depois de sintetizado, basta fazer o _deploy_  da nossa stack, para isso execute o comando:

```
cdk deploy
```

Com isso, você conseguiu deployar a sua aplicação com sucesso! É possível acessar os recursos como:

- API Gateway
- Lambda

E ver que tudo foi deployado corretamente.

#### Referências

- [Sua primeira aplicação CDK](https://docs.aws.amazon.com/pt_br/cdk/v2/guide/hello_world.html)

## Como usar?

Para usar, precisamos ter três pontos configurados corretamente:

- API Gateway (você já configurou no ponto anterior);
- O webhook;

### Configurando o webhook

Para criarmos o webhook, acesse a [documentação](../webhook/platform/webhook-platform-api.mdx)
para criar o webhook dentro da nossa plataforma e clique no botão: `Novo webhook`.
Você irá cair neste formulário:

![Webhook](/img/integrations/new-webhook-form.png)

Preenchendo ele, você seguirá a seguinte ordem:

1. `Nome`, insira o nome que preferir para os webhooks.
2. `Evento`, neste caso, é o evento que esperamos acontecer para disparar o webhook,
você selecionará o evento de: **Transação Pix Recebida**.
3. `Url`, aqui, coloque a URL do API Gateway que vai servir como gatilho (trigger)
para a sua função Lambda.

Depois de preencher esses três campos, clique em `Salvar`. Parabéns, você criou seu
novo webhook!

Para mais informações a respeito de como configurar seu webhook, temos outras
documentações a respeito:

- [Criando um webhook para interceptar um Pix e chamar uma API](../webhook/platform/webhook-platform-api.mdx)
- [Configurando os cabeçalhos HTTP do meu webhook](../webhook/webhook-headers.mdx)

---

## Integrando Pix com o Discord

import Embed from 'react-embed';

### Como integrar o Pix com o Discord

---

## Como integrar a woovi com ecommerces

Para integrar ecommerces a proposta para desenvolvimento vai ser dividido em duas partes

## 1. Criar cobranças utilizando a woovi como meio de pagamento

### 1.1 Pré-requisitos

- 1. Ter uma conta na woovi
- 2. Ter um ecommerce
- 3. Criar um appID dentro da plataforma da woovi do tipo plugin
- 4. Salvar o appID dentro do ecommerce

### 1.2 Fluxo de criação de cobrança

Nesse ponto é esperado que o lojista já consiga fazer os seguintes passos

- 1. Se possível, visualizar o plugin da woovi no store do ecommerce
- 2. Instalar o plugin da woovi no ecommerce
- 3. Configurar o plugin da woovi no ecommerce ( colocar o appID  )
- 4. Criar uma cobrança dentro do ecommerce utilizando a woovi como meio de pagamento.
  - 4.1.  Quando a cobrança for criada é estritamente necessário ser salvo um correlationID dentro do   pedido do ecommerce, e o mesmo deve ser enviado na requisição para a api da woovi.
  - 4.2. O cliente final deve conseguir escolher a woovi como meio de pagamento
  - 4.3. O lojista deve conseguir visualizar esse pedido(charge) dentro da plataforma da woovi
  - 4.4. O lojista deve conseguir visualizar esse pedido(charge) dentro do ecommerce
  - 4.5. O cliente final deve conseguir visualizar esse pedido dentro da aba meus pedidos
- 5. Deve ser possível passar informações como email, nome, idade, e CPF

## 2. Após ser criada a cobrança, e paga pelo cliente final

### 2.1 Pré-requisitos

- 2. Criar um webhook dentro da plataforma da woovi do tipo CHARGE COMPLETED
- 1. Conseguir executar o fluxo de criação de cobrança
- 3. Abrir um endpoint no ecommerce para receber a notificação da woovi
- 4. Validar se a notificação é realmente da woovi ( PONTO PRINCIPAL )

Nesse ponto entra a parte de notificação, onde a woovi vai notificar o ecommerce que a cobrança foi paga sendo assim é esperado que:

- 1. Quando o cliente final pagar a cobrança, a woovi vai notificar o ecommerce
- 2. O plugin recebe a notificação e valida se a notificação é realmente da woovi
- 3. O plugin busca o pedido pelo correlationID e atualiza o status do pedido para pago
- 4. Após feita essa busca é esperado que atualize o pedido para pago.

---

## Integrando Pix com WhatsApp via Woovi + BotConversa

## 1. Criando o webhook no BotConversa

Dentro da seção `Automação`, acesse a opção de `Webhook`. Você irá cair nesta página:

![Criar um webhook dentro da plataforma BotConversa](/img/botconversa-create-webhook.png)

Clique no botão `Criar webhook`. Será adicionado um novo item a lista de webhooks,
você pode inserir o nome que desejar. Neste caso, vamos nomeá-lo como `Teste` por ora.

O que você deve estar vendo deverá ser algo semelhante a isto:

![Webhook do BotConversa criado](/img/botconversa-webhook-created.png)

Após criar o webhook em questão, você pode clicar no mesmo e será levado para uma tela
detalhando algumas informações e ações do respectivo webhook.

O que você estará vendo é semelhante a isto:

![BotConversa webhook detalhe](/img/botconversa-webhook-detail.png)

No lugar do borrão preto você estará vendo o respectivo URL do seu webhook, será esta
URL que você irá cadastrar na nossa plataforma.

Clique no botão `Copiar` para copiar o respectivo URL do seu webhook.

## 2. Criando o webhook na Woovi

Para criar o webhook na Woovi, recomendamos que você siga o nosso 
[tutorial](/docs/webhook/platform/webhook-platform-api).

### Requisição de teste do webhook

Após você adicionar o webhook, volte ao detalhe do webhook dentro do BotConversa.
Clique no botão `Receber dados`. Se tudo ocorreu bem, você verá uma opção contendo
a resposta a sua primeira requisição:

![Woovi webhook primeira resposta](/img/botconversa-webhook-first-response.png)

Essa será as informações que você verá na resposta da requisição do webhook.

Você pode ignorá-la por enquanto. A primeira requisição que fazemos em todo endpoint
de webhook é responsável por validar se é uma URL válida ou não, serve estritamente
para testar o endpoint em questão.

### Requisição válida do webhook

Após receber a requisição de teste, você será capaz de receber as requisições reais
do nosso webhook. Neste caso, selecionamos a opção de `Nova Cobrança criada` para
seguirmos com o tutorial. Portanto, após:

1. Criar uma nova cobrança dentro da Woovi
2. Pressionar o botão de reload no detalhe do webhook no BotConversa

O que você verá são as seguintes informações:

![Woovi webhook resposta de cobrança criada](/img/botconversa-webhook-valid-response.png)

Isso é um _payload_ válido de um webhook quando se cria uma cobrança. Ali estará contido informações
como: valor da cobrança, informações do cliente, link de pagamento, BR code para pagamento (Pix copia e cola),
entre outras informações úteis.

## 3. Configurando o contato do webhook no BotConversa

Após adicionar o webhook do BotConversa dentro da Woovi, é necessário adicionar o contato
que receberá a mensagem no WhatsApp.

Você verá o seguinte formulário:

![BotConversa estado inicial do formulário de contato](/img/botconversa-webhook-initial-form-contact.png)

Preencha ambas as informações de acordo com o esperado. Como no exemplo abaixo:

![BotConversa estado inicial do formulário de contato](/img/botconversa-webhook-filled-form-contact.png)

## 4. Iniciando o fluxo de conversa e enviando a mensagem

Caso opte pela maneira mais simples. Você pode adicionar uma nova ação e escolher a opção `Enviar mensagem`,
desta forma, você pode adicionar a mensagem que será enviada ao respectivo contato.

Porém, nós recomendamos que tais ações seja feitas a partir de um "Fluxo de conversa", isto garante
que você tenha um melhor controle e um melhor detalhamento a respeito de como e quando as mensagens
serão enviadas.

### Criando o fluxo de conversa

Para criar o fluxo de conversa, acesse a opção no `Fluxo de conversas` no menu lateral.
Você verá a seguinte tela:

![BotConversa - Fluxo de conversas](/img/botconversa-conversation-flow-screen.png)

Após acessar a tela, clique no botão `Criar`. Aparecerá um modal onde você poderá inserir o nome do
respectivo fluxo. Para este exemplo, nomearemos como `Teste`.

Após criar o fluxo, acesse-o clicando no mesmo. O que você irá ver é o detalhe do fluxo em questão.
As caixinhas são blocos de ações, você pode ver mais a respeito neste tutorial [aqui](https://ajuda.botconversa.com.br/construtor-de-fluxos-botconversa/fluxos-de-conversa/o-que-e-um-bloco-de-conteudo).

Seu fluxo estará semelhante a este aqui:

![BotConversa - Detalhe do fluxo de conversa](/img/botconversa-conversation-detail.png)

Clique no bloco de conteúdo. Você será capaz de inserir um texto da forma que preferir.
Também é possível separar em múltiplas mensagens ou adicionar outras lógicas a depender
do que precise.

### Associando o fluxo de conversa a ação do webhook

Após criar e configurar o seu fluxo de conversa, volte ao detalhe do respectivo webhook
e adicione mais uma ação.

Selecione a opção `Enviar fluxo` e selecione o fluxo que você acabou de criar (ou o
fluxo que você desejar).

![BotConversa - Ação de fluxo de conversa](/img/botconversa-webhook-flow-action.png)

O que você verá é algo semelhante a imagem acima.

Deste modo, você irá executar o fluxo de conversa de acordo com a execução do webhook
dentro do BotConversa.

Parabéns! Você configurou o BotConversa com a Woovi!

## 5. Passos adicionas (opcional)

### Adicionando dados do webhook ao texto do fluxo de conversa

Caso queira inserir dados e informações da resposta do webhook, assista o tutorial a seguir: 
[Webhook disponibilizado para BotConversa ser acionado por outros sistemas sem intermediários](https://us06web.zoom.us/rec/play/3Xj5dcuBRDULOApuSKMPgwJa4eCmjzHkyBwRXvgR4OHDKq2FZwyiE-YZ3Rweygr4qn8kOOo74Zcyffc7.6-YttRdjMSm1VdNm?startTime=1664975296000&_x_zm_rtaid=PZVKWRNiRkeAYNHwBjDPnA.1673398847814.5bd6a02e3760d79e2115e1c2c8286b28&_x_zm_rhtaid=589).

## 6. Materiais complementares da comunidade Woovi

- [Como Gerar um PIX no WhatsApp com Woovi e BotConversa via Make](https://www.youtube.com/watch?v=5wdp1lCwyYY)

<iframe width="560" height="315" src="https://www.youtube.com/embed/5wdp1lCwyYY?si=UNvkwTXheuXWqGYE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

---

## Integrando woovi com Bubble.io

:::info

Essa documentação assume que você tenha preenchido alguns requisitos que são:

1. Ter uma conta no [Bubble.io](https://bubble.io)
2. Ter uma aplicação criada na woovi. Caso ainda não tenha feito, você pode criar uma seguindo [este tutorial](../apis/api-getting-started.md).

:::

## 1. Criando um App no Bubble.io

:::info

Caso você já tenha um App criado no [https://bubble.io](https://bubble.io), esse passo é opcional.

:::

Após acessar a home do [https://bubble.io](https://bubble.io). Você irá estar vendo uma tela similar a esta:

![Bubble.io Home Page](./__assets__/bubbleio-home-page.png)

Clique no botão `Create an app`. Irá aparecer um modal com as informações necessárias para criar um novo app. Selecione o plano do seu novo App.

Em seguida, você poderá estar optando por seguir o passo a passo de assistência do Bubble. Ele irá te ajudar a adicionar as configurações básicas para o seu site.

## 2. Adicionando um novo plugin

Caso o cadastro de um novo App tenha ocorrido com sucesso, você será redirecionado para uma página similar a esta:

![Bubble.io App detail page](./__assets__/bubbleio-app-page.png)

Para estar adicionando um novo plugin você deve selecionar a opção `Plugins`, na barra lateral à esquerda.

Pós acessar esta página, você será redirecionado para a seguinte página:

![Bubble.io plugins page](./__assets__/bubbleio-plugins-page.png)

Selecione a opção `Add plugins`, e logo em seguida clique no botão `Install` do plugin `API Connector`.

![Bubble.io plugins list](./__assets__/bubbleio-plugins-list.png)

Se a instalação ocorreu bem, você verá a seguinte tela:

![Bubble.io plugins installed](./__assets__/bubbleio-plugins-installed.png)

Você instalou com sucesso o plugin de API no Bubble.io!

## 3. Adicionando a API da woovi no API Connector

Pós instalar o `API Connector` dentro do Bubble.io, é necessário adicionar uma nova API.

Na tela do detalhe do plugin de `API Connector`, selecione a opção `Add another API`. Você verá uma tela similar a esta:

![Bubble.io API connector](./__assets__/bubbleio-api-connector-api.png)

Preencha as informações necessárias levando em consideração os seguintes pontos:

1. Dê um nome pra sua API no campo de `API Name`, garantindo que seja fácil identificar essa nova API.
2. No campo `Authentication`, selecione a opção: `Private key in header`.
3. Irá aparecer uma seção abaixo contendo os seguintes fields: `Key name` e `Key value`. Preencha-os da seguinte forma:
   - **Key name:** `Authorization`
   - **Key value:** O AppID da sua aplicação woovi.

:::info

Caso tenha dúvida em como pegar o `AppID` da sua aplicação woovi.

Siga este tutorial [aqui](../apis/api-getting-started.md).

:::

Os campos devem estar preenchidos de forma similar a imagem abaixo:

![Bubble.io API connector fields](./__assets__/bubbleio-api-connector-fields.png)

Dessa forma, você já fez a etapa de autenticação e autorização para estar consumindo a API da woovi de forma segura.

## 4. Consumindo um endpoint da woovi via Bubble.io

Neste mesmo campo do API Connector, ele irá adicionar uma nova chamada para um endpoint, você pode estar clicando no botão `Expand`, no canto direito e verá algo similar a imagem a seguir:

![Bubble.io API connector endpoint](./__assets__/bubbleio-api-connector-endpoint.png)

Conforme a documentação da [API da woovi](/api), vamos preencher estes campos com:

- O endpoint que deseja consumir;
- Os headers necessários;
- O body da requisição (caso necessário);

No exemplo abaixo, estamos consumindo o endpoint para criar uma cobrança Pix. Para _quaisquer_ endpoints, a chamada deve estar configurada de forma similar.

![Endpoint call](./__assets__/bubbleio-api-connector-endpoint-call.png)

Nesse caso, se atente aos seguintes pontos:

1. Colocamos o `Use as`, como `Action`. Isso permite que você possa estar acoplando ele ao click de um botão ou alguma outra ação do seu site.
2. Adicionar um novo header chamado `Content-Type` com valor `application/json`.
3. Troque o `Body type` para `Raw`. Isso vai impedir do Bubble formatar os valores presentes no body.
4. Adicione o body da requisição conforme o JSON esperado pelo endpoint.

Após preencher estes pontos, você pode estar clicando no botão `Initialize call`.

Se tudo foi preenchido corretamente, você verá um modal com o payload de resposta daquele endpoint.

Por fim, você integrou com sucesso a woovi ao Bubble.io!

---

## Integrando a woovi com a Shop Control 9

:::info

Essa documentação assume que você tenha preenchido alguns requisitos que são:

1. Ter uma aplicação criada na woovi. Caso ainda não tenha feito, você pode criar uma seguindo [este tutorial](../apis/api-getting-started.md).

:::

### 1. Acesse a seção `CADASTROS` e, em seguida, `FINANCEIRO`

![Shop9 register page](./__assets__/slide1-shop9.png)

### 2. Navegue até a opção `CONTAS BANCÁRIAS`

![Shop9 financial page](./__assets__/slide2-shop9.png)

### 3. Selecione a conta bancária correspondente

Nesta etapa, é necessário selecionar a conta bancária previamente cadastrada na Shop Control 9.

![Shop9 Banck Account page](./__assets__/slide3-shop9.png)

### 4. Cadastro do AppID

Agora, dirija-se à seção `PIX`, localize o campo `API KEY`, insira o AppID previamente gerado na plataforma woovi e finalize clicando em `GRAVAR`.

![Shop9 pix api page](./__assets__/slide4-shop9.png)

---

## Integrando a woovi com a Tracken

# Como Integrar a woovi com a Tracken?

Se você está buscando integrar a woovi com a Tracken, siga este guia passo a passo para realizar essa integração de forma eficaz.

## Passo 1: Acesso à Plataforma woovi

Para iniciar o processo de integração entre a woovi e a Tracken, acesse a plataforma woovi usando suas credenciais de acesso. Certifique-se de que você tenha permissões adequadas para criar uma nova API e que a sua conta virtual esteja ativa.

## Passo 2: Acessando a Seção de API/Plugin

Dentro da plataforma woovi, localize o menu "API/Plugin" na aba de navegação à esquerda.

![1](./__assets__/integrating-woovi-with-tracken-1.png)

## Passo 3: Criando uma Nova API

No menu "API/Plugin", procure e clique no botão "Nova API". Esse botão geralmente está localizado no canto superior direito da tela.

## Passo 4: Configurando a API para a Tracken

Ao criar uma nova API, você precisará configurar as informações corretas para a integração com a Tracken. Siga estas etapas:

### 4.1. Nome da API

Dê um nome descritivo para a nova API. Neste caso, nomeie-a como "Tracken" para facilitar a identificação.

### 4.2 Tipo de API

Selecione o tipo de API como "REST". Isso garante que a comunicação entre a woovi e a Tracken siga os padrões de integração RESTful.

### 4.3. Salvar

Após inserir as informações necessárias, clique no botão "Salvar" ou equivalente para criar a nova API com as configurações da Tracken.

![2](./__assets__/integrating-woovi-with-tracken-2.png)

## Passo 5: Obtenção do APPId

Após salvar a nova API, a plataforma woovi gerará um código chamado "APPId". Este código é essencial para a integração com a Tracken. Anote ou copie esse código, pois você precisará compartilhá-lo com a equipe da Tracken.

![3](./__assets__/integrating-woovi-with-tracken-3.png)

## Passo 6: Compartilhando o Código com a Tracken

Agora que você tem o código APPId gerado pela woovi, entre em contato com a Tracken e informe que deseja realizar a integração com a woovi. Forneça o código APPId para que a Tracken possa configurar a integração corretamente do lado deles.

## Conclusão

A integração entre a woovi e a Tracken é um processo fundamental para aproveitar ao máximo as capacidades dessas duas plataformas. Ao seguir este guia passo a passo e compartilhar o código APPId com a Tracken, você estará bem encaminhado para garantir uma integração bem-sucedida e eficiente entre as duas soluções. Certifique-se de manter uma comunicação clara e contínua com ambas as equipes para garantir que a integração atenda às suas necessidades específicas.

---

## Integrando woovi com Typebot

:::info

Essa documentação assume que você tenha preenchido alguns requisitos que são:

1. Ter uma conta no [Typebot](https://typebot.io/)
2. Ter um fluxo já criado no [Typebot](https://typebot.io/)
3. Ter uma aplicação criada na woovi. Caso ainda não tenha feito, você pode criar uma seguindo [Introdução à API Woovi](../apis/api-getting-started.md).

:::

## Criando uma cobrança utilizando o Typebot

Para está criando uma cobrança no Typebot é necessário que você utilize a caixinha `HTTP request`, você pode está localizando ela na seção de `Integrations` no Typebot.

![1](./__assets__/integrating-woovi-with-typebot-1.png)

Após isso, clique na caixinha para efetuar a configuração da mesma.

![2](./__assets__/integrating-woovi-with-typebot-2.png)

Quando abrir o _pop-up_, selecione a opção `Advanced configuration`.

Antes de partimos para a requisição que irá criar a cobrança, vamos fazer uma requisição que será responsável por criar o ID único da mesma.

Para isso, basta você especificar a seguinte configuração na caixinha:

- **URL**: `https://www.uuidgenerator.net/api/version4`

![3](./__assets__/integrating-woovi-with-typebot-3.png)

Nessa parte, vamos utilizar a API da woovi de criação de cobrança (segue o [link](/api#tag/charge/POST/api/v1/charge) da especificação), ou seja, vamos configurar com as seguintes informações:

Aqui está um exemplo da URL e o corpo da requisição:

- **URL**: `https://api.woovi.com/api/v1/charge`
- **Body**:
  ```json
  {
    "value": 100, // O valor da sua preferência
    "correlationID": "d4c681a0-5d28-4ba0-b66b-3ea3cc158388" // ID único da cobrança
  }
  ```

![4](./__assets__/integrating-woovi-with-typebot-4.png)

Após isso, seu fluxo de criação de cobrança está pronto para uso!

Segue uma imagem de como o fluxo ficou na forma final:

![5](./__assets__/integrating-woovi-with-typebot-5.png)

Caso queirar importar o fluxo criado nesse tutorial, basta baixar [aqui](./__assets__/typebot-flow.json).

---

## Como ativar a emissão de nota fiscal eletrônica de serviço

:::info

A integração de nota fiscal eletrônica está disponível apenas por solicitação via chat.

:::

:::caution

Essa documentação espera que você já tenha uma conta virtual criada na woovi.

:::

## 1. Adicionando a integração

Para começar a emitir notas fiscais, você deve adicionar a integração de notas fiscais. Para isso você pode seguir esses dois caminhos:

- Acessando diretamente o formulário de criação, clicando [aqui](https://app.woovi.com/home/integration-nfeio/tutorial);
- Após acessar a plataforma da [woovi](https://app.woovi.com/home), você pode acessá-lo através do menu, clicando em:
  1. API/Plugins;
  2. Nota fiscal eletrônica;
  3. Clique no botão `Adicionar`;

Após seguir um desses fluxos, você será redirecionado para a página de ativação da integração

## 2. Configurando a integração

Após clicar em ativar agora, você será redirecionado para a página de ajustes da integração e será necessário preencher algumas informações fiscais da sua empresa, essas informações garantem a conformidade tributária e podem ser facilmente obtidas com o auxílio do seu contador:

![Formulário de informações fiscais](./__assets__/invoice-tax-form.png)

1. **Assinatura municipal (código municipal):** Código fornecido pela prefeitura para identificação do prestador de serviço no município, necessário para emissão de nota fiscal eletrônica.
2. **Número de rps**: O Número do Recibo de Serviço Provisório é um número que identifica a transação antes da conversão em fatura eletrônica.
3. **Regime de imposto especial**: Indicação de impostos específicos aplicáveis ao serviço prestado, conforme legislação local ou federal.
4. **Código de serviço**: Identificador do tipo de serviço prestado, conforme a lista de serviços municipais, para cálculo correto de impostos e tributos..
5. **Regime tributário**: Categoria tributária da empresa, utilizada para determinar como são calculados os impostos e obrigações tributárias.

Logo após preencher e salvar as informações fisicais da sua empresa, você deverá verificar se a prefeitura da sua cidade requer credenciais para emitir notas fiscais, você fazer essa verificação entrando no serviço web da sua prefeitura. Caso seja necessário, preencha os campos mostrados abaixo com as devidas credencias e clique em `Salvar`:

![Formulário de credenciais](./__assets__/invoice-credentials.png)

Por fim, você deverá fazer o upload do seu certificado digital A1, assim como digitar a senha do documento no campo indicado conforme a imagem abaixo:

![Formulário do certificado A1](./__assets__/invoice-a1-certificate.png)

## 3. Finalizando a configuração

1. Depois de preencher todos os dados e enviar o certificado, o último passo é emitir uma nota fiscal de teste para validar a integração. Então você pode clicar no botão `Emissão de teste`, conforme a imagem abaixo:

![Botão de teste da emissão de nota fiscal](./__assets__/invoice-issue-test.png)

2. Após clicar no botão `Emissão de teste`, você será redirecionado para a página de detalhes da integração e será possível ver os dados enviados assim como o atual estado da integração, que após ser validado pelo nosso provedor de nota fiscal deverá ficar como abaixo:

![Card de detalhes da integração](./__assets__/invoice-integration-details-card.png)

3. Você pode visualizar os detalhes da nota fiscal gerada clicando nela na tabela acima. Ao clicar você será redirecionado para a página de detalhes da nota fiscal e é possível ver as informações da nota e o documento PDF clicando em `Ver nota fiscal`

![Card de detalhes da nota fiscal eletrônica](./__assets__/invoice-details.png)

4. Depois de verificar o documento da nota fiscal de teste gerada com o seu contador, você já pode começar a emitir notas fiscais na plataforma!

## 4. Lidando com falhas de validação ou mudanças de dados

Caso ocorra algum problema na etapa de validação dos dados, você pode clicar em `Editar` no canto inferior, corrigir os dados e refazer o fluxo de teste da nota fiscal de novo. Também, caso seja preciso atualizar os dados, você pode seguir os mesmos passos para atualizá-los.

![Card de detalhes da integração](./__assets__/invoice-edit-integration.png)

---

## Como emitir uma nota fiscal manualmente

:::caution

Essa documentação espera que você já tenha configurado a integração de nota fiscal eletrônica

:::

## 1. Ativando a emissão de nota fiscal eletrônica manual

Já configurado a integração, você pode habilitar a emissão selecionando a opcão `Ativo` e clicando em `Salvar` na página de configurações como visto embaixo.

![Ativar emissão de nota fiscal eletrônica](./__assets__/invoice-activate-issuing.png)

## 2. Emitindo uma nota fiscal eletrônica para cobranças pagas

:::caution

É possível emitir apenas uma nota fiscal por cobrança, porém caso a emissão falhe, é possível fazer uma nova emissão

:::

Para emitir uma nota fiscal, você deve:

1. Ir para a página de detalhes da cobrança
2. Clicar em `Emitir nota fiscal eletrônica`, como na imagem abaixo

![Emitir nota fiscal de uma cobrança](./__assets__/invoice-charge-issue.png)

3. Confirmar emissão de nota fiscal.

## 3. Visualizar notas fiscais emitidas

Logo abaixo os detalhes da cobrança, é possível encontrar a lista de notas fiscais emitidas.

![Emitir nota fiscal de uma cobrança](./__assets__/invoice-list.png)

---

## Como criar uma cobrança Pix via woovi usando Make?

Esse tutorial tem como objetivo realizar um passo a passo de como integrar nossa API
usando a ferramenta [Make](https://make.com/).

## Pré-requisitos

Caso deseje realizar a integração, é necessário que você já tenha se cadastrado na woovi,
e por fim tenha já criado uma nova API na nossa plataforma. Caso ainda não tenha feito isso,
você pode seguir o tutorial de como criar uma nova API [Introdução à API Woovi](../../apis/api-getting-started.md).

## 1. Adicionando o módulo para chamadas HTTP

Para realizar chamadas HTTP dentro de um cenário do Make, é necessário a utilização de um módulo
chamado `HTTP`.

![Adicionando módulo HTTP no cenário Make](./__assets__/make-add-http-module.png)

Conforme a imagem acima, basta procurar o módulo HTTP e adicioná-lo no seu cenário.

## 2. Fazendo uma requisição com o módulo HTTP

Após adicionar o módulo HTTP, você pode fazer uma requisição para a nossa API. Utilizando a seguinte
funcionalidade do módulo: `Fazer uma requisição` (pode estar em inglês, com o seguinte nome: `Make a request`).

![Fazendo uma requisição](./__assets__/make-make-a-request.png)

Após selecionar esta opção, você verá as seguintes opções conforme a imagem acima:

- `URL`: será inserido a URL referente a nossa API contendo o endpoint que deseja acessar.
  Para o nosso exemplo, estaremos usando o endpoint para criar uma cobrança (`https://api.woovi.com/api/v1/charge`),
  você poderá acessar todos os endpoints disponíveis pela nossa API a partir da [nossa documentação](/api).
- `Método`: o método HTTP que deseja utilizar, para criar uma nova cobrança, é necessário o método `POST`.
- `Headers`: os headers que irão na requisição, será necessário inserir um header `Authorization` com o valor disponibilizado pelo AppID.

Conforme nosso exemplo, após preencher todos os campos, você verá algo similar a imagem abaixo:

![Campo de requisições preenchidos](./__assets__/make-make-a-request-filled.png)

:::info

Lembre-se de inserir corretamente os seguintes pontos na sua requisição:

- `Body type` sendo `RAW`, dessa forma te permite passar um JSON no corpo da requisição, caso necessário.
- `Content-type` sendo `JSON (application/json)`, para que a API entenda que o corpo da requisição é um JSON.

Não esqueça de formatar corretamente o conteúdo da sua requisição, para garantir que esteja de acordo com um JSON
válido.

:::

## 4. Testando a requisição

Após preencher todos os campos, você pode clicar no botão `Rodar uma vez`, para realizar a requisição.

Se tudo ocorrer bem, você verá a resposta da requisição contendo na resposta o _status code_ `200`, e o campo
de `Data` contendo as informações da cobrança criada. Como no exemplo abaixo:

![Requisição HTTP feita com sucesso](./__assets__/make-request-done.png)

## 5. Utilizando esse módulo

Sua integração com a API da woovi já foi realizada com sucesso! Você pode estar colocando esse módulo
HTTP e acoplá-lo a outros cenários do Make, conforme a necessidade do seu fluxo.

---

## Integrando Webhook Pix com o N8N

import Embed from 'react-embed';

## Como integrar o Webhook Pix com o N8N

## Documentação

1. Crie uma API na Woovi [aqui](../apis/api-getting-started.md#passo-1---criar-um-novo-aplicativo)
2. Copie o AppID
3. Acesse a sua instância do N8N
4. Acesse `Configurações` > `Community nodes`
   4.1 Clique em `Install` e pesquise por `n8n-nodes-woovi`
   ![OpenPix Trigger](./__assets__/install-node.png)

5. Crie um novo Workflow e utilize o nó `Woovi Trigger`

![Woovi nodes](./__assets__/select-woovi-nodes.png)

---

## Integração N8N com Woovi

## O que é o N8N + Woovi?

O N8N é uma ferramenta de automação de fluxo de trabalho que permite que você conecte vários aplicativos e serviços para criar fluxos de trabalho automatizados. O N8N é uma ferramenta de código aberto e gratuita que pode ser executada localmente ou em um servidor.
A Woovi é uma plataforma de pagamentos e vendas que permite a você: criar cobranças automatizadas, realizar reembolsos e consultar transações e muito mais de forma simples e rápida.

## Como instalar o nó da Woovi no N8N?

Para encontrar o nó da Woovi no N8N, você deve:

1. Ir até a aba de configurações
2. Clica em “Community Nodes”
3. Clicar em instalar
4. Pesquisar por `n8n-nodes-woovi`

## O que é possível fazer com o nó da Woovi no N8N?

Com o nó da Woovi você consegue:

- Criar cobranças
- Buscar por cobranças (Request Access)
- Reembolsar cobranças (Request Access)
- Realizar saques (Request Access)

## Como configurar o nó da Woovi no N8N?

Primeiro, dentro do N8N:

1. Clique em “Credentials”
2. Clique em Add Credential
3. Selecione o tipo de credencial “Woovi API”
4. Preencha o campo de API Key com o seu APP ID
   4.1. Você pode encontrar o seu APP ID na aba de aplicações/plugins ou criar um novo [documentação](../apis/api-getting-started)

## Como criar cobrança usando N8N?

Dentro do seu Workflow, você deve:

1. Buscar pelo nó da Woovi
   ![Woovi nodes](./__assets__/select-woovi-nodes.png)
2. Selecionar a credencial que você criou
3. Preencher os campos de value com o valor desejado da cobrança em centavos
4. Preencher o campo de description com um correlationID único para cada cobrança

---

## Integração N8N com woovi sem o nosso Plugin

:::info
Antes de começar, certifique-se de ter configurado seu acesso à API da woovi. 
Você pode encontrar o guia completo de como obter suas credenciais em nossa [documentação de API Getting Started](/docs/apis/api-getting-started).
:::

## Como integrar o N8N com a woovi sem usar o plugin?

Você pode integrar a woovi com o N8N utilizando o nó HTTP Request nativo do N8N. Este guia mostrará como configurar e usar os endpoints da API da woovi.

### Pré-requisitos

1. Uma conta N8N
2. Seu APP ID da woovi (disponível na aba de aplicações/plugins)
3. Acesso à API da woovi

## Criando um Workflow para Criar Cobranças

1. Crie um novo workflow no N8N
2. Adicione um nó "HTTP Request"
3. Configure o nó com as seguintes propriedades:
   - Authentication: Matennha em "none"
   - Method: POST
   - URL: `https://api.woovi.com/api/v1/charge`
   - Send Headers: true
    - Adicione o header "Authorization" com seu `appID`
   - Send Body: true
   - Body Parameters:
    - Body Content Type: Coloque em "JSON"
    - Specify Body: Use o JSON
   - Adicione o corpo da requisição
```json
{
  "correlationID": "meu-correlation-id",
  "value": 200,
  "comment": "meu comentario"
}
```
![](./__assets__/n8n-without-plugin/create-charge/body-and-header-configuration.png)

Ao clicar em "Test step" você receberá uma saida similar a esta confirmando a criação da cobrança
![](./__assets__/n8n-without-plugin/create-charge/output-create-charge.png)

## Criando um Workflow para Consultar Cobranças

1. Adicione um nó "HTTP Request"
2. Configure o nó com as seguintes propriedades:
   - Authentication: Mantenha em "none"
   - Method: GET
   - URL: `https://api.woovi.com/api/v1/charge/MEU_CORRELATION_ID`
    - Substituia na URL o `MEU_CORRELATION_ID` pelo seu id de correlação
   - Send Headers: true
    - Adicione o header "Authorization" com seu `appID`
  - Send Body: false

![](./__assets__/n8n-without-plugin/get-charge/body-and-header-configuration.png)

Ao clicar em "Test step" você receberá uma saida similar a esta confirmando a criação da cobrança
![](./__assets__/n8n-without-plugin/get-charge/output-get-charge.png)

## Criando um Workflow para Reembolsar Cobranças

1. Adicione um nó "HTTP Request"
2. Configure o nó com as seguintes propriedades:
   - Authentication: Mantenha em "none"
   - Method: POST
   - URL: `https://api.woovi.com/api/v1/charge/MEU_CORRELATION_ID/refund`
    - Substituia na URL o `MEU_CORRELATION_ID` pelo seu id de correlação
   - Send Headers: true
    - Adicione o header "Authorization" com seu `appID`
   - Send Body: true
   - Body Parameters:
    - Body Content Type: Coloque em "JSON"
    - Specify Body: Use o JSON
   - Adicione o corpo da requisição
     ```json
     {
       "correlationID": "meu-refund-correlation-id"
     }
     ```

![](./__assets__/n8n-without-plugin/refund-charge/body-and-header-configuration.png)

Ao clicar em "Test step" você receberá uma saida similar a esta confirmando o reembolso da cobrança
![](./__assets__/n8n-without-plugin/refund-charge/output-refund-charge.png)

## Criando um Workflow para Escutar Webhooks da woovi

O primeiro passo é adicionar um nó "Webhook" ao seu workflow. Este nó será responsável por receber as notificações da woovi.

1. Adicione um nó "Webhook" ao seu workflow
2. Configure o nó com as seguintes propriedades:
   - HTTP Method: POST
   - Path: `webhook` (ou qualquer outro caminho que você preferir)

![](./__assets__/n8n-without-plugin/webhooks/configuration.png)

## Configurando o novo Webhook na woovi

1. Copie a URL do webhook que o N8N gerou (você pode encontrar esta URL na aba "Test" do nó Webhook)
2. Acesse o [Dashboard da woovi](https://app.woovi.com)
3. Vá para a seção "API/Plugins" e clique em "Novo Webhook"
4. Garanta que a opção "Ativo" esteja habilitada, dê um nome para o webhook, configure o tipo de evento a ser escutado e cole a URL do webhook do N8N no campo "URL"
5. Selecione os eventos que você deseja receber notificações. Os eventos disponíveis são:
   - OPENPIX:CHARGE_CREATED - Nova Cobrança Criada
   - OPENPIX:CHARGE_COMPLETED - Cobrança Paga
   - OPENPIX:CHARGE_EXPIRED - Cobrança Expirada
   - OPENPIX:CHARGE_COMPLETED_NOT_SAME_CUSTOMER_PAYER - Cobrança Paga por Outra Pessoa
   - OPENPIX:TRANSACTION_RECEIVED - Transação Pix Recebida
   - OPENPIX:TRANSACTION_REFUND_RECEIVED - Reembolso Concluído
   - OPENPIX:MOVEMENT_CONFIRMED - Pagamento Externo Confirmado (Pix Out)
   - OPENPIX:MOVEMENT_FAILED - Pagamento Externo com Falha (Pix Out)
   - OPENPIX:MOVEMENT_REMOVED - Pagamento Externo Removido (Pix Out)
   - OPENPIX:DISPUTE_CREATED - Disputa Criada
   - OPENPIX:DISPUTE_ACCEPTED - Disputa Aceita
   - OPENPIX:DISPUTE_REJECTED - Disputa Rejeitada
6. Clique em "Salvar"

![](./__assets__/n8n-without-plugin/webhooks/woovi-create-webhook.png)

Ao receber um webhook da woovi, você verá uma saída similar a esta:
![](./__assets__/n8n-without-plugin/webhooks/output-webhook.png)

## Dicas Importantes

1. Sempre use o correlationID único para cada cobrança
2. O valor deve ser enviado em centavos (ex: R$ 10,00 = 1000)
3. O correlationID de refund deve ser diferente do correlationID usado na criação de uma cobrança
4. Teste seus workflows em ambiente de desenvolvimento antes de usar em produção

## Documentação Técnica

Para mais detalhes sobre os endpoints, payloads e respostas da API, consulte nossa [documentação técnica completa](/api).

---

## Como funciona a integração OneClick com woovi?

## O que é o OneClick Integration

OneClick Integration é a feature criada exclusivamente pela woovi, responsável por integrar todas as plataformas de ecommerce e integrações de pagamento com a woovi.

## Como funciona a integração OneClick com woovi?

### 1. Criando o plugin

Ao criar o plugin que será integrado é necessário que seja possível salvar o appID, que é o responsável por identificar a aplicação que está realizando a integração. Para isso, é necessário criar um campo de texto para que o usuário possa salvar o appID, também possível que seja apenas um cache dentro de sua aplicação

### 2. Endereço de callback

O primeiro passo é possuir um endereço de url que será responsável por receber as requisições da woovi.
Ex: [https://www.suaaplicacao.com.br/woovi](https://www.suaaplicacao.com.br/woovi)

### 3. Criando a integração

Ao inserir a sua integração dentro do nosso formulário de oneclick( ex: [https://app.woovi.com/home/applications/magento2/add/oneclick](https://app.woovi.com/home/applications/magento2/add/oneclick)) será necessário apenas preencher o campo de callback com o endereço de callback que foi criado no passo 2.

### 4. Recebendo as requisições

Serão enviados duas chamadas para o endereço de callback, ambas do método POST

#### 4.1. Primeira chamada

A primeira chamada será uma teste, para identificar se o seu endpoint existe e está funcionando corretamente. O corpo da requisição será:

```json
{
  "data_criacao": "2023-07-12T13:58:06.821Z",
  "evento": "teste_webhook",
  "event": "OPENPIX:TRANSACTION_RECEIVED"
}
```

Você pode simular utilizando o seguinte comando bash :

```bash
curl -X 'POST' \
 'www.suaurl.com.br' \
 -H 'connection: close' \
 -H 'accept-encoding: gzip,deflate' \
 -H 'content-length: 68' \
 -H 'user-agent: node-fetch' \
 -H 'x-webhook-signature: ntX9Ix69oUV5OQK9dIhZaw/ovjPTMoGqzEYi/OQm05/7ceMQhj7wOvhkHYgP6Q4aLeeBeRxpaAtglR3V19YXyPvqr412RSJ40EGAe+OG8QIkc4RqYP4g7krINNQJOPZ1JSY3qLoIEX0SLRjAunOabnw+P05Xrizi5Fgn4YzkuoE=' \
 -H 'x-woovi-authorization: ' \
 -H 'content-type: application/json' \
 -H 'accept: application/json' \
 -d $'{"data_criacao":"2023-07-12T13:58:06.821Z","evento":"teste_webhook","event":"OPENPIX:TRANSACTION_RECEIVED"}'
 ```

#### 4.2. Segunda chamada

A segunda chamada será enviada somente se a primeira requisição retornar o status code 200 em seu endereço.
Ela é a responsável por enviar o appID em que você ira salvar dentro de sua integração

O corpo dessa requisição será

```json
{
  "event": "magento1-configure",
  "appID": "Q2xpZW50X0lkX2UwY2YyMTI2LWU0MGEtNDY4Yi05YmU2LTQ2ODg0ZTkzMTEwMDpDbGllbnRfU2VjcmV0XzQ1VUJYaU5VM2E1SGEvNnZTOGtCeEgzR1pRL0dOSmc0bTQ5ZGkyZ1g0bHc9",
  "date": "2023-07-12T13:58:05.996Z"
}
```

Você pode simular utilizando o seguinte comando bash :

```bash
curl -X 'POST' \
  'www.suaurl.com.br' \
 -H 'connection: close' \
 -H 'accept-encoding: gzip,deflate' \
 -H 'content-length: 218' \
 -H 'accept: */*' \
 -H 'user-agent: node-fetch' \
 -H 'content-type: application/json' \
 -H 'x-webhook-signature: IJ33ocEdFz8GM/I2n8tOK8WAyHlDBFIDZ0zVijrrGm/VL8K3AiFrIwNSbxSk0ZRX2hD5FTwmFOaToJd/4YD75j8rhl8alIRx+CjtJ4kJK5svpdTwia5fV2bTNp0MQV6VXnZM5cj26H7it3CCVq5dhtbcMcyBLfY96iQ6CvT9CKs=' \
 -d $'{"event":"woocommerce-configure","appID":"Q2xpZW50X0lkX2UwY2YyMTI2LWU0MGEtNDY4Yi05YmU2LTQ2ODg0ZTkzMTEwMDpDbGllbnRfU2VjcmV0XzQ1VUJYaU5VM2E1SGEvNnZTOGtCeEgzR1pRL0dOSmc0bTQ5ZGkyZ1g0bHc9","date":"2023-07-12T13:58:05.996Z"}'
 ```

### 5. Salvar o appID

Ao receber a segunda chamada é esperado que você salve o appID em sua integração, e enviá-lo em todas as requisições que forem realizadas para a woovi.

---

## Integrando Pix com o Google Sheets

import Embed from 'react-embed';

## Como integrar o Pix com o Google Sheets

---

## Como migrar para o novo aplicativo Shopify?

import Embed from 'react-embed';

:::info

O novo aplicativo permite utilizar a nova funcionalidade de Checkout transparente da shopify

:::

## Funcionamento do novo checkout transparente na Shopify

## 1. Desinstale o antigo aplicativo woovi

:::caution

A desinstalação do antigo aplicativo é importante para evitar conflitos entre a nova versão do woovi e a Shopify.

:::

Acesse o painel da Shopify e clique na área de Configurações.

![Shopify install step 1](./__assets__/shopify-uninstall-step-1.png)

No menu lateral, acesse a opção Pagamentos e clique sobre o aplicativo woovi.

![Shopify install step 1](./__assets__/shopify-uninstall-step-2.png)

Clique no botão Desativar.

![Shopify install step 1](./__assets__/shopify-uninstall-step-3.png)

Confirme a desativação clicando novamente em Desativar.

![Shopify install step 1](./__assets__/shopify-uninstall-step-4.png)

Após desativar, clique no botão Desinstalar.

![Shopify install step 1](./__assets__/shopify-uninstall-step-5.png)

Confirme a desinstalação clicando em Desinstalar.

![Shopify install step 1](./__assets__/shopify-uninstall-step-6.png)

Pronto! O aplicativo foi desinstalado com sucesso. Agora podemos prosseguir com a instalação da nova versão.

![Shopify install step 1](./__assets__/shopify-uninstall-step-7.png)

## 2. Instalar o novo aplicativo woovi Pay

Para integrar sua loja Shopify com a woovi, é necessário instalar o aplicativo woovi diretamente pela Shopify.

- Acesse nosso aplicativo na Shopify: [Plugin Woovi](https://apps.shopify.com/openpix-pay-app-prod)

Após acessar a página inicial, selecione a loja que deseja instalar o aplicativo:

![Shopify install step 1](./__assets__/shopify-install-step-1.png)

Após selecionar a loja, clique em Instalar:

![Shopify ](./__assets__/shopify-install-step-2.png)

O Shopify irá redirecioná-lo para o painel de instalação do aplicativo.

![Shopify install step 1](./__assets__/shopify-install-step-3.png)

Clique novamente no botao `Instalar`. Você será redirecionado para nossa plataforma, e a integração acontecerá de forma automática.

:::info

Caso não esteja logado na plataforma, basta continuar a autenticação e o fluxo de instalação seguirá automaticamente.

:::

![Shopify install step 1](./__assets__/shopify-install-step-4.png)

Após a integração dentro de nossa plataforma ser concluída, você será redirecionado novamente para o Shopify para ativar o aplicativo.

:::caution

Caso a instalação seja feita em uma loja de produção, desabilite o modo de teste.

:::

![Shopify install step 1](./__assets__/shopify-install-op.png)

Basta clicar em Ativar, e estará pronto para utilizar.

![Shopify install step 1](./__assets__/shopify-install-step-6.png)

---

## Como buscar as Orders criada pela woovi via Shopify?

:::note

Como pré-requisito, é necessário fazer uma configuração para consumir a API da Shopify.
Recomendamos seguir as documentações abaixo que estará instruindo como consumir a API independente
da linguagem utilizada.

- [Shopify GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql)

:::

Caso você queira acessar as informações das `Orders` criadas na Shopify a partir do nosso app `woovi`,
é necessário estar utilizando a API de `Orders` que a Shopify fornece: [Order API](https://shopify.dev/docs/api/admin-graphql/2023-07/queries/orders).

Nesse caso, será necessário estar realizando uma query pro campo `orders` filtrando as orders pelo gateway `woovi`,
conforme o exemplo abaixo:

```graphql
{
  orders(first: 100, query: "gateway:woovi") {
    edges {
      node {
        id
        name
        transactions {
          gateway
          paymentId
	      }
      }
    }
  }
}
```

Dado esse exemplo, estamos buscando **TODAS** as orders criadas a partir do gateway de pagamentos `woovi`,
e buscando pelos seguintes dados:

- `name`, é o antigo `order_number`, é o número da Order que a Shopify mostra no dashboard;
- `id`, o identificador único daquela cobrança;
- `transactions`, as transações relacionadas àquela Order, contendo:
  - `gateway`, qual gateway gerou aquela cobrança, no caso `woovi`,
  - `paymentId`, o identificador único daquela transação, caso exista.

Você pode estar buscando mais campos, conforme a necessidade. Caso queira ver quais campos existe a possibilidade de serem
buscados, acesse a documentação do objeto de [Order](https://shopify.dev/docs/api/admin-graphql/2023-07/objects/Order) da API.

---

## Como integrar a OpenPix com Shopify?

import Embed from 'react-embed';

:::caution

Essa documentação espera que você já tenha uma loja Shopify ativa e uma conta criada na OpenPix.

:::

## 1. Instalando o aplicativo OpenPix através do Shopify

Para integrar sua loja Shopify com a OpenPix, é necessário instalar o aplicativo OpenPix diretamente pela Shopify.

- Acesse nosso aplicativo na Shopify: [OpenPix Pay](https://apps.shopify.com/openpix-pay-app-prod)

Após acessar a página inicial, selecione a loja que deseja instalar o aplicativo:

![Shopify install step 1](./__assets__/shopify-install-step-1.png)

Após selecionar a loja, clique em Instalar:

![Shopify ](./__assets__/shopify-install-step-2.png)

O Shopify irá redirecioná-lo para o painel de instalação do aplicativo.

![Shopify install step 1](./__assets__/shopify-install-step-3.png)

Clique novamente no botao `Instalar`. Você será redirecionado para nossa plataforma, e a integração acontecerá de forma automática.

:::info

Caso não esteja logado na plataforma, basta continuar a autenticação e o fluxo de instalação seguirá automaticamente.

:::

![Shopify install step 1](./__assets__/shopify-install-step-4.png)

Após a integração dentro de nossa plataforma ser concluída, você será redirecionado novamente para o Shopify para ativar o aplicativo.

![Shopify install step 1](./__assets__/shopify-install-step-5.png)

Basta clicar em Ativar, e estará pronto para utilizar.

![Shopify install step 1](./__assets__/shopify-install-step-6.png)

:::info

Permitimos somente uma integração por loja.

:::

## Funcionamento do checkout Pix transparente Shopify

---

## Integrar SocPanel com Pix

## Pré requisitos para integrar o SocPanel com Pix

Para integrar o SocPanel com Pix, você deve:

- 1. Possuir um ambiente da SocPanel configurado
- 2. Possuir acesso à plataforma da woovi

## Como integrar o SocPanel com Pix?

### Adicionar a woovi como meio de pagamento

- 1. Acesse o ambiente da SocPanel e clique em **Meios de Pagamento**
- 2. Clique em **Adicionar Meio de Pagamento**

![SocPanel payment method](/img/integrations/soc-panel-payment-method.png)

- 1. Pesquise por **woovi** e clique em **Adicionar**
![SocPanel Info](/img/integrations/soc-panel-info.png)

### Configurar o woovi

- 1. Dentro da plataforma da woovi acesse [aqui](https://app.woovi.com.br/home/applications/add), e crie uma API
- 2. Copie o APP ID e cole no campo **Authorization** do SocPanel
![SocPanel AppID](/img/integrations/socpanel-app-id.png)
- 3. Crie um **Webhook** para receber as notificações de pagamento [aqui](https://app.woovi.com.br/home/applications/webhook/create)
  - 3.1 Copie o campo **URL** do seu webhook mostrado no SocPanel. Exemplo: `https://meusite.com/api/payments/woovi/webhook`
  - 3.2 Preencha a página de webhook assim:
    ![SocPanel AppID](/img/integrations/socpanel-webhook-page.png)
  - 3.3 Clique em **Salvar**
- 4. Acesse o detalhe do webhook criado
  - 4.1 Copie o campo **HMAC Secret Key** e cole no campo **HMAC Secret Key** do SocPanel
- 5. Garanta que o preenchimento dos campos está semelhante ao da imagem abaixo
  ![SocPanel AppID](/img/integrations/socpanel-filled-form.png)
- 6. Clique em **Adicionar tipo de pagamento** na plataforma da SocPanel e pronto!

---

## Integrando Pix com o Telegram

import Embed from 'react-embed';

## Como integrar o Pix com o Telegram

---

## Integração woovi com Assine Online

## O que é a Assine Online?

A Assine Online é uma plataforma que disponibiliza uma solução de assinatura digital para empresas.
Os usuários podem assinar documentos usando seu telefone celular ou computador.

## Como integrar a Assine Online com a woovi?

Para integrar a Assine Online com a woovi, você deve:

1. Criar uma conta na Assine Online
2. Crie uma aplicação na Assine Online [aqui](https://developers.assine.online/docs/starting/#criando-um-aplicativo)
3. Entre em contato com o suporte da woovi para realizar a integração

---

## Integração woovi Bridge

## O que é a woovi Bridge?

O woovi Bridge permite que aplicações sem urls/endpoints expostos na internet recebam webhook localmente.
- Casos de uso: PDV, sistemas embarcados, IoT.

### Como as informações são mandadas?
As informações são recebidas pela nossa aplicação e são mandadas em uma requisição POST para seu endpoint.
O corpo da requisição tem o seguinte formato:

```json
{
"value":5400,
"company":{"nameFriendly":"...","correlationID":"..."},
"identifier":"...",
"status":"COMPLETED",
"expiration":2592000,
"createdAt":"2025-06-11T14:33:58.679Z",
"paidAt":"2025-06-11T14:34:59.000Z",
"paymentLinkID":"..."
}
```

### Quais configurações posso fazer?
Essas são as configurações de webhook que são possíveis, colocando quais tópicos, qual endpoint e quantas vezes tentar novamente mandar a requisição caso falhe:

```json
webhook:
  endpoint_url: "http://localhost:3000/woovi"
  companies:
    - "companyCorrelationId"
    - “companyCorrelationId2”
  events:
    - “COMPLETED”
    - “ACTIVE”
```

### O que são os Companies?
As companies é uma configuração que você utiliza o correlationId de uma company para dizer que quer receber informações dela.
Você pode receber informações de quantas empresas diferentes quiser por meio das Companies.
- A estrutura padrão da configuração é:

```json
companies:
- "{correlationId1}"
	- "{correlationId2}"
```

### Como conseguir um CorrelationID?
O correlationID representa uma empresa em nosso sistema, você pode identificá-la por esse valor único.
- Por meio de nossa API você tem acesso a esse valor:

```json
curl -X GET "https://api.woovi.com/api/v1/company" \
  -H "Authorization: {APP_ID}"
```
Nosso sistema retornará as informações da company atrelada ao seu AppID que foi mandado no Header, em forma de JSON:

```json
{
	"officialName": "...",
	"tradeName": "...",
	"taxID": "...",
	"correlationID": "...",
}
```

### Endpoint

O endpoint precisa ser um endpoint já configurado em sua aplicação, ele tem que estar configurado para poder receber requisições HTTP POST.
Nossa aplicação espera uma resposta 200. Caso não receba 200, ele enviará a mensagem novamente seguindo as configurações de retry.

Exemplo de endpoint:

` endpoint_url: "http://localhost:3000/webhook" `

### Configurações de Eventos

As configurações de eventos permitem que você pegue informações de estados diferentes de uma cobrança.
Os possíveis eventos são:

 - COMPLETED
 - ACTIVE
 - COMPLETED: Evento que é disparado quando uma cobrança é paga.
 - ACTIVE: Evento que é disparado quando uma cobrança é criada.

 O arquivo de configuração permite que você configure esses eventos da seguinte forma:
 ```json
 events:
- "COMPLETED"
- "ACTIVE"
```

### Como iniciar a aplicação?
Você receberá um instalador, esse instalador irá configurar tudo que é necessário para que nossa aplicação funcione.
Tudo que você precisa fazer após a instalação é colocar seus dados no arquivo de configuração.

## Como configurar?
Pressione a tecla Windows + R. Ou seja, pressione a tecla Windows e ao mesmo tempo a tecla R do teclado.

![execute-2](./__assets__/win-r.png)

Nessa caixa de texto você só precisa colocar: %programdata%
 - Pressione ENTER.

Procure a pasta `woovi` e entre nela.
Nessa pasta terá dois arquivos, abra o arquivo `config.yaml`

![folder-2](./__assets__/config-woovi.png)

O arquivo se parecerá com este exemplo:

![folder-3](./__assets__/webhook-config.png)

Agora basta colocar as informações dos passos anteriores.
Após salvar o arquivo, reinicie o Computador.

:::note
O outro arquivo na pasta, o `woovi.txt` é onde os logs da aplicação serão guardados.
Caso hajam erros você pode conferir nesse arquivo.
:::

---

## Integração Zapier com Woovi

A [Zapier](https://zapier.com) é uma plataforma poderosa que viabiliza a integração fluida de mais de 5.000 aplicativos diversos em fluxos de trabalho automatizados e interconectados.

Com o selo oficial da Woovi, [o nosso aplicativo](https://zapier.com/apps/woovi/integrations) está agora disponível na ampla gama de apps listados na Zapier. Isso abre a porta para a integração dos serviços de Pix com outras aplicações, incluindo, por exemplo, a capacidade de sincronizar dados com planilhas do Google e envio de notificações no Slack.

## O que você pode alcançar com o app da Woovi?

Ao aproveitar o aplicativo da Woovi, você desbloqueia um universo de oportunidades. Aqui estão alguns exemplos de integrações práticas:

- Notificações no Slack: Receba alertas instantâneos no Slack para novas cobranças na Woovi.
- Registro em Planilhas Google: Mantenha registros automáticos de novos clientes em planilhas Google.
- Integração com Email Marketing: Adicione automaticamente novos clientes da Woovi à sua lista de contatos de email marketing.
- Gerenciamento de Reembolsos: Envie notificações de reembolso aos clientes e mantenha registros internos.
- Sincronização Financeira: Crie entradas financeiras em plataformas como QuickBooks para novas cobranças na Woovi.

## Ações e gatilhos

Nosso aplicativo possui as seguintes [ações](https://help.zapier.com/hc/en-us/articles/8496257774221-Set-up-your-Zap-action) (_actions_) que você pode utilizar em conjunto com outros aplicativos:

- Criar uma cobrança
- Remover uma cobrança
- Criar um cliente
- Criar reembolso de uma cobrança

Você também pode utilizar o [gatilho](https://help.zapier.com/hc/en-us/articles/8496244568589-Types-of-triggers-in-Zaps) (_trigger_) de webhook, que permite ativar outras ações (como enviar uma notificação no Slack) quando um evento acontece (como uma cobrança sendo paga).

## Autenticação

Ao utilizar alguma triger ou action da Woovi em seu fluxo no Zapier, é necessário se autenticar.

Isso é realizado na seção _Account_, através do botão _Sign In_:

![Seção de configuração da conta Zapier](./__assets__/zapier-setup-account-section.png)

Ao apertar esse botão, uma nova janela será aberta, onde você deverá adicionar o seu _App ID_ e um nome para sua conta (no campo _App name_).

## Ações

### Como adicionar uma ação da Woovi

Em seu fluxo Zapier, [adicione uma nova ação](https://help.zapier.com/hc/en-us/articles/8496257774221-Set-up-your-Zap-action) pesquisando por _Woovi_ no início de sua _action_:

![Pesquisando pelo app da Woovi no criador de actions](./__assets__/zapier-action-searching-woovi.png)

Agora é necessário selecionar um evento, que diz qual ação tomar. Por exemplo, aqui estamos selecionando o evento _Create charge_ para criação de uma cobrança:

![Selecionando o evento para criar uma cobrança](./__assets__/zapier-action-selecting-create-charge-event.png)

Devemos estar na seção _Account_ no momento, onde a [autenticação](#autenticação) deve ser feita.

Após a autenticação, é o momento de configurar sua action na seção _Action_, de acordo com o evento dela:

![Configurando a action de criação de cobrança](./__assets__/zapier-create-charge-configuration.png)

Tendo configurado a nossa action, agora você deve estar na seção _Test_ para testes da action:

![Seção de testes de uma action](./__assets__/zapier-testing-action.png)

Ao apertar o botão _Test action_ você efetuará o teste dela:

![Botão para testar uma action](./__assets__/zapier-test-action-button.png)

### Como criar uma cobrança?

Neste cenário de exemplo, faremos uso do Google Planilhas. Aqui, uma planilha de cobranças será configurada, onde cada nova linha inserida resultará na geração automática de uma cobrança.

Em primeiro lugar, crie uma planilha com os seguintes campos e adicione uma nova linha:

![Planilha de exemplo para criação de cobranças](./__assets__/zapier-create-charge-spreadsheet.png)

Após isso crie um [Zap](https://help.zapier.com/hc/en-us/articles/8496309697421-Create-Zaps) com o trigger _Ǹew Spreadsheet Row_ (nova linha na planilha) do app [Google Sheets](https://www.google.com/sheets/about/).

Tendo configurado e testado a trigger, adicione uma nova action da Woovi com o evento _Create charge_ (criar cobrança).

Ajuste os campos da ação na seção _Action_ de forma a coincidirem com as colunas da planilha:

![Planilha de exemplo para criação de cobranças](./__assets__/zapier-create-charge-configuration.png)

No campo `Type` selecione `DYNAMIC` para criação de uma cobrança à vista.

Após isso, prossiga para a seção _Test_ para testar o seu fluxo.

### Como remover uma cobrança?

[Adicione uma action](#como-adicionar-uma-ação-da-woovi) com o evento _Delete a charge_ em seu fluxo do Zapier.

Configure os campos da action na seção _Action_:

![Configurando a action de remover uma cobrança](./__assets__/zapier-remove-charge-action-configuration.png)

Como campo da action, temos o `id` que é onde você deve colocar o [`correlationID`](../concepts/correlation-id) ou o identificador da cobrança.

### Como criar um cliente?

[Adicione uma action](#como-adicionar-uma-ação-da-woovi) com o evento _Create customer_ em seu fluxo do Zapier.

Configure os campos da action na seção _Action_:

![Configurando a action de criar um cliente](./__assets__/zapier-create-customer-action-configuration.png)

A action possui as seguintes entradas pro cliente:
- `Name` (obrigatório): Nome.
- `Email`: E-mail do cliente.
- `Phone`: Número de telefone.
- `CorrelationID`: É o [`correlationID`](../concepts/correlation-id) do cliente, um identificador.
- `Address`: Endereço do cliente.
  - `Zip Code`: Coloque aqui o CEP.
  - `Street`: A rua do cliente.
  - `Number`: Número do endereço.
  - `Neighborhood`: Bairro.
  - `City`: Cidade.
  - `State`: Estado do cliente.
  - `Complement`: Complemento do endereço.
  - `Country`: País. Por exemplo: `BR` para Brasil.

### Como criar reembolso de uma cobrança?

[Adicione uma action](#como-adicionar-uma-ação-da-woovi) com o evento _Create a Charge Refund_ em seu fluxo do Zapier.

Configure os campos da action na seção _Action_:

![Configurando a action de criar um reembolso](./__assets__/zapier-create-charge-refund-action-configuration.png)

A action possui as seguintes entradas:

- `Refund CorrelationID`: Seu [`correlationID`](../concepts/correlation-id) para acompanhar este reembolso.
- `Charge Correlation ID`: O [correlationID](../concepts/correlation-id.md) da cobrança.
- `Value`: Valor do reembolso em centavos.
- `Comment`: Comentário da cobrança.

## Gatilhos

### Como configurar o webhook?

Os webhooks permitem que diferentes sistemas se comuniquem em tempo real, transmitindo dados de forma automática e instantânea.

É possível configurar um webhook no Zapier utilizando um trigger que é acionado sempre que uma cobrança for completamente paga, por exemplo.

Para utilizar, crie um novo Zap e ative o [trigger](https://help.zapier.com/hc/en-us/articles/8496244568589-Types-of-triggers-in-Zaps) da Woovi.

Ao criar um novo Zap, é possível encontrar o trigger da Woovi pesquisando por _woovi_:

![Pesquisando pelo trigger](./__assets__/zapier-trigger-search.png)

Selecione _New Webhook Event_ no campo de evento da trigger:

![Selecionando o evento da trigger](./__assets__/zapier-trigger-selecting-event.png)

[Realize a autenticação](#autenticação) na seção de _Account_.

![Realizando a autenticação](./__assets__/zapier-trigger-auth.png)

Configure a trigger:

![Configurando a trigger](./__assets__/zapier-trigger-configuration.png)

A trigger possui as seguintes entradas:

- `Webhook Name`: Nome do seu webhook. Coloque aqui o nome da sua integração, por exemplo.
- `Event Type`: Indica quando a trigger é ativada. No exemplo ela será ativada sempre quando uma cobrança for totalmente paga. Veja as possibilidades de eventos:
  - `OPENPIX:CHARGE_CREATED` - Uma cobrança foi criada.
  - `OPENPIX:CHARGE_COMPLETED` - Uma cobrança foi totalmente paga. 
  - `OPENPIX:CHARGE_EXPIRED` - Uma cobrança não foi totalmente paga e expirou.
  - `OPENPIX:TRANSACTION_RECEIVED` - Uma transação PIX foi recebida.
  - `OPENPIX:TRANSACTION_REFUND_RECEIVED` - Novo reembolso de transação PIX recebido ou reembolsado.
  - `OPENPIX:MOVEMENT_CONFIRMED` - A transação do pix referente ao pagamento é confirmada.
  - `OPENPIX:MOVEMENT_FAILED` - Falha no pagamento é quando o pagamento é aprovado e ocorre um erro.
  - `OPENPIX:MOVEMENT_REMOVED` - O pagamento foi removido por um usuário.
- `Is Active?`: É necessário ativar esta opção para que o webhook funcione.

Agora realize o teste de sua trigger na seção _Test_:

![Testando a trigger](./__assets__/zapier-trigger-test.png)

---

## Configure a plataforma Woovi

A plataforma Woovi foi criada para facilitar a experiência do programador, garantindo ao mesmo tempo o mais alto nível de segurança. Esta documentação ajuda os programadores ou administradores dos sistemas a configurar corretamente a plataforma.

*Utilizar métodos automatizados tais como Single-Sign-On e APIs são preferenciais, uma vez que proporcionam uma melhor experiência ao usuário, aumentam a segurança e automatizam os processos.*

## Começando

Uma vez registrado na plataforma, você será capaz de convidar mais usuários para a plataforma, configurar métodos de login como single-sign-on, APIs ou mesmo importar usuários utilizando arquivos Excel. 

## Configurando o Single Sign-On (SSO)

Woovi suporta múltiplos SSO identity providers (IdP). Um Identity Provider é um servidor que pode fornecer informações de identidade sobre os usuários da sua empresa. Por exemplo, o Google pode ser um fornecedor de identidade para empresas que utilizam a solução G Suite. Se a sua empresa está utilizando a solução G Suite, pode entrar automaticamente na Woovi utilizando a sua conta Google. então um servidor Google enviará a sua informação de identidade para esse site.

### Azure Single Sign On

Se a sua empresa utiliza o Azure Single Sign On, poderá entrar automaticamente na Woovi utilizando o Azure como IdP. Para utilizar esta estratégia de login, é preciso ativar esta opção no menu de definições.

### Google Single Sign On

Se a sua empresa utiliza a G Suite, poderá iniciar automaticamente uma sessão na Woovi utilizando o Google como IdP.

### SAML Single Sign on

Se a sua empresa utiliza SAML, poderá entrar automaticamente no Woovi SAML Servers como IdP.

## Segurança e Firewall

### Lista de Domínios Woovi permitidos

A fim de operar corretamente os usuários da sua empresa precisam ter acesso aos servidores da Woovi. A Woovi utiliza tecnologias web padrão e aplica a encriptação em todas as comunicações, na maioria dos casos a sua configuração deve funcionar fora da caixa, sem requisitos adicionais.

Se você se deparar com problemas utilizando a plataforma, por favor verifique os seguintes requisitos.

- Certifique-se de que possui uma lista de domínios permitidos da Woovi no seu servidor proxy, ou firewall interno. Os seus utilizadores devem poder acessar a todos os domínios e subdomínios.
  
  > Tem que listar todos os domínios permitidos da Woovi *.woovi.com

- Certifique-se de que não está bloqueando os e-mails do domínio da Woovi.
  
  > Tem que listar todos os domínios permitidos da Woovi *.woovi.com em seu fornecedor de e-mail
  
- Não armazenar em cache

    > Não alterar ou impor novas políticas de cache para conteúdo estático Woovi ou endereço IP. Woovi utiliza uma rede CDN global e proteções adicionais de servidor para que os IPs mudem frequentemente e sem aviso prévio.

---

## Precisa de ajuda?

Este projeto é mantido por uma equipe de apoio dedicada. Estamos aqui para ajudar!

## O que fazer se não conseguir encontrar documentação de apoio

Se não encontrar a informação que procura, pode fazer perguntas diretamente à nossa equipe de apoio utilizando a ferramenta de chat de apoio interno (necessita de ser registrado)

---

## Acessando o Ambiente de teste woovi

A plataforma woovi foi desenvolvida com o objetivo de simplificar e gerenciar totalmente geração, cobrança, liquidação e conciliação em tempo real de pagamentos instantâneos usando Pix. Proporcionando ao mesmo tempo ótima experiência de programção atentendo requisitos de máximos de segurança. Esta documentação visa auxiliar os programadores e administradores de sistemas na configuração adequada da plataforma, especialmente em relação ao método de pagamento Pix.

*Utilizar métodos automatizados tais como Single-Sign-On e APIs são preferenciais, uma vez que proporcionam uma melhor experiência ao usuário, aumentam a segurança e automatizam os processos.*

## Começando

:::caution

Os dados de produção não funcionam no ambiente de testes.

Para acessar o ambiente de testes, 

Registre-se novamente através da seguinte URL:

👉 https://app.woovi-sandbox.com/

:::

Após se registrar no ambiente de testes, você terá acesso a todas as funcionalidades do ambiente de produção, mas em um ambiente seguro para testes.

Você poderá:

- Convidar outros usuários para a plataforma;

- Configurar métodos de login;

- Gerar cobranças individuais ou em lote;

- Utilizar APIs e integrações;

- Importar usuários via arquivos Excel.

## Configurando o Single Sign-On (SSO)

woovi suporta múltiplos SSO identity providers (IdP). Um Identity Provider é um servidor que pode fornecer informações de identidade sobre os usuários da sua empresa. Por exemplo, o Google pode ser um fornecedor de identidade para empresas que utilizam a solução G Suite. Se a sua empresa está utilizando a solução G Suite, pode entrar automaticamente na woovi utilizando a sua conta Google. então um servidor Google enviará a sua informação de identidade para esse site.

### Azure Single Sign On

Se a sua empresa utiliza o Azure Single Sign On, poderá entrar automaticamente na woovi utilizando o Azure como IdP. Para utilizar esta estratégia de login, é preciso ativar esta opção no menu de definições.

### Google Single Sign On

Se a sua empresa utiliza a G Suite, poderá iniciar automaticamente uma sessão na woovi utilizando o Google como IdP.

### SAML Single Sign on

Se a sua empresa utiliza SAML, poderá entrar automaticamente no woovi SAML Servers como IdP.

## Segurança e Firewall

### Lista de Domínios woovi permitidos

A fim de operar corretamente os usuários da sua empresa precisam ter acesso aos servidores da woovi. A woovi utiliza tecnologias web padrão e aplica a encriptação em todas as comunicações, na maioria dos casos a sua configuração deve funcionar fora da caixa, sem requisitos adicionais.

Se você se deparar com problemas utilizando a plataforma, por favor verifique os seguintes requisitos:

- Certifique-se que os domínios da woovi estão liberados seu servidor proxy ou firewall. Além disso seus clientes também devem ter poder acessar todos os domínios e subdomínios.
  
  > Permitir todo tráfego para woovi *.woovi.com.br e/ou *.woovi.com

- Certifique-se de que não está bloqueando os e-mails do domínio da woovi.
  
  > Permitir emails da woovi *.woovi.com.br em seu fornecedor de e-mail
  > Permitir emails da woovi *.woovi.com em seu fornecedor de e-mail
  
- Não armazenar em cache

    > Não alterar ou impor novas políticas de cache para conteúdo estático woovi ou endereço IP. 
    > woovi utiliza uma rede CDN global e proteções adicionais de servidor para que os IPs mudem frequentemente e sem aviso prévio.

---

## Como cancelar uma nota fiscal emitida via api

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## Endpoint 

```
POST /api/v1/invoice/{invoiceId}/cancel
```
Você encontra a documentação mais detalhada desse endpoint nas [documentações de api](/api#tag/invoice/POST/api/v1/invoice/{correlationID}/cancel)

Para cancelar uma nota fical é necessário o id de uma nota fical já emidida posteriormente, após a requisição de cancelamento, os documentos virão marcados como nota fiscal cancelada.

### Erros mapeados

* `Invoice not found`
* `Integration not found`
* `Cannot cancel a not confirmed invoice`

### Exemplos em código

  

```sh
 curl --request POST \
     --url https://api.woovi.com/api/v1/invoice/{id}/cancel \
     --header 'Authorization: {AUTHORIZATION TOKEN}' \
     --header 'content-type: application/json'
```

```js
fetch('https://api.woovi.com/api/v1/invoice/{id}/cancel', {
  method: 'POST',
  headers: {
    Authorization: {AUTHORIZATION TOKEN},
    'Content-Type': 'application/json',
  },
}).then(async (res) => res.json())
```

---

## Como encontrar arquivos da nota fiscal

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## Endpoint 

```
GET /api/v1/invoice/{id}/pdf
GET /api/v1/invoice/{id}/xml
```
Você encontra a documentação mais detalhada desse endpoint nas [documentações de api](/api#tag/invoice/GET/api/v1/invoice/{correlationID}/pdf)

Para buscar os arquivos de uma nota fiscal específica você pode apenas buscar utilizando os endpoints listados acima, ambos devem retornar um arquivo correspondente pdf ou xml de acordo com a requisição

### Erros mapeados

* `Invoice not found`
* `Error while getting invoice documents`

### Exemplos em código

  

```sh
 curl --request GET \
     --url https://api.woovi.com/api/v1/invoice/{id}/pdf \
     --header 'Authorization: {AUTHORIZATION TOKEN}' \
     --header 'content-type: application/json'
```

```js
fetch('https://api.woovi.com/api/v1/invoice/{id}/pdf', {
  method: 'GET',
  headers: {
    Authorization: {AUTHORIZATION TOKEN},
    'Content-Type': 'application/json',
  },
}).then(async (res) => {
    const contentType = res.headers.get('Content-Type');

    if (contentType?.includes('application/pdf')) {
      const blob = await res.blob();
      const url = URL.createObjectURL(blob);

      return { pdfUrl: url };
    }

    if (contentType?.includes('application/json')) {
      return res.json();
    }

    return res.text();
  })
```

---

## Criar Nota Fiscal de serviço via API

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::caution

A emissão exige que a integração de nota fiscal da conta já esteja configurada e ativa. Veja [Configurando a emissão de nota fiscal via API](/docs/baas/baas-invoice-integration) ou [Como ativar a emissão pela plataforma](/docs/integrations/invoice/invoice-how-to-integrate).

:::

## Endpoint

```http
POST /api/v1/invoice
```

Autentique com o header `Authorization: SEU_APPID_AQUI`. Você encontra a documentação detalhada desse endpoint nas [documentações de api](/api#tag/invoice/POST/api/v1/invoice).

A API aceita dois formatos de payload, sempre exigindo dados de cobrança **ou** valor, e um cliente (via `customerId` ou objeto `customer`).

### Formato 1 – com valor

```json
{
  "correlationID": "nfse-assinatura-pro-2025-08",
  "description": "Assinatura Pro - Agosto/2025",
  "billingDate": "2025-08-31T23:59:59.000Z",
  "value": 12990,
  "customerId": "cus_123"
}
```

### Formato 2 – com cobrança

```json
{
  "correlationID": "nfse-mensalidade-premium-2025-08",
  "description": "Mensalidade Premium",
  "billingDate": "2025-08-31T23:59:59.000Z",
  "charge": "ch_abc",
  "customer": {
    "taxID": "12345678909",
    "name": "Maria Souza",
    "email": "maria@email.com",
    "phone": "+55 48 99999-0000",
    "address": {
      "country": "BR",
      "zipcode": "88000-000",
      "street": "Rua das Flores",
      "number": "100",
      "state": "SC"
    }
  }
}
```

### Campos do corpo da requisição

| Campo                      | Tipo   | Obrigatório                                     | Descrição                                                                                       |
| -------------------------- | ------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `correlationID`            | string | Sim                                             | Seu identificador único da nota fiscal. Não pode repetir dentro da mesma conta.                 |
| `billingDate`              | string | Sim                                             | Data de competência/vencimento da nota, no formato `YYYY-MM-DD` ou ISO 8601.                    |
| `charge`                   | string | Sim, se `value` não for enviado                 | `correlationID` de uma cobrança existente. O valor e o cliente da nota são obtidos da cobrança. |
| `value`                    | number | Sim, se `charge` não for enviado                | Valor da nota **em centavos** (ex.: `12990` equivale a R$ 129,90).                              |
| `customer`                 | object | Sim, quando emitir por `value` sem `customerId` | Dados do tomador do serviço, detalhados nas linhas seguintes.                                   |
| `customerId`               | string | Não                                             | `correlationID` de um cliente já cadastrado, como alternativa a enviar o objeto `customer`.     |
| `description`              | string | Não                                             | Descrição do serviço que aparece na NFS-e.                                                      |
| `customer.taxID`           | string | Sim (dentro de `customer`)                      | CPF ou CNPJ do tomador, somente números.                                                        |
| `customer.name`            | string | Sim (dentro de `customer`)                      | Nome ou razão social do tomador.                                                                |
| `customer.email`           | string | Sim (dentro de `customer`)                      | E-mail válido do tomador.                                                                       |
| `customer.phone`           | string | Sim (dentro de `customer`)                      | Telefone do tomador.                                                                            |
| `customer.address`         | object | Sim (dentro de `customer`)                      | Endereço do tomador.                                                                            |
| `customer.address.country` | string | Sim (dentro de `address`)                       | País do endereço.                                                                               |
| `customer.address.zipcode` | string | Sim (dentro de `address`)                       | CEP do endereço.                                                                                |
| `customer.address.street`  | string | Sim (dentro de `address`)                       | Logradouro.                                                                                     |
| `customer.address.number`  | string | Sim (dentro de `address`)                       | Número do endereço.                                                                             |
| `customer.address.state`   | string | Sim (dentro de `address`)                       | Sigla do estado brasileiro (ex.: `SP`).                                                         |

:::info

O `correlationID` é único por conta: cada conta tem o seu próprio espaço de identificadores, então o mesmo `correlationID` pode existir em contas diferentes.

:::

## Resposta

### Sucesso (201)

```json
{
  "invoice": {
    "id": "6a5f62d35ab4cd72544b1a48",
    "correlationID": "nfse-mensalidade-premium-2025-08",
    "value": 12990,
    "description": "Mensalidade Premium",
    "date": "2025-08-31T23:59:59.000Z",
    "billingDate": "2025-08-31T23:59:59.000Z",
    "status": "PENDING",
    "statusRaw": null,
    "customer": {
      "correlationID": "cus_123",
      "name": "Maria Souza"
    },
    "charge": {
      "correlationID": "ch_abc",
      "value": 12990,
      "status": "ACTIVE",
      "paidAt": null,
      "date": "2025-08-01T12:00:00.000Z"
    }
  }
}
```

A emissão é **assíncrona**. A resposta confirma que a nota foi registrada, não que ela já foi autorizada pela prefeitura — por isso o `status` volta como `PENDING`.

### Fluxo de status

```
PENDING  →  PROCESSING  →  CONFIRMED
```

O PDF e o XML só ficam disponíveis depois que a nota atinge `CONFIRMED`.

### Erros (400)

- `You need to configure the invoice integration`
- `Customer not found`
- `Customer is required`
- `Charge not found`
- `Customer address is invalid`

### Exemplos em código

  

```sh
curl --request POST \
  --url https://api.woovi.com/api/v1/invoice \
  --header 'Authorization: {AUTHORIZATION TOKEN}' \
  --header 'content-type: application/json' \
  -d '{
    "correlationID": "nfse-mensalidade-premium-2025-08",
    "description": "Mensalidade Premium",
    "billingDate": "2025-08-31T23:59:59.000Z",
    "charge": "ch_abc",
    "customerId": "cus_123"
  }'
```

```js
const response = await fetch('https://api.woovi.com/api/v1/invoice', {
  method: 'POST',
  headers: {
    Authorization: '{AUTHORIZATION TOKEN}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    correlationID: 'nfse-mensalidade-premium-2025-08',
    description: 'Mensalidade Premium',
    billingDate: '2025-08-31T23:59:59.000Z',
    charge: 'ch_abc',
    customerId: 'cus_123',
  }),
});

const data = await response.json();
```

  

## Consultando as notas emitidas

Use o endpoint de listagem para acompanhar o status da emissão:

```http
GET /api/v1/invoice
```

Parâmetros de query aceitos: `start` e `end` (filtro por data da nota), `skip` e `limit` (paginação).

```sh
curl --request GET \
  --url 'https://api.woovi.com/api/v1/invoice?start=2025-08-01&end=2025-08-31&skip=0&limit=100' \
  --header 'Authorization: {AUTHORIZATION TOKEN}'
```

Cada item da lista tem o mesmo formato do objeto `invoice` devolvido na criação.

## Próximos passos

- [Baixar o PDF e o XML da nota](/docs/invoice/how-to-get-invoice-files-by-api)
- [Cancelar uma nota emitida](/docs/invoice/how-to-cancel-issued-invoice-by-api)

---

## Acessando a sua conta Woovi

Para acessar a sua conta Woovi acesse [Login](https://app.woovi.com/login)

---

## Configuração do Single Sign On

*Usar o Single-Sign-On é extremamente recomendado, pois fornece uma melhor experiência do usuário e aumenta a segurança.*

## Configurando Single Sign-On (SSO)

Woovi suporta múltiplos SSO identity providers (IdP). Um Identity Provider é um servidor que pode fornecer informações de identidade sobre os usuários da sua empresa. Por exemplo, o Google pode ser um fornecedor de identidade para empresas que utilizam a solução G Suite. Se a sua empresa está utilizando a solução G Suite, pode entrar automaticamente na Woovi utilizando a sua conta Google. então um servidor Google enviará a sua informação de identidade para esse site.

### Azure Single Sign On

Se a sua empresa utiliza o Azure Single Sign On, poderá entrar automaticamente na Woovi utilizando o Azure como IdP. Para utilizar esta estratégia de login, é preciso ativar esta opção no menu de definições.

### Google Single Sign On

Se a sua empresa utiliza a G Suite, poderá iniciar automaticamente uma sessão na Woovi utilizando o Google como IdP.

### SAML Single Sign on

Se a sua empresa utiliza SAML, poderá entrar automaticamente no Woovi SAML Servers como IdP.

## Segurança & Firewall

---

## Restrição de Domínios

_A restrição de domínios permite controlar quais domínios de email podem acessar sua organização no Woovi._

## Vídeo Tutorial

<iframe width="560" height="315" src="https://www.youtube.com/embed/X8118kGykFA" title="Restrição de Domínios - Parte 1" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen" allowfullscreen></iframe>

## Como Funciona

A restrição de domínios é uma funcionalidade de segurança que permite que você defina quais domínios de email podem criar contas e acessar sua organização no Woovi.

### Benefícios

- **Segurança aprimorada**: Apenas usuários de domínios autorizados podem acessar
- **Controle de acesso**: Gerencie quem pode se registrar na sua organização
- **Prevenção de acesso não autorizado**: Bloqueia tentativas de login de domínios não permitidos

### Configuração

Para configurar restrições de domínio, acesse as configurações da sua organização e defina os domínios permitidos. Apenas usuários com endereços de email desses domínios poderão criar contas e acessar sua organização.

### Exemplos de Uso

- **Empresas**: Restringir acesso apenas para funcionários com emails corporativos
- **Organizações educacionais**: Permitir apenas emails de instituições de ensino específicas
- **Projetos específicos**: Limitar acesso a domínios de parceiros ou clientes específicos

## Configuração Passo a Passo

### 1. Acesse as Configurações da Organização

1. Faça login na sua conta Woovi
2. Navegue até **Configurações da Empresa** > **Login por**
3. Procure pela seção **Restrições de domínio de email**

### 2. Adicione Domínios Permitidos

1. Clique em **Restringir a domínios específicos**
2. Digite o domínio que deseja permitir (ex: `empresa.com`)
3. Aperte **Enter** ou clique em **Adicionar** para adicionar um novo domínio
4. Aperte em **Salvar**

### 3. Explicando configurações

- **Restringir a domínios específicos**: Apenas emails dos domínios configurados podem acessar
- **Permitir todos**: Remove todas as restrições (não recomendado)

### Problemas Comuns

**Usuário não consegue acessar mesmo com domínio correto:**

- Verifique se o domínio está exatamente como configurado
- Confirme se não há espaços extras na configuração
- Teste com diferentes subdomínios se aplicável

**Restrições não estão funcionando:**

- Verifique se a funcionalidade está habilitada
- Confirme se as configurações foram salvas corretamente
- Teste em modo incógnito para evitar cache

### Suporte

Se você encontrar problemas com a configuração de restrições de domínio, entre em contato com nosso suporte técnico através do chat ou email.

---

## Criando um meta pixel

O **Meta Pixel** (anteriormente conhecido como **Facebook Pixel**) é uma ferramenta que permite monitorar e rastrear as ações dos visitantes em seu site, fornecendo dados valiosos para campanhas de marketing, otimizações de anúncios e remarketing no Facebook.

Neste guia, você aprenderá como criar e configurar um Meta Pixel para o seu site e como integrá-lo usando React.

## Passos para Criar um Meta Pixel

### 1. Acessar o Gerenciador de Eventos do Facebook

1. Vá para o [Gerenciador de Eventos do Facebook](https://www.facebook.com/events_manager2).
2. No painel esquerdo, clique em **Conectar Fontes de Dados** e selecione **Web**.
3. Nomeie o seu **Meta Pixel** com algo identificável, como o nome do seu site ou campanha.

<!-- conectar manualmente, pixel da meta somente -->
### 2. Configuração de como conectar o Pixel

1. Selecione a opção **Conectar manualmente**.
2. Escolha a opção **Pixel da Meta somente**.

Antes de continuar, você precisará **copiar o ID do Pixel** para cadastra-lo na plataforma.

O ID do pixel está na **parte de baixo** junto ao nome do pixel que você acabou de criar.
![Como Conectar o Pixel](./__assets__/how-to-connect-pixel.png)

---

## Integrando Meta Pixel com a woovi

Nessa etapa, é requisitado que você tenha um **Meta Pixel** criado. Caso ainda não tenha feito, você pode seguir [este tutorial](./creating-a-meta-pixel.md).

## Passos para Integrar o Meta Pixel com a woovi

1. Acesse a [tela de API/Plugins](https://app.woovi.com/home/applications/tab/tutorial) da woovi.
2. Busque por **Facebook/Meta Pixel** e clique em **Adicionar**.
3. Insira o **ID do Pixel** que você copiou anteriormente.
4. Clique em **Salvar**.

A partir desse momento, a woovi estará integrada com o seu **Meta Pixel** e você poderá monitorar e rastrear as ações dos visitantes nos pagamentos realizados através da woovi / woovi.

---

## Como customizar a taxa de um afiliado?

:::info
Para você ter acesso a essa funcionadade você precisa ser parceiro da woovi.
:::

Acesse `Minhas empresas` via sidebar menu

![1](./__assets__/how-to-customize-the-fee-for-a-affiliate-1.png)

Acesse o detalhe do afiliado que você deseja configurar uma taxa customizada.

![2](./__assets__/how-to-customize-the-fee-for-a-affiliate-2.png)

- Acesse a aba `Ajustes`.
- Selecione a opção `Definir Taxa Personalizada`.
- Configure a taxa que você deseja.
- E logo em seguida, aperte o botão de `Salvar` para confirmar sua alteração.

![3](./__assets__/how-to-customize-the-fee-for-a-affiliate-3.png)

---

## O que é a taxa customizada do parceiro?

A taxa customizada do parceiro proporciona a flexibilidade de negociar uma taxa específica com determinados afiliados, adaptando-a de maneira personalizada em relação à taxa geral definida pelo parceiro.

---

## Como registrar diversas empresas afiliadas de uma vez?

## Fazendo o registro das contas

Existe situações onde é necessário que o parceiro consiga registrar várias empresas ao mesmo tempo.

Cenário: Um delivery quer usar a woovi e tem 200 parceiros. Como viabilizar essa operação rapidamente?

Na plataforma em `Minhas empresas`, clique no botão de `Empresa em lote`

![tutorial](./__assets__/how-register-lot-company/tutorial-1.png)

O template está disponível na plataforma.

Após enviar os dados:

![tutorial-2](./__assets__/how-register-lot-company/tutorial-2.png)

![tutorial-3](./__assets__/how-register-lot-company/tutorial-3.png)

---

## Como acessar a API com uma empresa afiliada?

## Criando o acesso via API

Nós disponibilizamos o _endpoint_ `/api/openpix/v1/partner/application` para que
você possa criar uma nova _application_ para a respectiva empresa afiliada.

Você pode acessar [aqui](/api#tag/partner-request-access/POST/api/v1/partner/application)
a documentação referente a esse _endpoint_.

Como parte do `body` da requisição, esperamos o envio dos seguintes itens: `application` e `taxID`,
respectivamente, eles consistem no seguinte:

- **`application`:** informações referentes a `application` que você deseja criar, isto é: o nome dela e o tipo.
  O tipo da aplicação pode ser um dos seguintes valores: `API`, `ORACLE` ou `PLUGIN`.
- **`name`**: O nome da sua `application`, facilita o processo de identificação da nova `application`.

Num exemplo prático, o body da sua requisição seguiria semelhante a este exemplo:

```json
{
  "application": {
    "name": "MyAPIAccess",
    "type": "API",
  },
  "taxID": {
    "taxID": "65914571000187",
    "type": "BR:CNPJ",
  }
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta,
você estará vendo as informações sobre a `application` recém criada.

Num exemplo, essa será a resposta a nossa resposta:

```json
{
  "application": {
    "name": "MyAPIAccess",
    "isActive": true,
    "type": "API",
    "clientId": "Client_Id_xxxx",
    "clientSecret": "Client_Secret_xxxx"
  }
}
```

### Utilizando o appID
Após criar sua nova `application`, você consegue obter seu `AppID` convertendo os valores de `clientId`
e `clientSecret` para [Base64](https://en.wikipedia.org/wiki/Base64). Segue um exemplo em JavaScript de 
como fazer isso:

```js
const appID = Buffer.from(`${clientId}:${clientSecret}`, 'utf8').toString('base64');
```

O `appID` será o valor que você usará no _header_ de `Authorization` para consumir as APIs Woovi.

---

## Como criar uma empresa afiliada via API?

## Criando uma empresa afiliada

Nós disponibilizamos o _endpoint_ `POST /api/v1/partner/company` para que
você possa criar um novo _pré-registro_ para uma empresa afiliada.

Você pode acessar [aqui](/api#tag/partner-request-access/POST/api/v1/partner/company)
a documentação referente a esse _endpoint_.

Como parte do `body` da requisição, esperamos o envio dos seguintes dois objetos: `preRegistration` e `user`,
respectivamente, eles consistem no seguinte:

- **`preRegistration`:** informações referentes a empresa que você deseja criar, isto é: o nome, website e cnpj.
- **`user`**: Os dados do usuário de acesso mestre aquela empresa, toda empresa afiliada precisa de um usuário mestre para que seja possível efetuar o login na plataforma posteriormente

Em um exemplo prático, o body da sua requisição seguiria semelhante a este exemplo:

```bash
curl -X POST "https://api.woovi.com/api/v1/partner/company" \
  -H "Authorization: {APP_ID}" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "preRegistration": {
      "name": "Example LLC",
      "taxID": {
        "taxID": "11111111111111",
        "type": "BR:CNPJ"
      },
      "website": "examplellc.com"
    },
    "user": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "johndoe@examplellc.com",
      "phone": "+5511912345678",
      "taxID": {
        "taxID": "1111111111",
        "type": "BR:CPF"
      }
    }
  }'
```

O mesmo `body`, isolado:

```json
{
  "preRegistration": {
    "name": "Example LLC",
    "taxID": {
      "taxID": "11111111111111",
      "type": "BR:CNPJ"
    },
    "website": "examplellc.com"
  },
  "user": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "johndoe@examplellc.com",
    "phone": "+5511912345678",
    "taxID": {
      "taxID": "1111111111",
      "type": "BR:CPF"
    }
  }
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta,
você estará vendo as informações sobre o seu afiliado recém criado.

Em um exemplo, essa será a nossa resposta:

```json
{
  "preRegistration": {
    "name": "Example LLC",
    "website": "examplellc.com",
    "taxID": {
      "taxID": "11111111111111",
      "type": "BR:CNPJ"
    }
  },
  "user": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "johndoe@examplellc.com",
    "phone": "+5511912345678",
    "taxID": {
      "taxID": "1111111111",
      "type": "BR:CPF"
    }
  }
}
```

:::info
Importante lembrar que esse é um pré-registro de um afiliado, após a validação da conta, o status permancerá como "Dados pendente" até a finalização do cadastro completo,  igual é mostrado no passo 4 na seção [Pré-registro de conta de um afiliado](./how-to-integrate-as-woovi-partner.md#pré-registro-de-conta-de-um-afiliado)
:::

---

## Como criar um webhook para uma empresa afiliada?

## Criando o webhook via API

Para criar um webhook é **obrigatório** que você tenha criado um `AppID` previamente
para a empresa afiliada. Caso não tenha feito ainda, você pode seguir o tutorial a seguir: 
[**Como acessar a API com uma empresa afiliada?**](./how-to-access-api-via-affiliated-company.md)

Após criar sua nova `application`, você consegue obter seu `AppID` convertendo os valores de `clientId`
e `clientSecret` para [Base64](https://en.wikipedia.org/wiki/Base64). Segue um exemplo em JavaScript de 
como fazer isso:

```js
const appID = Buffer.from(`${clientId}:${clientSecret}`, 'utf8').toString('base64');
```

O `appID` será o valor que você usará no _header_ de `Authorization` para garantir que está criando o
webhook para a empresa correta.

---

Após termos o `appID`, você pode consumir o endpoint `/api/openpix/v1/webhook` com o método `POST` caso
queira criar um novo webhook para a empresa afiliada. Você pode acessar [aqui](/api#tag/webhook/POST/api/v1/webhook)
a documentação referente a esse endpoint, caso desejar.

No `body` da requisição, nós esperamos os seguintes valores:

- **`name`**: O nome pelo qual você quer identificar este novo webhook;
- **`event`**: O evento que será o _gatilho_ do webhook. Atualmente, temos 6 possíveis gatilhos:
  - `OPENPIX:CHARGE_CREATED`: quando uma cobrança nova é criada;
  - `OPENPIX:CHARGE_COMPLETED`: quando uma cobrança foi paga;
  - `OPENPIX:CHARGE_COMPLETED_NOT_SAME_CUSTOMER_PAYER`: quando uma cobrança é paga e o pagador é diferente do cliente associado a cobrança;
  - `OPENPIX:CHARGE_EXPIRED `: quando uma cobrança foi expirada;
  - `OPENPIX:TRANSACTION_RECEIVED`: quando recebe uma nova transação Pix;
  - `OPENPIX:TRANSACTION_REFUND_RECEIVED`: quando é efetuado o reembolso de uma transação Pix;
- **`url`**: A URL em questão que o webhook vai consumir;
- **`isActive`**: indica se o webhook em questão está ativo ou não, se não, não será acionado;
- **`authorization`**: referente ao `Authorization` header, caso a URL precise;

Num exemplo prático do body, o `body` da sua requisição seguiria este formato: 

```json
{
  "webhook": {
    "name": "webhookName",
    "event": "OPENPIX:CHARGE_CREATED",
    "url": "https://mycompany.com.br/webhook",
    "authorization": "openpix",
    "isActive": true
  }
}
```

Reforçando que é necessário ter o `appID` referente a empresa afiliada no _header_ da sua requisição.

Se tudo ocorreu bem, você receberá uma resposta com o _status code_ `2xx` e no `body` da resposta, você
estará vendo as informações referente ao recém criado webhook.

Segue ume exemplo da resposta:

```json
{
  "webhook": {
    "id": "V2ViaG9vazo2MDNlYmUxZWRlYjkzNWU4NmQyMmNmMTg=",
    "name": "webhookName",
    "url": "https://mycompany.com.br/webhook",
    "authorization": "openpix",
    "isActive": true,
    "event": "OPENPIX:CHARGE_CREATED",
    "createdAt": "2023-01-04T22:29:10.720Z",
    "updatedAt": "2021-01-04T22:29:10.720Z"
  }
}
```

---

## Como integrar como parceiro da woovi?

:::info
Antes de seguir com a integração como parceiro você precisa solicitar a ativação dessa funcionalidade em sua conta através do nosso suporte
:::

### Dashboard

1) Acesse o nosso dashboard, no menu localizado no lado esquerdo clique em "Minhas Empresas" para visualizar todos seus afiliados

![](./__assets__/how-to-integrate-as-woovi-partner/side-menu-my-companies.png)  

2) Após a acessar a área "Minhas Empresas", você poderá visualizar duas abas e dois botões

Abas:
- Empresas: onde estarão todas as empresas que finalizaram o pŕe-cadastro como seu afiliado  
- Pré-registro: onde você verá todas as empresas que iniciaram um pré-cadastro como seu afiliado, porém não completaram a validação e ativação da conta  

Botões:
- Link de Afiliado: onde você poderá usar para copiar o link de pré-cadastro e enviar para algum afiliado seu efetuar um pré-registro de conta  
O link de afiliado é algo parecido com:
https://app.woovi.com/register?partner=Q29tcGFue23AdDLOK2NhZGVjZTZkMzQ4MTQ3MzEyZDc=

- Nova Empresa  
Onde você pode criar um pré-registro para alguma empresa que deseja se tornar sua afiliada  
Você pode fazer a criação da nova empresa através da nossa API, para saber mais bastar seguir a seção [como criar um afiliado via API](#como-criar-um-afiliado-via-api)

![](./__assets__/how-to-integrate-as-woovi-partner/afilliate-link-and-new-company.png)

## Pré-registro de conta de um Afiliado

1) Após enviar o link para seu afiliado ou você clicar em novas empresa, ele/você poderá cadastrar na woovi, essa conta será vinculado a sua empresa
> É importante que o afiliado preenchas todas as informações obrigatórias do formulário, aceite os termos e clique em continuar para seguir com a criação da conta de afiliado

![](./__assets__/how-to-integrate-as-woovi-partner/create-company-with-affiliate-link.png)

![](./__assets__/how-to-integrate-as-woovi-partner/info-send-email-to-validate-account.png)

Um link de validação será enviado para o email do afiliado cadastrado, após ele acessar o email ele poderá clicar e "Validar cadastro"

![](./__assets__/how-to-integrate-as-woovi-partner/link-email-affiliate-validate.png)

2) Ele será redirecionado para a plataforma da woovi novamente, e solicitare-mos um código de validação de número de telefone que será enviado para ele via SMS ou Whatsapp dele

![](./__assets__/how-to-integrate-as-woovi-partner/validate-phone-number-affiliate-account.png)

3) Após o afiliado se cadastrar, ele terá acesso a uma conta na woovi como seu afiliado
> Solicite para ele completar os dados de cadastrado dele, para que ele finaliza por completo o cadastro

![](./__assets__/how-to-integrate-as-woovi-partner/affiliate-home-screen.png)

4) Você poderá visualizar todas a empresas cadastradas como seu afiliado, também poderá ver quais empresas não completaram seu cadastro após a criação da conta

![#pending-data](./__assets__/how-to-integrate-as-woovi-partner/list-your-afilliates.png)

Ao selecionar um afiliado, você terá acesso a todas as informações daquele afiliado como

- Cobranças
- Webhooks logs
- Api/Plugins
- Contas
- Ajustes

![](./__assets__/how-to-integrate-as-woovi-partner/afilliate-details.png)

## Configuração de taxas via Dashboard

Você também pode customizar taxas de forma personalizada, siga a documentação abaixo para saber mais sobre:

:::info
Caso você não consiga visualizar a aba "ajustes" em "Minhas Empresas" ou nas suas empresas afiliadas, solicite a ativação para nosso suporte
:::

- [O que é taxa customizada?](./custom-fee/what-is.md)
- [Como customizar a taxa de um afiliado?](./custom-fee/how-to-customize-the-fee-for-a-affiliate)

## Como criar uma empresa afiliada via API
Você também pode fazer um pré-registro como também criar chaves de APIs e webhooks para suas empresas afiliadas, seguindo a documentação abaixo

- [Como criar uma empresa afiliada via API?](./how-to-create-a-affiliate-company-via-api.md)
- [Como acessar a API com uma empresa afiliada?](./how-to-access-api-via-affiliated-company.md)
- [Como criar um webhook para uma empresa afiliada?](./how-to-create-a-webhook-to-affiliated-company.md)

## Como criar um appID para seu afiliado via API
Você pode criar chaves de APIs para suas empresas afiliadas, seguindo a documentação abaixo

- [Como acessar a API com uma empresa afiliada?](./how-to-access-api-via-affiliated-company.md)

## Como listar todos afiliados via API

Você pode fazer um chamada para o nosso endpoint `/api/v1/partner/company` informando o seu `appID` utilizando os header de `Authorization`
Para saber mais sobre as especificações do nosso endpoint você pode acessar [nossa documentação tecnica](/api#tag/partner-request-access/GET/api/v1/partner/company)

![](./__assets__/how-to-integrate-as-woovi-partner/postman-get-affilliates.png)

1. Troque `BASE_URL` pela URL de produção `https://api.woovi.com`
3. Adicione o header `Authorization` da requisição e troque `API_TOKEN` pelo seu `appID`.

Caso ainda não tenha um `appID`, recomenda-mos fortemente você consultar nossa documenta de [começando uma integração](../apis/api-getting-started.md)

## Como listar um afiliado específico?

Você pode fazer um chamada para o nosso endpoint `/api/v1/partner/company/{taxID}` informando o seu `appID` no header de `Authorization` da sua requisição, e também substituindo o parâmetro `taxID` pelo CNPJ do seu afiliado pré-registrado
Para saber mais sobre as especificações do nosso endpoint você pode acessar [nossa documentação tecnica](/api#tag/partner-request-access/GET/api/v1/partner/company/{taxID})

![](./__assets__/how-to-integrate-as-woovi-partner/postman-get-affiliate-by-taxID.png)

1. Troque `BASE_URL` pela URL de produção `https://api.woovi.com`
2. Troque os números pelo seu que estão definidos na URL pelo CNPJ do seu afiliado
3. Adicione o header `Authorization` da requisição e troque `API_TOKEN` pelo seu `appID`.

:::info
Caso ainda não tenha um `appID`, recomenda-mos fortemente você consultar nossa documenta de [começando uma integração API](../apis/api-getting-started.md)
:::

---

## Parceiras

Ofereça Cobrança Pix, Cashback, Pix Crédito e muito mais aos seus clientes.

## Casos de Uso

- Software House que querem oferecer integrações de pagamentos para seus clientes
- Plataformas de E-commerce que querem oferecer integrações de pagamentos para seus clientes
- Plataformas de Resturantes/Deliveries que querem oferecer integrações de pagamentos para seus clientes

---

## Wabiz

## O que é a Wabiz?

A Wabiz é uma plataforma de gestão de restaurantes e deliveries que oferece uma solução completa para o seu negócio. Com a Wabiz você pode gerenciar seu cardápio, pedidos, entregas, clientes, pagamentos e muito mais.

## Como integrar com a Wabiz?

Para realizar a integração com a Wabiz junto com a woovi é bem simples, basta seguir os passos abaixo ou assistir o vídeo

### Vídeo

 
  <iframe src="https://www.loom.com/embed/62406674ecbf45ec901b923a873212c6?sid=9992761e-8a53-47b4-8f6e-e0b9b9987366"
          frameBorder="0"
          allowFullScreen
          style={{
            position: 'absolute',
            top: 0,
            left: 0,
            width: '100%',
            height: '100%',
          }}>
  </iframe>

### Apresentação Comercial da Wabiz + woovi

Acesse o link a seguir para baixar a apresentação comercial da Wabiz + woovi: [https://drive.google.com/file/d/1mzJUOZj2oadEgOIcfZ1DXag9rj9UlMd0/view](https://drive.google.com/file/d/1mzJUOZj2oadEgOIcfZ1DXag9rj9UlMd0/view)

### 1. Ter uma conta na Wabiz

É esperado que você já possua uma conta na Wabiz para realizar a integração com a woovi. Caso você ainda não possua uma conta, você pode criar uma conta gratuitamente através do link a seguir:
[Cadastrar-se na Wabiz](https://aplicativosparadelivery.com.br/)

### 2. Cadastrar conta na woovi

Após criar sua conta na Wabiz, você deve criar uma conta na woovi.

A criação de conta na woovi é bem simples, rápida e segura. [Acesse online este link](https://app.woovi.com/register?partner=Q29tcGFueTo2MmVkMWVhZGJjZTQ4ODI1Nzg2MTBjMGE=) para criar sua conta na woovi:

[![Tela de Registro woovi](./__assets__/register-form.png)](https://app.woovi.com/register?partner=Q29tcGFueTo2MmVkMWVhZGJjZTQ4ODI1Nzg2MTBjMGE=)

### 3. Criar uma conta virtual na woovi

Após ter acesso à plataforma da woovi você deve ativar sua conta virtual, conta em que você receberá todos os seus pagamentos. Para isso, basta seguir os passos bem explicados no link a seguir [https://ajuda.woovi.com/hc/duvidas-frequentes/articles/como-ativar-a-conta-virtual-da-minha-empresa](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/como-ativar-a-conta-virtual-da-minha-empresa)

### 4. Configurar a integração na Wabiz

Feito esses passos, a Wabiz cuida de todo o resto para você. Basta entrar em contato com o suporte da Wabiz e solicitar a integração com a woovi

---

## Verificação de Chave Pix

Este documento irá ajudá-lo a validar chave pix.

Uma chave pix é como se fosse um dominio DNS que aponta para uma conta no banco central, você paga para esta conta, e não diretamente para a chave

Logo é nescessario ter acesso ao numero da conta no banco central para realizar uma transação

Esse endpoint tem a função de validar esse vinculo com o banco central

![diagram sequencial checagem de chave pix](./__assets__/sequenceDiagrama_checagem_de_chave_pix.png)

O endpoint de verificação de chave de pix retornará os dados sobre uma chave de pix. A chave pode ser informada no path (GET) ou no corpo da requisição (POST).

- Usando GET com a chave no path:
```bash
curl -X GET "https://api.woovi.com/api/v1/pix-keys/{pix-key}/check" \
  -H "Authorization: {APP_ID}"
```

Você pode acessar [aqui](/api#tag/pixkey-check-request-access/GET/api/v1/pix-keys/{pixKey}/check) a documentação referente a esse _endpoint_.

- Usando POST com a chave no corpo (útil quando a chave contém caracteres que ficam ruins no path, como e-mails):
```bash
curl -X POST "https://api.woovi.com/api/v1/pix-keys/check" \
  -H "Authorization: {APP_ID}" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "pixKey": "<chave pix>"
  }'
```

Você pode acessar [aqui](/api#tag/pixkey-check-request-access/POST/api/v1/pix-keys/check) a documentação referente a esse _endpoint_.

## Limitação de Taxa

- O endpoint tem um limitador de taxa, devido às restrições do Bacen, por isso o Woovi tem um limite de taxa nesse endpoint.
- Quando você recebe um 404 em uma chave de pix, após alguns 404, você receberá um 429 e precisará aguardar o reabastecimento do limitador de taxa.

### O que é retornado ?

- O campo `type` segue o enum: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `RANDOM` ou `EVP`.
- `pixKey` volta na **forma normalizada**, independente de como você enviou:
  - CPF / CNPJ → só dígitos (`00000000191`, `00000000000191`)
  - EMAIL → em lowercase
  - PHONE → formato internacional E.164 (`+5511999998888`)
  - RANDOM / EVP → UUID de 36 chars intacto
- `owner.name` volta inteiro (não mascarado).
- `owner.taxID`: para **CPF** vem parcialmente mascarado, preservando os 3 primeiros e os 2 últimos dígitos (ex: `111.***.***-80`); para **CNPJ** vem inteiro e formatado (ex: `00.000.000/0001-91`).
- `owner.branch` e `owner.account` voltam totalmente mascarados (`****` / `********`).
- `owner.psp` é o **código ISPB** (8 dígitos) do PSP da chave, não o nome do banco — se precisar exibir o nome, mantenha um mapeamento ISPB → instituição do seu lado.
- A cada chamada o DICT é consultado de novo e um novo `pixKeyEndToEndId` é gerado. Esse identificador é o que você precisa guardar e enviar no endpoint de [Criar Pagamento](./payment-how-to-use-api-to-create.mdx).

```json
{
  "pixKeyEndToEndId": "E12345678202601011200abcdefghijk",
  "pixKey": "00000000191",
  "type": "CPF",
  "owner": {
    "name": "Fulano de Tal",
    "taxID": "000.***.***-91",
    "psp": "12345678",
    "branch": "****",
    "account": "********************"
  }
}
```

## Erros possíveis

- `400` — chave em formato inválido (não passou em `CPF` / `CNPJ` / `EMAIL` / `PHONE` / UUID de 36 chars)
- `404 PIX_KEY_INFO_NOT_FOUND` — chave válida mas não cadastrada no DICT
- `400` para chave de risco — `Pix key related to an account suspected of fraud`
- `400` para DICT indisponível — `Error verifying pix key`
- `429` — rate limit do Bacen estourado (veja a seção "Limitação de Taxa" acima)
- `403 PIX_KEY_CHECK_NOT_ALLOWED` — sua conta não tem a feature liberada

Na rota `GET` os erros voltam com `error` + `errorCode`. Na rota `POST` apenas `error` é retornado.

## Cobrança

Cada consulta bem-sucedida pode gerar uma tarifa, que vem das configurações de fee da sua conta. A cobrança é **idempotente por dia, conta e chave**: consultar a mesma chave Pix mais de uma vez na mesma conta no mesmo dia gera só uma cobrança. Erros (chave não encontrada, rate limit, etc.) não geram cobrança.

## Prompt para IA

Copie o trecho abaixo numa IA de coding (Claude / Cursor / Gemini / ChatGPT) pra implementar a integração no seu app:

> Implemente uma função `checkPixKey(pixKey)` que consulta uma chave Pix no DICT do Banco Central via Woovi e devolve nome do titular, banco e identificador necessário pra pagamento.
>
> **Endpoint**: `POST https://api.woovi.com/api/v1/pix-keys/check`
> **Header**: `Authorization: <APP_ID>` e `Content-Type: application/json`
> **Body**: `{ "pixKey": "<chave>" }` (aceita CPF, CNPJ, email, telefone ou EVP/UUID; não aceita BRcode/copia e cola — use o endpoint de decode/emv pra isso)
>
> **Resposta de sucesso (200)**:
> ```json
> {
>   "pixKeyEndToEndId": "E12345678202601011200abcdefghijk",
>   "pixKey": "<chave normalizada>",
>   "type": "CPF" | "CNPJ" | "EMAIL" | "PHONE" | "RANDOM" | "EVP",
>   "owner": {
>     "name": "<nome do titular>",
>     "taxID": "",
>     "psp": "",
>     "branch": "****",
>     "account": "********************"
>   }
> }
> ```
>
> **Erros a tratar**: 404 `PIX_KEY_INFO_NOT_FOUND` (chave não encontrada), 400 (chave inválida ou chave de risco), 429 (rate limit do Bacen), 403 `PIX_KEY_CHECK_NOT_ALLOWED` (feature não liberada).
>
> **Detalhes importantes**:
> - `psp` é só o código ISPB (8 dígitos) — pra mostrar nome do banco mantenha um mapeamento ISPB → nome do seu lado.
> - `pixKey` sempre volta normalizado: telefone em E.164 (`+55...`), email em lowercase, CPF/CNPJ só dígitos.
> - `owner.taxID` de CPF vem mascarado (ex `111.***.***-80`); de CNPJ vem inteiro.
> - Cada consulta bem-sucedida pode ter custo, mas é idempotente por dia/conta/chave.
> - Guarde o `pixKeyEndToEndId` retornado se for usar pra criar um pagamento depois.

---

## Decodificar QR Code Pix / Copia e Cola

Este documento irá ajudá-lo a decodificar uma string de QR Code Pix ou Copia e Cola (formato EMV / BR Code do BCB).

O Copia e Cola é a mesma string que o QR Code carrega visualmente — basta passar essa string no body que o endpoint devolve os dados já parseados.

O endpoint cobre os três cenários típicos:
- **Estático**: chave Pix, valor e nome do recebedor já estão dentro do próprio payload e voltam direto na resposta, sem nenhuma chamada externa.
- **Dinâmico de cobrança (COB / COBV)**: o payload carrega uma URL `location` apontando pro PSP emissor da cobrança. O endpoint resolve essa URL, baixa o payload retornado pelo PSP e devolve em `cobLocation.payload`. O conteúdo vem em JWS assinado pelo PSP, mas a Woovi **não valida** a assinatura ICP-Brasil nem o domínio — se precisar dessa garantia, valide pelo seu lado a partir do `url`/`payload` retornado.
- **Pix Automático (REC)**: similar ao dinâmico, mas a `location` vem em outra tag do EMV (`unreservedTemplates`) e aponta para a estrutura de recorrência (idRec, periodicidade, contrato). O endpoint resolve e devolve em `recLocation.payload`.

- Faça a requisição passando a string do QR / Copia e Cola no campo `emv`:
```bash
curl -X POST "https://api.woovi.com/api/v1/decode/emv" \
  -H "Authorization: {APP_ID}" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "emv": "<string do QR Code ou Copia e Cola>"
  }'
```

Você pode acessar [aqui](/api#tag/decode/POST/api/v1/decode/emv) a documentação referente a esse _endpoint_.

### O que é retornado ?

A resposta sempre traz o objeto `emv` com o payload parseado e, quando aplicável, `cobLocation` ou `recLocation` com os dados resolvidos no PSP emissor.

Exemplo de resposta para um QR dinâmico de cobrança imediata (COB):

```json
{
  "emv": {
    "payloadFormatIndicator": "01",
    "pointOfInitiationMethod": "12",
    "merchantAccountInformationPix": {
      "gui": "br.gov.bcb.pix",
      "url": "qr-h.woovi.digital/qr/v2/cob/fb274322-221c-43d4-b58b-fab36d87c75c"
    },
    "merchantCategoryCode": "0000",
    "transactionCurrency": "986",
    "transactionAmount": "10.00",
    "countryCode": "BR",
    "merchantName": "Fulano",
    "merchantCity": "Sao_Paulo",
    "additionalDataFieldTemplate": {
      "referenceLabel": "fb274322-221c-43d4-b58b-f"
    },
    "crc": "0C98"
  },
  "cobLocation": {
    "isValid": true,
    "locationErrors": [],
    "payload": {
      "calendar": {
        "presentation": "2025-02-25T13:27:54.168Z",
        "expiration": 86400,
        "creation": "2025-02-12T16:59:22.939Z"
      },
      "key": "4004901d-bd85-4769-8e52-cb4c42c506dc",
      "debtor": {
        "cpf": "62550186362",
        "name": "Fulano de Tal"
      },
      "additionalInfo": [
        { "name": "Entrega", "value": "Residencial" }
      ],
      "revision": 0,
      "status": "ATIVA",
      "txid": "d71a2ffd7a7b468eba993cef83428583",
      "value": { "original": "120.58" }
    },
    "url": "qr-h.woovi.digital/qr/v2/cob/fb274322-221c-43d4-b58b-fab36d87c75c"
  },
  "recLocation": null
}
```

Quando o QR é uma cobrança com vencimento (COBV), o `cobLocation.payload` traz campos adicionais — `calendar.dueDate`, `validityAfterDueDate`, subcampos de juros/multa/desconto em `value` e dados completos do recebedor. Esses campos vêm direto do PSP emissor da cobrança, então a presença depende do que o PSP devolve:

```json
{
  "emv": {
    "payloadFormatIndicator": "01",
    "pointOfInitiationMethod": "12",
    "merchantAccountInformationPix": {
      "gui": "br.gov.bcb.pix",
      "url": "qrcode.exemplo.com.br/v1/cobv/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
    },
    "merchantCategoryCode": "0000",
    "transactionCurrency": "986",
    "countryCode": "BR",
    "merchantName": "Fulano Comercio LTDA",
    "merchantCity": "FLORIANOPOLIS",
    "additionalDataFieldTemplate": {
      "referenceLabel": "***"
    },
    "crc": "F684"
  },
  "cobLocation": {
    "isValid": true,
    "locationErrors": [],
    "payload": {
      "calendar": {
        "dueDate": "2026-05-22",
        "validityAfterDueDate": 30,
        "creation": "2026-05-22T16:07:05.051Z",
        "presentation": "2026-05-22T16:07:05.051Z"
      },
      "value": {
        "original": "100.00",
        "final": "100.00",
        "interest": "0.00",
        "fine": "0.00",
        "discount": "0.00",
        "rebate": "0.00"
      },
      "receiver": {
        "street": "Rua Exemplo 123",
        "city": "Florianopolis",
        "state": "SC",
        "zipcode": "88000000",
        "cnpj": "00000000000191",
        "name": "Fulano Comercio LTDA"
      },
      "debtor": {
        "cpf": "00000000191",
        "name": "Maria Compradora"
      },
      "revision": 0,
      "key": "11111111-2222-3333-4444-555555555555",
      "txid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "status": "ATIVA"
    },
    "url": "qrcode.exemplo.com.br/v1/cobv/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
  },
  "recLocation": null
}
```

Exemplo de resposta para um QR de Pix Automático (REC):

```json
{
  "emv": {
    "payloadFormatIndicator": "01",
    "merchantAccountInformationPix": {
      "gui": "br.gov.bcb.pix",
      "pixKey": "f4c6089a-bfde-4c00-a2d9-9eaa584b0219",
      "additionalInformation": "CobrancaEstatica"
    },
    "merchantCategoryCode": "0000",
    "transactionCurrency": "986",
    "transactionAmount": "546.28",
    "countryCode": "BR",
    "merchantName": "Pix",
    "merchantCity": "BRASILIA",
    "additionalDataFieldTemplate": {
      "referenceLabel": "84767c56c2ab4e65b6670de2a"
    },
    "unreservedTemplates": {
      "gui": "br.gov.bcb.pix",
      "url": "qr-h.sandbox.pix.bcb.gov.br/rest/api/rec/4b62d4a088fe4f51bcb4c64cf0788691"
    },
    "crc": "4486"
  },
  "cobLocation": null,
  "recLocation": {
    "isValid": true,
    "locationErrors": [],
    "payload": {
      "updates": [
        { "date": "2025-10-24T18:42:58Z", "status": "CRIADA" }
      ],
      "calendar": {
        "startDate": "2025-10-24",
        "periodicity": "SEMANAL"
      },
      "idRec": "RN5481141720251024BnwNHejs9h9",
      "retryPolicy": "NAO_PERMITE",
      "receiver": {
        "cnpj": "44720743000101",
        "participantIspb": "54811417",
        "name": "Woovi Demo"
      },
      "value": { "valueRec": "0.01" },
      "link": {
        "contract": "Woovi Demo - Pix Automático",
        "debtor": {
          "cpf": "15775023706",
          "name": "Pedro Cliente"
        }
      }
    },
    "url": "qr-h.sandbox.pix.bcb.gov.br/rest/api/rec/4b62d4a088fe4f51bcb4c64cf0788691"
  }
}
```

Para QR estático sem location, `cobLocation` e `recLocation` voltam como `null` e a chave / valor / nome do recebedor já estão dentro de `emv` (campos `merchantAccountInformationPix.pixKey`, `transactionAmount`, `merchantName`).

### Quando combinar com a Verificação de Chave Pix

Se depois do decode você for efetivamente disparar um pagamento via API, use a [Verificação de Chave Pix](./check-pix-key.md) com a chave extraída — ela devolve o `pixKeyEndToEndId` exigido pelo endpoint de [Criar Pagamento](./payment-how-to-use-api-to-create.mdx).

## Prompt para IA

Copie o trecho abaixo numa IA de coding (Claude / Cursor / Gemini / ChatGPT) pra implementar a integração no seu app:

> Implemente uma função `decodePixCode(emv)` que aceita a string de um QR Code Pix ou copia e cola (formato BR Code) e devolve os dados do destinatário já parseados (chave Pix, valor, nome, banco), pronta pra preview antes de o usuário confirmar o pagamento.
>
> **Endpoint**: `POST https://api.woovi.com/api/v1/decode/emv`
> **Header**: `Authorization: <APP_ID>` e `Content-Type: application/json`
> **Body**: `{ "emv": "<string do QR Code ou copia e cola>" }`
>
> **A resposta sempre traz `emv` com o payload parseado**. Dependendo do tipo de QR, um dos dois objetos abaixo vem populado (o outro vem `null`):
>
> - **QR estático**: `cobLocation` e `recLocation` ambos `null`. A chave, valor e nome do recebedor já estão dentro de `emv.merchantAccountInformationPix.pixKey`, `emv.transactionAmount` e `emv.merchantName`.
> - **QR dinâmico de cobrança imediata (COB) ou com vencimento (COBV)**: `cobLocation.payload` traz os dados completos já resolvidos no PSP emissor — `calendar` (creation/presentation/expiration ou dueDate), `value.original` (e `value.final/interest/fine/discount/rebate` para COBV), `key` (chave do recebedor), `debtor`, `receiver`, `txid`, `status`.
> - **QR de Pix Automático (REC)**: `recLocation.payload` traz `idRec`, `calendar.periodicity` (`SEMANAL` / `MENSAL` / etc), `receiver`, `value.valueRec`, `link.contract`, `link.debtor`.
>
> Em todos os casos com location, `isValid` é `true` quando o PSP emissor respondeu e `false` quando não — trate como erro e mostre fallback.
>
> **UX recomendada**:
> - Para o usuário, mostre o valor e o nome do recebedor logo que o decode retornar, mesmo antes da confirmação final.
> - Se o BRcode for dinâmico, prefira os campos de `cobLocation.payload` ou `recLocation.payload` (vêm direto do PSP emissor, são autoritativos) sobre os campos dentro de `emv` (são só os do payload local).
> - Se for disparar um pagamento via API em seguida, chame o endpoint de Pix Check com a chave extraída pra obter o `pixKeyEndToEndId` (exigido pra criar pagamento).
>
> Trate erros 400 (EMV inválido) e 500 mostrando mensagem amigável e oferecendo entrada manual da chave.

---

## Como identificar os erros de um pagamento falho?

## Erros e Descrições

| Código do Erro         | Descrição                                                 | Detalhe                                                                              |
| ---------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| ALIAS_LIMIT_ERROR      | Limite de consultas chave pix excedido                    | Toda conta possui um limite de consulta de chaves pix sem ter o pagamento liquidado. |
| PAY_PIX_KEY_ERROR      | Erro ao realizar o pagamento para a chave pix informada   | Erro ao processar o pagamento para a chave pix do pagamento                          |
| PIX_KEY_INFO_ERROR     | Erro ao consultar informações da chave pix do pagamento   | Erro durante a consulta de informações da chave pix                                  |
| PIX_KEY_INFO_NOT_FOUND | Chave pix informada não encontrada/registrada em um banco | A chave pix não está registrada em uma instituição bancária                          |
| INVALID_PIX_KEY        | Chave pix inválida                                        | A chave pix informada é inválida ou possui formato incorreto                         |
| REACH_TRANSFER_LIMIT   | Limite de transferência atingido                          | A conta atingiu o limite diurno/noturno de transferência pix                         |
| NOT_ENOUGH_BALANCE     | Saldo insuficiente                                        | A conta ou subconta não possui saldo suficiente para realizar a transferência        |
| ENTRY_ASSOCIATED_WITH_RESTRICTED_ACCOUNT_OR_USER | Conta restrita por fraude | A conta associada à chave pix está restrita por fraude pelo Banco Central |

### Limite de consultas chave pix excedido

As consultas de chaves pix utiliza o algoritmo "Leaky Bucket" para fazer controle da mesma.

#### O que é o Leaky Bucket?

O "leaky bucket" é um algoritmo usado para limitar as requisições feitas ao DICT (Diretório de Identificadores de Contas Transacionais). Ele funciona como um balde com um pequeno furo embaixo. As requisições são como a água que entra no balde, e a capacidade de processamento do sistema é o furo por onde a água escoa. Se muita água entra de uma vez (muitas requisições), o balde enche e algumas requisições podem ser limitadas ou bloqueadas.

#### Limitação de Consultas de Chave Pix

Quando você consulta uma chave Pix, o sistema verifica se o recebedor é autêntico e cria uma mensagem de instrução de pagamento. No entanto, se você consulta uma chave e não conclui o pagamento, isso pode levar a uma limitação ou bloqueio das suas consultas futuras. Se a chave Pix for inválida, suas tentativas podem se esgotar rapidamente, resultando no bloqueio da operação.

#### Política de Limitação

Existem diferentes políticas de limitação com base no tipo de usuário, para empresas a regra o seguinte:

Pessoa Jurídica (PJ): O limite é de 20 consultas. A cada consulta não concluída, esse saldo é reduzido. O saldo é reestabelecido após 2 horas para cada token.

Entender esses limites é essencial para evitar bloqueios indesejados. Recomendamos que as consultas de chave Pix sejam feitas com a intenção de completar o pagamento, e que se evite consultas desnecessárias ou repetitivas.

:::info
Artigo Original [https://ajuda.woovi.com/hc/duvidas-frequentes/articles/limite-consulta-chave-pix-pagamentos](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/limite-consulta-chave-pix-pagamentos)
:::

---

## Fluxo de Pagamento consultando chave pix

### Fluxo básico de Pagamento

Este documento irá ajudar a entender como criar e aprovar um pagamento pix na woovi

![diagrama sequencial fluxo basico de pagamento woovi](./__assets__/sequenceDiagrama_fluxo_de_pagamento.png)

### 1. Checar chave pix e obter pixKeyEndToEndId
  * para checar uma chave pix veja: [Verificação de chave pix](./check-pix-key.md)
### 2. Criando um pagamento
 * Utilize o endpoint de pagamento para criar um novo pagamento
 * Utilize o valor de pixKeyEndToEndId adiquirido no passo anterior para gerar um novo pagamento
 * Utilize o appId para autenticar a requisição
 * Faça a requisição
 ```JSON
    curl -X POST "https://api.woovi.com/api/v1/payment" \
      -H "Authorization: <appId>" \
      -H "Content-Type: application/json" 
      --data-raw '{
    "value": "<number centavos>",
    "destinationAlias": "<chave pix>",
    "destinationAliasType": "<tipo de chave pix, CPF, CNPJ, ...>",
    "pixKeyEndToEndId": "<pixKeyEndToEndId>",
    "correlationID": "<string para identificação de pagamento>",
    "comment": "<comment>"
  }'
 ```
 * Caso tudo ocorra corretamente, um código 200 será retornado.
 * No corpo da resposta terá:
 ```JSON
{
  "payment": {
    "value": "<number>",
    "destinationAlias": "<string>",
    "destinationAliasType": "CPF",
    "qrCode": "<string>",
    "correlationID": "<string>",
    "comment": "<string>",
    "status": "DENIED"
  }
}
  ```
### 3. Aprovando pagamento
 * Utilize o endpoint de aprovar pagamento para aprovar um pagamento
 * Utilize o valor de correlationID escolhido no passo anterior para aprovar pagamento
 * Utilize o appId para autenticar a requisição
 * Faça a requisição
 ```JSON
    curl -X POST "https://api.woovi.com/api/v1/payment/approve" \
      -H "Authorization: <appId>" \
      -H "Content-Type: application/json" 
      --data-raw '{
    "correlationID": "<string para identificação de pagamento>",
  }'
 ```
 * Caso tudo ocorra corretamente, um código 200 será retornado.
 * No corpo da resposta terá:
 ```JSON
{
  "payment": {
    "value": "<number>",
    "destinationAlias": "<string>",
    "destinationAliasType": "CPF",
    "qrCode": "<string>",
    "correlationID": "<string>",
    "comment": "<string>",
    "status": "DENIED"
  },
  "transaction": {
    "value": "<number>",
    "endToEndId": "<string>",
    "time": "<string>"
  },
  "destination": {
    "name": "<string>",
    "taxID": "<string>",
    "pixKey": "<string>",
    "bank": "<string>",
    "branch": "<string>",
    "account": "<string>"
  }
}
```

:::warning 

O DICT não deve ser utilizado para consultas cadastrais nem para finalidades diferentes da realização de transações utilizando uma chave Pix.

Para mais detalhes, consulte o Manual Operacional do Diretório de Identificadores de Contas Transacionais (DICT).

:::

---

## Como Pagamentos funcionam?

## O que são pagamentos?

Para realizar um pagamento, basta acessar a função de Saques e Pagamentos no menu principal da Woovi, clicar em Novo Pagamento e inserir as informações necessárias:

![payment create form](/img/payment/payment-create-form.png)

- Chave Pix de destino
- Valor a ser pago
- Comentário (opcional)

Depois disso, basta solicitar o pagamento, logo após é só aprovar e pronto! O dinheiro será transferido instantaneamente para a conta do destinatário.

### Qual o custo para realizar pagamentos?

O custo para realizar um pagamento é de R$ 1,00 por transação confirmada.

### Quem pode solicitar e aprovar pagamentos?

Por segurança, apenas usuários com nível Administrador têm permissão para solicitar e aprovar pagamentos.

### Em quanto tempo um pagamento é processado?

Os pagamentos realizados através da Woovi são processados em tempo real, ou seja, o dinheiro é transferido instantaneamente para a conta do destinatário.

### Por que usar a função de pagamentos?

A função de pagamentos da Woovi é uma forma rápida, segura e conveniente de transferir dinheiro para outras pessoas. Com a Woovi, você não precisa mais lidar com as grandes taxas e burocracias dos bancos tradicionais, pois as transações são criadas e processadas de forma simples e rápida. Além disso, todas as transações são criptografadas e protegidas por medidas de segurança avançadas, garantindo a proteção dos seus dados e do seu dinheiro.

---

## Como adicionar fundos para realizar Pagamentos?

## Adicionando fundos para realizar Pagamentos

Adicionar fundos na Woovi é um processo simples e rápido.

- Acesse `Contas` via sidemenu
- Clique em `Detalhes da Conta` na conta em que deseja adicionar fundos
- Na seção de `Detalhe da conta` procure pela Chave Pix de sua conta
- No App do seu banco, realize uma transfêrencia da quantia desejada para a Chave Pix da sua conta Woovi

![account pix key](/img/payment/add-funds-payment.png)

Agora você pode usar os fundos para realizar Pagamentos na Woovi!

---

## Como Aprovar Pagamentos em Lote?

## Aprovando Pagamentos em Lote

:::info
Pagamentos com os status de em processamento ou confirmados não podem ser aprovados
:::

Com a woovi você consegue aprovar solicitações pagamentos de uma forma fácil e prática:

- Acesse `Saques/Pagamentos`
- Clique na aba de Pagamentos
- Selecione na lista as solicitações que deseja aprovar
- Clique em `Aprovar Pagamentos`

![payment batch approve](/img/payment/payment-batch-approve.png)

- Revise as informações e clique em `Aprovar Solicitações`

![payment batch approve confirm](/img/payment/payment-batch-approve-confirm.png)

---

## Como criar e aprovar um pagamento em uma única chamada?

## Criando e aprovando um pagamento em uma única chamada

O campo `autoApprove` no endpoint `POST /api/v1/payment` permite criar e aprovar um pagamento Pix em uma única requisição, eliminando a necessidade de chamar o endpoint `/api/v1/payment/approve` separadamente.

## Como usar

Envie `autoApprove: true` no corpo da requisição ao criar um pagamento:

```json
{
  "value": 100,
  "destinationAlias": "c4249323-b4ca-43f2-8139-8232aab09b93",
  "destinationAliasType": "RANDOM",
  "comment": "pagamento comentário",
  "correlationID": "payment-1",
  "autoApprove": true
}
```

## Resposta

Quando `autoApprove: true` e o pagamento é aprovado, a resposta traz o `payment` com status `APPROVED`:

```json
{
  "payment": {
    "value": 100,
    "status": "APPROVED",
    "destinationAlias": "c4249323-b4ca-43f2-8139-8232aab09b93",
    "destinationAliasType": "RANDOM",
    "comment": "pagamento comentário",
    "correlationID": "payment-1",
    "sourceAccountId": "6823414a524ed520d3518dd6"
  }
}
```

> **Importante:** a resposta imediata do `autoApprove` **não** retorna o campo `destination` (dados bancários do recebedor). Como o Pix é enviado de forma assíncrona, o status muda para `CONFIRMED` (ou `FAILED`) depois da liquidação. Para obter os dados do recebedor (`destination`) e da transação (`endToEndId` etc.), use uma das opções abaixo:
>
> - o webhook [`OPENPIX:MOVEMENT_CONFIRMED`](../webhook/examples/payment-payload.mdx), que carrega `destination`; ou
> - uma consulta `GET /api/v1/payment/{correlationID}` após a confirmação.

Consultando o pagamento depois de confirmado, a resposta inclui `transaction` e `destination`:

```json
{
  "payment": {
    "value": 100,
    "status": "CONFIRMED",
    "correlationID": "payment-1",
    "sourceAccountId": "6823414a524ed520d3518dd6"
  },
  "transaction": {
    "value": 100,
    "endToEndId": "E...",
    "time": "2025-01-01T00:00:00.000Z"
  },
  "destination": {
    "name": "Dan",
    "taxID": "31324227036",
    "pixKey": "c4249323-b4ca-43f2-8139-8232aab09b93",
    "bank": "A Bank",
    "branch": "0001",
    "account": "123456"
  }
}
```

## Comportamento sem o flag

Quando `autoApprove` é omitido ou `false`, o pagamento é criado normalmente com status `CREATED` e pode ser aprovado posteriormente via [`POST /api/v1/payment/approve`](./payment-how-to-use-api-to-approve-a-payment.md).

```json
{
  "payment": {
    "value": 100,
    "status": "CREATED",
    "correlationID": "payment-1"
  }
}
```

## Saldo insuficiente

Ao tentar aprovar com saldo insuficiente, a requisição retornará erro `400`:

```json
{
  "error": "You do not have enough balance to make this payment"
}
```

## Referência da API

Acesse a documentação completa do endpoint em [API Reference](/api#tag/payment-request-access/POST/api/v1/payment).

---

## Como Criar Pagamentos em Lote?

## Criando Pagamentos em Lote com Excel

Com a woovi você consegue criar solicitações pagamentos com dados de um excel seguindo os passos:

- Acesse `Saques/Pagamentos`
- Clique na aba de Pagamentos
- Clique em `Pagamento em Lote`
- Baixe o Modelo do Excel clicando no link

![payment batch template](/img/payment/payment-batch-template.png)

- Preencha o modelo com os dados desejados
- Arraste e solte o arquivo no menu, ou clique em `escolha um arquivo` e selecione o arquivo preenchido
- Clique em `Avançar`
- Após o processamento do arquivo você poderá revisar e corrigir os dados

![payment batch review](/img/payment/payment-batch-review.png)

- Clique em `Gerar Solicitações`
- Após a importação terminar você verá uma tela com o relatório da importação

![payment batch report](/img/payment/payment-batch-report.png)

- Clique em `Ver Solicitações` para ser redirecionado para as solicitações criadas

:::info
Após a criação das solitações, os pagamentos ainda devem ser aprovados por um usuário
:::

---

## Onde encontro o id da minha conta?

## Encontrando o id da sua conta

Você pode encontrar o id da sua conta seguindo esses passos:

- Acesse `Contas` via sidemenu
- Clique em `Detalhes da Conta` na conta em que deseja pegar o id
- Na seção de `Detalhe da conta` procure pelo campo `ID da conta`

![account id](/img/payment/payment-account-id.png)

---

## Como consultar e listar Pagamentos?

## Listando Pagamentos com a API

Nós disponibilizamos o _endpoint_ `GET /api/v1/payment` para que você possa
listar os pagamentos (Pix Out) da empresa, filtrando por período e paginando os
resultados. É o endpoint indicado para reconciliação: a partir dele você
recupera o `status` e o `correlationID` de cada pagamento.

Você pode acessar [aqui](</api#tag/payment-request-access/GET/api/v1/payment>)
a documentação de referência desse _endpoint_.

Para usar esse endpoint, o seu AppID precisa ter o escopo `PAYMENT_GET_LIST`
habilitado.

### Parâmetros de consulta

- **`start`**: data inicial do filtro (sobre o `createdAt` do pagamento), no formato ISO 8601, ex.: `2026-06-01T00:00:00Z`.
- **`end`**: data final do filtro (sobre o `createdAt` do pagamento), no formato ISO 8601, ex.: `2026-06-30T23:59:59Z`.
- **`skip`**: quantos registros pular (paginação). Padrão `0`.
- **`limit`**: quantos registros retornar por página. Padrão `100`.

Se nenhum `start`/`end` for informado, a listagem não aplica o filtro de data.

Num exemplo prático, a requisição seguiria semelhante a este exemplo:

```bash
curl --location 'https://api.woovi.com/api/v1/payment?start=2026-06-01T00:00:00Z&end=2026-06-30T23:59:59Z&limit=100' \
  --header 'Authorization: SEU_APP_ID'
```

A resposta traz, para cada pagamento, o objeto `payment` (com `status`,
`correlationID`, `value`, `comment`, `destinationAlias` e `sourceAccountId`), o
objeto `transaction` (com `endToEndId` e horário) e o objeto `destination` (dados
do destinatário), além do `pageInfo` da paginação:

```json
{
  "pageInfo": {
    "skip": 0,
    "limit": 100,
    "hasPreviousPage": false,
    "hasNextPage": false
  },
  "status": "OK",
  "payments": [
    {
      "payment": {
        "status": "CONFIRMED",
        "value": 100,
        "destinationAlias": "c4249323-b4ca-43f2-8139-8232aab09b93",
        "comment": "payment comment",
        "correlationID": "payment1",
        "sourceAccountId": "my-source-account-id"
      },
      "transaction": {
        "value": 100,
        "endToEndId": "transaction-end-to-end-id",
        "time": "2023-03-20T13:14:17.000Z"
      }
    }
  ]
}
```

### Paginação

Para percorrer todas as páginas, use `pageInfo.hasNextPage` para saber se há
mais resultados e avance com `skip`. Para volumes grandes ou períodos longos,
**prefira estreitar o intervalo `start`/`end`** em vez de aumentar muito o
`skip` — há um limite máximo de `skip`, e o filtro por data é a forma indicada
para paginações mais profundas.

## Consultando um pagamento específico

Para consultar um único pagamento pelo seu `correlationID`, use o _endpoint_
`GET /api/v1/payment/{id}`, onde `{id}` é o `correlationID` informado na criação:

```bash
curl --location 'https://api.woovi.com/api/v1/payment/payment1' \
  --header 'Authorization: SEU_APP_ID'
```

:::tip
O `correlationID` é a chave de idempotência do pagamento. Ao reprocessar um
pagamento, reuse o mesmo `correlationID` até ele chegar a um estado terminal
(`CONFIRMED` ou `REJECTED`) — gerar um `correlationID` novo para o mesmo
pagamento cria uma duplicata. Veja [Idempotência](../concepts/idempotence.md).
:::

---

## Como Pagar Contas?

Você pode pagar suas contas por pix utilizando a plataforma. Com isso você consegue pagar uma conta diretamente com o seu saldo na plataforma.

Para pagar contas utilizando a sua empresa siga os passos abaixo:

## 1. Solicitar o Pagamento de uma Conta

- Acesse `Saques e Pagamentos` via sidemenu
- Clique em `Pagar Conta`
- Preencha os campos informados

| Campo              | Descrição                                                                   |
| ------------------ | --------------------------------------------------------------------------- |
| Tipo de pagamento  | tipo do pagamento, copiar qr code ou ler qr code                            |
| QR Code            | código do qr code                                                           |
| Valor de Pagamento | valor total do pagamento, preenchido automaticamente ao preencher o qr code |
| Comentário         | comentário opcional que será enviado junto ao pagamento                     |
| Conta de origem    | conta de origem que vai realizar o pagamento                                |

- Clique em `Solicitar`

![pay bills](./__assets__/pay-bills.png)

## 2. Aprovar o Envio de um Pagamento

- Acesse `Saques e Pagamentos` via sidemenu
- Clique na aba de `Solicitações de Pagamentos`
- Clique na Solicitação a ser aprovada
- Clique em `Aprovar Pagamento`
- Confira os dados informados
- Clique em `Aprovar`

![approve payment bill](./__assets__/approve-payment-bill.png)

---

## Como Remover Solicitações de Pagamentos?

## Removendo Solicitações de Pagamentos

:::info
Pagamentos com os status de em processamento ou confirmados não podem ser removidos
:::

Remover solicitações de pagamentos na woovi é um processo simples e rápido.

- Acesse `Saques/Pagamentos`
- Clique na aba de Pagamentos
- Selecione na lista as solicitações que deseja remover
- Clique em `Remover Pagamentos`

![payment remove](/img/payment/payment-remove.png)

- Após isso você receberá uma confirmação que as solicitações foram removidas

---

## Como Solicitar Acesso a Pagamentos?

## Solicitando acesso para realizar Pagaemntos

Se você é um cliente Woovi e deseja solicitar a funcionalidade de pagamentos, saiba que é muito simples e fácil:
Para solicitar a funcionalidade de pagamentos, basta entrar em contato com o suporte da Woovi por meio do chat disponível na plataforma. Ao acessar o chat, um atendente estará disponível para auxiliá-lo e fornecer todas as informações necessárias para a ativação da funcionalidade.

É importante lembrar que, para solicitar a funcionalidade de pagamentos, é preciso ter uma conta ativa na Woovi. Se você ainda não possui uma conta, basta criar uma gratuitamente e, em seguida, entrar em contato com o suporte para ativar a funcionalidade de pagamentos.

---

## Como usar a API de Aprovar Pagamentos?

## Aprovando pagamentos com api

Nós disponibilizamos o _endpoint_ `/api/v1/payment/approve` para que você possa approvar um pagamento criado a partir da sua respectiva empresa filiada

Você pode acessar aqui
a documentação referente a esse _endpoint_.

Como parte do `body` da requisição, esperamos o envio dos seguintes itens: `correlationID`:

- **`correlationID`**: Um identificador único para o pagamento.

Num exemplo prático, o body da sua requisição seguiria semelhante a este exemplo:

```json
{
  "correlationID": "31ee9576-99ec-412a-9ac7-e142a4a6acf0",
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta,
você estará vendo as informações sobre o `payment` recém aprovado, dados da transação e destinatário.

Num exemplo, essa será a nossa resposta:

```json
{
  "payment": {
    "value": 100,
    "status": "APPROVED",
    "destinationAlias": "c4249323-b4ca-43f2-8139-8232aab09b93",
    "comment": "payment comment",
    "correlationID": "payment1",
    "sourceAccountId": "my-source-account-id"
  },
  "transaction": {
    "value": 100,
    "endToEndId": "transaction-end-to-end-id",
    "time": "2023-03-20T13:14:17.000Z"
  },
  "destination": {
    "name": "Dan",
    "taxID": "31324227036",
    "pixKey": "c4249323-b4ca-43f2-8139-8232aab09b93",
    "bank": "A Bank",
    "branch": "1",
    "account": "123456"
  }
}
```

## Saldo insuficiente ao aprovar pagamentos via API
Ao tentar realizar a aprovação de um pagamento via API e estiver sem saldo será retornado o seguinte erro:

```ts
{
    "error": "Você não possui saldo o suficiente para realizar esse pagamento"
}
```

Na plataforma o pagamento continuará com o status solicitado sendo possível realizar a aprovação do mesmo quando houver saldo suficiente.

---

## Como usar a API de Criar Pagamentos?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## Criando Pagamentos com a API

Nós disponibilizamos o _endpoint_ `/api/v1/payment` para que você possa criar
um novo _payment_ para a respectiva empresa afiliada.

Você pode acessar [aqui](</api#tag/payment-request-access/POST/api/v1/payment>)
a documentação referente a esse _endpoint_.

Como parte do `body` da requisição, possuímos dois modos de pagamento, por chave Pix e por QR Code:

1. Por chave Pix, esperamos o envio obrigatório dos itens `value`, `destinationAlias`, `destinationAliasType` e `correlationID`.
2. Por QR Code, esperamos o envio obrigatório dos itens `qrCode` e `correlationID`.

Abaixo temos a descrição de cada campo junto dos opcionais:

- **`value`**: O valor em centavos do pagamento a ser criado.
- **`destinationAlias`**: A chave pix destinatária do pagamento criado.
- **`destinationAliasType`**: A tipo da chave pix destinatária do pagamento criado. Deve ser um dos seguintes valores: CPF, CNPJ, EMAIL, PHONE, RANDOM.
- **`qrCode`**: O QR Code a ser pago
- **`correlationID`**: Um identificador único para o pagamento.
- **`comment`**: Comentário que será atrelado a seu pagamento quando a transferencia for realizada.
- **`sourceAccountId`**: O ID da conta de origem, se não informado será utilizado a conta padrão.

Num exemplo prático, o body da sua requisição seguiria semelhante a este exemplo:

```mdx-code-block
<Tabs>
  <TabItem value="pix-key" label="Usando chave Pix" default>
```

```json
{
  "value": 100,
  "destinationAlias": "38763885700",
  "destinationAliasType": "CPF",
  "correlationID": "31ee9576-99ec-412a-9ac7-e142a4a6acf0",
  "comment": "um comentário"
}
```

```mdx-code-block
  </TabItem>
  <TabItem value="qr-code" label="Usando QR Code" default>
```

```json
{
  "qrCode": "000201010212261060014br.gov.bcb.pix2584https://api.openpix.com.br/openpix/testing?transactionID=867ba5173c734202ac659721306b38c952040000530398654040.015802BR5909LOCALHOST6009Sao Paulo62360532867ba5173c734202ac659721306b38c963044BCA",
  "comment": "payment comment",
  "correlationID": "payment1"
}
```

```mdx-code-block
  </TabItem>
</Tabs>
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta,
você estará vendo as informações sobre o `payment` recém criado.

Num exemplo, essa será a nossa resposta:

```mdx-code-block
<Tabs>
  <TabItem value="pix-key" label="Payload usando chave Pix" default>
```

```json
{
  "payment": {
    "value": 100,
    "status": "CREATED",
    "destinationAlias": "c4249323-b4ca-43f2-8139-8232aab09b93",
    "destinationAliasType": "RANDOM",
    "comment": "payment comment",
    "correlationID": "payment1",
    "sourceAccountId": "my-source-account-id"
  }
}
```

```mdx-code-block
  </TabItem>
  <TabItem value="qr-code" label="Payload usando QR Code" default>
```

```json
{
  "payment": {
    "value": 100,
    "status": "CREATED",
    "destinationAlias": "c4249323-b4ca-43f2-8139-8232aab09b93",
    "destinationAliasType": "RANDOM",
    "qrCode": "000201010212261060014br.gov.bcb.pix2584https://api.openpix.com.br/openpix/testing?transactionID=867ba5173c734202ac659721306b38c952040000530398654040.015802BR5909LOCALHOST6009Sao Paulo62360532867ba5173c734202ac659721306b38c963044BCA",
    "comment": "payment comment",
    "correlationID": "payment1",
    "sourceAccountId": "my-source-account-id"
  }
}
```

```mdx-code-block
  </TabItem>
</Tabs>
```

---

## Como realizar Pagamentos?

Para realizar Pagamentos em sua empresa siga os passos abaixo:

## 1. Ativar Permissões para Pagamentos na Conta

- Acesse `Contas` via sidemenu
- Clique em `Detalhes da Conta` na conta que deseja realizar pagamentos
- Clique na aba de `Ajustes`
- Na seção de `Pagamentos` habilite a opção de `Permitir que a conta possa realizar pagamentos`

![payment permission](/img/payment/payment-permission.png)

## 2. Solicitar o Envio de um Pagamento

- Acesse `Saques e Pagamentos` via sidemenu
- Clique em `Solicitar Pagamento`
- Preencha os campos informados

| Campo                  | Descrição                                               |
| ---------------------- | ------------------------------------------------------- |
| Chave Pix do Recebedor | chave pix destinatária do pagamento                     |
| Valor de Pagamento     | valor total do pagamento                                |
| Comentário             | comentário opcional que será enviado junto ao pagamento |
| Conta de origem        | conta de origem que vai realizar o pagamento            |

- Clique em `Solicitar`

![new payment](/img/payment/new-payment.png)

## 3. Aprovar o Envio de um Pagamento

- Acesse `Saques e Pagamentos` via sidemenu
- Clique na aba de `Solicitações de Pagamentos`
- Clique na Solicitação a ser aprovada
- Clique em `Aprovar Pagamento`
- Confira os dados informados
- Clique em `Aprovar`

![approve payment](/img/payment/approve-payment.png)

## Saldo insuficiente ao aprovar pagamentos via Plataforma
Ao tentar realizar a aprovação de um pagamento via plataforma e estiver sem saldo o modal será exibido com a seguinte informação:

![Modal de aprovação de pagamentos com a informação de saldo insuficiente](__assets__/payment-how-to-use-modal-without-balance.png)

Na plataforma o pagamento continuará com o status solicitado sendo possível realizar a aprovação do mesmo quando houver saldo suficiente.

---

## Idempotência em Pagamentos: reuse o correlationID

## Idempotência em Pagamentos

O `correlationID` é a **chave de idempotência** dos pagamentos (Pix Out) criados
via `POST /api/v1/payment`: enquanto ele for o mesmo, o pagamento é criado uma
única vez.

- Se você reenviar uma requisição com o **mesmo** `correlationID` (retry por timeout, reprocessamento de planilha, etc.), a API rejeita a segunda chamada com `Já existe um pagamento com o correlationID fornecido` — o valor **não** sai duas vezes.
- Se você enviar um `correlationID` **diferente** para o mesmo pagamento, a API trata como um pagamento **novo** e o valor **sai novamente**. Não existe uma trava por "mesmo valor para o mesmo destinatário" — a unicidade é garantida apenas pelo `correlationID`.

Por isso, a regra de ouro ao reprocessar um pagamento é:

> **Reuse o mesmo `correlationID` em todas as tentativas até o pagamento chegar a um estado terminal (`CONFIRMED` ou `REJECTED`). Só gere um novo `correlationID` depois disso.**

Gerar um `correlationID` novo enquanto o pagamento ainda está pendente é a causa
mais comum de pagamentos duplicados ou triplicados em integrações.

```js
// ERRADO: novo correlationID a cada tentativa => duplica o pagamento
function pagarComRetry(pagamento) {
  return api.post('/api/v1/payment', {
    correlationID: uuidv4(), // <- ID novo a cada retry
    value: pagamento.value,
    destinationAlias: pagamento.pixKey,
    destinationAliasType: pagamento.pixKeyType,
  });
}

// CERTO: correlationID estável, gerado e persistido uma vez por pagamento
function pagarComRetry(pagamento) {
  // pagamento.correlationID é gerado e salvo no seu banco ao criar o pagamento,
  // e reusado em todas as tentativas até CONFIRMED/REJECTED
  return api.post('/api/v1/payment', {
    correlationID: pagamento.correlationID,
    value: pagamento.value,
    destinationAlias: pagamento.pixKey,
    destinationAliasType: pagamento.pixKeyType,
  });
}
```

Para acompanhar o estado de um pagamento e decidir quando é seguro gerar um novo
`correlationID`, consulte [Como consultar e listar Pagamentos?](./payment-how-to-list.md)
e a [Máquina de Estados do Pagamento](./payment-state-machine.md). Sobre o
conceito geral, veja [Idempotência](../concepts/idempotence.md) e
[Correlation ID](../concepts/correlation-id.md).

---

## Conciliação do pagamento Pix (Pix Out) — correlationID x endToEndId

# Conciliação do pagamento Pix (Pix Out)

## Resumo

Depois de criar um pagamento Pix (Pix Out) via `POST /api/v1/payment` com um
**`correlationID`** próprio, é comum precisar **relacionar** esse
`correlationID` com o **`endToEndId`** (o id oficial da transação Pix, gerado
pelo Banco Central) para fins de conciliação.

| Forma | Quando usar |
| --- | --- |
| **Webhook `OPENPIX:MOVEMENT_CONFIRMED`** | Você quer ser **avisado** no momento em que o pagamento é confirmado, já recebendo `correlationID` e `endToEndId` juntos — sem polling. |
| **`GET /api/v1/payment/{id}`** | Você quer **consultar sob demanda** um pagamento específico, usando o **`correlationID`** que você mesmo definiu. |
| **`GET /api/v1/payment`** | Você quer conciliar **em lote**, listando os pagamentos de um período. |

:::caution GET /api/v1/transaction não retorna o correlationID do pagamento
É comum tentar localizar o `correlationID` consultando
**`GET /api/v1/transaction`** (ou `GET /api/v1/transaction?withdrawal={endToEndId}`)
— mas esse endpoint lista as **transações Pix** (o evento processado pelo Banco
Central), não os **pagamentos** (o pedido que você fez). Por isso a resposta
traz `endToEndId`, `value`, `time`, contas, etc., mas **não** traz o
`correlationID` do pagamento que originou aquela transação.

Para relacionar as duas pontas, use sempre `GET /api/v1/payment/{id}` ou o
webhook `OPENPIX:MOVEMENT_CONFIRMED`, descritos abaixo.
:::

---

## Forma 1 (recomendada) — Webhook `OPENPIX:MOVEMENT_CONFIRMED`

Assim que o pagamento é confirmado, a Woovi dispara o webhook
**`OPENPIX:MOVEMENT_CONFIRMED`** já com o `payment.correlationID` e o
`transaction.endToEndId` no mesmo payload:

```json
{
  "event": "OPENPIX:MOVEMENT_CONFIRMED",
  "payment": {
    "value": 30,
    "status": "CONFIRMED",
    "destinationAlias": "06882328684",
    "comment": "",
    "correlationID": "222a1750-de17-406c-bd0c-25af9a5a5d08"
  },
  "transaction": {
    "value": 30,
    "endToEndId": "E23114447202303161242u80lZNR7nQZ",
    "time": "2023-03-16T12:42:47.526Z"
  }
}
```

Salvando esse mapeamento assim que o webhook chega, você deixa de precisar
consultar a API depois para descobrir o `endToEndId` de um pagamento — ele já
fica disponível no seu sistema desde a confirmação.

Para receber esse evento, crie um webhook selecionando o evento
**`OPENPIX:MOVEMENT_CONFIRMED`** — veja
**[Tipos de eventos do Webhook](/docs/webhook/webhook-events-type#openpixmovement_confirmed)**
e o **[Payload de Pagamentos](/docs/webhook/examples/webhook-payment-payload)**.
A criação pode ser feita **[via plataforma](/docs/webhook/platform/webhook-platform-api)**
ou **[via API](/docs/webhook/webhook-api)**; para validar a assinatura, veja
**[Validando o HMAC do webhook](/docs/webhook/seguranca/webhook-hmac)**.

:::info Em caso de falha
Quando o pagamento falha, o evento disparado é **`OPENPIX:MOVEMENT_FAILED`**,
com `payment.status` em `FAILED` e um objeto `error` com o motivo. Veja a
**[lista de erros de pagamento](/docs/payment/payment-failed-errors)**.
:::

---

## Forma 2 — Consultar pelo correlationID (`GET /api/v1/payment/{id}`)

Se preferir consultar sob demanda em vez de depender do webhook, use o
endpoint de pagamento passando o **`correlationID`** (ou o `id` interno) que
você definiu na criação:

[Get one Payment request](</api#tag/payment-request-access/GET/api/v1/payment/{id}>)

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/payment/222a1750-de17-406c-bd0c-25af9a5a5d08 \
  --header 'Authorization: {APP_ID}'
```

A resposta traz o `payment` (com `correlationID`, `status`, `value`, etc.) e,
quando a transação já existe, o objeto `transaction` com o `endToEndId`:

```json
{
  "payment": {
    "status": "CONFIRMED",
    "value": 30,
    "correlationID": "222a1750-de17-406c-bd0c-25af9a5a5d08",
    "destinationAlias": "06882328684"
  },
  "transaction": {
    "value": 30,
    "endToEndId": "E23114447202303161242u80lZNR7nQZ",
    "time": "2023-03-16T12:42:47.526Z"
  },
  "destination": {
    "name": "...",
    "taxID": "...",
    "pixKey": "...",
    "bank": "..."
  }
}
```

`payment.correlationID` e `transaction.endToEndId` vêm juntos na mesma
resposta — não é necessária nenhuma outra chamada para relacioná-los.

:::tip
O `correlationID` também é a chave de idempotência do pagamento — reuse-o em
retentativas até o pagamento chegar a um estado final (`CONFIRMED` ou
`FAILED`). Veja **[Idempotência em Pagamentos](/docs/payment/payment-idempotency)**
e a **[Máquina de Estados do Pagamento](/docs/payment/payment-state-machine)**.
:::

---

## Forma 3 — Listar em lote (`GET /api/v1/payment`)

Para fechar um período inteiro de uma vez — em vez de consultar pagamento por
pagamento — use a listagem, filtrando por data:

```bash
curl --request GET \
  --url 'https://api.woovi.com/api/v1/payment?start=2026-06-01T00:00:00Z&end=2026-06-30T23:59:59Z&limit=100' \
  --header 'Authorization: {APP_ID}'
```

Cada item da lista já traz `payment.correlationID` e `transaction.endToEndId`
juntos. Veja os detalhes de paginação em
**[Como consultar e listar Pagamentos?](/docs/payment/payment-how-to-list)**.

---

## E o reembolso? Como vincular um reembolso à transação original

O mesmo tipo de dúvida aparece na direção contrária: depois de estornar uma
cobrança recebida, como saber a qual cobrança original aquele reembolso
pertence?

A resposta é a mesma lógica: **use o identificador da cobrança original**
(`correlationID`, `transactionID` ou id interno) como âncora — tanto para criar
quanto para consultar os reembolsos, já que todo reembolso é criado e
consultado **dentro do contexto da cobrança que ele estorna**:

- **Criar:** `POST /api/v1/charge/{id}/refund` — veja
  **[Como criar um reembolso de uma cobrança usando a API?](/docs/refund/charge-refund-create-api)**
- **Consultar todos os reembolsos de uma cobrança:** `GET /api/v1/charge/{id}/refund`
  — veja **[Como buscar todos os reembolsos de uma cobrança usando a API?](/docs/refund/charge-refund-get-all-api)**

Assim, a partir do `correlationID` que você já usa para identificar a cobrança
no seu sistema, você chega direto em todos os reembolsos associados a ela, sem
precisar cruzar dados manualmente entre cobrança, transação e estorno.

---

## Fluxo recomendado

1. Crie o pagamento com um `correlationID` próprio, estável por operação (veja
   **[Idempotência em Pagamentos](/docs/payment/payment-idempotency)**).
2. Prefira o **webhook `OPENPIX:MOVEMENT_CONFIRMED`** para capturar
   `correlationID` e `endToEndId` juntos no momento da confirmação, sem
   polling.
3. Como alternativa ou reforço, consulte
   **`GET /api/v1/payment/{correlationID}`** sob demanda.
4. Para fechamento de período, use **`GET /api/v1/payment`** com `start`/`end`.
5. Para reembolsos de cobranças, ancore sempre pelo `correlationID`/`id` da
   **cobrança original** ao criar (`POST /api/v1/charge/{id}/refund`) e ao
   consultar (`GET /api/v1/charge/{id}/refund`).
6. Reserve **`GET /api/v1/transaction`** para consultar o histórico de
   transações Pix recebidas ou o detalhe de uma transação pelo `endToEndId` —
   não para localizar o `correlationID` de um pagamento.

---

## Máquina de Estados do Pagamento

## Como funciona a Máquina de Estados do Pagamento

Um Pagamento possui os seguinte estados.

### Solicitado

O estado Solicitado significa que um usuário solicitou que um pagamento seja feito a uma chave Pix, e esta aguardando ser aprovado.

Esse estado pode seguir para o seguinte estados:

- Processando
- Falhou

### Processando

O estado Processando significa que o pagamento foi aprovado, a transação criada e agora esta sendo processada.

Esse estado pode seguir para o seguinte estados:

- Confirmado
- Falhou

### Confirmado

O estado Confirmado significa que a transação do pagamento foi confirmada, e a chave pix informada recebeu os fundos.

Esse é um estado final e após atingir esse estado, não poderá sofrer mais nenhuma alteração.

### Falhou

O estado Falhou significa que houve algum erro criando ou durante a transação do pagamento.

Esse é um estado final e após atingir esse estado, não poderá sofrer mais nenhuma alteração.

---

## Token Bucket: limite de consultas de chave Pix

Toda consulta de chave Pix passa pelo DICT, o diretório de chaves do Banco Central. O Bacen limita quantas consultas cada participante pode fazer e penaliza consultas a chaves inexistentes — é assim que ele impede varredura de dados de titulares.

Para distribuir essa cota entre as contas, a Woovi usa um **token bucket** (balde de fichas): sua conta tem um saldo de tokens, cada consulta gasta tokens, e o balde é reabastecido continuamente.

Esse limite vale para a [Verificação de Chave Pix](./check-pix-key.md) e para qualquer chamada que precise resolver uma chave no DICT, como a [criação de um pagamento por chave Pix](./payment-how-to-use-api-to-create.mdx).

## Como funciona

- O balde é **por conta (taxID)**, não por AppID. Todas as suas aplicações e chaves de API compartilham o mesmo saldo.
- Cada consulta bem-sucedida gasta pouco; cada consulta que falha no DICT gasta muito.
- O balde é reabastecido a uma taxa fixa por minuto, até um teto máximo.
- Os valores padrão são **500 tokens de teto** e **20 tokens por minuto**, mas a sua conta pode ter limites diferentes. Nunca fixe esses números no código — leia sempre do endpoint `/api/v1/pix-keys/tokens`.

## Quanto custa cada consulta

| Resultado da consulta | Tokens |
| --- | --- |
| Chave encontrada no DICT | **-1** |
| Chave não encontrada (`404 PIX_KEY_INFO_NOT_FOUND`) | **-20** |
| Chave recusada pelo DICT como inválida | **-20** |
| `429` vindo do próprio DICT | **-20** |
| Chave que já está em cache da Woovi | **0** |
| Chave de uma conta Woovi (transferência interna) | **0** |

O que pesa não é o volume de consultas, e sim a **taxa de erro**: 500 consultas válidas cabem no balde padrão, mas 25 consultas a chaves inexistentes já o esvaziam.

### Cache reduz o custo

- Uma chave encontrada fica em cache pelo tempo que o próprio DICT indicar. Consultar a mesma chave de novo dentro dessa janela **não gasta token**.
- Uma chave não encontrada fica em cache por 5 minutos. Repetir a mesma chave inexistente dentro desses 5 minutos **não cobra os 20 tokens de novo** — mas cada chave inexistente diferente cobra.

### Pagar devolve tokens

Quando você consulta uma chave e **efetivamente envia o pagamento** para ela, sua conta recebe **+2 tokens de volta** no momento da aprovação.

## Quando você é bloqueado

O bloqueio acontece **antes de o saldo chegar a zero**: se o balde tiver **menos de 20 tokens**, a consulta é recusada sem nem chegar ao DICT.

```json
{
  "error": "You tried to consult many Pix keys that do not exist.",
  "errorCode": "TOO_MANY_REQUESTS"
}
```

A resposta vem com status `429`. Com a taxa padrão de 20 tokens por minuto, sair do zero e voltar a poder consultar leva cerca de **1 minuto**.

:::caution
Pagamentos por QR Code / Copia e Cola não gastam tokens, mas **também são bloqueados** quando o balde está abaixo do mínimo. Um balde esvaziado por consultas de chave inexistente derruba o seu fluxo de pagamento inteiro.
:::

## Consultando seu saldo

```bash
curl -X GET "https://api.woovi.com/api/v1/pix-keys/tokens" \
  -H "Authorization: {APP_ID}"
```

```json
{
  "tokens": 480,
  "nextRefresh": "2026-01-01T12:01:00.000Z",
  "maxTokens": 500,
  "tokensAfterRefresh": 500,
  "refreshRate": 20
}
```

- `tokens` — saldo atual, já com a recarga acumulada desde a última operação.
- `maxTokens` — teto do balde da sua conta.
- `refreshRate` — quantos tokens sua conta recupera por minuto.
- `nextRefresh` — quando entra a próxima recarga.
- `tokensAfterRefresh` — saldo previsto depois dessa recarga.

Você pode acessar [aqui](/api#tag/pixkey/GET/api/v1/pix-keys/tokens) a documentação referente a esse _endpoint_.

:::info
A recarga é calculada no momento da consulta, a partir do tempo decorrido. Você não perde tokens por ficar sem chamar a API — o saldo já vem atualizado.
:::

## Histórico de consumo

Cada movimentação do balde é registrada e pode ser auditada:

```bash
curl -X GET "https://api.woovi.com/api/v1/pix-keys/tokens/logs?limit=50" \
  -H "Authorization: {APP_ID}"
```

```json
{
  "logs": [
    {
      "operation": "REMOVE",
      "reason": "NOT_FOUND_PIX_KEY",
      "tokens": 20,
      "tokensBefore": 100,
      "tokensAfter": 80,
      "endToEndId": "E12345678202601011200abcdefghijk",
      "pixKey": "00000000191",
      "createdAt": "2026-01-01T10:30:00.000Z"
    },
    {
      "operation": "REFILL",
      "reason": "REFILL",
      "tokens": 20,
      "tokensBefore": 80,
      "tokensAfter": 100,
      "createdAt": "2026-01-01T10:31:00.000Z"
    }
  ],
  "pageInfo": {
    "skip": 0,
    "limit": 50,
    "hasPreviousPage": false,
    "hasNextPage": true
  }
}
```

Parâmetros de query aceitos: `skip`, `limit` e `companyBankAccount`.

Motivos possíveis em `reason`:

| `reason` | `operation` | O que aconteceu |
| --- | --- | --- |
| `DICT_LOOKUP` | `REMOVE` | Consulta bem-sucedida no DICT |
| `NOT_FOUND_PIX_KEY` | `REMOVE` | Chave não existe no DICT |
| `INVALID_PIX_KEY` | `REMOVE` | Chave recusada como inválida pelo DICT |
| `TOO_MANY_REQUESTS` | `REMOVE` | O DICT respondeu `429` |
| `REFILL` | `REFILL` | Recarga por tempo decorrido |
| `CACHE_HIT_REFUND` | `ADD` | Estorno de 2 tokens: pagamento enviado para chave que estava em cache |
| `DICT_MESSAGE_REFUND` | `ADD` | Estorno de 2 tokens: pagamento enviado para chave já consultada no DICT |
| `SUBACCOUNT_NOT_FOUND_REFUND` | `ADD` | Estorno em fluxo de subconta |

Use esse histórico para descobrir **qual chave** está drenando seu balde: filtre por `reason: NOT_FOUND_PIX_KEY` e olhe o campo `pixKey`.

Você pode acessar [aqui](/api#tag/pixkey/GET/api/v1/pix-keys/tokens/logs) a documentação referente a esse _endpoint_.

## Boas práticas

1. **Valide o formato da chave antes de chamar a API.** CPF, CNPJ, e-mail, telefone em E.164 ou UUID de 36 caracteres. Formato errado nem chega ao DICT, mas chave bem formatada e inexistente custa 20 tokens.
2. **Nunca faça retry de um `404`.** A chave não passa a existir na segunda tentativa, e cada nova chave inexistente custa 20 tokens.
3. **Guarde o `pixKeyEndToEndId`** retornado na verificação e reutilize-o na criação do pagamento, em vez de consultar a mesma chave duas vezes.
4. **Não valide chave digitada a cada tecla.** Consulte só quando o usuário terminar de digitar.
5. **Cheque o saldo antes de processar lotes.** Antes de um lote de N pagamentos, chame `/pix-keys/tokens` e compare com o seu volume.
6. **Trate o `429` com espera, não com retry imediato.** Use `nextRefresh` do endpoint de tokens para saber quando voltar.
7. **Monitore os logs.** Um pico de `NOT_FOUND_PIX_KEY` normalmente indica base de cadastro desatualizada ou digitação livre sem validação.

## Requisitos de acesso

Os endpoints `/pix-keys/tokens` e `/pix-keys/tokens/logs` exigem uma conta Woovi com a funcionalidade de verificação de chave Pix liberada. Sem isso a resposta é `403`:

```json
{
  "error": "Your account does not have the permission to use this endpoint"
}
```

Veja [Como Solicitar Acesso a Pagamentos?](./payment-how-to-request-access.md).

## Prompt para IA

Copie o trecho abaixo numa IA de coding (Claude / Cursor / Gemini / ChatGPT) pra tratar o rate limit no seu app:

> Implemente controle de rate limit para consultas de chave Pix na API da Woovi.
>
> **Contexto**: consultas de chave Pix consomem um "token bucket" por conta. Consulta bem-sucedida custa 1 token; chave não encontrada, chave inválida ou `429` do DICT custam 20 tokens. Consultas atendidas por cache custam 0. Quando o saldo fica abaixo de 20 tokens, a API responde `429` com `errorCode: TOO_MANY_REQUESTS`.
>
> **Endpoint de saldo**: `GET https://api.woovi.com/api/v1/pix-keys/tokens` com header `Authorization: <APP_ID>`, resposta `{ "tokens": number, "maxTokens": number, "refreshRate": number, "nextRefresh": string, "tokensAfterRefresh": number }`.
>
> **Endpoint de histórico**: `GET https://api.woovi.com/api/v1/pix-keys/tokens/logs?skip=0&limit=50`, resposta `{ logs: [{ operation, reason, tokens, tokensBefore, tokensAfter, endToEndId, pixKey, createdAt }], pageInfo }`.
>
> **Requisitos**:
> - Valide o formato da chave localmente (CPF, CNPJ, e-mail, telefone E.164, UUID de 36 chars) antes de qualquer chamada.
> - Nunca faça retry de `404` (chave não encontrada) — cada tentativa custa 20 tokens.
> - Em `429`, não faça retry imediato: consulte `/pix-keys/tokens` e espere até `nextRefresh`.
> - Antes de processar um lote, cheque `tokens` e não dispare mais consultas do que o saldo suporta.
> - Faça cache local do resultado da consulta e reutilize o `pixKeyEndToEndId` na criação do pagamento.
> - Não fixe `maxTokens` nem `refreshRate` no código: leia sempre da API, pois variam por conta.

---

## Fluxograma

## Criação de uma assinatura
```mermaid
sequenceDiagram
    Sua Empresa->>+Woovi: POST /subscription
    Woovi-->>-Sua Empresa: QR Code
    Sua Empresa->>+Consumidor: Enviar o QR Code
    Consumidor-->>Woovi: Aprovar QR Code
    alt Webhooks 
       Woovi->>Sua Empresa: event: PIX_AUTOMATIC_APPROVED
    end
```

## Criação da Cobrança Recorrente
A criação da Cobrança ocorre 4 dias antes da data de pagamento da cobrança. Isso é importante para garantir que está tudo certo com a cobrança, e que tanto a Woovi, quanto o banco de destino estejam aptos a realizar a cobrança.

```mermaid
sequenceDiagram
    Woovi->>Banco do Consumidor: Pedir Aprovação da Cobrança
    alt Webhooks 
       Woovi->>Sua Empresa: event: PIX_AUTOMATIC_COBR_CREATED
    end
    Banco do Consumidor->>Woovi: Cobrança Confirmada
     alt Webhooks 
       Woovi->>Sua Empresa: event: PIX_AUTOMATIC_COBR_APPROVED
    end
```

## Recebimento de um pagamento

Esse fluxo ocorre no dia do pagamento definido, após ter a cobrança confirmada.

```mermaid
sequenceDiagram
    Banco do Consumidor->>Woovi: Envia o pagamento
    alt Webhooks 
       Woovi->>Sua Empresa: event: PIX_AUTOMATIC_COBR_COMPLETED
    end
```

## Cobrança recorrente rejeitada

Esse fluxo ocorre quando uma cobrança é rejeitada pelo banco do consumidor sem retentativas.

O evento `PIX_AUTOMATIC_COBR_TRY_REJECTED` é recebido imediatamente após o banco informar da falha da cobrança

O evento `PIX_AUTOMATIC_COBR_REJECTED` é recebido após a expiração da cobrança e a última tentativa de cobrança falhou

```mermaid
sequenceDiagram
    Woovi->>Banco do Consumidor: Pedir Aprovação da Cobrança
    alt Webhooks 
       Woovi->>Sua Empresa: event: PIX_AUTOMATIC_COBR_CREATED
    end
    Banco do Consumidor->>Woovi: Tentativa de Cobrança rejeitada
   alt Webhooks 
       Woovi->>Sua Empresa: event: PIX_AUTOMATIC_COBR_TRY_REJECTED
       Woovi->>Sua Empresa: event: PIX_AUTOMATIC_COBR_REJECTED
    end
```

### Novas Retentativas
Caso tenha habilitado retentativas no cadastro da assinatura, após a primeira tentativa de cobrança rejeitada, serão feitas até 3 novas tentativas de cobranças.

A primeira será feita um dia após a data da cobrança.
A segunda na data intermediária entre a data da cobrança e a data de expiração.
A terceira na data de expiração da cobrança.

Cada tentativa de cobrança seguirá o fluxo abaixo em caso seja rejeitada.

```mermaid
sequenceDiagram
    Woovi->>Banco do Consumidor: Nova tentativa de Cobrança
    alt Webhooks 
       Woovi->>Sua Empresa: event: PIX_AUTOMATIC_COBR_TRY_REQUESTED
    end
    Banco do Consumidor->>Woovi: Tentativa de Cobrança rejeitada
    alt Webhooks 
       Woovi->>Sua Empresa: event: PIX_AUTOMATIC_COBR_TRY_REJECTED
    end
```

Se nenhuma tentativa for aceita até a data de expiração, será enviado o webhook `PIX_AUTOMATIC_COBR_REJECTED`

```mermaid
sequenceDiagram
    alt Webhooks 
       Woovi->>Sua Empresa: event: PIX_AUTOMATIC_COBR_REJECTED
    end
    
```

Caso a tentativa seja aceita, o seguinte fluxo ocorrerá

```mermaid
sequenceDiagram
    Woovi->>Banco do Consumidor: Nova tentativa de Cobrança
      alt Webhooks 
       Woovi->>Sua Empresa: event: PIX_AUTOMATIC_COBR_TRY_REQUESTED
    end
    Banco do Consumidor->>Woovi: Tentativa de Cobrança aceita
    alt Webhooks 
       Woovi->>Sua Empresa: event: PIX_AUTOMATIC_COBR_APPROVED
    end
```

---

## Listagem dos Webhooks

## Pix Automátio WEB HOOKS

O Objeto que retorna nos webhooks do PIX_AUTOMATIC é uma Assinatura, dentro dele tem acesso ao pix automático dentro do objeto (`pixRecurring`).

O campo `globalID` representa o id único da assinatura, ele deverá ser usado nos endpoints relacionados com assinatura.

### PIX_AUTOMATIC_APPROVED

Quando o pix automático é aprovado. Ele ocorre quando o consumidor lê o QRCode e aprova a recorrência em seu banco. Após disso o status é alterado para APPROVED.

Caso você esteja usando a jornada 3 (`PAYMENT_ON_APPROVAL`), vale lembrar que quando receber o webhook, a primeira parcela já foi paga, você também receberá o webhook de `COBR_COMPLETED`.

```json
{
  "event": "PIX_AUTOMATIC_APPROVED",
  "customer": {
    "name": "Dan",
    "email": "email0@example.com",
    "phone": "+5511999999999",
    "address": {
      "zipcode": "04556300",
      "street": "rua de são paulo",
      "number": "3432",
      "neighborhood": "BROOKLIN PAULISTA",
      "city": "VITORIA",
      "state": "SP",
      "complement": "CONJ 26",
      "country": "BR",
      "location": {
        "coordinates": []
      },
      "_id": "68a88321d65cb2d507a2ee1d"
    },
    "taxID": {
      "taxID": "111111111",
      "type": "BR:CPF"
    },
    "correlationID": "6f4131ea-b816-4b08-8ba6-11cf6b622a6e"
  },
  "dayGenerateCharge": 24,
  "value": 100,
  "status": "ACTIVE",
  "correlationID": "UniqueID1344445457t11653453223241",
  "pixRecurring": {
    "recurrencyId": "RN5481141720250822YHKirVyWBjF",
    "emv": "qrcode",
    "journey": "ONLY_RECURRENCY",
    "status": "APPROVED"
  },
  "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGE4ODMyMWQ2NWNiMmQ1MDdhMmVlMjk="
}
```
### PIX_AUTOMATIC_REJECTED

Quando o consumidor recusa a recorrência em seu aplicativo do banco. o Status é alterado para REJECTED.

```json
{
  "event": "PIX_AUTOMATIC_REJECTED",
  "customer": {
    "name": "Dan",
    "email": "email0@example.com",
    "phone": "+5511999999999",
    "address": {
      "zipcode": "04556300",
      "street": "rua de são paulo",
      "number": "3432",
      "neighborhood": "BROOKLIN PAULISTA",
      "city": "VITORIA",
      "state": "SP",
      "complement": "CONJ 26",
      "country": "BR",
      "location": {
        "coordinates": []
      },
      "_id": "68a88321d65cb2d507a2ee1d"
    },
    "taxID": {
      "taxID": "111111111",
      "type": "BR:CPF"
    },
    "correlationID": "6f4131ea-b816-4b08-8ba6-11cf6b622a6e"
  },
  "dayGenerateCharge": 24,
  "value": 100,
  "status": "INACTIVE",
  "correlationID": "UniqueID1344445457t11653453223241",
  "pixRecurring": {
    "recurrencyId": "RN5481141720250822YHKirVyWBjF",
    "emv": "qrcode",
    "journey": "ONLY_RECURRENCY",
    "status": "REJECTED"
  },
  "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGE4ODMyMWQ2NWNiMmQ1MDdhMmVlMjk="
}
```

## COBR WEB HOOKS

O Objeto que retorna nos webhooks do `COBR` é a parcela na qual a cobrança será feita, dentro dele tem acesso ao cobr.

A primeira cobrança da jornada 3 (`PAYMENT_ON_APPROVAL`), que é realizada no momento da leitura do QR Code, dispará tanto o evento de `PIX_AUTOMATIC_APPROVED` quanto o `PIX_AUTOMATIC_COBR_COMPLETED`.

O campo `globalID` representa o id único da parcela.
o campo `paymentSubscriptionGlobalID` representa o id único da assinatura
o campo `correlationID` representa o seu identificador único que foi enviado ao criar a assinatura

Dentro do objeto cobr você tem acesso ao `identifierId` que é o identificador único da cobrança recorrente.

### PIX_AUTOMATIC_COBR_CREATED

Quando o COBR é criado. Por padrão ele é criado 4 dias antes da data de cobrança. Após ser criado, é feita uma requisição para o banco do consumidor para ele ser aprovado ou rejeitado. Após o COBR ser criado, você poderá receber o webhook `PIX_AUTOMATIC_COBR_TRY_REJECTED` caso tenha falha na tentativa de cobrança ou `PIX_AUTOMATIC_COBR_APPROVED` caso a cobrança seja aprovada.

```json
{
  "event": "PIX_AUTOMATIC_COBR_CREATED",
  "dateGenerateCharge": "2025-08-24T12:00:00.000Z",
  "expiration": 259200,
  "installmentNumber": 1,
  "value": 100,
  "status": "SCHEDULED",
  "createdAt": "2025-08-22T14:48:02.697Z",
  "cobr": {
    "identifierId": "01K3942Y0DFEK73H541ZADVK0P",
    "recurrencyId": "RN5481141720250822YHKirVyWBjF",
    "status": "CREATED",
    "tries": [
      {
        "tryStatus": "REQUESTED",
        "value": 1,
        "finalityPurpose": "AGND",
        "requestedExecutionDate": "2025-09-05T12:00:00.000Z",
        "createdAt": "2025-09-04T03:01:58.543Z",
        "updatedAt": "2025-09-04T03:04:03.921Z",
      }
    ],
    "value": 100,
    "createdAt": "2025-08-22T14:49:22.702Z"
  },
  "correlationID": "9134e286-6f71-427a-bf00-100000000005",
  "paymentSubscriptionGlobalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGFjYmNkNGE5NTY1M2VmMjQzYjY2Zjc=",
  "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbkluc3RhbGxtZW50OjY4YTg4MzIyZDY1Y2IyZDUwN2EyZWUzYg=="
}
```

### PIX_AUTOMATIC_COBR_APPROVED

Quando o COBR é aprovado pelo banco do cliente, nesse caso a cobrança irá ser feita na data especificada em `dateGenerateCharge`.

```json
{
  "event": "PIX_AUTOMATIC_COBR_APPROVED",
  "dateGenerateCharge": "2025-08-24T12:00:00.000Z",
  "expiration": 259200,
  "installmentNumber": 1,
  "value": 100,
  "status": "ACTIVE",
  "createdAt": "2025-08-22T14:48:02.697Z",
  "cobr": {
    "identifierId": "01K3942Y0DFEK73H541ZADVK0P",
    "recurrencyId": "RN5481141720250822YHKirVyWBjF",
    "status": "ACTIVE",
    "tries": [
      {
        "tryStatus": "SCHEDULED",
        "value": 1,
        "finalityPurpose": "AGND",
        "requestedExecutionDate": "2025-09-05T12:00:00.000Z",
        "createdAt": "2025-09-04T03:01:58.543Z",
        "updatedAt": "2025-09-04T03:04:03.921Z",
      }
    ],
    "value": 100,
    "createdAt": "2025-08-22T14:49:22.702Z"
  },
  "correlationID": "9134e286-6f71-427a-bf00-100000000005",
  "paymentSubscriptionGlobalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGFjYmNkNGE5NTY1M2VmMjQzYjY2Zjc=",
  "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbkluc3RhbGxtZW50OjY4YTg4MzIyZDY1Y2IyZDUwN2EyZWUzYg=="
}
```

### PIX_AUTOMATIC_COBR_COMPLETED

Quando o COBR é pago pelo consumidor.

```json
{
  "event": "PIX_AUTOMATIC_COBR_COMPLETED",
  "dateGenerateCharge": "2025-08-24T12:00:00.000Z",
  "expiration": 259200,
  "installmentNumber": 1,
  "value": 100,
  "status": "COMPLETED",
  "createdAt": "2025-08-22T14:48:02.697Z",
  "cobr": {
    "identifierId": "01K3942Y0DFEK73H541ZADVK0P",
    "recurrencyId": "RN5481141720250822YHKirVyWBjF",
    "status": "COMPLETED",
    "endToEndId": "my-end-to-end-id",
    "tries": [
      {
        "tryStatus": "PAID",
        "value": 1,
        "finalityPurpose": "AGND",
        "requestedExecutionDate": "2025-09-05T12:00:00.000Z",
        "createdAt": "2025-09-04T03:01:58.543Z",
        "updatedAt": "2025-09-04T03:04:03.921Z",
      }
    ],
    "value": 100,
    "createdAt": "2025-08-22T14:49:22.702Z"
  },
  "correlationID": "9134e286-6f71-427a-bf00-100000000005",
  "paymentSubscriptionGlobalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGFjYmNkNGE5NTY1M2VmMjQzYjY2Zjc=",
  "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbkluc3RhbGxtZW50OjY4YTg4MzIyZDY1Y2IyZDUwN2EyZWUzYg=="
}
```

### PIX_AUTOMATIC_COBR_REJECTED

Quando o COBR é rejeitado pelo banco de cliente. O tipo do erro aparece no campo `rejectCode` do payload.
Esse webhook é disparado apenas uma vez, após todas as tentativas de cobranças serem realizadas. 

```json
{
  "event": "PIX_AUTOMATIC_COBR_REJECTED",
  "dateGenerateCharge": "2025-08-24T12:00:00.000Z",
  "expiration": 259200,
  "installmentNumber": 1,
  "value": 100,
  "status": "CANCEL",
  "createdAt": "2025-08-22T14:48:02.697Z",
  "cobr": {
    "identifierId": "01K3942Y0DFEK73H541ZADVK0P",
    "recurrencyId": "RN5481141720250822YHKirVyWBjF",
    "status": "REJECTED",
    "tries": [
      {
        "tryStatus": "REJECTED",
        "value": 1,
        "finalityPurpose": "AGND",
        "requestedExecutionDate": "2025-09-05T12:00:00.000Z",
        "createdAt": "2025-09-04T03:01:58.543Z",
        "updatedAt": "2025-09-04T03:04:03.921Z",
        "rejectCode": "DTED"
      }
    ],
    "rejectCode": "DTED"
    "value": 100,
    "createdAt": "2025-08-22T14:49:22.702Z",
  },
  "correlationID": "9134e286-6f71-427a-bf00-100000000005",
  "paymentSubscriptionGlobalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGFjYmNkNGE5NTY1M2VmMjQzYjY2Zjc=",
  "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbkluc3RhbGxtZW50OjY4YTg4MzIyZDY1Y2IyZDUwN2EyZWUzYg=="
}
```

## COBR TRY WEB HOOKS

Representam uma tentativa de cobrança

### PIX_AUTOMATIC_COBR_TRY_REQUESTED

Quando uma nova tentativa de cobrança é realizada, apenas o ocorre se o `retryPolicy` for igual a `THREE_RETRIES_7_DAYS`.
Quando um cobr é criado também é criado uma nova tentativa de cobrança, porém não enviamos esse webhook nesse caso, visto que o evento do PIX_AUTOMATIC_COBR_CREATED já é emitido.

```json
{
  "event": "PIX_AUTOMATIC_COBR_TRY_REJECTED",
  "dateGenerateCharge": "2025-09-05T12:00:00.000Z",
  "expiration": 1209600,
  "installmentNumber": 2,
  "value": 1,
  "status": "SCHEDULED",
  "createdAt": "2025-09-04T03:00:20.372Z",
  "cobr": {
    "identifierId": "01K49ARZMETSD7XJ2H86HV188H",
    "recurrencyId": "RN5481141720250811Vs0a16RIRVm",
    "status": "CREATED",
    "tries": [
      {
        "tryStatus": "REQUESTED",
        "value": 1,
        "finalityPurpose": "AGND",
        "requestedExecutionDate": "2025-09-05T12:00:00.000Z",
        "createdAt": "2025-09-04T03:01:58.543Z",
        "updatedAt": "2025-09-04T03:04:03.921Z",
        "rejectCode": "FBRD"
      }
    ],
    "value": 1,
    "description": "comment",
    "createdAt": "2025-09-04T03:01:58.543Z"
  },
  "correlationID": "9134e286-6f71-427a-bf00-100000000005",
  "paymentSubscriptionGlobalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2ODlhNTA1NmVjY2NkZTViMzdmYzE0MDE=",
  "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbkluc3RhbGxtZW50OjY4YjkwMGM0ZDE5ZTBlY2QwMmQ2NzViMg=="
}
```

### PIX_AUTOMATIC_COBR_TRY_REJECTED

Quando uma cobrança do pix automática é rejeitada pelo banco do pagador.

```json
{
  "event": "PIX_AUTOMATIC_COBR_TRY_REJECTED",
  "dateGenerateCharge": "2025-09-05T12:00:00.000Z",
  "expiration": 1209600,
  "installmentNumber": 2,
  "value": 1,
  "status": "CANCELED",
  "createdAt": "2025-09-04T03:00:20.372Z",
  "cobr": {
    "identifierId": "01K49ARZMETSD7XJ2H86HV188H",
    "recurrencyId": "RN5481141720250811Vs0a16RIRVm",
    "status": "FAILED_TRY",
    "tries": [
      {
        "tryStatus": "REJECTED",
        "value": 1,
        "finalityPurpose": "AGND",
        "requestedExecutionDate": "2025-09-05T12:00:00.000Z",
        "createdAt": "2025-09-04T03:01:58.543Z",
        "updatedAt": "2025-09-04T03:04:03.921Z",
        "rejectCode": "FBRD"
      }
    ],
    "value": 1,
    "description": "comment",
    "createdAt": "2025-09-04T03:01:58.543Z"
  },
  "correlationID": "9134e286-6f71-427a-bf00-100000000005",
  "paymentSubscriptionGlobalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2ODlhNTA1NmVjY2NkZTViMzdmYzE0MDE=",
  "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbkluc3RhbGxtZW50OjY4YjkwMGM0ZDE5ZTBlY2QwMmQ2NzViMg=="
}
```

---

## Rotas API

## Pix Automátio Rotas da API

Você pode ver em mais detalhes pelo [link](/api#tag/subscription

### Criar uma Assinatura

A principal rota é a `/api/v1/subscriptions`, na qual é possível realizar a criação de uma nova assinatura. [link](./pix-automatic-how-to-create.md)

### Listar uma assinatura

GET `/api/v1/subscriptions/{id}`

No objeto `pixRecurring` você tem acesso ao status do Pix Automático
 
```json
{
    "subscription": {
        "customer": {
            "name": "Dan",
            "email": "email0@example.com",
            "phone": "+5511999999999",
            "address": {
                "zipcode": "04556300",
                "street": "rua de são paulo",
                "number": "3432",
                "neighborhood": "BROOKLIN PAULISTA",
                "city": "SAO PAULO",
                "state": "SP",
                "complement": "CONJ 26",
                "country": "BR",
                "location": {
                    "coordinates": []
                },
                "_id": "68acbcd4a95653ef243b66eb"
            },
            "taxID": {
                "taxID": "111111111111",
                "type": "BR:CPF"
            },
            "correlationID": "6f4131ea-b816-4b08-8ba6-11cf6b622a6e"
        },
        "dayGenerateCharge": 25,
        "value": 100,
        "status": "ACTIVE",
        "correlationID": "My-UniqueID",
        "pixRecurring": {
            "recurrencyId": "RN5481141720250825yPWxVcFfpA1",
            "emv": "QRCODE",
            "journey": "PAYMENT_ON_APPROVAL",
            "status": "CREATED"
        },
        "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGFjYmNkNGE5NTY1M2VmMjQzYjY2Zjc="
    }
}
```

### Listar todas as assinaturas

GET `/api/v1/subscriptions/`

```json
{
  "subscriptions": [],
  "pageInfo": {
        "skip": 0,
        "limit": 100,
        "totalCount": 0,
        "hasPreviousPage": false,
        "hasNextPage": true
    }
}
```

### Buscar os dados de uma parcela

no objeto COBR vc tem acesso ao status da cobrança.

GET `/api/v1/installments/{id}`

```json
{
  "dateGenerateCharge": "2025-08-24T12:00:00.000Z",
  "expiration": 259200,
  "installmentNumber": 1,
  "value": 100,
  "status": "ACTIVE",
  "createdAt": "2025-08-22T14:48:02.697Z",
  "cobr": {
    "identifierId": "01K3942Y0DFEK73H541ZADVK0P",
    "recurrencyId": "RN5481141720250822YHKirVyWBjF",
    "installmentId": "68a88322d65cb2d507a2ee3b",
    "status": "ACTIVE",
    "value": 100,
    "createdAt": "2025-08-22T14:49:22.702Z"
  },
  "paymentSubscriptionGlobalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGFjYmM5MWE5NTY1M2VmMjQzYjY2OTk=",
  "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbkluc3RhbGxtZW50OjY4YTg4MzIyZDY1Y2IyZDUwN2EyZWUzYg=="
}
```

### Listar todas as parcelas de uma assinatura

GET `/api/v1/subscriptions/{id}/installments`

```json
{
  "installments": [],
  "pageInfo": {
        "skip": 0,
        "limit": 100,
        "totalCount": 0,
        "hasPreviousPage": false,
        "hasNextPage": true
    }
}
```

### Cancelar uma Assintarua

PUT `/api/v1/subscriptions/{id}/cancel`

---

## Criação manual de cobranças recorrente

## Criação manual de cobranças recorrentes

Segundo a documentação do banco central, as cobranças recorrentes podem ser feitas de 2 a 10 dias antes da data da cobrança. Nós da woovi definimos que a partir do 4 dia vamos criar as cobranças para as parcelas que ainda não possuem. 

Dessa forma, caso você queria criar as cobranças manualmente, seja para ter um controle maior sobre as cobranças recorrentes, seja para criação com valores dinâmicos, terá entre 5 a 10 dias antes da data cobrança para realizar a criação.

A primeira etapa é buscar qual a parcela que você desejará criar a cobrança manual. Para isso recomendamos buscar a última parcela da assinaturas com a requisição, enviando o identificador da assinatura.

GET `/api/v1/subscriptions/{id}/installments`

Para realizar a criação, basta identificar o globalID da Parcela, normalmente será a última com o status `SCHEDULED`.

> As parcelas são criadas de forma incremental, sempre que a última for paga ou cancelada. Será feita a criação da próxima com antecedência para você conseguir alterar o valor da cobrança

POST `/api/v1/installments/{id}/cobr`

no body da requisição é opcional enviar o novo valor em centavos.

```json
{
  "value": 100
}
```

Você pode ver em mais detalhes pelo [link](/api#tag/cobr

Caso a cobrança manual falhe, você poderá realizar novas retentativas de cobrança. 

POST `/api/v1/installments/{id}/cobr/retry`

no body da requisição é opcional enviar o novo valor em centavos.

```json
{
  "value": 100
}
```

---

## Como criar um Pix Automático com valor variável

## Como criar Pix Automático com valor variável

Ao criar um pix automático com valor dinâmico você deverá enviar os dois valores

- `value` que é o valor padrão da assinatura, ele que será cobrado na primeira parcela caso seja do tipo `PAYMENT_ON_APPROVAL`,
- `minimumValue` que é o valor mínimo que poderá ser cobrado pela assinatura

Vale lembrar que a assinatura de valor variável não tem um limite para o quanto você poderá cobrar, quem define esse limite é o usuário no aplicativo do banco de destino ao aprovar o QR Code. A única restrição é que o valor máximo definido por ele seja maior que o mínimo que você defininiu.

Dessa forma, ao realizar uma cobrança com valor superior ao mínimo ela poderá ser rejeitada a depender das restrições que o usuário definiu.

## Atualizar o valor da assinatura

Para atualizar o valor da assinatura você pode utilizar o endpoint PUT `/api/v1/subscriptions/{id}/value`

```json
{
  "value": 100
}
```

---

## Erros

## Erros relacionados a Cobrança

Ao gerar uma cobrança podem ocorrer diversos erros. Segue abaixo a listagem de todos os possíveis erros que podem ocorrer.

| Código | Motivo | Descrição |
|--------|--------|-----------|
| RJCT | Instrução de pagamento rejeitada pelo participante do usuário pagador. | Instrução de pagamento rejeitada pelo participante do usuário pagador. |
| AB10 | Transação interrompida devido a erro no participante do usuário pagador. | Transação interrompida devido a erro no participante do usuário pagador. |
| AC05 | Conta transacional do usuário pagador encerrada. | Conta transacional do usuário pagador encerrada. |
| AC06 | Conta transacional do usuário pagador encontra-se bloqueada. | Conta transacional do usuário pagador encontra-se bloqueada. |
| AG12 | Não é permitida solicitação de agendamento entre contas da mesma instituição. | Não é permitida solicitação de agendamento (pain.013) cujos recursos sejam transferidos de uma conta transacional para outra em uma mesma instituição participante ou entre participantes que utilizem o serviço de liquidação de um mesmo participante liquidante no SPI. |
| AM02 | Valor da cobrança ultrapassa o valor máximo estabelecido pelo usuário pagador. | Valor da cobrança ultrapassa o valor máximo estabelecido pelo usuário pagador. |
| AM09 | Valor da cobrança não corresponde ao valor estabelecido na recorrência. | Valor da cobrança não corresponde ao valor estabelecido na recorrência. |
| CRNC | CNPJ do usuário recebedor não corresponde ao dado da recorrência. | CNPJ do usuário recebedor informado na pain.013 não corresponde com o dado de identificação contida na recorrência. |
| DENC | CPF/CNPJ do usuário pagador não corresponde ao dado contido na recorrência/autorização. | CPF/CNPJ do usuário pagador não corresponde ao dado contido na recorrência/autorização. |
| DS27 | Participante não se encontra cadastrado ou ainda não iniciou a operação no SPI. | Participante não se encontra cadastrado ou ainda não iniciou a operação no SPI. |
| DTED | Divergência entre a data de vencimento informada e a periodicidade da recorrência e/ou as regras do produto. | Divergência entre a data de vencimento informada e a periodicidade da recorrência e/ou as regras do produto. |
| EXPR | Cobrança falhou devido a falta de saldo. | Cobrança falhou devido a falta de saldo na conta do usuário pagador. |
| DTNT | Novas tentativas de agendamento em desacordo com o limite de dias definido na regra de negócio. | Novas tentativas de agendamento pós vencimento em desacordo com o limite de dias definido na regra de negócio (a partir de D+8, considerando D0, a data do vencimento). |
| FCD1 | Pain.013 recebida com mais de 10 dias de antecedência da data prevista para a liquidação. | Pain.013 recebida com mais de 10 dias de antecedência da data prevista para a liquidação, em descumprimento às regras do negócio. |
| FCD2 | Pain.013 recebida com menos de 2 dias de antecedência da data prevista para a liquidação. | Pain.013 recebida com menos de 2 dias de antecedência da data prevista para a liquidação, em descumprimento às regras do negócio. |
| GRER | Motivo do erro genérico/diverso. | Motivo do erro genérico/diverso, utilizado apenas quando não houver outro domínio aplicável. |
| IRNT | Cobrança recorrente não permite novas tentativas de agendamento. | Cobrança recorrente não permite novas tentativas de agendamento pós vencimento (idRecorrencia com característica que não permite novas tentativas). |
| MIDI | idRecorrencia inexistente ou incorreto. | idRecorrencia inexistente ou incorreto. |
| MSUC | statusRecorrencia diferente de "CFDB" (confirmado pelo usuário pagador). | statusRecorrencia diferente de "CFDB" (confirmado pelo usuário pagador). |
| NIEC | Nova instrução de pagamento inválida, ordem de pagamento ainda pendente de envio ao SPI. | Nova instrução de pagamento inválida pois a mesma cobrança já possui ordem de pagamento agendada ainda pendente de envio ao SPI para liquidação. |
| NIPA | Nova instrução de pagamento inválida, pagamento já foi efetivado. | Nova instrução de pagamento inválida, pagamento já foi efetivado. |
| NITX | Nova instrução de pagamento não corresponde a uma cobrança recorrente gerada anteriormente. | Nova instrução de pagamento não corresponde a uma cobrança recorrente gerada anteriormente (IdConciliacaoDoRecebedor diferentes). Utilizada somente para as finalidades de agendamento 'NTAG' e 'RIFL'. |
| QUNT | Quantidade de novas tentativas de agendamento excede o limite definido pela regra de negócio. | Quantidade de novas tentativas de agendamento pós vencimento excede o limite definido pela regra de negócio (mais de 3 tentativas em intervalo de 7 dias após o vencimento, considerando D0, a data do vencimento). |
| RC09 | ISPB do participante do usuário pagador inválido ou inexistente. | ISPB do participante do usuário pagador inválido ou inexistente. |
| UDEI | CPF/CNPJ do devedor incorreto. | CPF/CNPJ do devedor incorreto. |

## Erros relacionados a Cancelamento de Agendamento

| Código | Motivo | Descrição |
|--------|--------|-----------|
| ACCT | Encerramento de conta transacional | Cancelamento do agendamento decorrente de encerramento da conta transacional do usuário pagador ou do usuário recebedor |
| BLCK | Bloqueio de conta transacional | Cancelamento do agendamento decorrente de bloqueio da conta transacional do usuário pagador ou do usuário recebedor |
| CCLD | Cancelamento da autorização para pagamentos periódicos | Cancelamento do agendamento decorrente do cancelamento da autorização para pagamentos periódicos |
| FAIL | Falha ou erro na liquidação | Cancelamento do agendamento por falha ou erro no fluxo de liquidação |
| OTHR | Cancelamento por outros motivos | Cancelamento de agendamento solicitado pelo participante do usuário pagador ou pelo participante do usuário recebedor, decorrente de outros motivos |
| SLBD | Solicitado pelo usuário pagador. | Cancelamento de agendamento solicitado pelo usuário pagador |
| SLCR | Solicitado pelo usuário recebedor. | Cancelamento de agendamento solicitado pelo usuário recebedor |

---

## Qual jornada do Pix Automático devo escolher?

Em caso de dúvida sobre qual é a melhor jornada para seu negócio. Nós recomendamos escolher a jornada 3 `(PAYMENT_ON_APPROVAL)`. Por que ela é mais simples de ser implementada e de ser compreendida. Uma vez que ao ler o QRCode o usuário já efeuta o pagamento e autoriza a cobrança, além de a assinatura entrar em vigor imediatamente.

Contudo, caso você já possua uma assinatura em andamento e deseja migrar para o Pix Automático, recomendamos a jornada 4, pois a cobrança continuará sendo feita da maneira tradional, via e-mail. Contudo, será feito um convite para o consumidor migrar para o Pix Automático, gerando uma maior comodidade. Visto que a cobrança é automática.

Em um caso que a assinatura apenas entrará em vigor em um momento tardio, como na próxima semana/mês. Nós sugerimos a jornada 2 `(ONLY_RECURRENCY)`. Porque a cobrança somente será efetuada quando de fato começar a assinatura.

Caso o consumidor demonstre uma necessidade de efetuar as cobranças de maneira automática. A jornada 1 será o ideal nesse caso. Pois será enviado uma notificação para o consumidor no seu aplicativo de banco o convidando para autorizar a recorrência.

---

## Como criar um Pix Automático?

Para criar um pix Automático você utilizará o mesmo endpoint de assinatura que já existe, porém necessitará de enviar alguns campos adicionais.

Você deverá fazer uma chamada POST para o _endpoint_ `/api/v1/subscriptions`.

Como parte do `body` da requisição, esperamos o envio dos seguintes itens:

- **`value`**: O valor em centavos da assinatura a ser criada.
- **`customer`**: O cliente da assinatura a ser cobrado. É obrigatório o envio do endereço do cliente. Este campo é [idempotente](../concepts/idempotence.md), o que significa que se você enviar dados de um cliente que já exista, utilizaremos o existente ao invés de criar um novo.
- **`type`**: Deve ser definido como `PIX_RECURRING`
- **`dayGenerateCharge`**: Dia do mês em que as cobranças serão geradas. Aceita um número de 1 a 31 (dia do mês) ou uma data ISO 8601 completa (ex.: `"2026-02-22T00:00:00.000Z"`) para definir a data de início da recorrência.
**Caso seja escolhido a jornada 3 (``PAYMENT_ON_APPROVAL``) a data deve ser o dia atual**. 
Caso o dia informado seja inferior ao dia atual, a primeira cobrança ocorrerá apenas no próximo mês.
- **`dayDue`**: Quantos dias para expirar cobrança. 
- **`comment`**: Texto usado como o contrato de adesão da recorrência (campo `contrato` do mandato). Deve ter menos de 30 caracteres. No Pix Automático o nome exibido para o pagador no aplicativo do banco é a razão social / nome fantasia do CNPJ da sua conta, não o `comment`.
- **`frequency`**: A frequência da recorrência. Valores aceitos no Pix Automático: `WEEKLY` (semanal), `MONTHLY` (mensal), `QUARTERLY` (trimestral, a cada 3 meses), `SEMIANNUALLY` (semestral) e `ANNUALLY` (anual). `BIMONTHLY` (bimestral) não é suportado pelo Pix Automático.

Dentro do objeto `pixRecurringOptions` você precisa definir alguns parâmetros exclusivos do pix automático:

- **`journey`**: Deve ser baseado em qual jornada escolheu utilizar (`ONLY_RECURRENCY`: Jornada 2,  `PAYMENT_ON_APPROVAL`: Jornada 3),
- **`retryPolicy`**: Qual Política de rententativa deve ser adotada ( `NON_PERMITED`: Sem política de retentativas, `THREE_RETRIES_7_DAYS`: 3 Retentativas em até 7 dias )
- **`minimumValue`** (Opcional): Caso sua cobrança tenha valor variável, você pode definir o valor mínimo a que deve ser aceito.

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "name": "Pix Automático",
  "value": 100,
  "customer": {
    "name": "Dan",
    "taxID": "31324227036",
    "email": "email0@example.com",
    "phone": "5511999999999",
    "address": {
        "zipcode": "04556300",
        "street": "rua de são paulo",
        "number": "3432",
        "neighborhood": "BROOKLIN PAULISTA",
        "city": "SAO PAULO",
        "state": "SP",
        "complement": "CONJ 26"
    }
  },
  "correlationID": "UniqueID",
  "comment": "Comentários",
  "frequency": "MONTHLY",
  "type": "PIX_RECURRING",
  "pixRecurringOptions": {
    "journey": "PAYMENT_ON_APPROVAL",
    "retryPolicy": "NON_PERMITED"
  },
  "dayGenerateCharge": 10,
  "dayDue": 3
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, retornaremos a assinatura criada.

Retornarmeros a seguinte resposta de exemplo:

```json
{
    "subscription": {
        "customer": {
            "name": "Teste",
            "email": "teste@pix.com",
            "address": {
                "zipcode": "04556300",
                "street": "rua de são paulo",
                "number": "3432",
                "neighborhood": "BROOKLIN PAULISTA",
                "city": "SAO PAULO",
                "state": "SP",
                "complement": "CONJ 26",
                "country": "BR",
                "_id": "689cafe1d7943ac642518543"
            },
            "taxID": {
                "taxID": "xxxxxxxx",
                "type": "BR:CPF"
            },
            "correlationID": "5a85c7a3-5c54-491d-a2f9-9c1ac486fd7a"
        },
        "dayGenerateCharge": 13,
        "value": 20,
        "status": "ACTIVE",
        "correlationID": "",
        "paymentLinkUrl": "https://woovi.dev/pay/8a421a7a-a9af-4b2d-add8-54fc1ac4320f",
        "pixRecurring": {
           "recurrencyId": "RN54811417202508244SORthDqe6c",
            "emv": "00020101021226870014br.gov.bcb.pix2565qr-h.woovi.digital/qr/v2/cob/464bf2d4-3b4b-4633-a9fc-c4b492f76e035204000053039865802BR5911Pedro Woovi6007VITORIA62070503***80870014br.gov.bcb.pix2565qr-h.woovi.digital/qr/v2/rec/a8493991-b364-4821-acea-f548ee239f416304E887",
            "journey": "PAYMENT_ON_APPROVAL",
            "status": "CREATED"
        },
        "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2ODljYWZlMWQ3OTQzYWM2NDI1MTg1NGY="
    }
}
```

## Início no mês seguinte

Para criar o mandato agora e cobrar o cliente apenas no próximo mês (ou em uma data futura), use a jornada 2 (`ONLY_RECURRENCY`). Nessa jornada nenhuma cobrança é disparada na criação — apenas o mandato de recorrência é registrado, e a primeira cobrança é gerada somente na data de início.

A data de início é definida pelo `dayGenerateCharge`, de duas formas:

- **Data ISO 8601** (recomendado): envie a data completa (ex.: `"2026-02-22T00:00:00.000Z"`). Ela passa a ser o início da recorrência e o dia dela vira o dia fixo das cobranças seguintes.
- **Número**: se o dia informado for menor que o dia de hoje, a primeira cobrança ocorre no próximo mês; se maior, ainda no mês atual.

Na jornada `ONLY_RECURRENCY`, a data de início precisa estar a pelo menos 3 dias de hoje, caso contrário a criação é rejeitada.

O `body` para uma assinatura mensal que começa apenas em 22/02/2026 seria semelhante a este:

```json
{
  "name": "Pix Automático",
  "value": 100,
  "customer": {
    "name": "Dan",
    "taxID": "31324227036",
    "email": "email0@example.com",
    "phone": "5511999999999",
    "address": {
        "zipcode": "04556300",
        "street": "rua de são paulo",
        "number": "3432",
        "neighborhood": "BROOKLIN PAULISTA",
        "city": "SAO PAULO",
        "state": "SP",
        "complement": "CONJ 26"
    }
  },
  "correlationID": "UniqueID",
  "comment": "Assinatura mensal",
  "frequency": "MONTHLY",
  "type": "PIX_RECURRING",
  "pixRecurringOptions": {
    "journey": "ONLY_RECURRENCY",
    "retryPolicy": "THREE_RETRIES_7_DAYS"
  },
  "dayGenerateCharge": "2026-02-22T00:00:00.000Z",
  "dayDue": 3
}
```

---

## Máquina de Estados do Pix Automático

### Assinatura (Subscription)

A assinatura é a entidade mais abrangente, no caso do pix automático, o seu tipo é `PIX_RECURRING`. A assinatura poderá ter os seguintes status:

- `ACTIVE`: Assinatura ativa e criando novas parcelas nas datas pré definidas.
- `COMPLETED`: Assinatura concluída e não criará novas parcelas. (Especificadamente quando a assinatura tem uma data final).
- `EXPIRED`: Possui uma parcela que foi expirada
- `INACTIVE`: Assinartura cancelada

```mermaid
flowchart LR
    A[ACTIVE] -->B(COMPLETED)
    A[ACTIVE] -->C(INACTIVE)
```

### Pix Automático (PixRecurring)

Quando a assinatura é do tipo `PIX_RECURRING`, ela terá um novo status dentro do objeto `pixRecurring`. Isso é necessário porque o status do Pix Automático é alterado de mandeira independente da assinatura.

O status sempre se inicia com `CREATED`, após o consumidor aprovar o QR Code no aplcativo do banco ele muda de status para `APPROVED`, nesse cenário, ele já comecará a criar as cobranças.

Caso o consumidor deseja cancelar a assinatura, ele pode cancelar a qualquer momento no aplicativo do banco. Nesse caso ele mudará de status para `REJECTED`.

Caso você deseja cancelar a assinatura, o status irá ser alterado para `CANCELED`.

- `CREATED`: Status padrão de quando é criado 
- `APPROVED`: Aprovado pelo consumidor e poderá ser criado as cobranças
- `CANCELED`: Cancelado pelo usuário
- `REJECTED`: Autorização removida pelo consumidor

```mermaid
flowchart LR
    A[CREATED] -->B(APPROVED)
    B[APPROVED] -->C(REJECTED)
    B[APPROVED] -->D(CANCELED)
```

### Parcela (Installment)

- `SCHEDULED`: Status padrão de quando é criada. Esse status significa que ela está agendada, e sua cobrança ocorerá na data prevista.
- `ACTIVE`: Ela é movida para esse status após estar agendada. Nesse status a COBR já foi criada e aprovado pelo banco do consumidor.
- `COMPLETED`: Quando o usuário pagou a cobrança que está relacionada
- `EXPIRED`: Quando a cobrança passou do prazo de vencimento e não teve pagamento
- `CANCELED`: Quando a parcela foi cancelada, pode ocorrer manualmente ou devido a um erro ao gerar a cobrança

As primeiras parcelas são geradas junto com a assinatura, com a data prevista definida pelo `dayGenerateCharge` com o status `SCHEDULED`. Em caso de assinatura mensal, elas são geradas sempre no mesmo dia, se ela for criada no dia 31 e o próximo mês não tiver essa data, ela será ajustada para o último dia do mês.

```mermaid
flowchart LR
    A[SCHEDULED] -->B(ACTIVE)
    B[ACTIVE] -->C(COMPLETED)
    B[ACTIVE] -->D(EXPIRED)
    B[ACTIVE] -->E(CANCELED)
```

### Cobrança Recorrente (CobR) 

As cobranças que serão criadas para debitar automaticamente do cliente.

Por padrão ele é criado 4 dias antes da data de cobrança. Após ser criado, é feita uma requisição para o banco do consumidor para ele ser aprovado ou rejeitado.

- `CREATED`: Status padrão de quando é criada
- `ACTIVE`: Cobrança aceita pelo banco do consumidor
- `CONCLUDED`: Cobrança realizada com sucesso
- `FAILED_TRY`: Tentativa de cobrança falhou
- `REJECTED`: Cobrança rejeitada pelo banco do consumidor, ela só mudará para esse status em duas situações: 
    - Após uma tentativa falhar e a cobrança atingir sua data de expiração, caso o retryPolicy seja `THREE_RETRIES_7_DAYS`
    - Após uma tentativa falhar e a cobrança não ser paga na data determinada, caso o retryPolicy seja `NON_PERMITED` 
- `CANCELED`: Cobrança cancelada 

```mermaid
flowchart LR
    A[CREATED] -->B(ACTIVE)
    A[CREATED] --> F[FAILED_TRY]
    F[FAILED_TRY] --> D(REJECTED)
    F[FAILED_TRY] --> B(ACTIVE)
    B[ACTIVE] -->C(CONCLUDED)
    B[ACTIVE] -->E(CANCELED)
```

### Retentativa Cobrança Recorrente (CobRTry) 

Sempre que uma cobrança for criada, também será criada uma tentativa de cobrança, caso ela falhe, dependendo da opção definida na assinatura (`retryPolicy`), poderão ser feitas novas tentativas de cobrança.

- `THREE_RETRIES_7_DAYS` serão feitas até 3 retentativas: a primeira um dia após data da cobrança, outra na data intermediária entre a data da cobrançca e data de expiração, e a última tentativa será feita na data de expiração.
- `NON_PERMITED` não serão feitas retentativas.

Cada retentativa possui um status próprio, somente é possível realizar uma nova retentativa caso a última seja rejeitada

- `REQUESTED`: Status padrão de quando é criada, simboliza que foi feito uma nova tentativa de cobrança
- `SCHEDULED`: Quando a tentativa de cobrança é aceita com sucesso pelo banco
- `PAID`: Quando a tentativa de cobrança é paga pelo banco
- `REJECTED`: Quando a tentativa de cobrança é rejeitada pelo banco, nessa situação poderão ser feitas novas tentativas

```mermaid
flowchart LR
    A[REQUESTED] -->B(SCHEDULED)
    B[SCHEDULED] -->C(PAID)
    A[REQUESTED] -->D(REJECTED)
```

---

## Como implementar passo a passo

## Configurar os webhooks

A primeira etapa é configurar os [webhooks](./5-webhooks/pix-automatic-webhooks.md) para ser notificado quando houver alguma alteração de status. Caso ainda não saiba como cadastrar os webhooks na nossa plataforma, veja o nosso [tutorial](../webhook/platform/webhook-platform-api.mdx)

Os indispensáveis são:

1. PIX_AUTOMATIC_APPROVED : Recorrência aprovada
2. PIX_AUTOMATIC_COBR_COMPLETED : Pagamento realizado com sucesso

A próxima etapa é realizar uma requisição POST para a [criação da assinatura](./pix-automatic-how-to-create.md)

---

## O que é o Pix Automático?

O Pix Automático permite cobranças automáticas, diretamente da conta bancária do usuário. Sendo ideal para pagamentos recorrentes como assinaturas ou mensalidades.

## Funcionamento

O Funcionamento do pix automático é composto por 2 etapas:

1. Criação da Assinatura
2. Autorização da assinatura pelo cliente

Após aprovação do cliente, as cobranças serão criadas a partir da configuração feita pela assinatura, podendo ser semanal, mensal, trimestral, semestral ou anual.

## Jornadas

As jornadas são as diferentes maneiras de se utilizar o Pix Automático definidas pelo Banco Central. Sendo elas:

### Jornada 1 | Autorização via Push Notification

Na jornada 1 o recebedor envia uma notificação ao usuário, convidando-o para entrar em uma recorrência.

### Jornada 2 | Autorização via QRCode

Na jornada 2, o recebedor enviará ao consumidor um QRCode que será responsável pela autorização da recorrência. Ao aceitar, a partir da data pré definidia na assinatura, serão feitas as próximas cobranças.

### Jornada 3 | Autorização + Pagamento da primeira parcela

Na jornada 3, o recebedor enviará ao consumidor um QRCode que será responsável pela autorização e a cobrança da primeira parcela da assinatura. Nesta jornada, não é possível recusar o pagamento da primeira parcela e apenas aceitar a recorrência. Caso esse seja o funcionamento desejado, utilize a jornada 2.

### Jornada 4 | Pagamento + Oferta da Recorrência

Na jornada 4, o recebedor enviará ao consumidor um QRCode que será responsável por uma cobrança e também será ofertada a possibilidade de uma recorrência. Essa oferta poderá tanto ser aceita quanto recusada.

## Falha na Cobrança

Ao criar uma assinatura você poderá definir sua política em caso de falha na cobrança. No momento existem duas opções:

1. `NON_PERMITED`: Sem novas retentativas
2. `THREE_RETRIES_7_DAYS`: Será feita até 3 novas cobranças no período de 7 dias

Se ao final das retentativas não for possível cobrar o usuário, a assinatura será cancelada.

---

## Perguntas Frequentes

## Perguntas Frequentes - Pix Crediário

## Posso criar um Pix Crediário para CPF ou CNPJ?
Sim, você pode criar para pessoa física ou jurídica

## Quando o Pix Crediário passa a valer de fato?
Somente após o pagamento da primeira parcela.

## O que acontece se o cliente não paga a primeira parcela?
O Pix Crediário é dado com expirado e todas suas parcelas são expiradas também.

---

## Como Funciona o Pix Crediário?

## Como funciona o Pix Crediário?
O Pix Crediário da Woovi é uma ferramenta de gestão de crediário digital. Primeiramente, o lojista seleciona ou cadastra o cliente, definindo o valor da venda e as condições de pagamento. Em seguida, um link de pagamento é gerado e enviado ao cliente. Ele escolhe o número de parcelas e paga a primeira. Pronto, venda concluída

- Você define as regras
- Flexibildadade para o Cliente
- Rápido e Prático
- Acesso para vendedores
- Envio por email
- Envio por WhatsApp
- Análise de Crédito
- Acordo para Clientes Inadimplentes
- Dashboard e Relatórios

## Como usar o Pix Crediário
1. Va até a sidebar e selecione Cobranças
2. Em cobranças no canto direito superior clique no botão Pix Crediário
    ![Steps acima exemplificados em uma imagem da plataforma](./__assets__/pix-crediary-how-work-1.png)
3. Em seguida preencha o formulário para criação do Pix Crediário
   ![Formulário de criação do Pix Crediário dentro da plataforma](./__assets__/pix-crediary-how-work-form.png)
   1. **Cliente a ser cobrado**: obrigatório o preenchimento de um cliente com nome, cpf/cnpj, telefone e email.
   2. **Dados da cobrança**: informe o valor do Pix Crediário (obrigatório) e uma descriçao (opcional).
   3. **Informações Adicionais**: adicione informações adicionais ao Pix Crediário (opcional).
   4. **Parcelas**: Selecione o número máximo de parcelas disponíveis para o cliente selecionar no momento do pagamento. Padrão 4 parcelas.
   5. **Tempo para pagamento**: tempo para pagamento da primeira parcela. Padrão final do dia seguinte.
   6. **Destino do pagamento**: conta que irá receber o pagamento das parcelas do Pix Crediário.
4. Preenche o formulário como desejar e clique em **Criar Cobrança**
5. Ao cria-lo você será redirecionado para o detalhe do Pix Crediário.
   ![Detalhe do Pix Crediário dentro da plataforma](./__assets__/pix-crediary-detail.png)
6. Uma vez criado o mesmo é enviado via email para seu cliente
   ![Email do Pix Crediário](./__assets__/pix-crediary-email.png)
7. Você pode executar ações de mensageria dentro da plataforma através dos botões existentes no detalhe da cobrança
   ![Botões do Pix Crediário](./__assets__/pix-crediary-buttons.png)
8. Quando seu cliente abrir o link de pagamento ele poderá selecionar a opção desejada de pagamento
   ![Link de pagamento do Pix Crediário](./__assets__/pix-crediary-payment-link.png)
9. Ao selecionar a opção será disponibilizado o QRCode Pix da primeira parcela junto com suas informações
   ![Link de pagamento do Pix Crediário com a primeira parcela ativa](./__assets__/pix-crediary-active.png)
10. Ao selecionar a forma de pagamento você poderá acompanhar as parcelas do Pix Crediário dentro do próprio detalhe da plataforma. Basta descer a página e acompanhar as parcelas:
    ![Detalhe do Pix Crediário com a primeira parcela ativa](./__assets__/pix-crediary-detail-active.png)

---

## Pix Crediário

## Pix Crediário: O acelerador de Vendas que o seu negócio precisa
Conheça o Pix Crediário, um sistema inovador para gerir crediários próprios cobrados por meio do Pix. Agilidade, simplicidade e segurança se unem para criar uma experiência de venda inovadora.

- Gestão Simplificada
- Cobranças Automáticas
- Mais Vendas e Menos Inadimplência

---

## Como criar uma nova chave pix.

## Como criar uma nova Chave Pix via api

Este documento irá ajudar a entender como criar uma chave Pix.

![fluxograma sequencial com cria uma chave pix](./__assets__/sequenceDiagrama_create_pix_key.png)

## 1. Montando a requisição.
  * Utilize o endpoint de chave pix para criar uma nova chave pix
  * Utilize o appId para autenticar a requisição.
  * Faça a requisição.
  ```JSON
   curl -X POST "https://api.woovi.com/api/v1/pix-keys" \
     -H "Authorization: <appId>" \
     -H "Content-Type: application/json" 
     --data-raw '{
        "pixKey": "<chave pix>",
        "type": "<tipo da chave pix 'CNPJ', ou 'EVP' (nesse caso não é nescessário enviar a chave pix, visto que será uma chave aleatória)>"
      }'
  ```

  * Caso tudo ocorra corretamente, um código 201 será retornado.
  * No corpo da resposta terá:
  ```JSON
    {
      "pixKey": {
        "pixKey": "<chave pix>",
        "type": "<tipo da chave pix>",
        "isDefault": true
      }
    }
  ```

OBS: para criar chaves pix do tipo "PHONE" ou "EMAIL", é necessário ter permissão especial. 
Caso deseje, entre em contato com o suporte e solicite a permissão.

---

## Tem que pagar mensalidade pra usar?

O produto Maquininha PIX não possui mensalidade nem assinatura para usar. Basta ter uma conta na Woovi, que é
gratuita, e uma [impressora térmica](https://woovi.com/articles/maquininhas/), gerar as cobranças e pedir para seus clientes efetuarem o pagamento.

---

## Funciona no celular?

No momento ainda não temos suporte para celular, mas em breve teremos.

---

## Como imprimir o recibo de um QR code estático na Maquininha Pix?

Com a Maquininha, trazemos a possibilidade de fazer a impressão tanto dos QR codes das
cobranças, quanto do recibo de pagamento delas.

![Integration detail](./__assets__/pix-machine-integration-detail.png)

Habilitando os filtros de **Todas as cobranças criadas na plataforma** e 
**Todas as cobranças pagas na plataforma**, habilitando ambos os filtros na sua integração,
sua Maquininha Pix automaticamente fará a impressão dos eventos conforme o nome descrito no filtro.

Toda cobrança criada a partir da plataforma, será automaticamente impresso pela Maquininha Pix, quando
habilitado o filtro de cobranças criadas. E todo pagamento dessas respectivas cobranças, será automaticamente
impresso quando o filtro de cobrança paga estiver habilitado.

---

## Como imprimir o recibo de um QR code estático na Maquininha Pix?(How-to)

Com a Maquininha Pix, trazemos a possibilidade de você imprimir fisicamente os recibos
de pagamento de um ou mais QR codes estáticos.

![Integration detail](./__assets__/pix-machine-integration-detail.png)

Você tem duas possíveis maneiras de estar imprimindo os recibos de pagamento de um QR code estático, você pode tanto imprimir todos os pagamentos relacionados ao QR code ou filtrar um QR code estático em específico.

Caso deseja imprimir o recibo do pagamento de todos os QR code estáticos, basta selecionar a opção de **"Todos os QRCode estáticos pagos na plataforma"**.

## Filtrando os QR codes estáticos

Caso deseja filtrar a impressão dos recibos de pagamento de acordo com um QR code estático em específico,
a etapa de número 3 do formulário te dá essa possibilidade.

![QR codes](./__assets__/pix-machine-integration-detail-qrcodes.png)

Clicando no campo de QR codes estáticos, abrirá uma lista para que possa selecionar quais QR codes estáticos
você deseja filtrar os eventos de pagamento.

:::info

Lembrando que é necessário desabilitar o filtro de **"Todos os QRCode estáticos pagos na plataforma"** para não haver nenhum conflito.

:::

---

## Como configuro cashback para meus clientes nas cobranças impressas?

[Neste artigo](/docs/cashback/cashback-how-to-config) você encontrará o passo a passo de como configurar o cashback para seus clientes nas cobranças
impressas.

---

## Como Instalar a Maquininha PIX

import Embed from 'react-embed';

:::info
É esperado que você já possua conta com a woovi, caso não tenha, [clique aqui](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/como-fazer-login-na-plataforma) para saber como criar uma conta.
:::

:::info
Para instalar a Maquininha PIX, você precisa de uma impressora térmica conectada em seu computador. Caso sua maquininha térmica não esteja conectada, [clique aqui](setup-pix-machine.md) para saber como conectar
:::

## Como instalar a Maquininha PIX

A Maquininha PIX é um produto da Woovi que permite que você gere cobranças PIX e imprima o QR Code fisicamente, para que seus clientes possam pagar com o PIX.

Acesse o tutorial da maquininha para instalar o nosso aplicativo: [https://app.woovi.com/home/pix-machine/tutorial](https://app.woovi.com/home/pix-machine/tutorial) e clique em `Download Windows`

Após baixar o arquivo, clique em `Abrir`, e em seguida, clique em `Executar`

## Após instalar o aplicativo

Com o aplicativo instalado será mostrado um ícone na área de trabalho, clique duas vezes para abrir o aplicativo.

![Maquininha App](__assets__/maquininha-app.png)

Com o aplicativo instalado, é necessário adicionar o ID de sua impressora térmica.

## Vinculando a impressora térmica

Com o aplicativo já instalado, acesse as configurações da sua maquininha [clicando aqui](https://app.woovi.com/home/pix-machine/settings) ou em `Maquininha PIX` > `Ajustes`, e copie o ID da impressora.

![Maquininha Settings](__assets__/maquininha-settings.png)

Com o ID da impressora copiado, abra o aplicativo da maquininha e cole o ID no campo `ID da impressora` e clique em `Salvar`.

![Maquininha Setup](__assets__/maquininha-setup.png)

Pronto! Sua maquininha está pronta para ser usada.

## Como testar se minha maquininha está funcionando

Para testar se sua maquininha está funcionando, crie uma cobrança qualquer na plataforma woovi e veja se a impressão foi feita corretamente.

---

## Como imprimir uma cobrança?

Ao gerar uma nova cobrança, do lado direito você terá algumas opções, sendo uma delas a opção **Imprimir na
maquininha**. Clicando nessa opção irá abrir uma modal para selecionar a sua impressora (este procedimento
acontece somente na primeira vez que você imprimir). Você deverá selecionar a impressora que deseja imprimir e
clicar em **Conectar**.

---

## É necessário instalar algum driver para imprimir uma cobrança?

Dependendo da especificação do sistema operacional e do seu dispositivo em que está sendo utilizado, será necessário sim instalar drivers adicionais para funcionar corretamente.

## macOS

No macOS não possui nenhuma restrição. Você pode conectar o seu dispositivo e imprimir normalmente sem nenhuma
reivindicação.

## Windows

Atualmente para você conectar sua impressora na plataforma será necessário instalar os drivers do seu dispositivo.

Aqui está os links de alguns drivers que recomendados, dado o conhecimentos dos principais modelos:

Modelo                | Drivers
----------------------|-------
MP-4200 TH (Bematech) | https://www.bztech.com.br/downloads/driver-bematech-mp-4200
EPSON TM-T20X         | https://epson.com.br/Suporte/Ponto-de-venda/Impressoras-de-recibos/Epson-TM-T20x/s/SPT_C31CH26031
Jetway JP 500         | http://www.jetway.com.br/suporte-e-downloads/

Caso você já tenha os drivers instalados e não obteve exitô ao
conectar seu dispositivo. Você pode utiliza o [Zadig](https://zadig.akeo.ie/) para reinstalar o driver USB do seu dispositivo.

### Como utilizar o Zadig

1. Entre no site https://zadig.akeo.ie/ e faça o download da última versão
2. Abra o Zadig
3. Clique em `Options` no menu superior

4. Marque a opção `List All Devices`

![step-1](/img/thermal-printer/zadig-step-1.png)

5. Depois selecione seu dispositivo

![step-2](/img/thermal-printer/zadig-step-2.png)

6. Selecione o driver `WinUSB`
7. Clique em `Reinstall Driver`

![step-3](/img/thermal-printer/zadig-step-3.png)

## Linux

Ainda não suportado.

---

## Como usar a Maquininha Pix na minha barbearia?

A Maquininha Pix fornece para as barbearia um meio automático, prático e fácil
de se automatizar o fluxo de pagamentos no seu estabelecimento. Nossa solução PDV,
fornece uma aplicação desktop que te permite instalar em qualquer máquina sem depender
de nenhum drive externo, facilitando a usabilidade da aplicação.

## Como instalar a Maquininha Pix no meu computador?

Para instalar a aplicação da Maquininha na sua máquina, siga este tutorial [Como Instalar a Maquininha PIX](./how-to-install-pix-machine.md).

Este tutorial te dará as etapas passo a passo para estar realizando a instalação
e a configuração inicial da aplicação no seu computador.

## Como imprimir usando a Maquininha Pix?

Com a solução da Maquininha Pix, você pode imprimir tanto os QR code Pix para pagamento,
quanto seus respectivos recibos confirmando o pagamento daquele QR code. Abaixo, temos um
tutorial explicando como realizar a impressão:

### Imprimindo o recibo de um QR code estático

Com o QR code estático, você consegue automatizar o seu processo de pagamento de forma fácil
e simplificada. Num cenário onde cada estação possui seu respectivo QR code atrelado ou 

Com um QR code estático criado a partir da nossa plataforma, você pode imprimi-lo e deixa-lo
físicamente, podendo deixar ele visível no seu caixa, em cada uma das mesas, ou até mesmo vindo
junto a comanda.

![QR code filter](./__assets__/pix-machine-qrcode-filter.png)

Na sua integração da impressora, dentro da Maquininha Pix, é necessário que ela tenha o filtro de
**"QR code estático pago"** selecionado. Deste modo, quando o cliente realizar o pagamento daquele QR code
que você compartilhou, a Maquininha irá automaticament imprimir o recibo de pagamento contendo as
informações da transação.

### Imprimindo uma cobrança Pix

Com a cobrança Pix, você consegue operar de forma mais meticulosa cada uma das cobranças geradas,
tendo a possibilidade de selecionar o respectivo cliente, informações adicionais, e mais. 

Com as cobranças, você tem a possibilidade tanto de imprimir o respectivo QR code daquela cobrança, quanto
o seu recibo de pagamento.

![Pix Machine Filtro de Charges](./__assets__/pix-machine-charge-filter.png)

Para a impressão do QR code de uma cobrança, a sua integração da Maquininha precisa ter o filtro de **"Cobrança criada"**
habilitado. Deste modo, conforme as cobranças vão sendo criadas a partir da nossa plataforma, a Maquininha
automaticamente irá fazer a impressão a partir da impressora selecionada via integração.

Para a impressão do recibo de pagamento de uma cobrança, a sua integração da Maquininha precisa ter o filtro de **"Cobrança paga"**
habilitado. Deste modo, assim que o cliente efetuar o pagamento do respectivo QR code daquela cobrança, a Maquininha 
automaticamente irá fazer a impressão a partir da impressora selecionada via integração.

---

## Perguntas frequentes(Pix-machine)

## Qual maquininha/impressora devo utilizar para imprimir as cobranças?

Você deve utilizar uma impressora térmica não fiscal e utilizar a que você já tem, mas caso ainda não tenha,
[neste artigo](https://woovi.com/articles/maquininhas/) você encontrará as que recomendamos à você, mas pode ser qualquer outra que você preferir.

## Qual a diferença entre a impressora térmica não fiscal e fiscal?

A impressora fiscal é utilizada para emitir o cupom fiscal para o consumidor final, além de ser empregada em
fechamentos de caixa, relatórios mensais de vendas e cancelamentos. Já a impressora não fiscal, chamada de
impressora de cupom, geralmente é utilizada para imprimir comprovantes de venda e senhas. Logo, a principal
diferença entre impressora não fiscal e impressora fiscal é que a primeira não possui memória fiscal e o lacre
de segurança, cujo uso deve ser fiscalizado. Além disso, não existem pré-requisitos para a compra ou utilização
das impressoras não fiscais, diferentes da impressora fiscal.

## É necessário instalar algum driver para imprimir uma cobrança?

Dependendo da especificação do sistema operacional e do seu dispositivo em que está sendo utilizado, será necessário sim instalar drivers adicionais para funcionar corretamente.

Neste tutorial, você pode estar conferindo como fazer a instalação de acordo com o modelo da
sua impressora térmica não-fiscal: [veja aqui](./is-it-necessary-to-install-any-driver-to-print-a-charge.md).

## Tem que pagar mensalidade pra usar?

O produto Maquininha PIX não possui mensalidade nem assinatura para usar. Basta ter uma conta na Woovi, que é
gratuita, e uma [impressora térmica](https://woovi.com/articles/maquininhas/), gerar as cobranças e pedir para seus clientes efetuarem o pagamento.

## Como configuro cashback para meus clientes nas cobranças impressas?

[Neste artigo](/docs/cashback/cashback-how-to-config) você encontrará o passo a passo de como configurar o cashback para seus clientes nas cobranças
impressas.

## Como configuro minha impressora térmica no Windows?

Para a utilização correta da Maquininha Pix, é necessário ter uma impressora térmica não-fiscal
conectado a sua máquina. Neste tutorial a seguir, instruímos no passo a passo de como configurar a impressora na sua maquina corretamente. [Veja aqui](./setup-pix-machine.md).

---

## Como usar a Maquininha Pix na minha pizzaria?

A Maquininha Pix fornece para as pizzarias um meio automático, prático e fácil
de se automatizar o fluxo de pagamentos no seu estabelecimento. Nossa solução PDV,
fornece uma aplicação desktop que te permite instalar em qualquer máquina sem depender
de nenhum drive externo, facilitando a usabilidade da aplicação.

## Como instalar a Maquininha Pix no meu computador?

Para instalar a aplicação da Maquininha na sua máquina, siga este tutorial [Como Instalar a Maquininha PIX](./how-to-install-pix-machine.md).

Este tutorial te dará as etapas passo a passo para estar realizando a instalação
e a configuração inicial da aplicação no seu computador.

## Como imprimir usando a Maquininha Pix?

Com a solução da Maquininha Pix, você pode imprimir tanto os QR code Pix para pagamento,
quanto seus respectivos recibos confirmando o pagamento daquele QR code. Abaixo, temos um
tutorial explicando como realizar a impressão:

### Imprimindo o recibo de um QR code estático

Com o QR code estático, você consegue automatizar o seu processo de pagamento de forma fácil
e simplificada. Principalmente voltada para pizzarias com alta rotatividade de clientes, que
também fornecem o serviço no próprio estabelecimento, o QR code estático pode ser a maneira
mais prática de estar fornecendo um método de pagamento Pix pros seus clientes.

Com um QR code estático criado a partir da nossa plataforma, você pode imprimi-lo e deixa-lo
físicamente, podendo deixar ele visível no seu caixa, em cada uma das mesas, ou até mesmo vindo
junto a comanda.

![QR code filter](./__assets__/pix-machine-qrcode-filter.png)

Na sua integração da impressora, dentro da Maquininha Pix, é necessário que ela tenha o filtro de
**"QR code estático pago"** selecionado. Deste modo, quando o cliente realizar o pagamento daquele QR code
que você compartilhou, a Maquininha irá automaticament imprimir o recibo de pagamento contendo as
informações da transação.

### Imprimindo uma cobrança Pix

Com a cobrança Pix, você consegue operar de forma mais meticulosa cada uma das cobranças geradas,
tendo a possibilidade de selecionar o respectivo cliente, informações adicionais, e mais. Principalmente
voltada para pizzarias que fornecem seus serviços a partir de delivery, e que operam por meios digitais,
junto a nossa solução de link de pagamento e a facilidade da cobrança via WhatsApp, pode ser o combinado
perfeito para alavancar ainda mais suas vendas.

Com as cobranças, você tem a possibilidade tanto de imprimir o respectivo QR code daquela cobrança, quanto
o seu recibo de pagamento.

![Pix Machine Filtro de Charges](./__assets__/pix-machine-charge-filter.png)

Para a impressão do QR code de uma cobrança, a sua integração da Maquininha precisa ter o filtro de **"Cobrança criada"**
habilitado. Deste modo, conforme as cobranças vão sendo criadas a partir da nossa plataforma, a Maquininha
automaticamente irá fazer a impressão a partir da impressora selecionada via integração.

Para a impressão do recibo de pagamento de uma cobrança, a sua integração da Maquininha precisa ter o filtro de **"Cobrança paga"**
habilitado. Deste modo, assim que o cliente efetuar o pagamento do respectivo QR code daquela cobrança, a Maquininha 
automaticamente irá fazer a impressão a partir da impressora selecionada via integração.

---

## Como usar a Maquininha Pix na minha restaurante?

A Maquininha Pix fornece para as restaurantes um meio automático, prático e fácil
de se automatizar o fluxo de pagamentos no seu estabelecimento. Nossa solução PDV,
fornece uma aplicação desktop que te permite instalar em qualquer máquina sem depender
de nenhum drive externo, facilitando a usabilidade da aplicação.

## Como instalar a Maquininha Pix no meu computador?

Para instalar a aplicação da Maquininha na sua máquina, siga este tutorial [Como Instalar a Maquininha PIX](./how-to-install-pix-machine.md).

Este tutorial te dará as etapas passo a passo para estar realizando a instalação
e a configuração inicial da aplicação no seu computador.

## Como imprimir usando a Maquininha Pix?

Com a solução da Maquininha Pix, você pode imprimir tanto os QR code Pix para pagamento,
quanto seus respectivos recibos confirmando o pagamento daquele QR code. Abaixo, temos um
tutorial explicando como realizar a impressão:

### Imprimindo o recibo de um QR code estático

Com o QR code estático, você consegue automatizar o seu processo de pagamento de forma fácil
e simplificada. Principalmente voltada para restaurantes com alta rotatividade de clientes, que
também fornecem o serviço no próprio estabelecimento, o QR code estático pode ser a maneira
mais prática de estar fornecendo um método de pagamento Pix pros seus clientes.

Com um QR code estático criado a partir da nossa plataforma, você pode imprimi-lo e deixa-lo
físicamente, podendo deixar ele visível no seu caixa, em cada uma das mesas, ou até mesmo vindo
junto a comanda.

![QR code filter](./__assets__/pix-machine-qrcode-filter.png)

Na sua integração da impressora, dentro da Maquininha Pix, é necessário que ela tenha o filtro de
**"QR code estático pago"** selecionado. Deste modo, quando o cliente realizar o pagamento daquele QR code
que você compartilhou, a Maquininha irá automaticament imprimir o recibo de pagamento contendo as
informações da transação.

### Imprimindo uma cobrança Pix

Com a cobrança Pix, você consegue operar de forma mais meticulosa cada uma das cobranças geradas,
tendo a possibilidade de selecionar o respectivo cliente, informações adicionais, e mais. Principalmente
voltada para restaurantes que fornecem seus serviços a partir de delivery, e que operam por meios digitais,
junto a nossa solução de link de pagamento e a facilidade da cobrança via WhatsApp, pode ser o combinado
perfeito para alavancar ainda mais suas vendas.

Com as cobranças, você tem a possibilidade tanto de imprimir o respectivo QR code daquela cobrança, quanto
o seu recibo de pagamento.

![Pix Machine Filtro de Charges](./__assets__/pix-machine-charge-filter.png)

Para a impressão do QR code de uma cobrança, a sua integração da Maquininha precisa ter o filtro de **"Cobrança criada"**
habilitado. Deste modo, conforme as cobranças vão sendo criadas a partir da nossa plataforma, a Maquininha
automaticamente irá fazer a impressão a partir da impressora selecionada via integração.

Para a impressão do recibo de pagamento de uma cobrança, a sua integração da Maquininha precisa ter o filtro de **"Cobrança paga"**
habilitado. Deste modo, assim que o cliente efetuar o pagamento do respectivo QR code daquela cobrança, a Maquininha 
automaticamente irá fazer a impressão a partir da impressora selecionada via integração.

---

## Configurando sua maquininha no Windows


Para configurar sua maquininha junto com o nosso aplicativo recomendados que você siga os passos abaixo:

### 1. Acesse sua barra Windows e digite `Impressoras e Scanners`

Feito isso clique em adicionar uma impressora ou scanner local

![Alt text](__assets__/configure-machine-1.png)

### 2. Adicione sua impressora clicando em `Add manually`

![Alt text](__assets__/configure-machine-2.png)

### 3. Selecione a opção `Add a local printer`

![Alt text](__assets__/configure-machine-3.png)

### 4. Selecione a opção `Use an existing port` e selecione a porta usb de sua maquininha térmica

![Alt text](__assets__/configure-machine-4.png)

### 5. Utilize os drivers genéricos da Microsoft

![Alt text](__assets__/configure-machine-5.png)

### 6. Dê um nome para sua impressora e clique em `Next`

![Alt text](__assets__/configure-machine-6.png)

### 7. Clique em `Next na parte de configuração de compartilhamento`

![Alt text](__assets__/configure-machine-7.png)

### 8. Clique em `Print a test page` para testar se sua impressora está funcionando

![Alt text](__assets__/configure-machine-8.png)

### 9. Pronto! Sua impressora está configurada e pronta para ser usada

---

## O que preciso fazer pra configurar minha maquininha e começar a imprimir as cobranças?

Não se faz necessário nenhum tipo de configuração. Basta que sua impressora esteja conectada no seu computador
ou notebook, abrir a plataforma da Woovi em sua conta, gerar uma nova cobrança e imprimi-la.

---

## Qual a diferença entre a impressora térmica não fiscal e fiscal?

A impressora fiscal é utilizada para emitir o cupom fiscal para o consumidor final, além de ser empregada em
fechamentos de caixa, relatórios mensais de vendas e cancelamentos. Já a impressora não fiscal, chamada de
impressora de cupom, geralmente é utilizada para imprimir comprovantes de venda e senhas. Logo, a principal
diferença entre impressora não fiscal e impressora fiscal é que a primeira não possui memória fiscal e o lacre
de segurança, cujo uso deve ser fiscalizado. Além disso, não existem pré-requisitos para a compra ou utilização
das impressoras não fiscais, diferentes da impressora fiscal.

---

## Qual a taxa cobrada pela woovi?

A taxa cobrada pela woovi nas transações com a Maquininha PIX é de 0.8% para cada transação, sendo a taxa mínima cobrada de R$0,50 centavos e a taxa máxima cobrada sendo de R$5,00 reais.

Exemplo 1: se você vender R$50,00 reais para seu cliente, o cálculo será de R$50,00 x 0.8%, que resulta em R$0,40 centavos, porém você pagará R$0,50 centavos, por ser a taxa mínima.

Exemplo 2: se você vender R$1.000,00 reais para seu cliente, o cálculo será de R$1.000,00 x 0.8%, que resulta em R$8,00 reais, porém você irá pagar somente R$5,00 reais, por ser a taxa máxima.

---

## Onde clica para imprimir uma cobrança?

Basta clicar no botão **Imprimir na maquininha** que a cobrança será impressa automaticamente.

---

## Quais navegadores são suportados?

No momento somente nos navegadores: Google Chrome, Edge e Opera.

---

## Qual maquininha/impressora devo utilizar para imprimir as cobranças?

Você deve utilizar uma impressora térmica não fiscal e utilizar a que você já tem, mas caso ainda não tenha,
[neste artigo](https://woovi.com/articles/maquininhas/) você encontrará as que recomendamos à você, mas pode ser qualquer outra que você preferir.

---

## Criando um App ID para o Plugin JS

## Criando uma aplicação para ser utilizado no Plugin JS

O appID é criado dentro da plataforma Woovi pelo administrador. Para criá-lo, acesse a documentação para criação de novas APIs clicando [aqui](/docs/apis/api-getting-started). Lembre de selecionar a API com o tipo **PLUGIN**.

> **Importante**: para visualizar o sidebar API/Plugins é necessário ter a permissão de: ADMIN.
> 
> Caso você não possua uma das permissão solicite para o admin da sua plataforma a inserção da mesma para seu usuário.
> 
> O usuário admin pode seguir este tutorial para [atualizar permissões de usuários](../faq/users.md)

Uma vez criada a API, copie o AppID para utilizar na integração do Plugin e siga para o próximo passo clicando em próximo no canto inferiro direito.

---

## Conceito

## Plugin JavaScript

O Plugin JavaScript Woovi permite que você crie cobranças Pix e renderiza cobranças Pix e QRCode Estáticos com poucas linhas de código

## Benefícios de utilizar o Plugin JavaScript

Ao utilizar o Plugin JavaScript você não precisa se preocupar com a renderização das cobranças Pix.

O Plugin JS renderiza o QRCode no desktop e renderiza o copia e cola no celular.

O Plugin JS também apresenta animações para quando o QRCode foi copiado com sucesso.

O Plugin JS possui websockets o que garante que o pagamento seja atualizado em tempo real, tanto para sucesso como para expiração.

O Plugin JS também garante que a cobrança apresenta os dados corretamente de Cashbacks e Descontos.

O Plugin JS renderiza um reloginho para criar a urgência de pagamento.

Novas melhorias de Design da Woovi são aplicadas automaticamente no Plugin JS.

![Plugin JS](./__assets__/plugin-order.png)

---

## FAQ

## Como Utilizar o Plugin JavaScript dentro de um iframe?

Para utilizar o Plugin JavaScript dentro de um iframe, você deve adicionar o atributo `allow="clipboard-read; clipboard-write"` no iframe.

Exemplo

```html
<iframe
  class="frameapp"
  frameborder="0"
  src="https://woovi.com/cashback"
  width="372"
  height="555"
  style="border: 10px blue solid;"
  allow="clipboard-read; clipboard-write"
></iframe>
```

---

## Como renderizar o Plugin sem o modal?


Caso você deseja renderizar o nosso plugin diretamente numa div, sem precisar de um modal para isso, você pode
utilizar o seguinte código:

```jsx
window.$woovi.push([
  'charge',
  {
    modal: false,
    // restante dos parâmetros relacionados ao pix
    // ...
  },
]);
```

O argumento `wrapper` é um _booleano_ que vai ditar se é necessário renderizar o plugin dentro de um modal ou não.

## Como defino em qual elemento o plugin será renderizado?

Por padrão, o plugin é renderizado dentro do elemento que contenha o id `#woovi`.

Caso tenha a necessidade de renderizar o plugin numa div com um atributo distinto, nós aceitamos um
query param `node` que pode ser passado na URL que carrega o plugin.

Exemplo:

```html
<script src="https://plugin.woovi.com.br/v1/woovi.js?node=#other-identifier" allow="clipboard-read; clipboard-write"></script>
```

Nesse caso, o plugin será carregado assumindo o elemento que contenha o id `#other-identifier`.

## Exemplo do plugin renderizado sem modal

![Plugin renderizado sem modal](./__assets__/plugin-screenshot-without-modal.png)

---

## Renderizando uma cobrança Pix existente


Para renderizar a cobrança Pix igual a Woovi renderiza no link de pagamento (ex. [https://woovi.com/pay/13829f18-ef6b-4842-9f6c-583f2b50940d](https://woovi.com/pay/13829f18-ef6b-4842-9f6c-583f2b50940d))

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Woovi Order</title>
  </head>
  <body>
    <!-- Woovi order -->
    <div 
      id='openpix-order' 
      data-appid={"your app id"}
      data-correlationid={"charge correlationID"} 
    />
    <script src="https://plugin.woovi.com/v1/openpix.js" async></script>
  </body>
</html>
```

![Plugin JS](./__assets__/plugin-order.png)

---

## Gerar QRCode Estático utilizando Plugin

## Gerando um QRCode Estático

```jsx
window.$openpix.push([
  'static',
  {
    key: 'pixKey - cpf/email/phone',
    value: 1000,
    name: 'Merchant Name',
    reference: 'Description name',
  },
]);
```

- key (obrigatório): chave de pix para receber o pagamento
- value (opcional): valor de cobrança em centavos
- name (opcional): nome do comerciante
- reference (opcional): descrição desta cobrança

---

## Integração React

Se você deseja ter um controle melhor da IU do seu aplicativo
Você pode usar [@openpix/react](https://www.npmjs.com/package/@openpix/react) para criar facilmente novas cobranças e receber atualizações de status de pagamento.

## Como instalar

```jsx
pnpm add @openpix/react
```

## Configurar Polyfills
Este plugin usa o core-js para polyfill Promises

Instale core-js

```jsx
pnpm add core-js
```

Adicione seu entrypoint do seu App

```jsx
import 'core-js/stable';
```

## Usando com React

```jsx
import 'core-js/stable';
import { useState } from 'react';
import { useWoovi } from '@openpix/react';
import QRCode from 'qrcode.react';

const App = () => {
  const [charge, setCharge] = useState(null);
  
  const onPay = (charge) => {
    // TODO do something
    console.log('charge was paid');
  }

  const { chargeCreate } = useWoovi({
    appID: process.env.APP_ID,
    onPay,
  });

  const newCharge = async () => {
    const payload = {
      correlationID: 'myCorrelationID',
      value: 1, // one cent
      comment: 'Donate',
    }

    const { charge, error } = await chargeCreate(payload);

    if (error) {
      setError(error);
      return;
    }

    setCharge(charge);
  }

  if (charge) {
    return (
      <QRCode
        size={200}
        renderAs={'svg'}
        value={charge.brCode}
        includeMargin={false}
      />
    );
  }

  return (
    <>
      <button onClick={newCharge}>
        Create New Charge
      </button>
    </>
  )
}
```

## Usando com React Native ou Expo

```jsx
import 'core-js/stable';
import { useState } from 'react';
import { useWoovi } from '@openpix/react';
import QRCode from 'react-native-qrcode-svg';

const App = () => {
  const [charge, setCharge] = useState(null);
  
  const onPay = (charge) => {
    // TODO do something
    console.log('charge was paid');
  }

  const { chargeCreate } = useWoovi({
    appID: process.env.APP_ID,
    onPay,
  });

  const newCharge = async () => {
    const payload = {
      correlationID: 'myCorrelationID',
      value: 1, // one cent
      comment: 'Donate',
    }

    const { charge, error } = await chargeCreate(payload);

    if (error) {
      setError(error);
      return;
    }

    setCharge(charge);
  }

  if (charge) {
    return (
      <QRCode
        size={200}
        value={charge.brCode}
      />
    );
  }

  return (
    <>
      <button onClick={newCharge}>
        Create New Charge
      </button>
    </>
  )
}
```

---

## Exemplos(Plugin)

Aqui está a demonstração de como integrar o Plugin Woovi em seu aplicativo de frontend. O que temos nesta demonstração:
- gera uma cobrança com valor de 1 centavo
- recebe eventos do plugin como status de pagamento
- mostra automaticamente quando a cobrança foi paga

[React Plugin Demo](https://github.com/Open-Pix/react-openpix-plugin-demo)

Você também pode testar o Plugin usando nosso [Online Demo](https://woovi.com/plugin/).

---

## Plugin

A Woovi possui 2 plugins para ser utilizados em seu negócio, o Plugin de `Order` e o Plugin de `Widget`.

## O que é necessário saber antes de utilizar os plugins?

- É necessário entender que para utilizar as API's e plugins disponibilizados dentro da Woovi você precisa ter um AppID válido, veja como criar [aqui](./app-id.md).

- Ao tentar consumir o plugin para criar uma cobrança você precisa gerar um correlationID único, para conseguir buscar essa cobrança dentro da Woovi, se você não informar um novo correlationID para uma nova cobrança, sera mostrado a cobrança anterior relacionada a esse correlationID

## Começando com o Plugin de `Widget`

O Plugin de `Widget` permite criar facilmente cobranças Pix dentro do seu frontend Javascript.
E deve ser utilizado quando a cobrança ainda precisa ser criada na Woovi.

### Criando o Plugin de `Widget`

A primeira coisa é incluir a tag de script do plugin Woovi na parte inferior do arquivo html

```html
<script src="https://plugin.woovi.com/v1/woovi.js" async>
```

O script pode ser importado dentro de um arquivo `.html`. Por exemplo, se seu aplicativo for um aplicativo em React, o script do Plugin Woovi será importado dentro de `index.html`.

Veja o exemplo abaixo:

```html
<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <title>Demo Woovi Plugin</title>
  </head>
  <body>
    <div id="root"></div>
    <script src="https://plugin.woovi.com/v1/woovi.js" async></script>
  </body>
</html>
```

Até este momento, nada deve acontecer, pois o plugin não foi inicializado.
Para confirmar se o plugin foi inicializado corretamente, você pode acessar o console do seu navegador e buscar por esses logs

```
[Woovi] connecting, attemp 0
[Woovi] connected
```

### Inicializando o plugin `Widget`

O plugin é consumido usando o objeto `Window` nativo da API Javascript. Para inicializar, crie um array `$openpix` window para se comunicar com o plugin.
Insira a chave do seu [appID](./app-id.md) como abaixo:

```jsx
window.$openpix = window.$openpix || []; // priorize o objeto já instanciado
window.$openpix.push(['config', { appID: 'YourWooviAppId' }]);
```

Agora seu plugin está pronto para ser consumido.

### Gerando uma cobrança Pix

O Plugin Woovi injeta uma variável `$openpix` especial para permitir que seu aplicativo se comunique com o Plugin

Você pode criar uma nova Cobrança Pix como este:

```jsx
window.$openpix.push([
  'pix',
  {
    value: 1000, // R$ 10,00
    correlationID: 'myCorrelationId',
    description: 'product A',
  },
]);
```

- value (obrigatório): valor da cobrança em centavos, obrigatório em todas as cobranças
- correlationID (obrigatório): correlationID única para identificar a cobrança, obrigatório em todas as cobranças
- description (opcional): descrição a ser adicionada ao EMV BRCode Pix

#### Arquivo HTML

```html
<!DOCTYPE html>
<html lang="pt-BR">

  <head>
    <meta charset="UTF-8" />
    <title>Demo Woovi Plugin</title>
  </head>

  <body>
    <button onclick="displayWooviModal()">
      Clique para abrir o modal
    </button>
    <script src="https://plugin.woovi.com/v1/woovi.js" async></script>
    <script>
      function displayWooviModal() {
        window.$openpix = window.$openpix || [];

        window.$openpix.push(['config', {
          appID: 'yourWooviAppId',
        }]);

        window.$openpix.push([
          'pix',
          {
            value: 1000,
            correlationID: 'randomCorrelationID',
            description: 'product A',
          },
        ]);
      }
    </script>
  </body>

</html>
```

#### Resultado

![photo-example-plugin](/img/plugin/photo-example-plugin.png)

### Gerando uma cobrança Pix com Cliente

Você pode criar uma nova Cobrança Pix adicionando um cliente assim:

```jsx
window.$openpix.push([
  'pix',
  {
    value: 1000, // R$ 10,00
    correlationID: 'myCorrelationId',
    description: 'product A',
    customer: {
      name: 'Customer',
      email: 'customer@gmail.com',
      taxID: '098.969.330-90',
      phone: '+5511940461111',
    },
  },
]);
```

- customer (opcional): cliente selecionado a ser cobrado
  - name: nome do cliente
  - email: email do cliente
  - taxID: CPF ou CNPJ do cliente
  - phone: telefone do cliente

### Gerando uma cobrança Pix com Informações Adicionais

Você pode criar uma nova cobrança Pix com informações adicionais da seguinte forma:

```jsx
window.$openpix.push([
  'pix',
  {
    value: 1000, // R$ 10,00
    correlationID: 'myCorrelationId',
    description: 'product A',
    additionalInfo: [
      {
        key: 'Product',
        value: 'Pencil',
      },
      {
        key: 'Order',
        value: '1748',
      },
    ],
  },
]);
```

- additionalInfo (opcional): Informações adicionais relacionadas a cobrança
  - key: chave que contêm o valor da informação adicional
  - value: é um valor que contêm a informação adicional passada. Ex: '123'

`Obs: quando o usuário scanear o QrCode ele irá ver`

#### Resultado

![photo-example-additionalInfo](/img/plugin/photo-example-additionalInfo.png)

### Gerando uma cobrança Pix com Tempo de Expiração

Você pode criar uma nova cobrança Pix com um tempo de expiração da seguinte forma:

```jsx
window.$openpix.push([
  'pix',
  {
    value: 1000, // R$ 10,00
    correlationID: 'myCorrelationId',
    expiresIn: 2100, // 35 minutos em segundos
  },
]);
```

- expiresIn (opcional): tempo em segundos que a cobrança permanecerá disponível.
  - Deve ser maior que 15 minutos
  - Exemplo: `expiresIn: 1200` = 20 minutos

#### Quando a cobrança expirar ela terá este layout

![photo-example-expired](/img/plugin/photo-example-expired.png)

### Consultar o Estado de Pagamento do Plugin

Os eventos disponiveis são

- `CHARGE_COMPLETED`: quando a cobrança foi paga pelo cliente e deu baixa na Woovi.
- `CHARGE_EXPIRED`: quando a cobrança foi expirada.
- `ON_CLOSE`: quando o modal da cobrança foi fechado.
- `ON_ERROR`: quando ocorre algum erro no plugin.

```jsx
const logEvents = (e) => {
  if (e.type === 'CHARGE_COMPLETED') {
    console.log('a cobrança foi paga');
  }

  if (e.type === 'CHARGE_EXPIRED') {
    console.log('a cobrança foi expirada');
  }

  if (e.type === 'ON_CLOSE') {
    console.log('o modal da cobrança foi fechado');
  }

  if (e.type === 'ON_ERROR') {
    console.log('ocorreu um erro');
  }
}

// only register event listener when plugin is already loaded
if(!!window.$openpix?.addEventListener) {
  const unsubscribe = window.$openpix.addEventListener(logEvents);

  // parar de escutar os eventos
  // unsubscribe();
}
```

#### Exemplo de arquivo HTML

```html

<!DOCTYPE html>
<html lang="pt-BR">

  <head>
    <meta charset="UTF-8" />
    <title>Demo Woovi Plugin</title>
  </head>

  <body>
    <button onclick="displayWooviModal()">
      Clique para abrir o modal
    </button>
    <script src="https://plugin.woovi.com/v1/woovi.js" async></script>
    <script>
      function displayWooviModal() {
        window.$openpix = window.$openpix || []; // priorize o objeto já instanciado

        window.$openpix.push(['config', {
          appID: 'yourAppId'
        }]);

        window.$openpix.push([
          'pix',
          {
            value: 1000, // R$ 10,00
            correlationID: 'yourRandomCorrelationId',
          },
        ]);

        const logEvents = (e) => {
          if (e.type === 'CHARGE_COMPLETED') {
            console.log('a cobrança foi paga');
          }

          if (e.type === 'CHARGE_EXPIRED') {
            console.log('a cobrança foi expirada');
          }

          if (e.type === 'ON_CLOSE') {
            console.log('o modal da cobrança foi fechado');
          }

          if (e.type === 'ON_ERROR') {
            console.log('ocorreu um erro');
          }
        }
        
      // only register event listener when plugin is already loaded
        if(!!window.$openpix?.addEventListener) {
          const unsubscribe = window.$openpix.addEventListener(logEvents);

          // parar de escutar os eventos
          // unsubscribe();
        }
      }
    </script>
  </body>

</html>
```

## Começando com o Plugin de `Order`

O Plugin de `Order` é utilizado somente para mostrar cobranças já criadas na Woovi, ou seja, você cria essa cobrança em um backend, e depois exibe ela consumindo o plugin de `Order`.
Nele todos os eventos de cobrança paga e expirada funcionam, e são atualizados em tempo real.

### Criando o Plugin de `Order`

Semelhante ao Plugin de `Widget` você precisa criar um arquivo `.html` criar uma div em que você gostaria que o plugin fosse injeto, e criar uma tag script para o plugin.

Porém nessa chamada você informa alguns outros dados, como `appID`, `correlationID` e `node` via query-string. Esse node é referente ao atributo id do elemento que você quer que o plugin seja injetado.
ex: `?appID=<APPIDVALIDO>&correlationID=<CORRELATION-ID-VALIDO>&node=<DIV-PARA-INJETAR>`

```html
<!DOCTYPE html>
<html lang="pt-BR">

<head>
  <meta charset="UTF-8" />
  <title>Demo Woovi Plugin</title>
</head>

<body>
  <div id="openpix-order"></div> <!-- o node nesse caso é "openpix-order" -->
  <script src="https://plugin.woovi.com/v1/woovi.js?appID=appID&correlationID=appID&node=openpix-order"></script>
</body>

</html>
```

#### Resultado

![order-example-plugin](/img/plugin/photo-example-plugin.png)

---

## Como usar a API para criar um QRCode Estático (cob)?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para criar uma QRCode estático Pix, você utiliza o _endpoint_ `/api/v1/pixQrCode` da API.

Você pode acessar [aqui](/api#tag/pixqrcode/POST/api/v1/qrcode-static)
a documentação referente a esse _endpoint_.

### Campos obrigatórios

Os campos obrigatórios para criar um QRCode Estático Pix são os sequintes:

- **`name`**: O nome de identificação desse QRCode na plataforma Woovi.
- **`identifier`**: Um identificador único para o QRCode Estático Pix.

#### Identifier

Este identificador deverá possuir:

- tamanho máximo de 25 caracteres
- apenas números e letras
- sem caracteres especiais
- sem espaços em branco

Abaixo, temos um exemplo de como gerar esse identificar em javascript utilizando uuid:

```ts
import { v4 as uuidv4 } from 'uuid';

export const getDefaultIdentifier = () =>
  uuidv4().toString().replace(/-/g, '').slice(0, 25);
```

### Campos opcionais

- **`correlationID`**: seu correlation ID relacionado ao ID do QRCode no seu banco de dados. Utilizado para trackear o dado. Esse campo é Único.
- **`value`**: valor do QRCode em centavos. Quando vazio o cliente poderá inserir o valor do QRCode no momento do pagamento Pix para o mesmo.obrigatórios
- **`comment`**: comentários relacionado ao QRCode que aparece para o cliente final no momento do pagamento pix.

## Exemplo

O body da sua requisição será semelhante a este exemplo:

- QRCode com nome e identificador apenas:

```json
{
  "name": "QRcode Teste",
  "identificador": "c782e0ac833d4a899e739b60b"
}
```

- QRCode com nome, identificador, valor de 10,00 reais:

```json
{
  "name": "QRcode Teste",
  "identifier": "c782e0ac833d4a899e739b60b",
  "value": 1000,
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, retornaremos o QRCode criado.

Retornarmeros a seguinte resposta de exemplo:

```json
{
  "pixQrCode": {
    "name": "QRCode Teste",
    "identifier": "c782e0ac833d4a899e739b60b",
    "correlationID": "91a67996-cd4c-4104-b943-4076ad6319fa",
    "paymentLinkID": "1efcc519-3056-4a6c-94cd-d686969d8a61",
    "createdAt": "2023-03-06T13:54:57.899Z",
    "updatedAt": "2023-03-06T13:54:57.899Z",
    "brCode": "00020126580014br.gov.bcb.pix013600ad360c-92c7-45ab-adb3-188307a6e4d05204000053039865802BR5910Woovi_Demo6009Sao_Paulo62290525c782e0ac833d4a899e739b60b6304533D",
    "paymentLinkUrl": "https://woovi.com/pay/1efcc519-3056-4a6c-94cd-d686969d8a61",
    "qrCodeImage": "https://api.woovi.com/openpix/charge/brcode/image/1efcc519-3056-4a6c-94cd-d686969d8a61.png"
  }
}
```

### Exemplos em código

  

```sh
curl --request POST \
  --url https://api.woovi.com/api/v1/qrcode-static \
  --header 'Authorization: REPLACE_KEY_VALUE' \
  --header 'content-type: application/json' \
  --data '{"name":"string","correlationID":"string","value":0,"comment":"string","identifier":"string"}'
```

  
  

```js
const http = require("https");

const options = {
  "method": "POST",
  "hostname": "api.woovi.com",
  "port": null,
  "path": "/api/v1/qrcode-static",
  "headers": {
    "content-type": "application/json",
    "Authorization": "REPLACE_KEY_VALUE"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({
  name: 'string',
  correlationID: 'string',
  value: 0,
  comment: 'string',
  identifier: 'string'
}));
req.end();
```

---

## Exportar QRCodes Estáticos

Você pode exportar a lista de QRCodes Estáticos dentro da plataforma para um excel. Siga os passos abaixo:

1. Acesse a rota https://app.woovi.com/home/qrcodes/tab/list
2. Clique em exportar no lado direito
![qrcode estatico button](./__assets__/qrcode-export-btn.png)
3. A plataforma irá processar seu export e você será avisado quando o mesmo estiver pronto.
4. Veja como acessar sua exportação [aqui](/docs/export/export-intro)

---

## QRCode Estático

QRCode Estático é um QRCode que permite aceitar múltiplos pagamentos.

Ele permite decidir um valor predeterminado ou deixar o pagador escolher o valor na hora do pagamento

## Casos de Uso

- Aceitar pagamentos em eventos presenciais
- Aceitar pagamentos em lives [Twitch](https://www.twitch.tv/)
- Aceitar doações
- Aceitar pagamentos em lojas físicas
- Aceitar pagamentos em `vending maching`
- Aceitar pagamentos na [https://www.etiquetas.io/](https://www.etiquetas.io/)

---

## Como obter recibos via API?

- [O que é recibo?](./recibo.md)
- [Começando com a integração via API](../apis/start-api-integration.md)

Documentação técnica da estrutura do endpoint de recibo:
[`/api/v1/receipt/{ReceiptType}/{EndToEndId}`](/api#tag/receipt/GET/api/v1/receipt/{ReceiptType}/{EndToEndId})

Modelo de requisição:  
https://api.woovi.com/api/v1/receipt/:receiptType/:endToEndId

Exemplo de uso:  
https://api.woovi.com/api/v1/receipt/pix-in/E2202312345678901234567890123456

### Como obter um endToEndId via dashboard

Para obter um endToEndId do tipo pix-in, vá ao dashboard, em "Extrato" localize a aba transações e clique nela
![](./__assets__/get-receipt-via-api/dash-extrato.png)

![](./__assets__/get-receipt-via-api/dash-extrato-transactions.png)

Na lateral esquerda, localize o botão "Filtro", filtre pelo tipo "Recebimento" e aplique o filtro  
![](./__assets__/get-receipt-via-api/locate-filter-button.png)

Depois, você pode copiar seu endToEndId e adicioná-lo à URL da requisição da API, utilizando o tipo de comprovante como sendo pix-in  
![](./__assets__/get-receipt-via-api/transaction-filter.png)

![](./__assets__/get-receipt-via-api/locate-your-transaction.png)

Os mesmos passos podem ser utilizados para obter endToEndId de outros tipos, como pix-out e pix-refund.  
Veja mais sobre tipos na seção de [Explicando Tipos](#explicando-tipos) abaixo.

### Como obter um recibo com o endToEndId?

1) Baixe e instale um cliente HTTP, como Postman, Bruno ou Insomnia.
> Neste guia, estarei utilizando o Postman como cliente HTTP.
2) Crie uma nova requisição e adicione a URL de exemplo no campo onde há um espaço vazio ao lado da palavra GET.  
   ![](./__assets__/get-receipt-via-api/create-new-request.png)
> URL de exemplo: https://api.woovi.com/api/v1/receipt/:receiptType/:endToEndId
3) Substitua onde está `:receiptType` pelo tipo de recibo que você está querendo buscar (pix-in, pix-out ou pix-refund).
4) Substitua onde está `:endToEndId` pelo endToEndId dos seus recebimentos, pagamentos ou reembolsos.
5) Feito isso, você terá uma URL semelhante ao exemplo abaixo:
> https://api.woovi.com/api/v1/receipt/pix-in/E2202312345678901234567890123456
6) Agora precisamos configurar nosso appID para autenticação via API. Para isso, clique na aba "Headers" e crie novos campos de chave e valor. Defina a chave com o valor "Authorization" e, no valor dessa chave, coloque seu appID.  
   ![](./__assets__/get-receipt-via-api/header-authorization.png)
7) Com a configuração do appID de autorização feita, podemos realizar uma chamada à API clicando no botão azul "Send" no Postman.

> Caso ainda não tenha um appID do tipo API, recomendamos fortemente que você visite a nossa documentação de [primeiros passos com API](../apis/api-getting-started.md).

### Explicando tipos:

**Pix In** é equivalente ao filtro de "Recebimentos" no nosso dashboard.  
O tipo `pix-in` deve ser utilizado quando você recebe um pagamento em sua conta, como por exemplo quando você gera uma cobrança e ela é paga por alguém. Você recebe um pagamento (transação pix-in, entrada de Pix).

**Pix Out** é equivalente ao filtro de "Pagamentos" no nosso dashboard.  
O tipo `pix-out` deve ser utilizado quando você faz um pagamento para uma chave Pix ou paga uma cobrança, como por exemplo quando alguém gera uma cobrança e você a paga. Um saque é realizado da sua conta para outra, por isso chamamos de pix-out (saída de Pix).

**Pix Refund** é equivalente ao filtro de "Reembolso" no nosso dashboard.  
Para o tipo `pix-refund`, temos duas variantes chamadas de "Pix Refund Sent" e "Pix Refund Received". Ele deve ser utilizado quando é realizado um reembolso de algum pagamento que você recebeu ou pagou.
- "Pix Refund Sent" é quando você efetua um reembolso para alguém.
- "Pix Refund Received" é quando você recebe um reembolso.

---

## O que é um recibo?

Ao fazer um pagamento, você consegue visualizar o recibo do mesmo. Para comprovar que essa operação foi de fato feita. 

## Como fazer visualizar um recibo?

Entre na plataforma e acesse o menu de Saques/Pagamentos.

![Imagem da plataforma](./__assets__/plataform.png) 

Selecione um pagamento e clique em *Imprimir comprovante*

![Pagamento](./__assets__/payment.png)

Visualize o recebido

![recibo](./__assets__/receipt.png)

## Como receber esse recibo via API?

Acesse a documentação da API [aqui](/api/#tag/receipt)

Caso n saiba criar uma API, acesse a documentacao de primeiros passos [aqui](/docs/apis/getting-started-api)

O endpoint que você precisa usar é um GET (/api/v1/receipt/:EndToEndId)

O EndToEndId é o ID do pagamento, você consegue visualizar essa informação na plataforma

Resposta da API em caso de sucesso:

![Resposta api](./__assets__/api.png)

---

## Como criar uma reembolso de uma cobrança usando a API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para criar uma novo reembolso de uma cobrança usando a API, você deverá fazer uma chamada POST para o _endpoint_ `/api/v1/charge/{correlationID}/refund` usando `correlationID` da cobrança.

Você pode acessar [aqui](/api#tag/charge-refund/POST/api/v1/charge/{id}/refund) a documentação referente a esse _endpoint_.

Como parte do `BODY` da requisição, esperamos o envio dos seguintes itens:

:::caution
O `correlationID` enviado no BODY da requisição **não** é o correlationID identificador da cobrança.  
Trata-se, na verdade, de um **ID de idempotência**, que **você deve gerar** para controlar reembolsos de forma segura e consistente no seu sistema.
:::

- **`correlationID`**: O correlationID do reembolso a ser criado. Este campo é usado para [idempotencia](../concepts/idempotence.md) de reembolsos de cobranças.

O body também aceita outros campos **opcionais**:

- **`value`**: O valor em centavos do reembolso a ser criado. Se não informado será usado o valor total da cobrança ou o valor restante da cobrança que ainda não foi reembolsado.
- **`comment`**: O comentário do reembolso a ser criado. Não deve ser maior que 140 caracteres.

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "correlationID": "aafee9f5-94b3-4e3d-ab6a-416d0a1218cb",
  "value": 100,
  "comment": "Comentário do reembolso"
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, retornaremos o reembolso criada.

Retornarmeros a seguinte resposta de exemplo:

```json
{
  "refund": {
    "status": "IN_PROCESSING"
    "value": 100
    "correlationID": "aafee9f5-94b3-4e3d-ab6a-416d0a1218cb"
    "endToEndId": "E23114447202304181826HJNwY577YDX"
    "time": "2023-03-02T17:28:51.882Z",
    "comment": "Comentário do reembolso"
  }
}
```

### Exemplos em código

  

```sh
 curl --request POST \
     --url https://api.woovi.com/api/v1/charge/{correlationID}/refund \
     --header 'Authorization: AUTHORIZATION' \
     --header 'content-type: application/json' \
     --data '{"correlationID": "aafee9f5-94b3-4e3d-ab6a-416d0a1218cb","value": 100,"comment": "Comentário do reembolso"}'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/charge/{correlationID}/refund', {
  method: 'POST',
  body: JSON.stringify({
    correlationID: 'aafee9f5-94b3-4e3d-ab6a-416d0a1218cb',
    value: 100,
    comment: "Comentário do reembolso"
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como buscar todos os reembolsos de uma cobrança usando a API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para buscar todos os reembolsos de uma cobrança usando a API, você deverá fazer uma chamada GET para o _endpoint_ `/api/v1/charge/{correlationID}/refund` usando `correlationID` da cobrança.

Você pode acessar [aqui](/api#tag/charge-refund/GET/api/v1/charge/{id}/refund) a documentação referente a esse _endpoint_.

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, retornaremos os reembolsos da cobrança.

Retornarmeros a seguinte resposta de exemplo:

```json
{
  "refunds": [
    {
      "status": "IN_PROCESSING"
      "value": 100
      "correlationID": "aafee9f5-94b3-4e3d-ab6a-416d0a1218cb"
      "endToEndId": "E23114447202304181826HJNwY577YDX"
      "time": "2023-03-02T17:28:51.882Z"
    },
    {
      "status": "CONFIRMED"
      "value": 40
      "correlationID": "589a378e-ab45-4f30-bd4d-4496c60f88cf"
      "endToEndId": "E23114447202304181057pOhPMsp2pJZ"
      "time": "2021-03-05T14:49:02.922Z",
      "comment": "Comentário do reembolso"
    }
  ]
}
```

### Exemplos em código

  

```sh
 curl --request GET \
     --url https://api.woovi.com/api/v1/charge/{correlationID}/refund \
     --header 'Authorization: AUTHORIZATION'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/charge/{correlationID}/refund', {
  headers: {
    Authorization: 'AUTHORIZATION',
  },
}).then((res) => res.json());
```

---

## Como contribuir com o SDK

## Contribuindo com o woovi Java SDK
O desenvolvimento do nosso Java SDK é opensource e pode ser encontrado em nosso [repositório público](https://github.com/Open-Pix/ruby-sdk). Para contribuir basta ler a sessão de [contributing](https://github.com/Open-Pix/java-sdk#contributing)

---

## Recursos

## Lista de recursos disponíveis

Existem recursos disponíveis para cada tipo de operação. Para cada recurso, existe uma classe que representa o recurso e
uma classe que representa uma lista de recursos. Essas classes são as classes de paginação: `Paginator<T>`.

### Paginação

A classe `Paginator<T>` é uma classe que representa uma lista de recursos. Ela possui os seguintes métodos:

- `Future<List<T>> itemsAsync()`: Obtém os itens da página atual.
- `Future<PageInfo> pageInfoAsync()`: Obtém as informações da página atual.
- `void next()`: Vai para a próxima página.
- `void previous()`: Vai para a página anterior.

As funções `next` e `previous` atualizam uma informação da classe, e os dados só serão lidos
da próxima vez que for chamado o método `itemsAsync` ou `pageInfoAsync`.

### Charge

- `Charge`: Representa uma cobrança.

#### Criar uma cobrança

```java
// Cria uma charge
ChargeBuilder charge = new ChargeBuilder()
    .value(100)
    .comment("comment")
    .correlationID("correlationId")
    .destinationAlias("destinationAlias")
    .sourceAccountId("sourceAccountId");

sdk.createChargeAsync(charge).get();
```

#### Obter uma cobrança

```java
// Obtém uma cobrança pelo ID. string.
sdk.getChargeAsync(correlationID).get();
```

#### Remover uma cobrança

```java
// Remove uma cobrança pelo ID. string.
sdk.deleteChargeAsync(correlationID).get();
```

### PixQrCode

- `PixQrCode`: Representa um pix qr code.

#### Criar um pix qr code

```java
// Cria um pix qr code
PixQrCodeBuilder pixQrCode = new PixQrCodeBuilder()
    .value(100)
    .comment("comment")
    .correlationID("correlationId")
    .destinationAlias("destinationAlias")
    .sourceAccountId("sourceAccountId");

sdk.createPixQrCodeAsync(pixQrCode).get();
```

#### Obter um pix qr code

```java
// Obtém um pix qr code pelo ID. string.
sdk.getPixQrCodeAsync(correlationID).get();
```

### Transação

- `Transaction`: Representa uma transação.

#### Obter uma transação

```java
// Obtém uma transação pelo ID. string.
sdk.getTransactionAsync(correlationID).get();
```

### Conta

- `Account`: Representa uma conta.

#### Obter uma conta

```java
// Obtém uma conta pelo ID. string.
sdk.getAccountAsync(correlationID).get();
```

#### Obter uma lista de contas

```java
// Obtém uma lista de contas.
sdk.getAccountsAsync().get();
```

#### Performar saque

```java
// Performa um saque.
sdk.withdrawAsync(id, value).get();
```

### Reembolso

- `Refund`: Representa um reembolso.

#### Criar um reembolso

```java
// Cria um reembolso
RefundBuilder refund = new RefundBuilder()
    .value(100)
    .comment("comment")
    .correlationID("correlationId")
    .destinationAccountId("destinationAccountId")
    .sourceAccountId("sourceAccountId");

sdk.createRefundAsync(refund).get();
```

#### Obter um reembolso

```java
// Obtém um reembolso pelo ID. string.
sdk.getRefundAsync(correlationID).get();
```

### Webhook

- `Webhook`: Representa um webhook.

#### Verificar assinatura de um webhook

Toda invocação de webhook em sua aplicação traz um cabeçalho HTTP chamado x-webhook-signature, que consiste na
assinatura gerada utilizando a chave secreta da Woovi e o payload (corpo da requisição HTTP) do webhook. Ao receber esse
cabeçalho, você pode validar se a assinatura é válida e prosseguir com o fluxo do webhook.

```
x-webhook-signature: lL2nnXgmLFGgxJ8+jCDguqouU4ucrIxYJcU5SPrJFaNcJajTJHYVldqc/z4YFIjAjtPEALe699WosgPY08W7CLpidvtm06Qwa4YMB0l/DcTS93O91NdSH/adjugEKiOb76Zj/0jB8mqOmWCFYbweOBa17bssuEkd5Lw7Q5L314Y=
```

Veja um [exemplo de validação de assinatura](/docs/webhook/seguranca/webhook-signature-validation#exemplo-de-valida%C3%A7%C3%A3o).

Para verificar a assinatura de um webhook, você precisa do corpo da requisição, o cabeçalho `x-webhook-signature` e o
conteúdo enviado no request.

```java
// Verifica a assinatura de um webhook
import br.com.woovi.OpenSSL;

// The body of the request sent by the woovi servers
String payload = "...";

// The signature in the header `x-webhook-signature`
String signature = "...";

if OpenSSL.verify(payload, signature) {
    // The signature is valid
} else {
    // The signature is invalid
}
```

#### Criar um webhook

```java
// Cria um webhook
WebhookBuilder builder = new WebhookBuilder()
    .number(100)
    .url("https://google.com")
    .enableWebhook();

sdk.createWebhookAsync(builder).get();
```

#### Deletar um webhook

```java
// Deleta um webhook pelo ID. string.
sdk.deleteWebhookAsync(correlationID).get();
```

### Customer

- `Customer`: Representa um customer.

#### Criar um customer

```java
// Cria um customer
CustomerBuilder builder = new CustomerBuilder()
    .name("name")
    .email("email@gmail.com")
    .taxIdNumber("947.761.930-04")
    .phoneNumber("4299999-9999")
    .address(address);

sdk.createCustomerAsync(builder).get();
```

#### Obter um customer

```java
// Obtém um customer pelo ID. string.
sdk.getCustomerAsync(correlationID).get();
```

### Pagamento

- `Payment`: Representa um pagamento.

#### Criar um pagamento

```java
// Cria um pagamento
PaymentBuilder payment = new PaymentBuilder()
    .value(100)
    .comment("comment")
    .correlationID("correlationId")
    .destinationAccountId("destinationAccountId")
    .sourceAccountId("sourceAccountId");

sdk.createPaymentAsync(payment).get();
```

#### Obter um pagamento

```java
// Obtém um pagamento pelo ID. string.
sdk.getPaymentAsync(correlationID).get();
```
6 KB

---

## Como começar

## Instalando

É necessário ter o Java com versão superior à 8.0 instalado com o [Gradle](https://gradle.org) ou [Maven](https://maven.apache.org/).

Use o repositório do "Maven Central" para instalar o SDK:

```groovy
repositories {
    mavenCentral()
}
```

E também adicione a dependência do SDK:

```groovy
dependencies {
    implementation 'br.com.woovi:java-sdk:0.0.13'
}
```

Dessa forma, o SDK, um cliente HTTP (`ktor`) e uma implementação serão instalados.

## Criando o cliente

O ponto de entrada do SDK é um `WooviSDK`:

```java
package br.com.woovi;

import br.com.woovi.sdk.WooviSDK;

import java.util.concurrent.ExecutionException;

public class Main {
    public static void main(String[] args) {
        // Para começar a usar o SDK Java
        WooviSDK sdk = new WooviSDK(System.getenv("APP_ID"));
    }
}

```

O constructor cria um novo cliente a partir de um ID de aplicativo obtido no [site da woovi](https://app.woovi.com.br/home/applications/tab/list). Também é possível passar configurações para o SDK, como o executor, para isso você pode observar os "overloads" dessa função, que por definição são os construtores com o mesmo nome, mas com parâmetros diferentes. Você também pode utilizar o método estático `WooviSdk.of` para construir.

Através dos "overloads" você pode específicar, a "url base", o "executor"(que é o ambiente onde vão ser despachadas as threads), uma instância de json e uma instância de http client.

Ambas instâncias de json e http client você pode configurar parâmetros internos, como `explicitNulls`,
leniência, e outros, que não vem ao caso, no momento. Todas elas estão documentadas em código, e são fáceis de ler.

## Chamando a API

Um SDK possui _métodos_ para acessar a API da woovi. Todos eles são assíncronos, e retornam um `Future` que pode ser usado para obter o resultado da chamada.

```java
sdk.allCustomersAsync().get();
```

Cada função retorna um futuro, que pode ser acessado em "single-thread" utilizando o método `get` ou em "multi-thread" utilizando o método `join`.

## Procurando páginas

Para procurar páginas, você pode utilizar os métodos, que tem como parâmetro os "start", "end", "charge", e outros, que são os parâmetros de paginação da API. Um exemplo desses métodos, é o método `transactionsAsync`, que retorna uma página de transações.

```java
// Você pode utilizar o método get para obter o resultado da chamada. E não passar nenhum parametro, porque os parametros são opcionais.
sdk.transactionsAsync().get();

// Você pode utilizar os seguintes parametros: 
sdk.transactionsAsync(start, end, charge, pixQrCode, withdrawal).get();
```

### Formato das entradas

Cada formato de entrada é uma classe com tipos, geralmente são nomeados como `Builder` no final, por exemplo `ChargeBuilder`.

```java
// Cria uma charge
ChargeBuilder charge = new ChargeBuilder()
    .value(100)
    .comment("comment")
    .correlationID("correlationId")
    .destinationAlias("destinationAlias")
    .sourceAccountId("sourceAccountId");

sdk.createChargeAsync(charge).get();
```

Argumentos simples como strings e inteiros são utilizados no caso de operações de obtenção de apenas um recurso ou remoção. Por exemplo

```java
// Obtém uma cobrança pelo ID. string.
sdk.getChargeAsync(correlationID);

// Remove uma cobrança pelo ID. string.
sdk.deleteChargeASync(correlationID);
```

### Formato de saída

A execução de uma operação irá devolver resultados da API na forma de um objeto ou na forma de um paginador, especialmente em operações de listagem, como na listagem de transações.

```java,
/**
 * Criando um pix qr code
 *
 * Retorna um objeto
 */
PixQrCodeBuilder builder = new PixQrCodeBuilder()
        .identifier("identificador")
        .name("nome"); 

System.out.println(sdk.createPixQrCodeAsync(builder).get());

/**
 * Resultado: (Identado para fins de leitura)
 *
 * PixQrCodeResponse(
 *   pixQrCode=PixQrCode(
 *     name=nome,
 *     identifier=identificador,
 *     correlationID=bad32cd4-123e-49f7-8ca4-f1381c633831,
 *     paymentLinkID=a42a8a56-ab8e-4fc3-833d-c7dc1ff7473f,
 *     createdAt=2023-07-28T01:41:58.920Z,
 *     updatedAt=2023-07-28T01:41:58.920Z,
 *     brCode=00020126580014br.gov.bcb.pix013600ad360c-92c7-45ab-adb3-188307a6e4d05204000053039865802BR5910Woovi_Demo6009Sao_Paulo62170513identificador63040E64,
 *     paymentLinkUrl=https://woovi.com.br/pay/a42a8a56-ab8e-4fc3-833d-c7dc1ff7473f,
 *     qrCodeImage=https://api.woovi.com.br/woovi/charge/brcode/image/a42a8a56-ab8e-4fc3-833d-c7dc1ff7473f.png
 *   ),
 *   correlationID=null,
 *   brCode=null,
 * ) 
 */
```

## JavaDocs

Em cada operação disponível para um determinado tipo de recurso, existem [Java Docs](https://docs.oracle.com/en/java/) disponíveis informando o formato de entrada e saída da operação com um link para a documentação da API Rest e exemplo de utilização.

Para utilizar, é sugerido utilizar um editor com como o Eclipse ou o IntelliJ que possuem suporte para Java e bastante tooling para facilitar o desenvolvimento. 

Também é possível consultar a documentação no site da woovi caso haja dúvidas.

## Recursos disponíveis

Os seguintes recursos estão disponíveis no `Client`:

- `Future<PixQrCodeResponse> getPixQrCodeAsync(...)`: Obtém um Pix QR Code pelo ID.

- `Future<PixQrCodeList> allPixQrCodesAsync(...)`: Lista todos os Pix QR Codes.

- `Future<PixQrCodeResponse> createPixQrCodeAsync(...)`: Cria um Pix QR Code.

- `Future<Account> getAccountAsync(...)`: Obtém uma conta pelo ID.

- `Future<AccountListResponse> allAccountsAsync(...)`: Lista todas as contas.

- `Future<WithdrawResponse> withdrawAsync(...)`: Realiza um saque.

- `Future<PaymentResponseObject> getPaymentAsync(...)`: Obtém um pagamento pelo ID.

- `Future<PaymentListResponse> allPaymentsAsync(...)`: Lista todos os pagamentos.

- `Future<PaymentResponseObject> createPaymentAsync(...)`: Cria um pagamento.

- `Future<ChargeDeleteResponse> deleteChargeAsync(...)`: Remove uma cobrança pelo ID.

- `Future<ChargeResponse> getChargeAsync(...)`: Obtém uma cobrança pelo ID.

- `Future<ChargeListResponse> chargesAsync(...)`: Lista todas as cobranças.

- `Future<ChargeResponse> createChargeAsync(...)`: Cria uma cobrança.

- `Future<File> chargeQrCodeImageAsync(...)`: Obtém a imagem de um QR Code de uma cobrança.

- `Future<Customer> getCustomerAsync(...)`: Obtém um cliente pelo ID.

- `Future<CustomerListResponse> allCustomersAsync(...)`: Lista todos os clientes.

- `Future<CustomerResponse> createCustomerAsync(...)`: Cria um cliente.

- `Future<RefundResponse> getRefundAsync(...)`: Obtém um reembolso pelo ID.

- `Future<RefundListResponse> allRefundsAsync(...)`: Lista todos os reembolsos.

- `Future<RefundResponse> createRefundAsync(...)`: Cria um reembolso.

- `Future<WebhookDeleteResponse> deleteWebhookAsync(...)`: Remove um webhook pelo ID.

- `Future<WebhookListResponse> allWebhooksAsync(...)`: Lista todos os webhooks.

- `Future<WebhookResponse> createWebhookAsync(...)`: Cria um webhook.

- `Future<TransactionResponse> getTransactionAsync(...)`: Obtém uma transação pelo ID.

- `Future<TransactionListResponse> transactionsAsync(...)`: Lista todas as transações.

## Dependências

O SDK depende de implementações das:
- [Ktor Client](https://ktor.io/docs/create-client.html) (e outras dependências)
- [Kotlinx Coroutines](https://github.com/Kotlin/kotlinx.coroutines)
- [Kotlinx Serialization](https://github.com/Kotlin/kotlinx.serialization)

O Ktor client é utilizado para realizar as requisições HTTP, e as outras dependências são utilizadas para realizar as requisições de forma assíncrona.

---

## O que é o SDK de Java?

O SDK de Java é um kit de ferramentas criado com o objetivo de integrar facilmente os serviços da woovi em suas aplicações Java.

Permite criar assinaturas recorrentes, cobranças, solicitações de pagamentos, webhooks, bem como gerenciar outros dados da API.

É possível enviar requisições customizadas utilizando nosso cliente, que adiciona todas as informações necessárias, como informações de autenticação e realiza a decodificação das respostas em formato JSON.

Utilizando o nosso paginador integrado, é fácil criar paginações para listagem de dados, com métodos que seguem os padrões do Java. É suportado em todos os endpoints de listagem de dados.

[JavaDoc](https://www.jetbrains.com/help/idea/working-with-code-documentation.html) estão em todas as classes e métodos para facilitar a utilização de nosso SDK pelo seu editor favorito, como Visual Studio Code por exemplo.

O SDK é mantido oficialmente pela woovi e distribuído pelo [Maven Central](https://search.maven.org/).

O código está disponível no [repositório do GitHub](https://github.com/Open-Pix/java-sdk).

---

## Manipulação de erros

Ao utilizar o SDK de Node, espera-se que a integração seja robusta. Sendo assim, é fundamental lidar com possíveis imprevistos da API ou do transporte de dados na forma de [_exceptions_](https://nodejs.org/api/errors.html).

Quando a API retorna um erro, uma exception é lançada, onde é apresentado os erros da api.
A Sdk foi construida de forma que, caso um erro seja obtido, a requisição é tentada novamente outras 2 vezes afim de minimizar erros falsos antes da exceção ser lançada.

É considerado erro todas as respostas de api em que status seja de uma faixa diferente de 200.

Veja como você pode capturar todos os possíveis erros do SDK:

```js
import { createClient } from "./dist";

const woovi = createClient({ appId: "seu-app-id" });

try {
    woovi.transfer.create({fromPixKey: "pix-1", toPixKey: "pix-2", value: 100});
} catch (e) {
    console.log(e); //espera-se um objeto semelhante a: { error: "string" }
}
```

---

## Como configurar o sdk para acessar o ambiente sandbox/teste?

Para configurar o sdk para utilizar os endpoints de sandbox basta alterar a contante que guarda a url base.

## Como alterar a url base

Para alterar siga os seguintes passos:
* acesse o arquivo que guarda as constantes do sdk: [src/utils/constants/index.ts](https://github.com/woovibr/woovi-nodejs-sdk/blob/1d32edf47fb5634adb6ff7bbb7ea4db15d80cc0a/src/utils/constants/index.ts)
* procure pela constante `API_BASE_URL` que se encontra no inicio do arquivo
```TS
import type { BinaryToTextEncoding } from "node:crypto";

export const API_BASE_URL = "https://api.woovi.com" as const; //<- aqui se encontra a constante
export const API_RETRIES = 1 as const;
export const API_RETRIE_DELAY = 1000 as const;

export const SDK_VERSION: string = "1.0.0";

//... resto do arquivo
```

* agora basta alterar para `https://api.woovi-sandbox.com"`
* pronto o sdk agora ira sempre chamar os endpoints de sandbox

OBS: para voltar a chamar o endpoint de produção basta refazer o processo inserindo `https://api.woovi.com"`

---

## Recursos(Node)

## Conta

Chame o método `account` seu cliente da API para obter o recurso de contas.

[Documentação do endpoint para mais detalhes](/api#tag/account).

### Pegar uma conta

Chame o método `get` no recurso de contas passando um accountId:

[Documentação do endpoint para mais detalhes](/api#tag/account/GET/api/v1/account/{accountId}).

```js
const response = await woovi.account.get({ accountId: 'algum-id' });
```

### Obter uma lista de contas

Obtenha as contas usando o método `list` no recurso de contas:

[Documentação do endpoint para mais detalhes](/api#tag/account/GET/api/v1/account).

```js
const response = await woovi.account.list({ limit: 10, skip: 0 }); //o objeto de paginação é opcional
```

### Fazer uma retirada(withdraw)

Faça withdraw em uma conta usando do método `withdraw` no recurso de contas.

[Documentação do endpoint para mais detalhes](/api#tag/account/POST/api/v1/account/{accountId}/withdraw).

```js
const response = await woovi.account.withdraw({
  accountId: 'string',
  value: 200,
});
```

## na próxima compra de cashback

Chame o método `cashbackFidelity` seu cliente da API para obter o recurso de na próxima compra de cashback.

[Documentação do endpoint para mais detalhes](/api#tag/cashback-fidelity).

### Pegar a quantidade de cashback que um usuário tem para receber

Chame o método `get` no recurso de na próxima compra de cashback passando um taxID:

[Documentação do endpoint para mais detalhes](/api#tag/cashback-fidelity/GET/api/v1/cashback-fidelity/balance/{taxID}).

```js
const response = await woovi.cashbackFidelity.get({ taxID: 'algum-tax-id' });
```

### Criar(ou pegar) uma na próxima compra de cashback pra um cliente

Crie o recurso chamando o método `create`no recurso de na próxima compra de cashback.

[Documentação do endpoint para mais detalhes](/api#tag/cashback-fidelity/POST/api/v1/cashback-fidelity).

```js
const response = await woovi.cashbackFidelity.create({
  value: 100,
  taxID: 11111111111,
});
```

## Cobrança

Chame o método `charge` seu cliente da API para obter o recurso de cobrança.

[Documentação do endpoint para mais detalhes](/api#tag/charge).

### Pegar uma cobrança

Chame o método `get` no recurso de cobranças passando um id:

[Documentação do endpoint para mais detalhes](/api#tag/charge/DELETE/api/v1/charge/{id}).

```js
const response = await woovi.charge.get({ id: 'algum-id' });
```

### Obter uma lista de cobranças

Obtenha as cobranças usando o método `list` no recurso de cobranças:

[Documentação do endpoint para mais detalhes](/api#tag/charge/GET/api/v1/charge/{id}).

```js
const response = await woovi.charge.list({ limit: 10, skip: 0 }); //o objeto de paginação é opcional
```

### Crie uma cobrança

Crie uma cobrança usando o método `create` no recurso de cobranças:

[Documentação do endpoint para mais detalhes](/api#tag/charge/GET/api/v1/charge).

```js
const response = await woovi.charge.create({
  correlationID: '9134e286-6f71-427a-bf00-241681624587',
  value: 100,
  comment: 'good',
  customer: {
    name: 'Dan',
    taxID: '31324227036',
    email: 'email0@example.com',
    phone: '5511999999999',
  },
  additionalInfo: [
    {
      key: 'Product',
      value: 'Pencil',
    },
    {
      key: 'Invoice',
      value: '18476',
    },
    {
      key: 'Order',
      value: '302',
    },
  ],
});
```

### Pegar imagem de um qr code de uma cobrança

Obtenha o qr code de uma cobrança usando o método `getQrCode` no recurso de cobranças:

[Documentação do endpoint para mais detalhes](/api#tag/charge/GET/openpix/charge/brcode/image/{id}.png).

```js
const response = await woovi.charge.getQrCode({ size: '768' });
```

### Deletar uma cobrança

Delete uma cobrança usando o método `delete` no recurso de cobranças:

[Documentação do endpoint para mais detalhes](/api#tag/charge/DELETE/api/v1/charge/{id}).

```js
const response = await woovi.charge.delete({ id: 'algum-id' });
```

## Estorno de Cobrança

Chame o método `chargeRefund` seu cliente da API para obter o recurso de estorno de uma cobrança.

[Documentação do endpoint para mais detalhes](/api#tag/charge-refund).

### Obter uma lista de estorno cobranças

Obtenha os estornos de cobrança usando o método `list` no recurso de estorno de cobrança:

[Documentação do endpoint para mais detalhes](/api#tag/charge-refund/GET/api/v1/charge/{id}/refund).

```js
const response = await woovi.chargeRefund.list({ limit: 10, skip: 0 }); //o objeto de paginação é opcional
```

### Crie uma cobrança

Crie um estorno de cobrança usando o método `create` no recurso de estorno cobranças:

[Documentação do endpoint para mais detalhes](/api#tag/charge/GET/api/v1/charge).

```js
const response = await woovi.chargeRefund.create({
  id: 'algum-id',
  correlationID: 'a273e72c-9547-4c75-a213-3b0a2735b8d5',
  value: 100,
  comment: 'Comentário do reembolso',
});
```

## Cliente

Chame o método `customer` seu cliente da API para obter o recurso de cliente.

[Documentação do endpoint para mais detalhes](/api#tag/customer).

### Pegar uma cliente

Chame o método `get` no recurso de clientes passando um id:

[Documentação do endpoint para mais detalhes](/api#tag/customer/GET/api/v1/customer/{id}).

```js
const response = await woovi.customer.get({ id: 'algum-id' });
```

### Obter uma lista de clientes

Obtenha os clientes usando o método `list` no recurso de clientes:

[Documentação do endpoint para mais detalhes](/api#tag/customer/GET/api/v1/customer).

```js
const response = await woovi.customer.list({ limit: 10, skip: 0 }); //o objeto de paginação é opcional
```

### Crie uma cliente

Crie uma cliente usando o método `create` no recurso de clientes:

[Documentação do endpoint para mais detalhes](/api#tag/customer/POST/api/v1/customer).

```js
const response = await woovi.customer.create({
  name: 'Dan',
  taxID: '31324227036',
  email: 'email0@example.com',
  phone: '5511999999999',
  correlationID: '9134e286-6f71-427a-bf00-241681624586',
  address: {
    zipcode: '30421322',
    street: 'Street',
    number: '100',
    neighborhood: 'Neighborhood',
    city: 'Belo Horizonte',
    state: 'MG',
    complement: 'APTO',
    country: 'BR',
  },
});
```

### Fazer update num cliente

Faça um update em um cliente usando o método `update` no recurso de clientes.

[Documentação do endpoint para mais detalhes](/api#tag/customer/POST/api/v1/customer).

```js
const response = await woovi.customer.update({
  correlationID: 'some id',
  name: 'Dan',
  email: 'email0@example.com',
  phone: '5511999999999',
  address: {
    zipcode: '30421322',
    street: 'Street',
    number: '100',
    neighborhood: 'Neighborhood',
    city: 'Belo Horizonte',
    state: 'MG',
    complement: 'APTO',
    country: 'BR',
  },
});
```

## Parceiros

Chame o método `partner` seu cliente da API para obter o recurso de parceiros.

[Documentação do endpoint para mais detalhes](</api#tag/partner-request-access>).

### Pegar um pré-registro de parceiro

Chame o método `getPreRegistration` no recurso de parceiros passando um taxID:

[Documentação do endpoint para mais detalhes](</api#tag/partner-request-access/GET/api/v1/partner/company/{taxID}>).

```js
const response = await woovi.partner.getPreRegistration({
  taxID: 'algum-tax-id',
});
```

### Obter todos os pré-registros

Obtenha os pré-registros de parceiros usando o método `list` no recurso de parceiros:

[Documentação do endpoint para mais detalhes](</api#tag/partner-request-access/GET/api/v1/partner/company>).

```js
const response = await woovi.partner.list({ limit: 10, skip: 0 }); //o objeto de paginação é opcional
```

### Crie um parceiro

Crie uma parceiro usando o método `create` no recurso de parceiros:

[Documentação do endpoint para mais detalhes](</api#tag/partner-request-access/POST/api/v1/partner/company>).

```js
const response = await woovi.partner.create({
  preRegistration: {
    name: 'Example LLC',
    taxID: {
      taxID: '11111111111111',
      type: 'BR:CNPJ',
    },
    website: 'examplellc.com',
  },
  user: {
    firstName: 'John',
    lastName: 'Doe',
    email: 'johndoe@examplellc.com',
    phone: '+5511912345678',
  },
});
```

### Criar uma aplicação para algum de seus pré-registros

Para criar uma aplicação, use o método `createApplication` no recurso de parceiros.

[Documentação do endpoint para mais detalhes](</api#tag/partner-request-access/POST/api/v1/partner/application>).

```js
const response = await woovi.partner.createApplication({
  application: {
    name: 'MyAPIAccess',
    type: 'API',
  },
  taxID: {
    taxID: '65914571000187',
    type: 'BR:CNPJ',
  },
});
```

## Pagamento

Chame o método `payment` seu cliente da API para obter o recurso de pagamentos.

[Documentação do endpoint para mais detalhes](</api#tag/partner-request-access)/>).

### Aprove um pagamento

Chame o método `approve` no recurso de pagamentos passando um correlationID:

[Documentação do endpoint para mais detalhes](</api#tag/payment-request-access/POST/api/v1/payment/approve>).

```js
const response = await woovi.payment.approve({
  correlationID: 'algum-correlation-id',
});
```

### Obter um pagamento

Obtenha um pagamento usando o método `get` no recurso de pagamentos:

[Documentação do endpoint para mais detalhes](</api#tag/payment-request-access/GET/api/v1/payment/{id}>).

```js
const response = await woovi.payment.get({ id: 'algum-id' });
```

### Obter uma lista de pagamentos

Obtenha uma lista de pagamentos usando o método `list` no recurso de pagamentos.

[Documentação do endpoint para mais detalhes](</api#tag/payment-request-access/GET/api/v1/payment>).

```js
const response = await woovi.payment.list({ limit: 10, skip: 0 }); //o objeto de paginação é opcional
```

### Criar uma requisição de pagamento

Para criar uma requisição de pagamento, use o método `create` no recurso de payment.

[Documentação do endpoint para mais detalhes](</api#tag/payment-request-access/POST/api/v1/payment>).

```js
const response = await woovi.payment.create({
  value: 100,
  destinationAlias: 'c4249323-b4ca-43f2-8139-8232aab09b93',
  destinationAliasType: 'RANDOM',
  comment: 'payment comment',
  correlationID: 'payment1',
  sourceAccountId: 'my-source-account-id',
});
```

## Pegar um Qr Code

Chame o método `pixQrCode` seu cliente da API para obter o recurso de qr code.

[Documentação do endpoint para mais detalhes](/api#tag/pixqrcode).

### Obter um qr code

Obtenha um qr code usando o método `get` no recurso de qr code:

[Documentação do endpoint para mais detalhes](/api#tag/pixqrcode/GET/api/v1/qrcode-static/{id}).

```js
const response = await woovi.pixQrCode.get({ id: 'algum-id' });
```

### Obter uma lista de pagamentos

Obtenha uma lista de qr codes usando o método `list` no recurso de qr code.

[Documentação do endpoint para mais detalhes](/api#tag/pixqrcode/GET/api/v1/qrcode-static).

```js
const response = await woovi.pixQrCode.list({ limit: 10, skip: 0 }); //o objeto de paginação é opcional
```

### Criar um qr code estático.

Para criar um qr code estático, use o método `create` no recurso de qr code.

[Documentação do endpoint para mais detalhes](/api#tag/pixqrcode/POST/api/v1/qrcode-static).

```js
const response = await woovi.pixQrCode.create({
  name: 'my-qr-code',
  correlationID: '9134e286-6f71-427a-bf00-241681624586',
  value: 100,
  comment: 'good',
});
```

## Estorno

Chame o método `refund` seu cliente da API para obter o recurso de estorno.

[Documentação do endpoint para mais detalhes](/api#tag/refund).

### Obter um estorno

Obtenha um estorno usando o método `get` no recurso de estorno:

[Documentação do endpoint para mais detalhes](/api#tag/refund/GET/api/v1/refund/{id}).

```js
const response = await woovi.refund.get({ id: 'algum-id' });
```

### Obter uma lista de estornos

Obtenha uma lista de estornos usando o método `list` no recurso de estorno.

[Documentação do endpoint para mais detalhes](/api#tag/refund/GET/api/v1/refund).

```js
const response = await woovi.refund.list({ limit: 10, skip: 0 }); //o objeto de paginação é opcional
```

### Criar um novo estorno

Para criar um estorno, use o método `create` no recurso de estorno.

[Documentação do endpoint para mais detalhes](/api#tag/refund/POST/api/v1/refund).

```js
const response = await woovi.refund.create({
  transactionEndToEndId: '9134e286-6f71-427a-bf00-241681624586',
  correlationID: '9134e286-6f71-427a-bf00-241681624586',
  value: 100,
  comment: 'Comentário do reembolso',
});
```

## Assinatura

Chame o método `subscription` seu cliente da API para obter o recurso de assinatura.

[Documentação do endpoint para mais detalhes](/api#tag/subscription).

### Obter uma assinaturas

Obtenha uma assinatura de estornos usando o método `get` no recurso de assinatura.

[Documentação do endpoint para mais detalhes](/api#tag/subscription/GET/api/v1/subscriptions/{id}).

```js
const response = await woovi.subscription.get({ id: 'algum-id' });
```

### Criar uma assinatura

Para criar uma assinatura, use o método `create` no recurso de assinatura.

[Documentação do endpoint para mais detalhes](/api#tag/subscription/POST/api/v1/subscriptions).

```js
const response = await woovi.subscriptions.create({
  value: 100,
  customer: {
    name: 'Dan',
    taxID: '31324227036',
    email: 'email0@example.com',
    phone: '5511999999999',
  },
  dayGenerateCharge: 15,
});
```

## Transações

Chame o método `transactions` seu cliente da API para obter o recurso de transações.

[Documentação do endpoint para mais detalhes](/api#tag/transactions).

### Obter uma transação

Obtenha uma transação usando o método `get` no recurso de transações.

[Documentação do endpoint para mais detalhes](/api#tag/transactions/GET/api/v1/transaction/{id}).

```js
const response = await woovi.transactions.get({ id: 'algum-id' });
```

### Obter uma lista de transações

Obtenha uma lista de transações usando o método `list` no recurso de transação.

[Documentação do endpoint para mais detalhes](/api#tag/transactions/GET/api/v1/transaction).

```js
const response = await woovi.transactions.list({
  pagination: { limit: 10, skip: 0 },
  query: {},
}); //o objeto de paginação e parametros de query é opcional
```

## Transferencias

Chame o método `transfer` seu cliente da API para obter o recurso de transferencia.

[Documentação do endpoint para mais detalhes](</api#tag/transfer-request-access)>).

### Criar uma transferencia

Para criar uma transferencia, use o método `create` no recurso de transferencias.

[Documentação do endpoint para mais detalhes](</api#tag/transfer-request-access/POST/api/v1/transfer>).

```js
const response = await woovi.transfer.create({
  value: 100,
  fromPixKey: 'from@woovi.com.br',
  toPixKey: 'to@woovi.com.br',
});
```

## Webhooks

Chame o método `webhook` seu cliente da API para obter o recurso de webhook.

[Documentação do endpoint para mais detalhes](/api#tag/webhook).

### Deletar um webhook

Delete um webhook usando o método `delete` no recurso de webhooks.

[Documentação do endpoint para mais detalhes](/api#tag/webhook/DELETE/api/v1/webhook/{id}).

```js
const response = await woovi.webhook.delete({ id: 'algum-id' });
```

### Obter uma lista de webhooks

Obtenha uma lista de webhooks usando o método `list` no recurso de webhook.

[Documentação do endpoint para mais detalhes](/api#tag/webhook/GET/api/v1/webhook).

```js
const response = await woovi.webhook.list({
  pagination: { limit: 10, skip: 0 },
  query: {},
}); //o objeto de paginação e query são opcionais
```

### Criar um novo webhook

Para criar um webhook, use o método `create` no recurso de webhook.

[Documentação do endpoint para mais detalhes](/api#tag/webhook/POST/api/v1/webhook).

```js
const response = await woovi.webhook.create({
  webhook: {
    name: 'webhookName',
    event: 'OPENPIX:CHARGE_CREATED',
    url: 'https://mycompany.com.br/webhook',
    authorization: 'woovi',
    isActive: true,
  },
});
```

### Handler HTTP

O método webhook conta com um recurso especial chamado handle, ótimo para ser usado para validar recursos diretamente na sua api. Veja a seguir como ultiliza-lo:

```js
import { createClient } from '@woovi/node-sdk';

const woovi = createClient({ appId: 'seu-app-id' });

const handler = woovi.webhook.handler({
  onChargeCompleted: async (payload) => {},
  onChargeExpired: async (payload) => {},
});

export const POST = handler.POST;
```

Post recebe sua requisição.

Isso permite com que você possa validar um webhook em uma api que você pode construir.

## Subcontas

Chame o método `subAccount` seu cliente da API para obter o recurso de subcontas.

[Documentação do endpoint para mais detalhes](</api#tag/subaccount)>).

### Pegar detalhes de uma subcontas

Para pegar detalhes de uma subconta, use o metodo `get`no recurso de subcontas.

[Documentação do endpoint para mais detalhes](</api#tag/subaccount/GET/api/v1/subaccount/{id}>).

```js
const response = await woovi.subAccount.get({ id: 'algum-id' });
```

### Listar subcontas

Obtenha uma lista de subcontas usando o método `list` no recurso de subcontas.

[Documentação do endpoint para mais detalhes](</api#tag/subaccount/GET/api/v1/subaccount>).

```js
const response = await woovi.subAccount.list({ limit: 10, skip: 0 }); //o objeto de paginação é opcional
```

### Criar uma nova subconta

Para criar um subconta, use o método `create` no recurso de subconta.

[Documentação do endpoint para mais detalhes](</api#tag/subaccount/POST/api/v1/subaccount>).

```js
const response = await woovi.subAccount.create({
  pixKey: '9134e286-6f71-427a-bf00-241681624587',
  name: 'Test Account',
});
```

### Fazer uma retirada(withdraw)

Faça withdraw em uma subconta usando do método `withdraw` no recurso de subcontas.

[Documentação do endpoint para mais detalhes](</api#tag/subaccount/POST/api/v1/subaccount/{id}/withdraw>).

```js
const response = await woovi.subAccount.withdraw({ id: 'pix-key' });
```

---

## Como começar(Node)

## Instalando

Preferencialmente, recomendamos o NodeJs em sua versão LTS (latest).

Execute o comando abaixo que instala as dependências necessárias com o npm:

```bash
$ npm install @woovi/node-sdk
```

Dessa forma, o SDK será instalado.

## Criando o cliente

O ponto de entrada do SDK é um `createClient` para o serviço.

CommonJs:
```js
const WooviSdk = require("@woovi/node-sdk");

// Para inicializar
const woovi = WooviSdk.createClient({appId: "seu-app-id"});
```

Ts/Module:
```ts 
import { createClient } from "@woovi/node-sdk"

// Para inicializar
const woovi = createClient({appId: "seu-app-id"})
```

O método `createClient` cria um novo cliente a partir de um ID de aplicativo obtido no [site da woovi](https://app.woovi.com.br/home/applications/tab/list).

## Chamando a API

Um cliente possui _recursos_ (por exemplo: clientes, cobranças, assinaturas, etc.) que podem ser acessados através de `createClient`.

```js
woovi.customer
```

Cada recurso irá ter um conjunto de métodos que podem serem executados para realizarem operações:

```js
const client = woovi.customer.create({}); //lembre-se de passar o payload de criação de cliente
```

## Operações em recursos

Em cada recurso, há uma convenção nos nomes das operações, na qual, em sua maioria, se resumem em:

- `get`: Obter apenas um recurso. Associado ao verbo HTTP `GET`.
- `list`: Obter vários recursos, de forma paginada. Associado ao verbo HTTP `GET`.
- `create`: Criar um recurso. Associado ao verbo HTTP `POST`.
- `delete`: Remover um recurso. Associado ao verbo HTTP `DELETE`.

### Formato das entradas

No caso de operações de listagem, normalmente se aceita um objeto com um uma chave opcional de paginação.

```js
woovi.refund.list({ skip: 0, limit: 20 })
```

### Formato de saída

A execução de uma operação irá devolver resultados da API na forma de um array direto ou na forma de um paginador, caso este seja aplicado ao metodo usado.

## Tipagem

Em cada operação disponível para um determinado tipo de recurso, existem tipagens disponíveis direto na resposta, informando o formato de entrada e saída da operação com um link para a documentação da API Rest e exemplo de utilização.

Para utilizar, é sugerido utilizar um editor com Intellisense como [Visual Studio Code](https://code.visualstudio.com/).

Também é possível consultar a documentação no site da woovi caso haja dúvidas.

## Recursos disponíveis

Os seguintes recursos estão disponíveis no `Client` gerado:

- `woovi.account`: Operações em uma conta.
- `woovi.cashback`: Operações em cashback.
- `woovi.charge`: Operações em uma carga de pagamento.
- `woovi.chargeRefund`: Operações em em extorno de uma carga.
- `woovi.customer`: Operações em clientes.
- `woovi.partner`: Operações em parceiros.
- `woovi.pixQrCode`: Operações em codigos qr relacionados a pix.
- `woovi.refund`: Operações em extorno.
- `woovi.subAccount`: Operações em sub contas.
- `woovi.subscription`: Operações em inscrições.
- `woovi.transactions`: Operações em transações.
- `woovi.transfer`: Operações em transferencias.
- `woovi.webhook`: Operações em webhook.

# Webhook

O método webhook conta com um recurso especial chamado handle, ótimo para ser usado para validar recursos diretamente na sua api. Veja a seguir como ultiliza-lo:

```js
import { createClient } from "@woovi/node-sdk";

const woovi = createClient({ appId: "seu-app-id" });

const handler = woovi.webhook.handler({
  onChargeCompleted: async (payload) => {},
  onChargeExpired: async (payload) => {},
});

export const POST = handler.POST;
```

Post recebe sua requisição.

## Dependências
O projeto não ultiliza de dependencias externas para seu funcionamento.

---

## O que é o SDK de Node?

O SDK de Node é um kit de ferramentas criado com o objetivo de integrar facilmente os serviços da woovi em suas aplicações construidas em NodeJs.

Permite criar assinaturas recorrentes, cobranças, solicitações de pagamentos, webhooks, bem como gerenciar outros dados da API.

É possível enviar requisições customizadas utilizando nosso cliente, que adiciona todas as informações necessárias, como informações de autenticação e realiza a decodificação das respostas em formato JSON.

Utilizando o nosso paginador integrado, é fácil criar paginações para listagem de dados. É suportado em todos os endpoints de listagem de dados.

O SDK é mantido oficialmente pela woovi e distribuído pelo [Npm](https://www.npmjs.com/).

O código está num [repositório do GitHub](https://github.com/woovibr/woovi-nodejs-sdk).

---

## Requisições HTTP customizadas

O SDK permite que seja enviado requisições customizadas para um cliente HTTP possivelmente customizado.

## Como criar requisições

Requisições do SDK são representadas pela classe `woovi\PhpSdk\Request` que permite configurar o caminho do endpoint, corpo, parâmetros de consulta (query parameters) e de paginação e o método HTTP através de uma interface "fluente".

Veja como utilizar:

```php
use woovi\PhpSdk\Request;

/**
 * Se a URI base for https://api.woovi.com, então a requisição terá
 *  - A URI como https://api.woovi.com/api/v1/example-endpoint?query1=10&query2=true
 *  - Método POST, para criar um recurso, por exemplo
 *  - Corpo como um array que irá ser convertido para uma string JSON
 */
$request = (new Request)
    ->method("POST") // Métodos HTTP como GET, POST, PUT e DELETE.
    ->path("/api/v1/example-endpoint") // Caminho
    ->queryParams(["query1" => 10, "query2" => true]) // Parâmetros de consulta
    ->body([
        "dado1" => "",
        "dado2" => "",
    ]); // Corpo
```

## Como enviar requisições

Para enviar requisições, utilize o objeto do tipo `woovi\PhpSdk\RequestTransport` para enviar a requisição. Este objeto pode ser obtido no cliente da API.

Este objeto tem um método `transport` que transporta requisições e decodifica a resposta JSON, retornando um array associativo.

```php
$requestTransport = $client->getRequestTransport();

/** @var array<string, mixed> $result */
$result = $requestTransport->transport($request);
```

Também adiciona cabeçalhos como `Authorization` para autenticação e `Content-type` para especificar o tipo do corpo da requisição.

## Como customizar o cliente HTTP

É possível escolher qual _cliente HTTP_ utilizar apenas instalando a dependência do cliente no Composer e o cliente será automaticamente descoberto pelo [HTTPlug](http://httplug.io/), junto com as fábricas de mensagem do [PSR-17](https://www.php-fig.org/psr/psr-17/).

Caso seja necessário utilizar instâncias de fábrica de mensagem ou cliente HTTP já existentes, crie uma instância personalizada de `RequestTransport`:

```php
use woovi\PhpSdk\RequestTransport;

$requestTransport = new RequestTransport(
    // Seu app ID
    $appId,

    // URI base (por ex.: https://api.woovi.com)
    // Somente o protocolo e o domínio são permitidos na URI base.
    // Não coloque caminhos como /api/v1
    $baseUri,

    // Um objeto que implementa a interface \Psr\Http\Client\ClientInterface (PSR-18)
    // Opcional.
    $httpClient,

    // Um objeto que implementa a interface \Psr\Http\Message\RequestFactoryInterface (PSR-17)
    // Opcional.
    $requestFactory,

    // Um objeto que implementa a interface \Psr\Http\Message\StreamFactoryInterface (PSR-17)
    // Opcional.
    $streamFactory,
);
```

Com o `RequestTransport` personalizado criado, passe para o construtor de `woovi\PhpSdk\Client`:

```php
use woovi\PhpSdk\Client;

$client = new Client($requestTransport);
```

## Customizando a URI base

É possível customizar a URI base do cliente da API para enviar requisições para outras APIs. Isto permite escolher entre a API da woovi ou Woovi, por exemplo.

O método `create` aceita uma URI base no segundo parâmetro:

```php
Client::create("seu appid", "https://api.woovi.com");
Client::create("seu appid", "https://api.woovi.com");
```

---

## Manipulação de erros(Php)

Ao utilizar o SDK de PHP, espera-se que a integração seja robusta; sendo assim, é fundamental lidar com possíveis imprevistos da API ou do transporte de dados na forma de [_exceptions_](https://www.php.net/manual/en/language.exceptions.php).

Quando a API retorna um erro, uma exception do tipo `\woovi\PhpSdk\ApiErrorException` é lançada.

Caso ocorra algum erro no transporte dos dados, o cliente HTTP utilizado irá lançar uma exceção que _estende_ `\Psr\Http\Client\ClientExceptionInterface` de acordo com a [PSR-18](https://www.php-fig.org/psr/psr-18/#clientexceptioninterface).

A mensagem de erro de uma possível exceção pode ser obtida pelo método  [`getMessage`](https://www.php.net/manual/pt_BR/exception.getmessage.php).

Veja como você pode capturar todos os possíveis erros do SDK:

```php
use woovi\PhpSdk\ApiErrorException;
use Psr\Http\Client\ClientExceptionInterface;

try {
    $charge = [
        "value" => 100, // R$ 100,00
        "correlationID" => "anothercorrelationid-" . strval(time()),
    ];

  /** @var \woovi\PhpSdk\Client $client */
    $result = $client->charges()->create($charge);
} catch (ApiErrorException|ClientExceptionInterface $e) {
    // Lida com os erros relacionados ao SDK.
    echo "Ocorreu um erro durante a criação da cobrança: " . $e->getMessage() . "<br>\n";
}
```

---

## Exemplos de integração

Veja alguns exemplos de integrações com o SDK de PHP:

## PHP puro

Preparamos um exemplo de utilização com o SDK de PHP no repositório [Open-Pix/php-backend-integration](https://github.com/Open-Pix/php-backend-integration).

Consiste numa API simples para realizar doações.

Demonstramos como você pode criar uma cobrança, lidar com webhooks, instalar o SDK e mais.

O código encontra-se em um formato simples e contém uma quantidade significativa de comentários, a fim de facilitar o seu entendimento.

### Como você pode executar

Faça o clone do repositório: `git clone https://github.com/Open-Pix/php-backend-integration.git`.

Entre no diretório do repositório: `cd php-backend-integration`.

Copie o arquivo `env.example.php` para `env.php` e configure seu AppID da woovi.

Caso tenha o [Docker Compose](https://docs.docker.com/compose/install/) instalado, execute o seguinte comando:
```bash
docker-compose up
```

Tendo o [Composer](https://getcomposer.org) e o PHP `>=8.1.0` instalados diretamente em sua máquina, execute o comando `./start-server.sh`.

A partir desse momento, a API estará rodando em http://0.0.0.0:8080 por padrão.

Para tornar as coisas ainda mais convenientes, adicionamos um arquivo [`postman.json`](https://github.com/Open-Pix/php-backend-integration/blob/main/postman.json) ao repositório, o qual contém uma coleção de _endpoints_ do [Postman](https://www.postman.com/).

## OpenCart v3

Nossa extensão oficial para o OpenCart v3 utiliza nosso SDK em PHP para criar cobranças, validar webhooks e realizar outras funções.

Veja o código-fonte dela no [GitHub](https://github.com/Open-Pix/opencart3-woovi).

Para saber mais sobre essa extensão, consulte a nossa [documentação](../../ecommerce/opencart/opencart3-extension).

## Laravel

Produzimos um simples aplicativo web de doações que demonstra o fluxo do SDK de PHP, como criação de cobranças, atualização em tempo real dos status das doações via webhooks, instalação e configuração do SDK de PHP e mais.

Veja em nosso repositório como foi feita a integração: https://github.com/Open-Pix/laravel-backend-integration

---

## Começando sua integração woovi com Laravel

Temos um exemplo de integração com o SDK de PHP e Laravel preparado para você em nosso repositório do GitHub: [https://github.com/Open-Pix/laravel-backend-integration](https://github.com/Open-Pix/laravel-backend-integration)

Mostra o fluxo do SDK de PHP em ação, incluindo a criação de cobranças, a atualização dos status das doações em tempo real por meio de webhooks, bem como a instalação e configuração do SDK de PHP, e muito mais.

## Instalação

### Pré-requisitos

- Tenha um [App ID](/docs/plugin/app-id) em sua conta woovi.
- Ter Docker ou Composer e MySQL instalados.

### Laravel Sail / Docker (maneira recomendada)

Nossa aplicação de exemplo dispõe de uma configuração do [Laravel Sail](https://laravel.com/docs/10.x/sail), a qual está disponível para proporcionar uma interface perfeitamente integrada com o Docker em suas aplicações Laravel.

Siga as etapas abaixo para usar o Docker via Sail:

- Tenha o [Docker Compose](https://docs.docker.com/compose/install/) instalado.
- Clone o repositório: `git clone https://github.com/Open-Pix/laravel-backend-integration`
- Vá para o diretório do repositório: `cd laravel-backend-integration`
- [Instale as dependências do Composer utilizando Docker](https://laravel.com/docs/10.x/sail#installing-composer-dependencies-for-existente-projects):

  ```bash
  docker run --rm \
     -u "$(id -u):$(id -g)" \
     -v "$(pwd):/var/www/html" \
     -w /var/www/html \
     laravelsail/php82-composer:latest \
     composer install --ignore-platform-reqs
  ```

- Copie `.env.example` para `.env`: `cp .env.example .env`
- Configure seu AppID no arquivo `.env`.
- Inicie os serviços (servidor, banco de dados e etc.): `./vendor/bin/sail up -d`.
- Gere uma chave de criptografia: `./vendor/bin/sail art key:generate`
- Execute as migrações do banco de dados: `./vendor/bin/sail art migrate`.
- [Certifique-se de que as alterações no arquivo `.env` tenham efeito limpando o cache:](https://laravel.com/docs/10.x/configuration#configuration-caching): `php artisan config:clear`.

### Composer

Tendo o [Composer](https://getcomposer.org) e o PHP `>=8.2.0` instalados diretamente em sua máquina, siga os passos:

- Clone o repositório: `git clone https://github.com/Open-Pix/laravel-backend-integration`
- Vá para o diretório do repositório: `cd laravel-backend-integration`
- Instale as dependências do Composer: `composer install`
- Copie `.env.example` para `.env`: `cp .env.example .env`
- Gere uma chave de criptografia: `php artisan key:generate`
- Execute as migrações do banco de dados: `php artisan migrate`
- Inicie o servidor: `php artisan serve`
- Configure seu AppID no arquivo `.env`.
- [Certifique-se de que as alterações no arquivo `.env` tenham efeito limpando o cache:](https://laravel.com/docs/10.x/configuration#configuration-caching): `php artisan config:clear`.

## Acessando o exemplo

Por padrão, a aplicação web é executada na URL [http://0.0.0.0](http://0.0.0.0).

## Visualização de logs

Os logs deste exemplo de integração estarão na pasta de armazenamento de logs do Laravel, sendo por padrão `storage/logs`.

Saiba mais na [documentação do Laravel](https://laravel.com/docs/10.x/logging).

## Solução de problemas

Preparamos um guia para você com possíveis soluções para problemas. [Saiba mais](./troubleshooting.md).

---

## Começando sua integração woovi com Laravel(Laravel)

[Laravel](https://laravel.com/) é um poderoso framework em PHP com uma sintaxe elegante e expressiva, que permite avançar rapidamente em suas soluções, sem se preocupar com detalhes pequenos.

A [woovi](https://woovi.com) vai além de uma plataforma: é um portal para o futuro dos negócios. Nesse espaço, você não só recebe pagamentos via Pix, mas também mergulha em oportunidades para encantar clientes, aumentar vendas e reinventar a gestão financeira do seu negócio. Com a woovi, você não apenas vende; você **transcende**.

Unindo a força do Laravel à woovi, você não apenas **aumentará suas vendas**, mas também se moverá de forma **rápida**.

## Instalando o SDK de PHP em seu projeto Laravel

O SDK PHP foi criado com o propósito de simplificar a integração dos serviços da woovi às suas aplicações em PHP, assegurando uma integração suave e eficiente. Essa é a abordagem **ideal** para implementar a woovi em seus projetos do Laravel.

Comece garantindo que você tenha instalado um cliente HTTP e uma implementação PSR-17:

```bash
composer require guzzlehttp/guzzle guzzlehttp/psr7
```

Após esse passo, prossiga instalando nosso SDK:

```bash
composer require open-pix/php-sdk
```

## Configurando o SDK de PHP

### Autenticação

É necessário você possuir um AppID para autenticação.

É possível criar acessando a [plataforma](https://app.woovi.com/home/applications/add) na página de criar uma nova API/Plugin.

### Armazenando as configurações

Agora que você tem um AppID, é necessário armazená-lo de forma segura dentro da sua aplicação, evitando compartilhá-lo nos sistemas de controle de versão.

O local ideal para armazenar configurações da API seria em seu arquivo `.env`. [Saiba mais](https://laravel.com/docs/10.x/configuration#environment-configuration) na documentação do Laravel.

Esse arquivo é utilizado para armazenar configurações e não é enviado para seu sistema de controle de versão, como o Git.

Adicione essas duas configurações em seu arquivo `.env`:
```bash
woovi_APP_ID="COLOQUE SEU APP ID AQUI"
woovi_BASE_URI="https://api.woovi.com"
```

Após esse passo, limpe o [cache de configurações](https://laravel.com/docs/10.x/configuration#configuration-caching):
```bash
php artisan config:clear
```

### Registrando o SDK

Iremos registrar o SDK no [contêiner de serviços](https://laravel.com/docs/10.x/container) do Laravel utilizando [service providers](https://laravel.com/docs/10.x/providers).

De forma simplificada, o contêiner de serviços é responsável por gerenciar os objetos de serviço da aplicação, enquanto um provedor de serviço (_service provider_) tem a responsabilidade de registrar um objeto nesse contêiner.

Ao registrar o SDK no contêiner, você poderá [utilizá-lo em qualquer parte](https://laravel.com/docs/10.x/container#resolving) da sua aplicação com facilidade, sem a necessidade de instanciá-lo repetidamente.

Para criar o provedor de serviço `wooviServiceProvider`, execute o [comando abaixo](https://laravel.com/docs/10.x/providers#writing-service-providers):

```bash
php artisan make:provider wooviServiceProvider
```

Altere o método register para que possa efetuar o registro do cliente no contêiner, utilizando como referência o provedor de serviço abaixo:

```php
<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use woovi\PhpSdk\Client;

class wooviServiceProvider extends ServiceProvider
{
    /**
     * Register services.
     */
    public function register(): void
    {
        $this->app->singleton(Client::class, function () {
            $appId = env('woovi_APP_ID');
            $baseUri = env('woovi_BASE_URI', 'https://api.woovi.com');

            return Client::create($appId, $baseUri);
        });
    }
}
```

Após criar o provedor de serviços, é necessário [registrá-lo](https://laravel.com/docs/10.x/providers#registering-providers), adicionando-o ao arquivo de configuração `config/app.php`:

```php
    // ...
    'providers' => ServiceProvider::defaultProviders()->merge([
        // ...

        /*
         * Application Service Providers...
         */

        // ...
        App\Providers\wooviServiceProvider::class,
    ])->toArray(),
    // ...
```

Não se esqueça de limpar o cache de configuração, já que você fez uma atualização nas configurações:

```bash
php artisan config:clear
```

## Como utilizar o SDK

Após ter realizado o registro do SDK no contêiner, utilizar nossa API nos controller, classes de serviço, rotas, entre outros, torna-se uma tarefa bastante simples. Explore as diversas possibilidades disponíveis na [documentação do Laravel](https://laravel.com/docs/10.x/container#resolving).

Por exemplo, para utilizar a nossa API em um controller, siga o exemplo abaixo:

```php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use woovi\PhpSdk\Client;

class DonationController extends Controller
{
    public function __construct(private Client $woovi)
    {}

    public function create()
    {
        $this->woovi->charges()->create([
            // Cria uma cobrança de 1 centavo.
            "value" => 1,
        ]);
    }
}
```

Nesse exemplo, estamos utilizando a funcionalidade de [injeção automática](https://laravel.com/docs/10.x/container#automatic-injection) do Laravel.

## Exemplo de integração

Temos disponível um exemplo de integração Laravel que irá te auxiliar na utilização do Laravel. [Saiba mais](./example-integration.md).

---

## Renderizando o QR Code de uma cobrança Pix no Laravel

Para renderizar o QR Code de uma cobrança Pix em uma página da sua aplicação Laravel, acesse o template Blade que irá exibir a cobrança.

Após isso, crie um elemento com o ID `woovi-order` que irá renderizar a cobrança Pix.

```blade
<div id="woovi-order"></div>
```

É necessário carregar um script que renderizará a cobrança Pix:

```blade
<script src="https://plugin.woovi.com.br/v1/woovi.js?appID={{ $appID }}&correlationID={{ $correlationID }}"></script>
```

Nesse template Blade, é necessário passar as seguintes variáveis:
- `correlationID`: O [correlationID](../../../../concepts/correlation-id.md) específico da cobrança.
- `appID`: Seu código de autenticação utilizado durante a criação da cobrança.

---

## Como receber webhooks em sua aplicação Laravel

## Webhooks

Webhooks permitem que uma aplicação ou serviço envie automaticamente informações ou dados para outra aplicação ou serviço sempre que um evento específico ocorre.

A API da woovi, por exemplo, pode enviar um webhook para a sua aplicação sempre que uma cobrança for paga ou cancelada, possibilitando que sua aplicação seja notificada em **tempo real** sobre essas mudanças de status.

## Como receber webhooks

Vamos seguir os seguintes passos:

### Criar a rota

Para receber os webhooks, é fundamental estabelecer um endpoint dedicado ao processamento de todas as notificações.

No contexto do Laravel, você pode criar uma nova rota, como por exemplo `/woovi/webhook`, no arquivo `routes/web.php`:

```php
use App\Http\Controllers\woovi\WebhookController;

Route::post('/woovi/webhook', [WebhookController::class, 'receive']);
```

A seguir, você pode configurar o controller responsável pelo tratamento desses webhooks:

```php
<?php

// ./app/Http/Controllers/woovi/WebhookController.php

namespace App\Http\Controllers\woovi;

use App\Models\Donation;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use woovi\PhpSdk\Client;

class WebhookController extends Controller
{
    const SIGNATURE_HEADER = "x-webhook-signature";

    const woovi_CHARGE_COMPLETED_EVENT = "OPENPIX:CHARGE_COMPLETED";

    public function __construct(private Client $woovi)
    {
    }

    /**
     * Recebe todos os webhooks enviados pela plataforma.
     */
    public function receive(Request $request)
    {
      // ...
    }
}
```

### Como desabilitar a verificação CSRF

O CSRF no Laravel é uma medida de segurança que protege contra ataques nos quais um invasor tenta forçar um usuário autenticado a executar ações não autorizadas.

Todas as requisições `POST` devem conter um token CSRF para garantir que a ação tenha sido autorizada, inclusive para o endpoint de webhook.

Para evitar erros de CSRF, é necessário desabilitar essa verificação, adicionando o caminho da rota dos webhooks, como `/woovi/webhook`, no array `$except` do arquivo `./app/Http/Middleware/VerifyCsrfToken.php`. Por exemplo:

```php
<?php

namespace App\Http\Middleware;

use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken as Middleware;

class VerifyCsrfToken extends Middleware
{
    /**
     * The URIs that should be excluded from CSRF verification.
     *
     * @var array<int, string>
     */
    protected $except = [
        "/woovi/webhook", // Coloque aqui o caminho para a sua rota
    ];
}
```

Não se preocupe, pois isso será substituído pela verificação da assinatura dos webhooks.

### Validando a assinatura

Adicione esse método em seu controller:

```php
/**
 * Permite requisições somente a partir da woovi.
 * 
 * Caso ocorra algum erro, irá retornar uma `Response`
 * que indica um erro na validação. Ocorrendo nenhum erro,
 * irá retornar apenas `null`.
 */
private function allowRequestOnlyFromwoovi(Request $request)
{
    $rawPayload = $request->getContent();

    // self::SIGNATURE_HEADER = "x-webhook-signature"
    $signature = $request->header(self::SIGNATURE_HEADER);

    $isWebhookValid = ! empty($rawPayload)
        && ! empty($signature)
        && $this->woovi->webhooks()->isWebhookValid($rawPayload, $signature);

    if ($isWebhookValid) return null;

    return response()->json([
        "errors" => [
            [
                "message" => "Invalid webhook signature."
            ],
        ],
    ], 400);
}
```

Chamando esse método irá garantir que somente a woovi tenha webhooks processados pela sua aplicação através da [validação da assinatura de webhooks utilizando o SDK de PHP](../../resources.md#validar-um-webhook).

Veja um exemplo de chamada desse método no método `receive`:

```php
/**
 * Recebe todos os webhooks enviados pela plataforma.
 */
public function receive(Request $request)
{
  // Se retornar uma resposta, então devolvemos para
  // o cliente da requisição, que nesse caso irá ser um erro.
  if ($response = $this->allowRequestOnlyFromwoovi($request)) return $response;

  // Continuamos com o processamento...
  return $this->handleWebhook($request);
}
```

### Recebendo os dados de um webhook

É possível receber os parâmetros da requisição de webhook utilizando o método [`input`](https://laravel.com/docs/10.x/requests#retrieving-an-input-value) de uma `Request` do Laravel. Veja um exemplo:

```php
// Obtém o parâmetro `event` da requisição.
$event = $request->input("event");
```

### Validando os eventos recebidos

Durante o processamento dos webhooks, é possível validar seus tipos e encaminhá-los para métodos mais especializados, de acordo com o tipo de webhook, por exemplo.

Cada requisição irá trazer consigo um parâmetro `event` contendo o tipo do webhook. Veja algumas possibilidades de valores:

- `OPENPIX:CHARGE_CREATED` - Nova cobrança criada.
- `OPENPIX:CHARGE_COMPLETED` - Cobrança concluída é quando uma cobrança é totalmente paga.
- `OPENPIX:CHARGE_EXPIRED` - Cobrança expirada é quando uma cobrança não foi totalmente paga e expirou.
- `OPENPIX:TRANSACTION_RECEIVED` - Nova transação PIX recebida.
- `OPENPIX:TRANSACTION_REFUND_RECEIVED` - Novo reembolso de transação PIX recebido ou reembolsado.
- `OPENPIX:MOVEMENT_CONFIRMED` - Pagamento confirmado é quando a transação do pix referente ao pagamento é confirmada.
- `OPENPIX:MOVEMENT_FAILED` - Falha no pagamento é quando o pagamento é aprovado e ocorre um erro.
- `OPENPIX:MOVEMENT_REMOVED` - O pagamento foi removido por um usuário.

Assumindo que você tenha um método `handleWebhook` que recebe todos os webhooks com a assinatura validada, veja o exemplo:

```php
/**
 * Dispara o método apropriado de acordo com o tipo
 * validado do webhook.
 */
private function handleWebhook(Request $request)
{
    // Valida se o webhook é de quando uma cobrança foi paga
    // utilizando o método `isChargePaidPayload`.
    if ($this->isChargePaidPayload($request)) {
        // Dispara o método `handleChargePaidWebhook`
        // quando uma cobrança for paga.
        return $this->handleChargePaidWebhook($request);
    }

    // Valida se o webhook é de teste utilizando
    // o método `isTestPayload`.
    if ($this->isTestPayload($request)) {
        // Dispara o método `handleTestWebhook` se for um webhook de teste.
        return $this->handleTestWebhook();
    }

    return response()->json([
        "errors" => [
            [
                "message" => "Invalid webhook type.",
            ],
        ]
    ], 400);
}
```

Utilizamos o parâmetro `event` para diferenciar diante os outros tipos de webhooks:

```php
/**
 * Verifica se é o webhook de quando uma cobrança foi paga.
 */
private function isChargePaidPayload(Request $request)
{
    $event = $request->input("event");

    $allowedEvents = [
        // Indicam quais eventos são considerados como
        // uma cobrança sendo paga.

        // "OPENPIX:CHARGE_COMPLETED"
        self::woovi_CHARGE_COMPLETED_EVENT,
        
        // "OPENPIX:TRANSACTION_RECEIVED"
        self::woovi_TRANSACTION_RECEIVED_EVENT,
    ];

    $isChargePaidEvent = ! empty($event) && in_array($event, $allowedEvents);

    return $isChargePaidEvent
        && ! empty($request->input("charge.correlationID"));
}
```

### Webhook de teste

Ao configurar uma nova integração via webhooks na plataforma, ela enviará um webhook de teste para verificar se tudo está correto com sua aplicação.

Esse webhook de teste será enviado com o campo `event` contendo o valor especificado pelo evento selecionado na plataforma. 
Por exemplo, se você selecionar o evento `Cobrança paga`, o campo `event` será `OPENPIX:CHARGE_COMPLETED`.

Veja como é possível verificar se um webhook é de teste:

```php
/**
 * Verifica se o webhook é do tipo de teste.
 *
 * A plataforma da woovi envia um webhook de teste
 * para validar se o receptor de webhooks está funcionando.
 */
private function isTestPayload(Request $request)
{
    $event = $request->input("event");

    return ! empty($event) && $event === self::woovi_CHARGE_COMPLETED_EVENT;
}
```

Veja um exemplo de processamento desse webhook:

```php
/**
 * Processa o webhook de teste enviado pela plataforma.
 */
private function handleTestWebhook()
{
    return response()->json(["message" => "Success."]);
}
```

### Processando um webhook

Neste exemplo abaixo, você pode ver como receber uma notificação de que uma cobrança foi paga na woovi e atualizar o status de uma doação para 'paga'.

```php
/**
 * Ativado quando uma cobrança foi paga.
 */
public function handleChargePaidWebhook(Request $request)
{
    // Obtemos o correlationID do webhook utilizando o método `input`
    // de uma `$request`.
    // Um identificador único que relaciona uma cobrança Pix com uma doação.
    $correlationID = $request->input("charge.correlationID");

    // Encontra a doação a partir do correlationID da cobrança.
    $donation = Donation::where("correlationID", $correlationID)->first();

    // Verifica se essa doação existe.
    if (empty($donation)) {
        return response()->json([
            "errors" => [
                [
                    "message" => "Donation not found.",
                ],
            ],
        ], 404);
    }

    // Atualiza o status da doação para paga.
    $donation->status = "PAID";
    $donation->save();

    // Retorna uma resposta 200 para a plataforma woovi.
    return response()->json(["message" => "Success."]);
}
```

## Exemplo de integração com webhooks

Temos um exemplo completo do controller que recebe webhooks [nesse arquivo](https://github.com/Open-Pix/laravel-backend-integration/blob/623baa803e501c5bbd75f19ad43a3b61e205c534/app/Http/Controllers/WebhookController.php).

Veja mais exemplos de integração com Laravel em [nosso repositório](https://github.com/Open-Pix/laravel-backend-integration).

---

## Solução de problemas

Veja sobre os possíveis problemas que podem ocorrer ao utilizar nossa integração com o Laravel:

## `cURL error 60: SSL certificate problem: unable to get local issuer certificate`

Esse erro ocorre quando o certificado SSL está ausente ou inválido, principalmente ao acessar um servidor local de desenvolvimento ou um servidor com configurações de segurança inadequadas.

Para resolver:

1. Baixe o último certificado em https://curl.haxx.se/ca/cacert.pem
2. Adicione essa configuração em seu arquivo `php.ini`: `curl.cainfo="/caminho/para/o/arquivo/cacert.pem"`
3. Reinicie o servidor se necessário.

Veja alguns links que podem ser úteis:

- https://stackoverflow.com/questions/24611640/curl-60-ssl-certificate-problem-unable-to-get-local-issuer-certificate
- https://github.com/guzzle/guzzle/issues/1935#issuecomment-371756738

---

## Recursos(Php)

## Clientes

Chame o método `customers` seu cliente da API para obter o recurso de clientes.

[Documentação do endpoint para mais detalhes](/api#tag/customer).

### Criar um cliente

Chame o método `create` no recurso de clientes passando um array com os dados do cliente:

[Documentação do endpoint para mais detalhes](/api#tag/customer/POST/api/v1/customer).

```php
$customer = [
    "name" => "Dan",
    "taxID" => generateCPF(),
    "email" => "email0@example.com",
    "phone" => "5511999999999",
    "correlationID" => "test-php-sdk-" . generateUUID(),
];

$result = $client->customers()->create($customer);

/**
 * Exemplo de resultado:
 *
 * $result = [
 *     "customer" => [
 *         "name" => "Dan",
 *         "email" => "email0@example.com",
 *         "phone" => "+5511999999999",
 *         "correlationID" => "test-php-sdk-be734fd4-ce4f-4f37-853b-cac3e73ed223",
 *         "taxID" => [
 *           "taxID" => "0000000000",
 *           "type" => "BR:CPF",
 *         ],
 *     ],
 * ];
 */
```

### Obter um cliente

Obtenha um cliente por um ID chamando `getOne` no recurso de clientes:

[Documentação do endpoint para mais detalhes](/api#tag/customer/GET/api/v1/customer).

```php
$result = $client->customers()->getOne("test-php-sdk-8e7e3622-b209-46ef-b353-ec568e893177");

/**
 * Exemplo de resultado:
 *
 * $result = [
 *   "status" => "OK",
 *   "customer" => [
 *       "name" => "Dan",
 *       "email" => "email0@example.com",
 *       "phone" => "+5511999999999",
 *       "correlationID" => "test-php-sdk-8e7e3622-b209-46ef-b353-ec568e893177",
 *       "taxID" => [
 *           "taxID" => "00000000000",
 *           "type" => "BR:CPF",
 *       ],
 *   ],
 * ];
 */
```

### Listar clientes

Liste clientes chamando o método `list` no recurso de clientes, que retorna um paginador:

[Documentação do endpoint para mais detalhes](/api#tag/customer/GET/api/v1/customer).

```php
$paginator = $client->customers()->list();

$remainingCustomers = 10;

foreach ($paginator as $result) {
    foreach ($result["customers"] as $customer) {
        echo $customer["taxID"]["taxID"]; // CPF do Cliente

        $remainingCustomers--;

        if ($remainingCustomers == 0) break 2;
    }
}
```

## Cobranças

O recurso de cobranças é acessado chamando o método `charges` no cliente da API.

[Documentação do endpoint para mais detalhes](/api#tag/charge).

### Criar uma cobrança

Chame o método `create` no recurso de cobranças:

[Documentação do endpoint para mais detalhes](/api#tag/charge/POST/api/v1/charge).

```php
$customer = [
    "name" => "Dan",
    "taxID" => generateCPF(),
    "email" => "email0@example.com",
    "phone" => "5511999999999",
    "correlationID" => "test-php-sdk-" . generateUUID(),
];

$client->customers()->create($customer); // Criar o cliente.

$charge = [
    "value" => 1000, // R$ 10,00
    "correlationID" => "test-php-sdk-charge-" . generateUUID(),
    "customer" => $customer, // Especificar o cliente.
];

/**
 * Torne o endpoint idempotente, retornará uma cobrança existente
 * se já tiver uma com o correlationID.
 */
$returnExisting = true;

$result = $client->charges()->create($charge, $returnExisting);

/**
 * Exemplo de resultado:
 *
 * $result = [
 *     "charge" => [
 *         "status" => "ACTIVE",
 *         "customer" => [
 *             "name" => "Dan",
 *             "email" => "email0@example.com",
 *             "phone" => "5511999999999",
 *             "taxID" => [
 *                 "taxID" => "00000000000",
 *                 "type" => "BR:CPF",
 *             ],
 *         ],
 *         "value" => 100,
 *         "comment" => "good",
 *         "correlationID" => "test-php-sdk-charge-9134e286-6f71-427a-bf00-241681624586",
 *         "paymentLinkID" => "7777a23s-6f71-427a-bf00-241681624586",
 *         "paymentLinkUrl" => "https://woovi.com.br/pay/9134e286-6f71-427a-bf00-241681624586",
 *         "qrCodeImage" => "https://api.woovi.com.br/woovi/charge/brcode/image/9134e286-6f71-427a-bf00-241681624586.png",
 *         "expiresIn" => 2592000,
 *         "expiresDate" => "2021-04-01T17:28:51.882Z",
 *         "createdAt" => "2021-03-02T17:28:51.882Z",
 *         "updatedAt" => "2021-03-02T17:28:51.882Z",
 *         "brCode" => "000201010212261060014br.gov.bcb.pix2584https://api.woovi.com.br/woovi/testing?transactionID=867ba5173c734202ac659721306b38c952040000530398654040.015802BR5909LOCALHOST6009Sao Paulo62360532867ba5173c734202ac659721306b38c963044BCA",
 *         "additionalInfo" => [],
 *     ],
 * ];
 */
```

### Obter uma cobrança

Chame o método `getOne` no recurso de cobranças:

[Documentação do endpoint para mais detalhes](/api#tag/charge/GET/api/v1/charge).

```php
$result = $client->charges()->getOne("coloque o ID da cobrança aqui");

$result["charge"]["value"]; // Valor da cobrança.
$result["charge"]["customer"]; // Cliente. Array.

// e mais campos...
```

### Listar cobranças

Chame o método `list` no recurso de cobranças:

[Documentação do endpoint para mais detalhes](/api#tag/charge/GET/api/v1/charge).

```php
$paginator = $client->charges()->list([
    // Data de início usada na consulta. Em conformidade com RFC 3339. Opcional.
    // Exemplo: 2023-01-01T00:00:00Z
    "start" => (new DateTimeImmutable("2023-01-01", new DateTimeZone("UTC")))->format(DateTime::RFC3339),

    // Data de término usada na consulta. Em conformidade com RFC 3339. Opcional.
    // Exemplo: 2023-12-01T00:00:00Z
    "end" => (new DateTimeImmutable("2023-12-01", new DateTimeZone("UTC")))->format(DateTime::RFC3339),

    // Status da cobrança. Opcional.
    // Pode ser: "ACTIVE", "COMPLETED" ou "EXPIRED".
    "status" => "EXPIRED",
]);

$remainingCharges = 10;

foreach ($paginator as $result) {
    foreach ($result["charges"] as $charge) {
        echo $charge["value"] . "\n";

        $remainingCharges--;

        if ($remainingCharges == 0) break 2;
    }
}
```

### Remover uma cobrança

Para remover uma cobrança, chame o método `delete` no recurso de cobranças, passando o ID:

[Documentação do endpoint para mais detalhes](/api#tag/charge/DELETE/api/v1/charge/{id}).

```php
$client->charges()->delete("id da cobrança");
```

### Obtenha uma imagem do Qr Code de uma cobrança

Para obter o link de uma imagem do Qr Code de uma cobrança, chame `getQrCodeImageLink`, que retornará uma string e aceita o ID do link de pagamento da cobrança (`paymentLinkID`) com um tamanho da imagem (`size`):

[Documentação do endpoint para mais detalhes](/api#tag/charge/GET/openpix/charge/brcode/image/{id}.png).

```php
$paymentLinkID = "7777-6f71-427a-bf00-241681624586"; // ID do link de pagamento da cobrança.
$size = 1024; // Tamanho da imagem.

$result = $client->charges()->getQrCodeImageLink($paymentLinkID, $size);

/**
 * Exemplo de resultado:
 *
 * $result = "https://api.woovi.com.br/woovi/charge/brcode/image/7777-6f71-427a-bf00-241681624586.png?size=1024";
 */
```

## Assinaturas

O recurso de assinaturas é acessado chamando o método `subscriptions` no cliente da API.

[Documentação do endpoint para mais detalhes](/api#tag/subscription).

```php
$client->subscriptions();
```

### Criar uma assinatura

Crie uma assinatura chamando o método `create` no recurso de assinaturas:

[Documentação do endpoint para mais detalhes](/api#tag/subscription/POST/api/v1/subscriptions).

```php
$customer = [
    "name" => "Dan (php-sdk)",
    "taxID" => generateCPF(), // CPF
    "email" => "php-sdk0@example.com",
    "phone" => "5511999999999",
    "correlationID" => "test-php-sdk-" . generateUUID(),
];

// Criar o cliente da assinatura.
$client->customers()->create($customer);

$subscription = [
    "value" => 1000, // Valor da assinatura em centavos. (R$ 10,00)
    "customer" => $customer, // Especificar o cliente da assinatura.

    // Dia do mês em que as cobranças serão geradas. Máximo de 27.
    // Padrão é 5.
    "dayGenerateCharge" => 5,
];

$result = $client->subscriptions()->create($subscription);

/**
 * Exemplo de resultado:
 *
 * $result = [
 *     "subscription" => [
 *         "globalID" => "UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=",
 *         "customer" => [
 *             "name" => "Dan (php-sdk)",
 *             "email" => "php-sdk0@example.com",
 *             "phone" => "5511999999999",
 *             "taxID" => [
 *                 "taxID" => "00000000000",
 *                 "type" => "BR:CPF",
 *             ],
 *         ],
 *         "value" => 1000,
 *         "dayGenerateCharge" => 5,
 *     ],
 * ];
 */
```

### Obter uma assinatura

Obtenha uma assinatura chamando o método `getOne` no recurso de assinaturas passando o ID:

[Documentação do endpoint para mais detalhes](/api#tag/subscription/GET/api/v1/subscriptions).

```php
$result = $client->subscriptions()->getOne("ID da assinatura");

/**
 * Exemplo de resultado:
 *
 * $result = [
 *     "subscription" => [
 *         "globalID" => "UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=",
 *         "customer" => [
 *             "name" => "Dan",
 *             "email" => "email0@example.com",
 *             "phone" => "5511999999999",
 *             "taxID" => [
 *                 "taxID" => "31324227036",
 *                 "type" => "BR:CPF",
 *             ],
 *         ],
 *         "value" => 100,
 *         "dayGenerateCharge" => 5,
 *     ],
 * ];
 */
```

## Transações

O recurso de transações é acessado chamando o método `transactions` no cliente da API.

[Documentação do endpoint para mais detalhes](/api#tag/transactions).

```php
$client->transactions();
```

### Obtendo uma transação

Para obter uma transação pelo ID da transação do woovi ou pelo `endToEndId` da transação do banco, é necessário chamar o método `getOne` no recurso de transações, passando o respectivo ID:

[Documentação do endpoint para mais detalhes](/api#tag/transactions/GET/api/v1/transaction/{id}).

```php
$client->transactions()->getOne("ID da transação");

/**
 * Exemplo de resultado:
 *
 * $result = [
 *     "transaction" => [
 *         "customer" => [
 *             "name" => "Dan",
 *             "email" => "email0@example.com",
 *             "phone" => "5511999999999",
 *             "taxID" => [
 *                 "taxID" => "31324227036",
 *                 "type" => "BR:CPF",
 *             ],
 *             "correlationID" => "9134e286-6f71-427a-bf00-241681624586",
 *         ],
 *         "payer" => [
 *             "name" => "Dan",
 *             "email" => "email0@example.com",
 *             "phone" => "5511999999999",
 *             "taxID" => [
 *                 "taxID" => "31324227036",
 *                 "type" => "BR:CPF",
 *             ],
 *             "correlationID" => "9134e286-6f71-427a-bf00-241681624586",
 *         ],
 *         "charge" => [
 *             "status" => "ACTIVE",
 *             "customer" => "603f81fcc6bccc24326ffb43",
 *             "correlationID" => "9134e286-6f71-427a-bf00-241681624586",
 *             "createdAt" => "2021-03-03T12:33:00.546Z",
 *             "updatedAt" => "2021-03-03T12:33:00.546Z",
 *         ],
 *         "withdraw" => [
 *             "value" => 100,
 *             "time" => "2021-03-03T12:33:00.536Z",
 *             "infoPagador" => "payer info 1",
 *             "endToEndId" => "E18236120202012032010s01345689XBY",
 *             "createdAt" => "2021-03-03T12:33:00.546Z",
 *         ],
 *         "infoPagador" => "payer info 0",
 *         "value" => 100,
 *         "time" => "2021-03-03T12:33:00.536Z",
 *         "transactionID" => "transactionID",
 *         "type" => "PAYMENT",
 *         "endToEndId" => "E18236120202012032010s0133872GZA",
 *         "globalID" => "UGl4VHJhbnNhY3Rpb246NzE5MWYxYjAyMDQ2YmY1ZjUzZGNmYTBi",
 *     ],
 * ];
 */
```

### Listar transações

Chame o método `list` no recurso de transações passando parâmetros de consulta que irá retornar um paginador com transações:

[Documentação do endpoint para mais detalhes](/api#tag/transactions/GET/api/v1/transaction).

```php
$paginator = $client->transactions()->list([
    // Data de início usada na consulta. Em conformidade com RFC 3339. Opcional.
    // Exemplo: 2023-01-01T00:00:00Z
    "start" => (new DateTimeImmutable("2023-01-01", new DateTimeZone("UTC")))->format(DateTime::RFC3339),

    // Data de término usada na consulta. Em conformidade com RFC 3339. Opcional.
    // Exemplo: 2023-12-01T00:00:00Z
    "end" => (new DateTimeImmutable("2023-12-01", new DateTimeZone("UTC")))->format(DateTime::RFC3339),

    // Você pode utilizar o ID de cobrança, o correlationID ou o ID de transação de cobrança
    // para obter uma lista de transações relacionadas a esta transação.
    "charge" => "id aqui",

    // Você pode usar o ID estático do QrCode, o correlationID ou o campo `identifier` do
    // QrCode estático para obter uma lista de QrCode relacionados a esta transação.
    "pixQrCode" => "id aqui",

    // Você pode usar o ID ou `endToEndId` de uma transação de retirada
    // para obter todas as transações relacionadas à retirada.
    "withdrawal" => "id aqui",
]);

$remainingTransactions = 10;

foreach ($paginator as $result) {
    foreach ($result["transactions"] as $transaction) {
        echo $transaction["value"] . "\n"; // Valor da transação.
        // e mais campos...

        $remainingTransactions--;

        if ($remainingTransactions == 0) break 2;
    }
}
```

## Pagamentos

O recurso de pagamentos é acessado chamando o método `payments` no cliente da API.

[Documentação do endpoint para mais detalhes](/api#tag/payment-request-access).

```php
$client->payments();
```

### Criar pagamento

Crie uma solicitação de pagamento chamando o método `create` no recurso de pagamentos.

Documentação do endpoint para mais detalhes.

```php
$payment = [
    // Valor do pagamento solicitado em centavos.
    "value" => 100,

    // A chave pix onde pagamento deve ser enviado.
    "destinationAlias" => "c4249323-b4ca-43f2-8139-8232aab09b93",

    // O comentário que será enviado juntamente com o seu pagamento.
    "comment" => "comentário",

    // Um identificador exclusivo para o seu pagamento.
    "correlationID" => "payment1",

    // Um id opcional para a conta de origem do pagamento, caso não informado assumirá a conta padrão.
    "sourceAccountId" => "my-source-account-id",
];

$result = $client->payments()->create($payment);

/**
 * Exemplo de resultado:
 *
 * $result = [
 *    "payment" => [
 *        "value" => 100,
 *        "status" => "CREATED",
 *        "destinationAlias" => "c4249323-b4ca-43f2-8139-8232aab09b93",
 *        "comment" => "payment comment",
 *        "correlationID" => "payment1",
 *        "sourceAccountId" => "my-source-account-id",
 *    ],
 *  ],
 * ];
 */
```

### Obtendo um pagamento

Chame o método `getOne` no recurso de pagamentos para obter uma solicitação de pagamento a partir de um ID de pagamento ou correlationID.

Documentação do endpoint para mais detalhes.

```php
$paymentOrCorrelationID = "id";

$result = $client->payments()->getOne($paymentOrCorrelationID);

/**
 * Exemplo de resultado.
 *
 * $result = [
 *     "payment" => [
 *         "value" => 100,
 *         "status" => "CONFIRMED",
 *         "destinationAlias" => "c4249323-b4ca-43f2-8139-8232aab09b93",
 *         "comment" => "payment comment",
 *         "correlationID" => "payment1",
 *         "sourceAccountId" => "my-source-account-id",
 *     ],
 *     "transaction" => [
 *         "value" => 100,
 *         "endToEndId" => "transaction-end-to-end-id",
 *         "time" => "2023-03-20T13:14:17.000Z",
 *     ],
 *     "destination" => [
 *         "name" => "Dan",
 *         "taxID" => "31324227036",
 *         "pixKey" => "c4249323-b4ca-43f2-8139-8232aab09b93",
 *         "bank" => "A Bank",
 *         "branch" => "1",
 *         "account" => "123456",
 *     ],
 * ];
 */
```

### Listar pagamentos

Chame o método `list` no recurso de pagamentos passando parâmetros de consulta que irá retornar um paginador com pagamentos:

Documentação do endpoint para mais detalhes.

```php
$paginator = $client->payments()->list();

$remainingPayments = 10;

foreach ($paginator as $result) {
    foreach ($result["payments"] as $payment) {
        echo $payment["payment"]["value"] . "\n"; // Valor do pagamento

        // A chave pix onde o pagamento deve ser enviado
        echo $payment["payment"]["destinationAlias"] . "\n";

        // correlationID para acompanhar este pagamento
        echo $payment["payment"]["correlationID"] . "\n";

        // e mais campos...

        $remainingPayments--;

        if ($remainingPayments == 0) break 2;
    }
}
```

## Refunds

O recurso de reembolsos é acessado chamando o método `refunds` no cliente da API.

[Documentação do endpoint para mais detalhes](/api#tag/refund).

```php
$client->refunds();
```

### Criar um reembolso

Crie um reembolso chamando o método `create` no recurso de reembolsos:

[Documentação do endpoint para mais detalhes](/api#tag/refund/POST/api/v1/refund).

```php
$refund = [
    // Seu ID de transação, ou ID `endToEnd`, para acompanhar este reembolso
    "transactionEndToEndId" => "9134e286-6f71-427a-bf00-241681624586",

    // Seu correlationID, identificador exclusivo para o reembolso
    "correlationID" => "9134e286-6f71-427a-bf00-241681624586",

    "value" => 100,

    // Comentário deste reembolso. Comprimento máximo de 140 caracteres
    "comment" => "Comentário do reembolso",
];

$result = $client->refunds()->create($refund);

/**
 * Exemplo de resultado:
 *
 * $result = [
 *     "refund" => [
 *         "status" => "IN_PROCESSING",
 *         "value" => 100,
 *         "correlationID" => "9134e286-6f71-427a-bf00-241681624586",
 *         "refundId" => "9134e2866f71427abf00241681624586",
 *         "time" => "2021-03-02T17:28:51.882Z",
 *         "comment" => "Comentário do reembolso",
 *     ],
 * ];
 */
```

### Obter um reembolso

Para obter um reembolso pelo ID de reembolso ou correlationID, chame o método `getOne`:

[Documentação do endpoint para mais detalhes](/api#tag/refund/GET/api/v1/refund/{id}).

```php
$result = $client->refunds()->getOne("Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA==");

/**
 * Exemplo de resultado:
 *
 * $result = [
 *     "pixTransactionRefund" => [
 *         "value" => 100,
 *         "correlationID" => "7777-6f71-427a-bf00-241681624586",
 *         "refundId" => "11bf5b37e0b842e08dcfdc8c4aefc000",
 *         "returnIdentification" => "D09089356202108032000a543e325902",
 *         "comment" => "Comentário do reembolso",
 *     ],
 * ];
 */
```

### Listar reembolsos

Chame o método `list` no recurso de reembolsos que irá retornar um paginador com reembolsos:

[Documentação do endpoint para mais detalhes](/api#tag/refund/GET/api/v1/refund).

```php
$paginator = $client->refunds()->list();

$remainingRefunds = 10;

foreach ($paginator as $result) {
    foreach ($result["refunds"] as $key => $refund) {
        echo $refund["value"] . "\n";

        // Hora do reembolso
        echo $refund["time"] . "\n";

        // Pode ser "IN_PROCESSING", "REFUNDED" ou "NOT_ACCOMPLISHED".
        echo $refund["status"] . "\n";

        // correlationID para acompanhar este reembolso
        echo $refund["correlationID"] . "\n";

        echo $refund["refundId"] . "\n";
        echo $refund["returnIdentification"] . "\n";

        $remainingRefunds--;

        echo "-------------------------\n";

        if ($remainingRefunds == 0) break 2;
    }
}
```

## Webhooks

O recurso de webhooks é acessado chamando o método `webhooks` no cliente da API.

[Documentação do endpoint para mais detalhes](/api#tag/webhook).

```php
$client->webhooks();
```

### Criar um webhook

Crie um webhook chamando o método `create` no recurso de webhooks:

[Documentação do endpoint para mais detalhes](/api#tag/webhook/POST/api/v1/webhook).

```php
$webhook = [
    "webhook" => [
        "name" => "webhookName (php-sdk)",

        // Eventos disponíveis para registrar um webhook para ouvir. Se ninguém selecionar ninguém, o evento padrão será OPENPIX:TRANSACTION_RECEIVED.
        // OPENPIX:CHARGE_CREATED - Nova cobrança criada.
        // OPENPIX:CHARGE_COMPLETED - Cobrança concluída é quando uma cobrança é totalmente paga.
        // OPENPIX:CHARGE_EXPIRED - Cobrança expirada é quando uma cobrança não foi totalmente paga e expirou.
        // OPENPIX:TRANSACTION_RECEIVED - Nova transação PIX recebida.
        // OPENPIX:TRANSACTION_REFUND_RECEIVED - Novo reembolso de transação PIX recebido ou reembolsado.
        // OPENPIX:MOVEMENT_CONFIRMED - Pagamento confirmado é quando a transação do pix referente ao pagamento é confirmada.
        // OPENPIX:MOVEMENT_FAILED - Falha no pagamento é quando o pagamento é aprovado e ocorre um erro.
        // OPENPIX:MOVEMENT_REMOVED - O pagamento foi removido por um usuário.
        "event" => "OPENPIX:CHARGE_CREATED",

        "url" => "https://example.com",
        "authorization" => "woovi-php-sdk",
        "isActive" => true,
    ],
];

$result = $client->webhooks()->create($webhook);

/**
 * Exemplo de resultado:
 *
 * $result = [
 *     "webhook" => [
 *         "id" => "V2ViaG9vazo2MDNlYmUxZWRlYjkzNWU4NmQyMmNmMTg=",
 *         "name" => "webhookName",
 *         "url" => "https://mycompany.com.br/webhook",
 *         "authorization" => "woovi",
 *         "isActive" => true,
 *         "event" => "OPENPIX:TRANSACTION_RECEIVED",
 *         "createdAt" => "2021-03-02T22:29:10.720Z",
 *         "updatedAt" => "2021-03-02T22:29:10.720Z",
 *     ],
 * ];
 */
```

### Como receber um webhook

Quando ocorre um evento na API, como uma cobrança sendo paga, uma requisição é enviada para a URL configurada durante a criação do webhook. Essa requisição conterá um [_payload_](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Messages#corpo) (dados) em formato JSON, juntamente com um cabeçalho que precisa ser [validado](#validar-um-webhook).

Para validar o webhook, é necessário ter a _exata_ string original do payload, o que pode ser realizado utilizando a função [`file_get_contents`](https://www.php.net/manual/pt_BR/function.file-get-contents.php) em conjunto com o _stream_ (fluxo) de entrada [`php://input`](https://www.php.net/manual/pt_BR/wrappers.php.php):

```php
// Obtém uma string "crua" contendo o payload enviado.
$rawPayload = file_get_contents("php://input");
```

Também é possível utilizar um método específico do seu framework para obter a string do payload. Por exemplo, no Laravel e Symfony, você pode utilizar o método [`getContent`](https://symfony.com/doc/current/components/http_foundation.html#accessing-request-data):
```php
/** @var \Symfony\Component\HttpFoundation\Request $request */
$rawPayload = $request->getContent();
```

Uma vez que o payload é obtido como uma string, é **essencial** [validar a assinatura](#validar-um-webhook).

Após validar o payload, você poderá utilizar os dados contidos nele. Para isso, basta decodificar a string JSON usando a função [`json_decode`](https://www.php.net/manual/pt_BR/function.json-decode.php) ou, se preferir, utilizar o método específico do seu framework. Abaixo, segue um exemplo de um receptor de webhooks:

```php
namespace YourIntegration\Http;

/**
 * Webhook request example handler.
 */
class WebhookHandler
{
    const woovi_CHARGE_COMPLETED = "OPENPIX:CHARGE_COMPLETED";

    /**
     * Handle an webhook request sent by API.
     */
    public function __invoke()
    {
        $rawPayload = file_get_contents("php://input", true);
        $signature = getallheaders()["x-webhook-signature"] ?? "";

        if (! $this->client->webhooks()->isWebhookValid($rawPayload, $signature)) {
            http_response_code(400);
            echo "Assinatura inválida\n";
            return;
        }

        $payload = json_decode($rawPayload, true);

        if ($payload["event"] === self::woovi_CHARGE_COMPLETED) {
            http_response_code(200);
            echo "A cobrança foi paga totalmente!\n";
            return;
        }
    }
}
```

### Listar webhooks

Chame o método `list` no recurso de webhooks que irá retornar um paginador com webhooks:

[Documentação do endpoint para mais detalhes](/api#tag/webhook/GET/api/v1/webhook).

```php
// É possível passar uma string opcional com uma URL para filtrar todos os webhooks
$paginator = $client->webhooks()->list("https://example.com");

$remainingWebhooks = 10;

foreach ($paginator as $result) {
    foreach ($result["webhooks"] as $key => $webhook) {
        echo $webhook["id"] . "\n";
        echo $webhook["name"] . "\n";
        echo $webhook["event"] . "\n"; // Quando o webhook é disparado
        echo $webhook["url"] . "\n";
        echo $webhook["isActive"] . "\n";

        // e mais campos...

        $remainingWebhooks--;

        echo "---------------------------\n";

        if ($remainingWebhooks == 0) break 2;
    }
}
```

### Remover um webhook

Para remover um webhook, chame o método `delete` no recurso de webhooks, passando o ID:

[Documentação do endpoint para mais detalhes](/api#tag/webhook/DELETE/api/v1/webhook/{id}).

```php
$client->webhooks()->delete("id do webhook");
```

### Validar um webhook

Toda invocação de webhook em sua aplicação traz um cabeçalho HTTP chamado `x-webhook-signature`, que consiste na assinatura gerada utilizando a chave secreta da Woovi e o _payload_ (corpo da requisição HTTP) do webhook. Ao receber esse cabeçalho, você pode validar se a assinatura é válida e prosseguir com o fluxo do webhook.

Exemplo do cabeçalho HTTP:

```yaml
x-webhook-signature: lL2nnXgmLFGgxJ8+jCDguqouU4ucrIxYJcU5SPrJFaNcJajTJHYVldqc/z4YFIjAjtPEALe699WosgPY08W7CLpidvtm06Qwa4YMB0l/DcTS93O91NdSH/adjugEKiOb76Zj/0jB8mqOmWCFYbweOBa17bssuEkd5Lw7Q5L314Y=
```

[Veja um payload de exemplo recebido numa invocação de um webhook](/docs/webhook/seguranca/webhook-signature-validation#exemplo-de-valida%C3%A7%C3%A3o).

Para validar a assinatura de uma chamada de webhook, utilize o método `isWebhookValid` no recurso de webhooks. Esse método retornará `true` se a assinatura fornecida junto com o payload for válida, ou `false` caso contrário.

```php
// Precisamos obter o corpo da requisição como uma string JSON
// Para isto, podemos utilizar a função `file_get_contents`.
// Exemplo de payload: '{ "charge": { "status": "COMPLETED", ... }, ... }'
$payload = file_get_contents("php://input");

// Também precisamos da assinatura
// Podemos utilizar a função `getallheaders`.
$signature = getallheaders()["x-webhook-signature"];

if ($client->webhooks()->isWebhookValid($payload, $signature)) {
    // Continue seu fluxo pro webhook...
} else {
    // Pare o fluxo do webhook, pois ele não é válido!
}
```

---

## Como começar(Php)

## Instalando

É necessário ter o PHP com versão superior à 7.4 instalado com o [Composer](https://getcomposer.org).

Execute o comando abaixo que instala as dependências necessárias com o Composer:

```bash
$ composer require open-pix/php-sdk guzzlehttp/guzzle guzzlehttp/psr7
```

Dessa forma, o SDK, um cliente HTTP (`guzzlehttp/guzzle`) e uma implementação da [PSR-17](https://www.php-fig.org/psr/psr-17/) (`guzzlehttp/psr7`) serão instalados.

## Criando o cliente

O ponto de entrada do SDK é um `Client`:

```php
use woovi\PhpSdk\Client;

// Para utilizar woovi
$client = Client::create("coloque seu appid aqui");
```

O método `create` cria um novo cliente a partir de um ID de aplicativo obtido no [site da woovi](https://app.woovi.com.br/home/applications/tab/list).

## Chamando a API

Um cliente possui _recursos_ (por exemplo: clientes, cobranças, assinaturas, etc.) que podem ser acessados através da execução de métodos no `Client`.

```php
$client->customers();
```

Cada recurso irá ter um conjunto de métodos que podem serem executados para realizarem operações:

```php
// Cria um cliente.
$dadosCliente = [
    "name" => "Dan", // Nome
    "taxID" => "31324227036", // CPF
    "email" => "email0@example.com", // E-mail
    "phone" => "5511999999999", // Telefone
    "correlationID" => "9134e286-6f71-427a-bf00-241681624586", // ID de correlação
];

$result = $client->customers()->create($dadosCliente);
```

## Operações em recursos

Em cada recurso, há uma convenção nos nomes das operações, na qual:

- `getOne`: Obter apenas um recurso. Associado ao verbo HTTP `GET`.
- `list`: Retornar um _paginador_, com o resultado da página atual podendo ser obtido executando o método `current`. Associado ao verbo HTTP `GET`.
- `create`: Criar um recurso. Associado ao verbo HTTP `POST`.
- `delete`: Remover um recurso. Associado ao verbo HTTP `DELETE`.

### Formato das entradas

No caso de operações de listagem ou de criação, os argumentos de entradas são comumente _arrays_.

```php
// Cria uma assinatura.
$assinatura = [
    "value" => 100, // Valor
    "customer" => [
        "name" => "Dan", // Nome
        "taxID" => "31324227036", // CPF
        "email" => "email0@example.com", // Email
        "phone" => "5511999999999", // Telefone
    ],
    // Dia do mês em que as cobranças serão geradas. Máximo de 27.
    "dayGenerateCharge" => 15,
];

$client->subscriptions()->create($assinatura);
```

Argumentos simples como strings e inteiros são utilizados no caso de operações de obtenção de apenas um recurso ou remoção.

```php
// Obtém uma cobrança pelo ID. string.
$client->charges()->getOne($correlationID);

// Remove uma cobrança pelo ID. string.
$client->charges()->delete($correlationID);
```

### Formato de saída

A execução de uma operação irá devolver resultados da API na forma de um array direto ou na forma de um paginador, especialmente em operações de listagem, como na listagem de transações.

```php
/**
 * Criando uma solicitação de pagamento.
 *
 * Retorna um array.
 */
$result = $client->payments()->create([
    "value" => 100,
    "destinationAlias" => "c4249323-b4ca-43f2-8139-8232aab09b93",
    "comment" => "payment comment",
    "correlationID" => "payment1",
    "sourceAccountId" => "my-source-account-id",
]);

/**
 * Resultado:
 *
 * $result = [
 *    "payment" => [
 *        "value" => 100,
 *        "status" => "CREATED",
 *        "destinationAlias" => "c4249323-b4ca-43f2-8139-8232aab09b93",
 *        "comment" => "payment comment",
 *        "correlationID" => "payment1",
 *        "sourceAccountId" => "my-source-account-id",
 *    ],
 *  ],
 * ];
 */
```

## Paginação

Em recursos em que é possível paginação, há um método `list` que retorna um objeto `Paginator`.

Um objeto `Paginator` possui métodos que auxiliam na paginação dos resultados de operações de listagem de recursos.

Este objeto implementa a interface [`Iterator`](https://www.php.net/manual/pt_BR/class.iterator.php), portanto possui métodos como `current` e `next` e pode ser utilizado em loops `foreach`.

```php
// Utilizando foreach para obter 100 clientes.
// Cuidado ao utilizar, pois pode obter todos os clientes disponíveis da API de uma só vez.

$paginator = $client->customers()->list();

$remainingCustomers = 100;

// O foreach chama o método `current`, `next` e `valid` automaticamente.
foreach ($paginator as $result) {
    foreach ($result["customers"] as $customer) {
        // Ativa delay de 200ms.
        usleep(100000);

        echo "Nome do cliente: " . $customer["name"] . "\n";

        $remainingCustomers--;

        if ($remainingCustomers == 0) break 2;
    }
}

// Utilizando loop do/while para obter 100 clientes.
$paginator = $client->customers()->list();

$remainingCustomers = 100;

do {
    // Ativa delay de 200ms.
    usleep(200000);

    // Envia a solicitação HTTP para a API e retorna o resultado como um array.
    $result = $paginator->current();

    foreach ($result["customers"] as $customer) {
        echo "Nome do cliente: " . $customer["name"] . "\n";

        $remainingCustomers--;

        if ($remainingCustomers == 0) break;
    }

    // Avança uma página
    $paginator->next();
} while ($paginator->valid() && $remainingCustomers != 0);
```

### Métodos disponíveis

Veja os métodos disponíveis em objetos `Paginator`:

**Obs.: as páginas iniciam em zero, como arrays.**

```php
// Utilizando como exemplo a listagem de clientes
$paginator = $client->customers()->list();

$paginator->key(); // Obtém o número da página atual. (pg. atual 0)
$paginator->next(); // Avança uma página. (pg. atual 1)
$paginator->previous(); // Retrocede uma página. (pg. atual 0)
$paginator->valid(); // Retorna `true` se há próxima página e `false` caso contrário.
$paginator->perPage(30); // Quantidade de itens por página.
$paginator->skip(30); // Pula 30 clientes. (pg. atual 1)
$paginator->rewind(); // Volta para a página inicial. (pg. atual 0)
$paginator->go(2); // Vai para a página 2 (pg. atual 2)
$paginator->getTotalResourcesCount(); // Obtém a quantidade *total* de clientes disponíveis na API

// Envia uma requisição para a API e retorna o array de resultado
// Aqui, irá obter o array de resultado da página 2.
$page = $paginator->current();

// Retorna o nome do primeiro cliente da página 2.
echo $page["customers"][0]["name"];
```

## PHPDocs

Em cada operação disponível para um determinado tipo de recurso, existem [PHPDocs](https://docs.phpdoc.org/guide/getting-started/what-is-a-docblock.html) disponíveis informando o formato de entrada e saída da operação com um link para a documentação da API Rest e exemplo de utilização.

Para utilizar, é sugerido utilizar um editor com Intellisense como [PhpStorm](https://www.jetbrains.com/pt-br/phpstorm/) ou [Visual Studio Code](https://code.visualstudio.com/) com a extensão [Intelephense](https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client).

Também é possível consultar a documentação no site da woovi caso haja dúvidas.

## Recursos disponíveis

Os seguintes recursos estão disponíveis no `Client`:

- `$client->customers()`: Operações em clientes.
- `$client->subscriptions()`: Operações em assinaturas.
- `$client->charges()`: Operações em cobranças.
- `$client->refunds()`: Operações em restituições.
- `$client->payments()`: Operações em solicitações de pagamentos.
- `$client->transactions()`: Operações em transações.
- `$client->webhooks()`: Operações em webhooks.

## Dependências

O SDK depende de implementações das PSRs 17 e [18](https://www.php-fig.org/psr/psr-18/).

A PSR-17 é usada para fornecer interfaces para mensagens HTTP, tanto requisições quanto respostas. Por outro lado, a PSR-18 é usada para fornecer interfaces para clientes HTTP.

Sendo interfaces, é necessário ter uma implementação instalada, como `guzzlehttp/guzzle` para a PSR-18 e `guzzlehttp/psr7` para a PSR-17.

As PSRs são utilizadas para não depender diretamente de clientes HTTP, deixado a cargo do desenvolvedor.

## Exemplos de integração

[Veja exemplos de integração com o SDK de PHP](./examples.md).

---

## O que é o SDK de PHP?

O SDK de PHP é um kit de ferramentas criado com o objetivo de integrar facilmente os serviços da woovi em suas aplicações PHP.

Para tanto, o SDK permite que utilize qualquer cliente HTTP compatível com [PSR-18](https://www.php-fig.org/psr/psr-18/), como [Guzzle](https://docs.guzzlephp.org/en/stable/) e [symfony/http-client](https://symfony.com/doc/current/http_client.html). Portanto, é possível utilizar qualquer plataforma de PHP, como Laravel, Symfony. Para integrações customizadas é possível utilizar também em ecommerces, como Magento, WooCommerce, PrestaShop e etc.

Permite criar assinaturas recorrentes, cobranças, solicitações de pagamentos, webhooks, bem como gerenciar outros dados da API.

É possível enviar requisições customizadas utilizando nosso cliente, que adiciona todas as informações necessárias, como informações de autenticação e realiza a decodificação das respostas em formato JSON.

Utilizando o nosso paginador integrado, é fácil criar paginações para listagem de dados, com métodos que seguem os padrões do PHP. É suportado em todos os endpoints de listagem de dados.

[PhpDocs](https://www.phpdoc.org/) estão em todas as classes e métodos para facilitar a utilização de nosso SDK pelo seu editor favorito, como PhpStorm e Visual Studio Code.

O SDK é mantido oficialmente pela woovi e distribuído pelo [Packagist e Composer](https://getcomposer.org/).

O código está num [repositório do GitHub](https://github.com/Open-Pix/php-sdk).

---

## Como contribuir com o SDK(Ruby)

## Contribuindo com o woovi Ruby SDK
O desenvolvimento do nosso Ruby SDK é opensource e pode ser encontrado em nosso [repositório público](https://github.com/Open-Pix/ruby-sdk). Para contribuir basta ler a sessão de [contributing](https://github.com/Open-Pix/ruby-sdk#contributing)

---

## Como começar?

## Instalando
Se o seu projeto utiliza Bundle para gerenciar dependencias, simplesmente adicione ao seu Gemfile

```
gem 'woovi-ruby_sdk', '~> 1.1.1' # como boa prática, use a restrição para versões sempre mais especifica possivel, evitando breaking changes
```

## Uso
A classe principal para interagir com o SDK é a `woovi::RubySdk::Client`.

### Inicializando o client
```ruby
require 'woovi/ruby_sdk'

# Seu AppID via https://app.woovi.com/home/applications/tab/list
app_id = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

client = woovi::RubySdk::Client.new(app_id)
```

### Chamando a API
O client da acesso aos endpoints da API da woovi, no qual sua documentação se encontra [aqui](/api).

Os endpoints disponiveis atraves do SDK sāo:
- Charge (cobranças)
- Customer (clientes)
- Payment (pagamentos)
- Refund (reembolso)
- Subscription (assinaturas/recorrência)
- Webhook (webhooks)

```ruby
# Os endpoints estāo disponiveis dentro do client através de "recursos", acessiveis atraves do nome do recurso no plural, por exemplo, para cobranças (charge)
client.charges # retorna acesso ao endpoint de cobranças

# Com uma instancia de recurso, você ganha acesso aos métodos disponiveis para aquele endpoint
# Por exemplo, para buscar cobranças
api_response = client.charges.fetch

# O retorno da API é devolvido através de uma instancia de woovi::RubySdk::ApiResponse
# Esse objeto guarda informações da resposta do request, como:
api_response.success? # se o request foi completado sem erros
api_response.pagination_meta # informações sobre paginaçāo
api_response.resource_response # retorno com as cobranças, ou o recurso solicitado

# Caso prefira tratar erros/lidar com Errors ao chamar um endpoint, existem as versões com bang (! exclamaçāo) dos métodos que chamam a API
client.charges.fetch! # levanta um Error caso o request nāo seja bem sucedido
```

### Operações disponiveis em recursos
Em cada recurso podem existir os seguintes métodos:
- `init_body` para inicializar o body de um request POST (criar um recurso)
- `save` para criar request de POST, criando um recurso
- `fetch` para criar um request de GET, listando uma coleçāo de um recurso
- `find` para criar um request de GET, buscando um recurso em especifico
- `destroy` para criar um request de DELETE, deletando um recurso em especifico

#### Descricao de cada operaçāo
`init_body`
```ruby
# Recebe como params
# params (um hash com os atributos de cada recurso)
# rest (um hash para atributos não normalizados/listados na documentaçao que queira enviar mesmo assim)

charge_params = {
  correlation_id: 'my-correlation-id',
  value: 50000
}

client.charges.init_body(params: charge_params)

# uso com rest
client.charges.init_body(params: charge_params, rest: { 'key' => 'value' })
```

`save`
```ruby
# Recebe como params
# extra_headers (um hash que oferece a possibilidade de adicionar headers extras na request)
# return_existing (um boolean que faz com que seja retornado um recurso, caso ele ja exista, saiba mais aqui /docs/concepts/idempotence)

# apos inicializar o body
response = client.charges.save

# uso com return_existing
response = client.charges.save(return_existing: true)

# uso com extra_headers
response = client.charges.save(extra_headers: { authentication: 'BEARER token' })
```

`fetch`
```ruby
# Recebe como params
# skip (parametro utilizado para paginacao, define quantos records "pular" ao retornar os recursos)
# limit (parametro utilizado para paginacao, define quantos records retornar por pagina)
# params (parametro utilizado para passar outros params na URL, por exemplo filtros, como "start", "end")
# extra_headers (um hash que oferece a possibilidade de adicionar headers extras na request)

response = client.charges.fetch

# uso com paginacao
response = client.charges.fetch(skip: 10, limit: 5)

# uso com params
response = client.charges.fetch(params: { start: '2020-01-01T00:00:00Z', end: '2020-01-05T00:00:00Z' })

# uso com extra_headers
response = client.charges.fetch(extra_headers: { authentication: 'BEARER token' })
```

`find`
```ruby
# Recebe como params
# id (parametro utilizado para identificar o recurso que deseja buscar)
# extra_headers (um hash que oferece a possibilidade de adicionar headers extras na request)

response = client.charges.find(id: 'my-id')

# uso com extra_headers
response = client.charges.find(id: 'my-id', extra_headers: { authentication: 'BEARER token' })
```

`destroy`
```ruby
# Recebe como params
# id (parametro utilizado para identificar o recurso que deseja deletar)
# extra_headers (um hash que oferece a possibilidade de adicionar headers extras na request)

response = client.charges.destroy(id: 'my-id')

# uso com extra_headers
response = client.charges.destroy(id: 'my-id', extra_headers: { authentication: 'BEARER token' })
```

### Objeto ApiResponse
O objeto `woovi::RubySdk::ApiResponse` possui os seguintes metodos para ler a resposta:

- `success?` retorna um booleano indicando se o request foi bem sucedido
- `body` retorna o body retornado pela API atraves de um hash, parseado do JSON recebido
- `status` retorna o status code da resposta da API
- `resource_response` retorna os records retornados pela API, pode ser um Array de records, no caso de uma collection, ou um recurso unico
- `error_response` retorna a mensagem de erro caso o request nāo tenha sido bem sucedido
- `pagination_meta` retorna metadados referente a paginaçao de recursos, no caso de uma collection

### Paginaçao

A SDK possui alguns métodos que ajudam a trabalhar com paginação no caso de recursos de uma collection.

O parametros utilizados para paginação são:
- `skip` define quantos records "pular", ou seja, vai retornar a partir do record skip + 1, **o valor default é 0**
- `limit` define quantos records retornar por página, **o valor default é 100**

```ruby
# Para começar devemos fazer um request com fetch para setar os parametros iniciais
response = client.charges.fetch(skip: 0, limit: 10)

# A partir dai, podemos chamar o fetch_next_page! ou fetch_previous_page! e buscar a proxima página
response = client.charges.fetch_next_page! # perceba que o método possui bang, ou seja, ele vai levantar um error caso a operação seja impossivel de ser executada, faça os tratamentos necessários para poder cuidar desses casos

# IMPORTANTE
# O a paginação vai manter o escopo de filtro utilizado no fetch inicial, ou seja, se você esta filtrando os records por data ou outros filtros, ele irão se manter ao buscar outras páginas.
```

**IMPORTANTE**
A paginação vai manter o escopo de filtro utilizado no fetch inicial, ou seja, se você esta filtrando os records por data ou outros filtros, ele irão se manter ao buscar outras páginas.

### Tratamento de Erros
Todos os recursos disponiveis possuem sua versão com bang (!), que levantam um `Error` sempre que algo de errado aconteça, seja como resposta do request, ou erros de paginação, por exemplo.
Todos os erros estão acompanhados de mensagens e o status code da resposta da API para ajudar a resolver o problema.

Os métodos e as possiveis classes de erro a serem levantadas são:
**save!** -> `woovi::RubySdk::Resources::RequestError`
**fetch!** -> `woovi::RubySdk::Resources::RequestError`
**fetch_next_page!** -> `woovi::RubySdk::Resources::RequestError`, `woovi::RubySdk::Resources::NotFetchedError`, `woovi::RubySdk::Resources::PageNotDefinedError`
**fetch_previous_page!** -> `woovi::RubySdk::Resources::RequestError`, `woovi::RubySdk::Resources::NotFetchedError`, `woovi::RubySdk::Resources::PageNotDefinedError`
**find!** -> `woovi::RubySdk::Resources::RequestError`
**destroy!** -> `woovi::RubySdk::Resources::RequestError`

Caso não queira que erros sejam levantados, utilize a versão safe (sem bang !), você pode ver a resposta de erro no `error_response` do objeto de resposta sempre que `success?` esteja retornando `false`.

---

## Recursos(Ruby)

## Lista de recursos disponíveis

### Charges
```ruby
require 'woovi/ruby_sdk'

app_id = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

client = woovi::RubySdk::Client.new(app_id)

# Listar Charges
response = client.charges.fetch(skip: 0, limit: 10)

# Buscar próxima página
response = client.charges.fetch_next_page!

# Buscar página anterior
response = client.charges.fetch_previous_page!

# Criar um Charge
charge_params = {
  correlation_id: 'my-correlation-id',
  value: 50000
}
# inicializar o body
client.charges.init_body(params: charge_params)
# faz o request para criar o recurso
response = client.charges.save

# Metodos auxiliares para ajudar a construir body de criaçao
# adicionar additional_info
key = "minha-chave#123"
value = "valor desejado"
client.charges.add_additional_info(key, value)

# adicionar interests
interest = 0.5
client.charges.set_interests(interest)

# adicionar fines
fine = 0.2
client.charges.set_fines(fine)

# Buscar um Charge específico
response = client.charges.find(id: "id-do-charge")

# Deletar um Charge específico
response = client.charges.destroy(id: "id-do-charge")
```

### Customer
```ruby
require 'woovi/ruby_sdk'

app_id = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

client = woovi::RubySdk::Client.new(app_id)

# Listar Customers
response = client.customers.fetch(skip: 0, limit: 10)

# Buscar próxima página
response = client.customers.fetch_next_page!

# Buscar página anterior
response = client.customers.fetch_previous_page!

# Criar um Customer
customer_params = {
  name: 'Client Name',
  tax_id: 12306252832
}
# inicializar o body
client.customers.init_body(params: customer_params)
# faz o request para criar o recurso
response = client.customers.save

# Buscar um Customer específico
response = client.customers.find(id: "id-do-customer")
```

### Payment
```ruby
require 'woovi/ruby_sdk'

app_id = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

client = woovi::RubySdk::Client.new(app_id)

# Listar Payments
response = client.payments.fetch(skip: 0, limit: 10)

# Buscar próxima página
response = client.payments.fetch_next_page!

# Buscar página anterior
response = client.payments.fetch_previous_page!

# Criar um Payment
payment_params = {
  value: 100,
  correlation_id: "my-correlation-id-123-!@#"
}
# inicializar o body
client.payments.init_body(params: payment_params)
# faz o request para criar o recurso
response = client.payments.save

# Buscar um Payment específico
response = client.payments.find(id: "id-do-payment")
```

### Refund
```ruby
require 'woovi/ruby_sdk'

app_id = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

client = woovi::RubySdk::Client.new(app_id)

# Listar Refunds
response = client.refunds.fetch(skip: 0, limit: 10)

# Buscar próxima página
response = client.refunds.fetch_next_page!

# Buscar página anterior
response = client.refunds.fetch_previous_page!

# Criar um Refund
refund_params = {
  value: 100,
  correlation_id: "my-correlation-id-123-!@#",
  transaction_end_to_end_id: "my-transaction-id-123-!@#"
}
# inicializar o body
client.refunds.init_body(params: refund_params)
# faz o request para criar o recurso
response = client.refunds.save

# Buscar um Refund específico
response = client.refunds.find(id: "id-do-refund")
```

### Subscription
```ruby
require 'woovi/ruby_sdk'

app_id = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

client = woovi::RubySdk::Client.new(app_id)

# Criar um Subscription
subscription_params = {
  client: {
    name: "Cliente Legal",
    tax_id: "123456"
  },
  value: 1234
}
# inicializar o body
client.refunds.init_body(params: subscription_params)
# faz o request para criar o recurso
response = client.subscriptions.save

# Buscar um Subscription específico
response = client.subscriptions.find(id: "id-do-subscription")
```

### Webhooks
```ruby
require 'woovi/ruby_sdk'

app_id = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

client = woovi::RubySdk::Client.new(app_id)

# Listar Webhooks
response = client.webhooks.fetch(skip: 0, limit: 10)

# Buscar próxima página
response = client.webhooks.fetch_next_page!

# Buscar página anterior
response = client.webhooks.fetch_previous_page!

# Criar um Webhook
webhook_params = {
  name: "nome do webhook",
  event: "OPENPIX:CHARGE_CREATED",
  url: "https://meu-endpoint/woovi/webhooks"
}
# inicializar o body
client.webhooks.init_body(params: webhook_params)
# faz o request para criar o recurso
response = client.webhooks.save

# Deletar um Webhook específico
response = client.webhooks.destroy(id: "id-do-webhook")
```

---

## O que é o SDK de Ruby?

O SDK de Ruby é um kit de ferramentas criado com o objetivo de integrar facilmente os serviços da woovi em suas aplicações Ruby.

Permite criar assinaturas recorrentes, cobranças, solicitações de pagamentos, webhooks, bem como gerenciar outros dados da API.

É possível enviar requisições customizadas utilizando nosso cliente, que adiciona todas as informações necessárias, como informações de autenticação e realiza a decodificação das respostas em formato JSON.

Utilizando o nosso paginador integrado, é fácil criar paginações para listagem de dados, com métodos que seguem os padrões do Ruby. É suportado em todos os endpoints de listagem de dados.

[RDoc](https://ruby-doc.org/3.2.2/) estão em todas as classes e métodos para facilitar a utilização de nosso SDK pelo seu editor favorito, como Visual Studio Code por exemplo.

O SDK é mantido oficialmente pela woovi e distribuído pelo [RubyGems](https://rubygems.org/).

O código está disponível nop [repositório do GitHub](https://github.com/Open-Pix/ruby-sdk).

---

## Política de Backup

*Versão: Março de 2021*

*Histórico do documento*

| Data  | Descrição | Autor | Revisores |
| -  | - | - | - |
| Março de 2021 | Adicionar notas sobre criptografia em repouso | RAT | SIBS, RAT |
| Janeiro de 2021 | Publicar a Política de Cópia de Segurança como um Documento Separado | ANB | SIBS |

## Guia de Backup

**Os dados devem ser protegidos, armazenados em um ambiente seguro e com backup regular.** 

## Política de backup & Segurança

### Política de backup
 
- Os backups serão executados automaticamente a cada 2 horas
- Os backups serão arquivados (cold storage) após 24 horas
- Os backups serão excluídos permanentemente (exclusão definitiva) após 30 dias

### Segurança de backup

A segurança de backups é complementar à [Política de Segurança](security-policy) 

| Item | Descrição |
| - | - |
| Encriptação em descanso | Os dados de backup devem ser criptografados usando chaves de criptografia exclusivas.As chaves devem ser armazenadas em um hardware [HSM] de enclave seguro. Isto garante que os dados não sejam lidos por uma pessoa não autorizada, caso os arquivos sejam comprometidos.Com a criptografia em descanso, os bancos de dados criptografam os dados antes de armazená-los no disco.O acesso às chaves [HSM] deve ser protegido por chaves [IAM]. |
| Chaves de acesso exclusivas | As chaves de acesso [IAM] são necessárias para fazer upload e recuperar dados de backup e devem ser executadas de forma diferente e funções de acesso separadas. |
| Isolamento de cluster | Os backups de ambientes de produção devem ser armazenados em depósitos separados. |
| Excluir | Os dados de backup devem ser automaticamente excluídos permanentemente após 30 dias. |
| Sem meio físico | Os backups só são armazenados em arquivos digitais, não deve ser utilizado nenhum meio físico, como fitas, discos, discos rígidos externos. |

[IAM]: https://en.wikipedia.org/wiki/Identity_management
[HSM]: https://en.wikipedia.org/wiki/Hardware_security_module

---

## Diretrizes de Segurança

*Versão: Março de 2021*

*Histórico do documento*

| Data  | Descrição | Autor | Revisores |
| -  | - | - | - |
| Março de 2021 | Notas de banco de dados corrigidas, melhorar notas de Infosec | ANB | SIBS |
| Janeiro de 2021 | Primeira versão | JCB | RAT, SIBS |

## Estratégia & Guia de desenvolvimento de Software Seguro

Somos uma plataforma digital como tal, nossa segurança estará fortemente relacionada a como: Projetar, Codificar, Construir, Liberar Código para produção.

Código de qualidade significa menos riscos e maior segurança.

## Princípios de Segurança

**ACREDITAMOS QUE A SEGURANÇA NÃO É NEGOCIÁVEL E DEVE ESTAR PRESENTE, TESTADA E APLICADA EM TODOS OS ASPECTOS E ETAPAS DO PRODUTO.** 

**A SEGURANÇA DEVE ESTAR PRESENTE EM DOCUMENTOS, CÓDIGO, CÓDIGO FONTE, TESTES, MENSAGENS, ANÁLISES, IMAGENS OU QUALQUER OUTRA INFRAESTRUTURA DIGITAL OU FÍSICA USADA PARA FORNECER SERVIÇOS AOS NOSSOS CLIENTES.**

### Propriedade do código

Os desenvolvedores devem agir como proprietários e guardiões do código que constroem.

As equipes de desenvolvimento devem operar em equipes. Permitir que os desenvolvedores sejam proprietários e responsáveis ​​pelo que codificam.

O desenvolvimento só começa depois que a linha de base da interface do usuário e da experiência (UI / UX) é concluída. 

Codificamos apenas quando requisitos e resultados claros são definidos. Os desenvolvedores são encorajados, têm permissão e espera-se que desafiem e até recusem designs pouco claros ou diretrizes enganosas.

### Construção contínua

Contaremos fortemente com a construção e integração contínuas.

Assim que o desenvolvimento de uma nova versão for iniciado, ela será disponibilizada para teste. Somente após a aprovação, ele será enviada para o ambiente de produção.

Ao codificar para o aplicativo móvel, as plataformas IOS e Android são criadas simultaneamente, enrolando na estrutura React Native. Os recursos e o escopo de cada sprint serão definidos em conjunto com a equipe de Produto.

Esta abordagem permite um aprendizado rápido e contínuo sobre as funcionalidades do App, bem como ajustes e correções de possíveis erros de forma ágil.

Um sprint só termina depois que o código chega à produção.

## Segurança de Front End 

### Segurança de aplicativos móveis
 
Nossos aplicativos são recursos importantes para nossos clientes. No entanto, não controlamos toda a cadeia de distribuição de aplicativos móveis. Os dispositivos podem ser comprometidos, os downloads podem ser alterados, nossos aplicativos podem ser comprometidos por terceiros e transformados em vetores de ataque de segurança em potencial. A fim de garantir a segurança do aplicativo irá cobrir vários requisitos de segurança em relação ao ciclo de vida do aplicativo: Desenvolvimento, Teste, Lançamento e Uso. Cada etapa terá um escopo separado e um conjunto de requisitos como parte de nossas rotinas de segurança.

### Premissas de segurança de APPs

**NÃO ACREDITE EM NINGUÉM**

Os dispositivos podem ser comprometidos, adulterados, alterados, infectados com vírus. O sistema operacional do dispositivo, nem o hardware e sua estrutura de segurança não são confiáveis. Por exemplo, os certificados raiz podem ser injetados, forjados ou removidos. Chaves de usuário podem ser comprometidas.

**A CAMADA DE REDE PODE SER COMPROMETIDA**

A comunicação entre a nosso App e o nosso próprio backend pode ser comprometida. Não vamos confiar na camada de rede que os utilizadores da nossa plataforma. Exemplos: ataque man in the middle.

**PEGADA MÍNIMA**

O Front-end consumirá apenas o que precisa, apenas quando necessário, deixando espaço mínimo para trás. Os dados serão solicitados lentamente e usados ​​somente quando necessário. Após uso o front-end deve descartar dados.

## Requisitos de segurança de APPs

| Item | Descrição |
| - | - |
| **Simplificação de código** | A simplificação do código reduz a área de cobertura do código que precisa ser testado e certificado. Isso reduz os riscos de incompatibilidade de código. Dentro do escopo do aplicativo móvel, os aplicativos IOS e Android compartilham o mesmo repositório, reutilizando a maior parte do código. Isso é possível através do React Native, a principal linguagem de programação para Apps. Essa estratégia reduz a complexidade do código enquanto mantém uma ótima experiência do cliente. |
| **Diretrizes de qualidade de código** | O desenvolvimento de aplicativos deve usar as práticas recomendadas de código.ES7 Automatic Lint [Unit Testing]Asynchronous functions (async/await)Modern component renderingRelay Modern.|
| **Processo de compilação para produção** | A compilação final (compilação de produção) deve ser sempre gerada pelo sistema [CI/CD]. Nenhuma intervenção humana é realizada ao criar o build final que irá para o ambiente de produção |

## Segurança na web

A maioria de nossos clientes se conecta à plataforma usando navegadores regularmente. A Web é um componente chave da plataforma e está amplamente exposta na Internet.

A Web é um potencial vetor de ataques à segurança.

A fim de garantir que a segurança da web abranja vários requisitos de segurança em relação ao ciclo de vida do aplicativo: Desenvolvimento, teste, lançamento e uso. Cada etapa terá um escopo separado e um conjunto de requisitos como parte de nossas rotinas de segurança.

### Requisitos de segurança da web

| Item | Descrição |
| - | - |
| **Simplificação de código** | A Web usa uma única base de código no React. O React permite que os componentes sejam construídos como tijolos de lego. Cada componente pode ser testado individualmente.A simplificação reduz os riscos de incompatibilidade de código. |
| **Diretrizes de código** | O aplicativo deve usar as práticas recomendadas de código de desenvolvimento. ES7Automatic Lint[Unit Testing]Modern component rendering |
| **Processo de construção** | A compilação final (compilação de produção) deve ser sempre gerada pelo sistema [CI/CD]. O build é gerado em uma plataforma automatizada. Depois que o código é compilado, ele é movido para um registro de contêiner privado. O registro é consumido pelo Agente Kubernetes, que recarregará o contêiner diretamente do registro. |

## Política de teste

Os testes são um elemento chave para a qualidade e segurança do código.

Nossa política de testes exige que o código usado na produção seja acompanhado de seus respectivos testes. Além de seguir boas práticas de desenvolvimento, sempre escrevemos os testes primeiro, antes de criar linhas de código.

### Testes automatizados

O código é sempre aceito se fornecido com testes de unidade relevantes aplicáveis. A melhor prática espera; Escreva os testes primeiro, depois o código.

Para cada commit, os testes serão executados novamente. Sempre usamos testes contínuos e automatizados. Os testes automatizados são executados em nossa plataforma de [CI/CD].

Os testes serão executados automaticamente, mesmo se o novo código não for aplicável ao repositório principal.

Além disso, a equipe de desenvolvimento recebe, em tempo real, o resultado de todos os testes.

### Testes humanos

Todas as versões terão uma revisão final manual, executada por uma pessoa usando o ambiente de teste.

### Teste de tipados. Validação de código durante o desenvolvimento
 
O código JavaScript usará a estrutura de validação usando código tipado baseado em [TypeScript]. Esta ferramenta ajuda a validar a qualidade do código no momento da edição e avisa o desenvolvedor se forem encontrados erros de consistência. O uso do [TypeScript] é extremamente importante para atender a uma premissa básica deste projeto: Reutilização de código. 

Os componentes do código só podem ser reutilizados com qualidade se, em sua origem, declararem de forma clara e concisa quais dados esperam receber e / ou produzir.

### Revisão de código

Cada desenvolvedor da equipe tem seu revisor par, ou seja, outro desenvolvedor que não participou do desenvolvimento do código atuará como levantador de barreiras realizando a revisão do código de forma crítica e construtiva.

Os repositórios devem ser privados, as ramificações são protegidas. Cada confirmação deve ser executada usando uma solicitação pull. As solicitações pull só serão mescladas se dois ou mais desenvolvedores aprovarem o commit.

### API unificada e componentes de back-end

Ao se comunicar com o back-end, o aplicativo ou aplicativo de navegador usará um único componente no código que lida com todas as comunicações do mundo externo.

Todas as solicitações originadas do cliente devem passar pelo componente API e devem se conectar a um serviço de back-end conhecido.
 
 
### Minimize o uso de memória 

O código ou as bibliotecas devem fazer pouco uso da memória. Isso é fundamental em dispositivos de baixo custo, onde a RAM costuma ser limitada. Além disto uso excessivo de memória indica possíveis falhas de segurança ou dá margem para ataques usando vetores de código baseados em memory leak.

O uso de funções como should component update em componentes melhora drasticamente a experiência do usuário, pois reduz significativamente o uso de recursos de computação em dispositivos móveis. Para dispositivos Android com pouca RAM e ou poucos recursos de CPU, o uso correto deste recurso pode aumentar significativamente o número de dispositivos suportados, especialmente no caso de dispositivos de baixo custo.

### Bibliotecas maduras e estáveis
 
Bibliotecas de código devem ser preferencialmente adotar a versão [LTS], quando esta política não estiver presente adoremos última versão estável. Será dada preferência a implementações usando código aberto que possam ser auditadas.

Como estratégia de desenvolvimento contínuo, sempre praticamos manter o código de produção em sintonia com cada nova versão (estável) do React Native (para dispositivos Android e IOS) e com React para plataformas web.

### Preferencia pela última versão LTS 

Todo JavaScript produzido deve usar preferencialmente se basear em [LTS], ES6 e funções de versão mais recente. Async / await (funções ES7) devem ser utilizadas sempre que sejam necessárias operações assíncronas.

 
### Ferramentas monitoramento relatórios de falhas

As ferramentas de monitoramento e relatórios de falhas não devem registrar nenhuma informação de identificação pessoal [PII]. 

Essas são as informações que podem ser usadas sozinhas ou com outras informações para identificar, contatar ou localizar uma única pessoa, ou para identificar um indivíduo no contexto.

## Segurança de Back-End

### Segurança na nuvem
 
A plataforma Woovi é executada na nuvem. A nuvem reduz nosso tempo de entrada no mercado, permite prototipagem rápida e custos controlados. No entanto, a nuvem é um ambiente compartilhado e deve ser considerado um
ambiente que pode ser comprometido.

Independentemente da nuvem ou DataCenter utilizado a segurança da plataforma permanece sob nossa responsabilidade.

### Premissas de segurança na nuvem

**NÃO ACREDITE EM NINGUÉM**

A nuvem é apenas o servidor de outra pessoa, gerenciado por terceiros. Devemos levar em consideração em nosso código que o provedor de nuvem pode e será eventualmente comprometido. 
	
**TUDO FALHA EVENTUALMENTE**

Mesmo o melhor provedor de nuvem irá falhar. Mesmo o melhor esquema de replicação falhará.

**ENCRYPT**

Os dados devem ser criptografados o tempo todo. Os dados devem ser criptografados durante o percurso ou quando armazenados.

### Requisitos de segurança da nuvem

| Item | Descrição |
| - | - |
| **Criptografia em repouso** | Os dados do banco de dados devem ser criptografados usando chaves de criptografia exclusivas. As chaves devem ser armazenadas em chaves HSM de enclave seguro. Isso garante que os dados não sejam lidos por uma pessoa não autorizada, caso os arquivos sejam comprometidos.Com a criptografia em repouso, os bancos de dados criptografam os dados antes de armazená-los no disco.O acesso às chaves [HSM] deve ser protegidas por chaves IAM.
| **Containers** | Todos os serviços de back-end devem ser executados em seu próprio contêiner designado. |
| **Diretrizes de código** |  O aplicativo deve usar as práticas recomendadas de código de desenvolvimentoES, using latest [LTS]Automatic Lint[Unit Testing]Asynchronous functions (async/await) |
| **Separação de deveres** | A separação de funções e o controle de acesso baseado em funções são inerentes ao design da nuvem.Os sistemas que executam códigos ou monitoram a saúde e a disponibilidade da rede de [HSM] não devem estar envolvidos na criação e gerenciamento do material chave armazenado em [HSM]. |
| **Processo de construção** | A compilação final (compilação de produção) deve ser sempre gerada pelo sistema [CI/CD].O build é gerado em uma plataforma automatizada. Depois que o código é compilado, ele é movido para um registro de contêiner privado. O registro é consumido pelo Agente Kubernetes, que recarrega os contêineres diretamente do registro. |
| **Acesso limitado à infraestrutura em nuvem** | O acesso ao provedor de nuvem é restrito a um número reduzido de desenvolvedores seniores na empresa, todos membros da empresa.Os desenvolvedores só têm acesso ao código-fonte. O ambiente de desenvolvimento é separado do ambiente produtivo (ambiente de preparação).As alterações de código, seja no desenvolvimento, teste ou produção, são realizadas apenas por meio da plataforma de implantação contínua, portanto, é possível rastrear e controlar cada alteração no código. |
| **MFA** | Os humanos devem usar a autenticação com [MFA] ao se conectar à infraestrutura em nuvem. |
| **Gerenciamento de chave IAM** | Each environment will use its own set of keys. Keys will be loaded directly into Kubernetes. |
| **As chaves IAM devem ser rotacionadas a cada 6 meses.** | A rotação de chaves é realizada diretamente no ambiente de configuração do Kubernetes |

## Política de backup & Segurança

### Política de Backup
 
Política de backup e requisitos de segurança [Política de backup](backup-policy)

[MFA]: https://en.wikipedia.org/wiki/Multi-factor_authentication
[CI/CD]: https://en.wikipedia.org/wiki/CI/CD
[Continuous Delivery]: https://en.wikipedia.org/wiki/Continuous_delivery
[TypeScript]: https://en.wikipedia.org/wiki/TypeScript
[LTS]: https://en.wikipedia.org/wiki/Long-term_support
[Unit Testing]: https://en.wikipedia.org/wiki/Unit_testing
[HSM]: https://en.wikipedia.org/wiki/Hardware_security_module
[PII]: https://en.wikipedia.org/wiki/Personal_data

---

## Credencial exposta ou vazada: como remediar

Esta é a documentação pública de remediação da Woovi para credenciais expostas.
Use esta página se um AppID, `clientSecret` ou secret key de webhook da Woovi foi
publicado em um repositório público, log, ticket, print, pacote npm/composer,
bundle de frontend, ou detectado por uma ferramenta de _secret scanning_.

:::danger Trate como comprometida
Qualquer credencial que saiu do seu ambiente controlado deve ser considerada
comprometida, mesmo que o repositório fosse privado, mesmo que o commit tenha
sido revertido e mesmo que o vazamento tenha durado poucos minutos. Reescrever o
histórico do Git **não** remedia o vazamento — só a rotação da credencial remedia.
:::

## Resumo (faça agora)

1. **Rotacione ou revogue** a credencial no painel da Woovi — isso invalida a credencial exposta imediatamente.
2. **Atualize seus sistemas** com a nova credencial.
3. **Revise o extrato, as transações e a auditoria** do período em que a credencial ficou exposta e, se encontrar qualquer atividade que não reconhece, escreva para [security@woovi.com](mailto:security@woovi.com).

## 1. Identifique o tipo de credencial

| Credencial | Onde é usada | Como reconhecer | Risco |
| - | - | - | - |
| **AppID de API** | Header `Authorization` das chamadas a `api.woovi.com` | String base64 que decodifica para `Client_Id_<uuid>:Client_Secret_<...>` | **Alto** — permite chamar a API em nome da sua empresa, dentro dos escopos atribuídos |
| **AppID de Plugin** | Frontend / checkout | Mesmo formato do AppID de API | **Baixo/Médio** — é público por design e só acessa rotas de plugin, mas recomendamos rotacionar |
| **`clientSecret` de WooviApp** (OAuth) | Backend do seu app, na troca do `code` | Retornado uma única vez na criação do app em [store.woovi.com](https://store.woovi.com/create) | **Alto** — permite se passar pelo seu app no fluxo OAuth |
| **`clientId` / `clientSecret` de Limites de Conta** | HTTP Basic Auth (`Authorization: Basic ...`) | Par de credenciais criado no painel de limites | **Alto** |
| **Secret key HMAC de Webhook** | Validação do header `X-OpenPix-Signature` | Secret exibido no detalhe do webhook em `API/Plugins` | **Médio** — permite forjar webhooks que o seu sistema aceitaria como legítimos |

Se você não conseguir identificar o tipo, trate como AppID de API (o cenário mais
sensível) e siga o passo 2.

## 2. Rotacione ou revogue a credencial

### AppID de API ou de Plugin

Rotacionar gera um novo AppID e **invalida o antigo imediatamente**:

1. Acesse [app.woovi.com](https://app.woovi.com.br/home/applications/tab/list) e vá em **API/Plugins → API/Plugins**.
2. Selecione a aplicação cuja chave foi exposta.
3. Clique em **Regerar AppID**.
4. Confirme com o seu segundo fator de autenticação (2FA).
5. Copie o novo AppID — ele é exibido apenas nesse momento.

Se a integração não é mais usada, prefira **remover a aplicação** em vez de
rotacionar. Você também pode remover a aplicação pela API, autenticando com o
próprio AppID exposto:

```bash
curl --request DELETE \
  --url https://api.woovi.com/api/v1/application \
  --header 'Authorization: APPID_EXPOSTO'
```

Essa rota exige o escopo `APPLICATION_DELETE`. A aplicação _master_ da empresa
não pode ser removida — nesse caso, rotacione pelo painel.

:::tip
Se a mesma credencial estava em uso por várias integrações, crie um AppID por
integração antes de rotacionar. Assim o próximo incidente afeta apenas um sistema.
:::

### `clientSecret` de WooviApp (OAuth)

O `clientSecret` é exibido apenas uma vez na criação e a Woovi armazena somente o
hash SHA-256 dele — não há como recuperá-lo nem rotacioná-lo. Para remediar:

1. Cadastre um novo app em [store.woovi.com/create](https://store.woovi.com/create) com as mesmas _redirect URIs_ e permissões.
2. Migre seu backend para o novo `clientId` / `clientSecret`.
3. Remova o app antigo.

Cada empresa que autorizou o seu app pode revogar o acesso a qualquer momento em
[store.woovi.com/authorized-apps](https://store.woovi.com/authorized-apps), e a
revogação invalida o _access token_ imediatamente. Oriente seus clientes a
revogar o app antigo depois da migração.

### `clientId` / `clientSecret` de Limites de Conta

Crie um novo par de credenciais no painel, atualize sua integração e remova o par
exposto.

### Secret key HMAC de Webhook

A secret key faz parte da configuração do webhook. Para trocá-la, remova o
webhook e cadastre-o novamente — o novo webhook recebe uma nova secret key.
Consulte [Validando Webhook payload usando HMAC-SHA1](../webhook/seguranca/webhook-hmac.mdx).

Considere migrar para a validação por
[chave pública (`x-webhook-signature`)](../webhook/seguranca/webhook-signature-validation.mdx),
que não depende de um secret compartilhado e portanto não pode vazar do seu lado.

## 3. Avalie o impacto

Com a credencial rotacionada, verifique o que aconteceu enquanto ela estava exposta:

- **Extrato e transações** — procure cobranças, pagamentos, saques ou reembolsos que você não reconhece.
- **Auditoria** — todas as ações na plataforma são auditadas com IP e geolocalização.
- **Sessões** — confira as sessões ativas e os alertas de login de dispositivos ou locais desconhecidos.
- **Webhooks** — se a secret key HMAC vazou, revise os eventos que seu sistema processou no período.

Encontrou algo suspeito? Escreva imediatamente para
[security@woovi.com](mailto:security@woovi.com) com o AppID afetado (nunca o
valor completo da credencial), a janela de tempo e o que você observou.

## 4. Previna o próximo vazamento

- **Nunca versione credenciais.** Use variáveis de ambiente ou um gerenciador de segredos.
- **Restrinja escopos.** Um AppID sem escopos definidos tem acesso completo às rotas do seu tipo de aplicação. Veja [Adicionando escopos ao seu AppID](../apis/api-scopes.md).
- **Restrinja IPs.** Libere apenas os IPs dos seus servidores. Veja [Adicionando filtro de IP à sua API](../apis/api-security-ip-whitelist.md).
- **Uma chave por integração.** Não reutilize AppIDs entre serviços ou ambientes.
- **Desative chaves não utilizadas.**
- **Nunca use um AppID de API no frontend.** Para frontend existe o tipo Plugin.
- **Habilite MFA** para todos os usuários da sua empresa. Veja [Autenticação multi-fator](./security-user-mfa.md).
- **Ative o _secret scanning_** no seu provedor de Git para ser avisado antes de nós.

## 5. Fale com a Woovi

| Assunto | Canal |
| - | - |
| Credencial vazada, atividade suspeita, incidente de segurança | [security@woovi.com](mailto:security@woovi.com) · [infosec@woovi.com](mailto:infosec@woovi.com) |
| Divulgação responsável de vulnerabilidade | [security@woovi.com](mailto:security@woovi.com) |
| Dúvidas de integração e suporte | [ajuda.woovi.com](https://ajuda.woovi.com) |

## Para plataformas de _secret scanning_

Esta página é a URL canônica de remediação pública da Woovi e pode ser
referenciada em alertas de vazamento de credenciais Woovi.

- Português: `https://developers.woovi.com/docs/security/security-leaked-credentials`
- English: `https://developers.woovi.com/en/docs/security/security-leaked-credentials`

Para reportar credenciais Woovi encontradas em fontes públicas, ou para tratar de
um programa de parceria de _secret scanning_, escreva para
[security@woovi.com](mailto:security@woovi.com).

Veja também: [Política de Segurança](./security-policy.md) e
[Diretrizes de Segurança](./security-guidelines.md).

---

## Política de Segurança

*Versão: Abril de 2021*

*Histórico do documento*

| Data  | Descrição | Autor | Revisores |
| -  | - | - | - |
| Abril de 2021 | Diretrizes de desenvolvimento de Software em documento próprio | RAT | SIBS |
| Março de 2021 | Revisão Política de Fornecedores | DNS | RAT, SIBS |
| Janeiro de 2021 | Primeira versão | RAT | RAT, SIBS |

## Objetivo
Este documento descreve a política de segurança que é adotada em toda a organização. Esta política se aplica à Colaboradores, Clientes, Usuários, Fornecedores, Sistemas, Infra-estrutura, Produtos e Serviços. Esta política tem como objetivo  proteger os dados de todos os Stakeholders.

## Princípios de segurança que nos norteiam:

**1. SEGURANÇA NÃO É NEGOCIÁVEL.**

**2. ZELAR PELA SEGURANÇA É UM ATO CONTÍNUO. Cultura de segurança deve estar presente sempre que nos relacionamos com nossos Clientes, Usuários, Colaboradores e Fornecedores** 

**3. SEGURANÇA DEVE ESTAR PRESENTE EM TODOS NOSSOS PRODUTOS E SERVIÇOS; Segurança deve compreender todo o ciclo de vida dos nossos produtos e serviços abrangendo Documentação, Código, Código Fonte, Testes, Mensagens, Análises, Imagens e qualquer infra-estrutura seja física ou digital usada para fornecer serviços ou produtos aos nossos clientes.**

**4. TODOS SÃO RESPONSÁVEIS. Todos devem zelar, manter e assegurar segurança para nossos clientes, usuários, colaboradores, produtos, serviços e serviços.**

## Política de Usuários e Senhas

| Item | Descrição |
| - | - |
| **Usuários Únicos** | Todos os colaboradores, usuários, clientes, e ou fornecedores com acesso à sistemas devem ter contas de acesso únicas e nominais. Sendo expressamente vetado compartilhamento de senhas. |
| **Senhas** | Uso de senhas é obrigatório para acesso a todo e qualquer sistema. Indiferente se sejam sistemas internos ou externos. |
| **Senhas Fortes** | Sistemas de login e cadastro de usuários devem impor uso de senhas fortes. Sistemas de login não devem bloquear ou restringir uso de aplicativos de armazenamento de senhas. |
| **MFA** | Todos os sistemas devem suportar [MFA]. Plataforma deve recomendar e encorajar uso de [MFA] |
| **SSO** | Usuários de clientes empresariais podem acessar seus respectivos ambientes utilizando [SSO]. Plataforma deve, sempre que possível, recomendar, encorajar e facilitar uso de [SSO]. |
| **Logs** | Todos os acessos às plataformas, incluindo falhas de acesso, devem ser monitorados. |
| **Monitoramento** | Acesso à sistemas plataformas deve ser monitorado em tempo real. |
| **Criptografia** | Senhas devem ser, obrigatoriamente, criptografadas usando hashes assimétricos que impendem que a senha original seja recuperada. |
| **Segregação de acesso** | Sistemas devem implementar níveis de acesso para cada usuário, baseado em [RBAC] |

## Política de Equipamentos

| Item | Descrição |
| - | - |
| **Anti-virus** | Todos equipamentos devem usar anti-virus continuamente. O Anti-virus não pode ser desabilitado pelo usuário. |
| **Senhas** | Uso de senhas é obrigatório para acesso a todo e qualquer equipamento. |
| **Criptografia** | Sistemas operacionais dos usuários devem usar criptografia em todos seus discos. |
| **Logs** | Todos os acessos às dispositivos, incluindo falhas de acesso deve ser monitorado. |

## Política de segurança de Backend e Plataformas 

| Item | Descrição |
| - | - |
| **Segregação de ambientes** | Ambientes de produção, testes e desenvolvimento são segregados e apartados. |
| **Acesso restrito** | Acesso ao ambientes de produção devem ser estritamente restrito aos usuários devidamente qualificados e autorizados para acesso ao backend. |
| **Monitoramento** | Todo e qualquer acesso ao ambiente de produção, testes e desenvolvimento tem que ser monitorado em tempo real. Incluindo falhas. |
| **Criptografia** | Todo o acesso à plataforma deve ser criptografado. Armazenamento de dados de ambientes devem ser criptografado. |
| **Desenvolvimento Seguro** | Software deve ser desenvolvido, tesado e homologado com cultura de segurança. Desenvolvimento de Software seguro tem diretrizes de seguranças próprias [Diretriz de desenvolvimento de Software Seguro](security-guidelines) |

## Política de Segurança para ambientes Cloud
 
A plataforma é executada na (Cloud) nuvem. A nuvem reduz nosso tempo de entrada no mercado, permite prototipagem rápida e custos controlados. No entanto, a nuvem é inevitavelmente um ambiente de terceiros e deve ser considerado um
ambiente que pode ser comprometido. **Independentemente do provedor de nuvem utilizado a segurança da plataforma permanece sob nossa responsabilidade.**

### Premissas de segurança na Nuvem

| Item | Descrição |
| - | - |
| **Confiança Zero** | A nuvem é apenas o servidor de outra empresa, gerenciado por terceiros. Devemos levar em consideração em nosso código que o provedor de nuvem pode e será eventualmente comprometido. |
| **Tolerância à falhas** | Mesmo o melhor provedor de nuvem irá falhar. Mesmo o melhor esquema de replicação falhará. A plataforma, código, ambientes e sistemas deve prever e se proteger de falhas de terceiros. |
| **Criptografia** | Os dados devem ser criptografados o tempo todo. Os dados devem ser criptografados durante o percurso ou quando armazenados. |

### Requisitos de segurança da Nuvem

| Item | Descrição |
| - | - |
| **Criptografia em repouso** | Os dados do banco de dados devem ser criptografados usando chaves de criptografia exclusivas. As chaves devem ser armazenadas em chaves [HSM]. Isso garante que os dados não sejam lidos por uma pessoa não autorizada, caso os arquivos sejam comprometidos.Com a criptografia em repouso, os bancos de dados criptografam os dados antes de armazená-los no disco.O acesso às chaves [HSM] deve ser protegidas por chaves [IAM].
| **Containers** | Todos os serviços de back-end devem ser executados em seu próprio contêiner designado. |
| **Diretrizes de código** | Desenvolvimento de software deve levar em consideração ambiente Cloud, exposição de APIs na Internet, e ambiente e usuários hostil. Desenvolvimento de Software seguro tem diretrizes de seguranças próprias [Diretriz de desenvolvimento de software seguro](security-guidelines) | |
| **Separação de deveres** | A separação de funções e o controle de acesso baseado em funções são inerentes ao design da nuvem.Os sistemas que executam códigos ou monitoram a saúde e a disponibilidade da rede de seus não devem estar envolvidos na criação e gerenciamento de outros ambientes. |
| **Acesso limitado à infraestrutura em nuvem** | O acesso ao provedor de nuvem é restrito a um número reduzido de desenvolvedores seniores na empresa, todos membros da empresa.Os desenvolvedores só têm acesso ao código-fonte. O ambiente de desenvolvimento é separado do ambiente produtivo (ambiente de preparação).As alterações de código, seja no desenvolvimento, teste ou produção, são realizadas apenas por meio da plataforma de implantação contínua, portanto, é possível rastrear e controlar cada alteração no código. |
| **MFA** | Os colaboradores humanos devem, obrigatóriamente, usar a autenticação com [MFA] ao se conectar à infraestrutura em nuvem. |
| **Gerenciamento de chave IAM** | Each environment will use its own set of keys. Keys will be loaded directly into Kubernetes. |
| **Rotação de chaves** | Chaves devem ser rotacionadas a cada 6 meses. A rotação de chaves é realizada diretamente no ambiente de configuração do Kubernetes. |

## Política de segurança de Fornecedores

| Item | Descrição |
| - | - |
| **Pré-certificação** | Fornecedores devem certificados previamente validados e para aferir usas capacidades de segurança. |
| **Mesma Barra** | Fornecedores devem atingir ou superar a barra de segurança em seus processos e controles internos. |

### Política de Backup
 
Política de backup é definida em documento dedicado [Política de backup](backup-policy)

[RBAC]: https://en.wikipedia.org/wiki/Role-based_access_control
[SSO]: https://en.wikipedia.org/wiki/Single_sign-on
[MFA]: https://en.wikipedia.org/wiki/Multi-factor_authentication
[HSM]: https://en.wikipedia.org/wiki/Hardware_security_module
[IAM]: https://en.wikipedia.org/wiki/Identity_management

---

## Security Self Assessment

*Versão: Março de 2023*

*Histórico do documento*

| Data  | Descrição | Autor | Revisores |
| -  | - | - | - |
| Março de 2023 | Atulizar data ultimo Pentest | JHS | RAT |
| Fevereiro de 2023 | Inclusão novas questões | JHS | RAT |
| Março de 2021 | Inclusão novas questões | JHS | SIBS, RAT |

## Self Assessment - Security Questionnaire 

> Name of Company: Woovi / Woovi LLC
>
> Applications: In scope for this Security Questionnaire 
>
> Woovi is a instant payment provider

**Primary Contact for Security**
> Name: Infosec Team
>
> Email: security (at) woovi.com

**Secondary Contact for Security**
> Name: Sibelius Seraphini
>
> Job Title: CTO
>
> Email: sibelius (at) woovi.com

**Tertiary Contact for Security**
> Name: Rafael Turk
> 
> Job Title: CoFounder
> 
> Email: rafael (at) woovi.com

## Company Information
| Question | Comments | 
| --  | -- | 
| Geographic Country location of employees, including contractors with access to production infrastructure and applications | Brazil | 
| Company Certifications and Accreditations e.g. ISO, SAS-70, PCI DSS, HIPAA or other | Certification is in progress expected for 4Q |
| Regulatory compliance requirements and industry standards | Brazil LGDP |
| Data Center Information | AWS |
| Data Center Country Location | GRU - AWS GRU - São Paulo Region |
| Who is responsible for the data center facility? | Cloud based, AWS |
| Who is responsible for system administration? Also, note any Third party companies for Data Center Hosting and Operations | Woovi |
| Any Third party companies have access to Data Center Hosting and Operations? | No. Restricted to Woovi |
| Give details of the facility’s data center security and business continuity resources e.g. closed room, physical access controls, card reader, video surveillance, power, cooling, etc. | AWS managed |
| Security Practices In your solution do you test for OWASP and other vulnerabilities? | Yes. | 

## Product information
| Question | Comments | 
| --  | -- | 
| Does your solution involve PII/Sensitive data originating from Cloud Software as a Service (SaaS)? | Yes. | 
| The platform may use Customer data originating from Cloud Services (Saas) to authorize payments transactions? | Yes. This is a core feature of the platform |
| Does your solution store retrieve PII/Sensitive data in Cloud Services (SaaS, PaaS)? | Yes. Ecommerce plugins may pass Customer Name and TaxID to enrich payment information |
| Gateway may use Customer data originating from  Cloud Services (Saas) to authorize payments transactions. | Yes. |
| Does your solution retrieve PII/Sensitive data from  on-premise applications? | N/A Our platform don't have any onpremisse solutions. |
| Gateway may use Customer data originating from  Cloud Services (Saas) to authorize payments transactions. | Yes. |
| Do you have a mobile application that persists PII/Sensitive data on the device? | N/A. Our platform don't use any kind of Mobile Apps. |

## Web App information
| Question | Comments | 
| -  | - | 
| Does your solution implement CORS Support? | Yes. Across all apps, and all domain properties. |
| Do you use a digital certificate to encrypt data communication? | Yes. Across all domain properties. | 
| Do you use Application firewall (WAF)  to detect and block intrusion attempts? | Yes. Multiple layers across all domain properties. |
| Do you use load balancers? | Yes. We use load balancers, plus multiple datacenter locations (Datacenter Zones) to support High availability. |
| Do you have a process to discover and track security vulnerabilities and corrective measures in Open Source or 3rd party software your deliverables have a dependency on? | Yes. We have an internal Blue Team and Red Teams. Additional external third party security review, via independent partner every quarter |
| Do you have a channel for external researchers to report security vulnerabilities to your directly? | Yes.  via email at security@woovi.com or infosec@woovi.com |
| Do you support Security.txt? | Yes.  https://woovi.com/.well-known/security.txt |

## Customer Security
| Question | Comments | 
| -  | - | 
| Do you have a process to notify your customers about security vulnerabilities and distribute security patches in your deliverables? | Yes. |
| Do you have a process to notify your customers about security vulnerabilities in Open Source that your deliverables include? | Yes. |

## Vendor security 
| Question | Comments | 
| -  | - | 
| Do you have a process to validade your vendors? | Yes.  [Vendor Policy](/docs/security/security-policy#pol%C3%ADtica-de-seguran%C3%A7a-de-fornecedores)|

## Pentest
| Question | Comments | 
| --  | -- | 
| Do you perform regular pentests? | Yes.  We perform several automated pentests with software based external audit tools and multiple internal pentests with our on internal infosec team. |
| Do you perform regular independet (third party)? | Yes.  We perform several external via third party infosec companies. |
| When was the last external (via independent partner) pentest? | Last pentest was performed in January 2023. |

## Training and awareness 
| Question | Comments | 
| -  | - | 
| Your business has regular information security awareness training for all staff, including temporary, locum or contracted employees, to ensure they are all aware of and fulfil their responsibilities. | Partially implemented. |

---

## Adicionando autenticação multi-fator via App à sua conta

A autenticação multi-fator (MFA) é uma camada adicional de segurança que requer
mais de uma forma de autenticação para verificar a identidade do usuário. Isso pode ser
feito através de um aplicativo de autenticação, como o Google Authenticator, Microsoft Authenticator,
Authy, entre outros.

## Ativando a autenticação multi-fator

Para ativar a autenticação multi-fator, siga os passos abaixo:

Acesse a [página de configurações](https://app.woovi.com.br/home/me/account/edit) da sua conta.

Na seção "Informação da Plataforma", clique em "Autenticação multifator"

![Primeiro passo](./__assets__/security-user-mfa-first-step.png)

Clique no botão "Ativar autenticação de dois fatores"

Escaneie o QR Code com o aplicativo de autenticação, caso não conseguir, você pode inserir o código manualmente.

:::info

Caso não seja possivel escanear o QR code a partir do seu dispositivo, você pode estar
inserindo manualmente o código conforme o informado quando você clica em `"chave de configuração"`.

:::

Após escanear o QR Code, insira o código gerado pelo aplicativo de autenticação no campo abaixo de "Digite o código de verificação".

![Segundo passo](./__assets__/security-user-mfa-second-step.png)

Clique no botão "Salvar"

Você configurou a autenticação multi-fator com sucesso!

![Terceiro passo](./__assets__/security-user-mfa-third-step.png)

Com isso, todas as ações que exigem uma autenticação na sua conta, alteração de senha,
saques, pagamentos externos, entre outros, irão exigir a autenticação multi-fator para serem realizadas.

## Trocando o dispositivo de autenticação multi-fator

Caso você tenha trocado de dispositivo ou perdido o acesso ao aplicativo de autenticação,
você deverá entrar em contato com o nosso time de suporte que irá realizar todo o processo
para auxiliar na troca do dispositivo.

## Desativando a autenticação multi-fator

Caso você queira desativar a autenticação multi-fator, siga os passos abaixo:

![Terceiro passo](./__assets__/security-user-mfa-third-step.png)

1. Acesse a [página de configurações](https://app.woovi.com.br/home/me/account/edit) da sua conta.
2. Na seção "Informação da Plataforma", clique em "Autenticação multifator"
3. Clique no botão "Desativar"
4. Você precisará confirmar a desativação da autenticação multi-fator inserindo o código gerado pelo aplicativo de autenticação no campo abaixo de "Digite o código de verificação".
5. Após confirmar, a autenticação multi-fator será desativada com sucesso.

Lembre-se que a autenticação multi-fator é uma camada adicional de segurança para a sua conta,
desativá-la pode deixar a sua conta mais vulnerável a ataques. Caso você tenha desativado a
autenticação multi-fator, recomendamos que você ative novamente o mais rápido possível.

## Como selecionar o método de autenticação preferido?

Caso você tenha mais de um método de autenticação configurado, você pode selecionar o método
preferido para autenticação multi-fator. Para isso, siga os passos abaixo:

1. Acesse a [página de configurações](https://app.woovi.com.br/home/me/account/edit) da sua conta.
2. Na seção "Informação da Plataforma", clique em "Método de autenticação multi-fator preferido"
3. Selecione o método de autenticação que você deseja utilizar como preferido.
4. Clique no botão "Salvar"
5. Você configurou o método de autenticação multi-fator preferido com sucesso!

## Recomendações de Apps de Autenticação

Existem diversos aplicativos de autenticação disponíveis no mercado, abaixo listamos alguns
dos mais utilizados:

- Google Authenticator
- Microsoft Authenticator
- Authy
- LastPass Authenticator
- 1Password

Caso você tenha dúvidas sobre qual aplicativo utilizar, recomendamos que você entre em contato
com o suporte do aplicativo de autenticação para obter mais informações.

---

## Split Partner

O termo "Split Payment" refere-se à divisão de pagamentos em transações financeiras. Em um ambiente onde vários vendedores ou prestadores de serviço atuam, é comum que o pagamento de uma única transação precise ser dividido entre mais de uma entidade. Esse é o cenário em que o Split Payment se torna essencial.

Na funcionalidade de **split partner**, o split de pagamentos é usado para que a empresa parceira possa receber uma taxa de cada transação que é paga pela empresa afiliada. Essa taxa é o markup adicionado pelo parceiro.

Imagine, por exemplo, que você compre vários produtos em um marketplace que reúne diferentes lojas. Em vez de receber um pagamento para cada loja individualmente, você faz um único pagamento. O sistema de Split Payment, então, é responsável por garantir que cada lojista ou prestador de serviço pague sua parte apropriada desse pagamento coletivo para o marketplace parceiro.

### Como funciona?

**Definição de Taxas**: Uma empresa parceira, que pode ter diversas empresas afiliadas, configura uma taxa a ser cobrada em cada cobrança que é paga pela empresa afiliada.

**Visibilidade de Transações**: No extrato da empresa afiliada, apenas a taxa do parceiro aparece como um débito, tornando o processo transparente e fácil de entender para a afiliada.

**Relatórios para o Parceiro**: A empresa parceira vê a taxa afiliada como crédito em seu extrato. Isso garante uma gestão financeira clara e direta, permitindo que o parceiro tenha uma visão completa das suas receitas e despesas.

### Benefícios do Split Partner

**Eficiência Financeira**: As transações são processadas automaticamente, reduzindo o trabalho manual e a possibilidade de erros.

**Transparência nas Relações Comerciais**: Ambas as partes, parceiro e afiliada, têm clareza sobre as taxas aplicadas, facilitando a reconciliação e a compreensão das transações.

**Flexibilidade**: O parceiro tem a liberdade de definir a taxa ou markup que deseja aplicar, permitindo uma estratégia de preços adaptável.

**Gestão Simplificada**: Com visões claras do extrato para ambas as partes, a gestão financeira torna-se mais direta e menos propensa a complicações.

Em resumo, o Split Partner da Woovi é uma solução inovadora que atende às demandas específicas de empresas e seus parceiros no cenário atual de pagamentos digitais. Ao combinar os recursos do Split Payment com a capacidade de aplicar markups de forma transparente, a Woovi está definindo novos padrões em pagamentos afiliados.

---

## Como configurar taxa de parceiro

Dentro da funcionalidade de **Split Partner** o partner pode configurar taxas para serem cobradas em cada transação que é paga pela empresa afiliada.
Essa taxa pode ser configurada da seguinte maneira:

1 - Acesse a aba **Minhas Empresas** e vá em  **Ajustes**.

![Configurar taxa](/img/split/partner/configure-fee.png)

2 - Escolha se deseja usar taxa padrão da plataforma ou uma taxa personalizada.

Caso escolha **Usar taxa padrão da plataforma** a taxa cobrada da empresa afiliada será somente a taxa referente ao plano da plataforma do afiliado, sem valor adicional referente a taxa do parceiro. Caso queira cobrar um valor adicionar (markup) além da taxa padrão cobrada pela plataforma, é necessário selecionar a opção **Definir taxa personalizada**.

Ao usar a opção **Definir taxa personalizada** você poderá definir uma taxa personalizada para ser cobrada além do valor padrão da plataforma, os valores de cada tipo de taxa estarão detalhados abaixo para cada tipo de taxa.

### Taxa de Valor Fixo

![Configurar taxa fixa](/img/split/partner/fixed-fee.png)

No Exemplo acima vemos para uma cobrança de R$ 100,00 e uma taxa fixa de R$ 5,00, ou seja, como no caso dessa conta de exemplo a tarifa Woovi seria R$ 0,50, parceiro receberia a taxa de R$ 4,50 ambas pagas automaticamente através da cobrança do afiliado.

Extratos gerados em cada conta caso seja escolhido a taxa fixa (valores fictícios):

**Extrato do parceiro:**

![Extrato do parceiro por cobrança com fee percentual](/img/split/partner/partner-statement-fixedc.png)

**Extrato do afiliado:**

![Extrato do afiliado por cobrança com fee percentual](/img/split/partner/affiliate-sstatement-fixed.png)

### Taxa de Percentual

![Configurar taxa percentual](/img/split/partner/percent-fee.png)

No Exemplo acima vemos para uma cobrança de R$ 100,00 e uma percentual no valor de R$ 10,00, ou seja, como no caso dessa conta de exemplo a tarifa Woovi seria R$ 0,80 o parceiro receberia a taxa de R$ 9,20 ambas pagas automaticamente através da cobrança do afiliado.

Extratos gerados em cada conta caso seja escolhido a taxa percentual (valores fictícios):

**Extrato do parceiro:**

![Extrato do parceiro por cobrança com fee percentual](/img/split/partner/partner-statement-percentage.png)

**Extrato do afiliado:**

![Extrato do afiliado por cobrança com fee percentual](/img/split/partner/affiliate-statement-percentage.png)

---

## Como cadastrar Empresas Parceiras para Split Partner

### Solicitando acesso para utilizar Split Partner

Se você é um cliente Woovi e deseja solicitar a funcionalidade de split partner, saiba que é muito simples e fácil: Para solicitar a funcionalidade, basta entrar em contato com o suporte da Woovi por meio do chat disponível na plataforma. Ao acessar o chat, um atendente estará disponível para auxiliá-lo e fornecer todas as informações necessárias para a ativação da funcionalidade.

É importante lembrar que, para solicitar a funcionalidade de split partner, é preciso ter uma conta ativa na Woovi. Se você ainda não possui uma conta, basta criar uma gratuitamente e, em seguida, entrar em contato com o suporte para ativar a funcionalidade de pagamentos.

## Empresas afiliadas

Temos algumas maneiras de associar uma empresa como afiliada a sua empresa via plataforma Woovi acessando a aba **Minhas Empresas**.

![Adicionar empresas afiliadas](/img/split/partner/add-affiliates.png)

Método **Link de afiliado:**

Clicando no botão **Link de afiliado** você automaticamente copiará para area de transferência do seu computador um link que pode ser enviado para a empresa que deseja associar a sua empresa como afiliada. Empresas cadastradas dessa maneira estarão automaticamente associadas como afiliados a sua empresa.

Método **Empresas em Lote:**

1 - Na aba **Minhas Empresas** selecione o método **Empresas em Lote**

![Adicionar empresas afiliadas em lote](/img/split/partner/batch-add-companies.png)

2 - Baixe o excel modelo para preenchimento clicando em **modelo do excel**, preencha e faça o upload do arquivo na plataforma, arrastando para área indicada ou clicando em   **escolha um arquivo** para escolher o arquivo no seu computador.

3  - Clique em avançar para ver a prévia das empresas que serão adicionadas ou possíveis correções nos dados do arquivo, caso os dados estejam formatados adequadamente o botão **Registrar Empresas** ficará liberado para finalizar o processo.

![Tela de confirmação](/img/split/partner/batch-add-confirmation.png)

Método **Nova Empresa:**

Neste método você será redirecionado para um formulário de registro, onde você poderá preencher os dados da empresa que deseja associar a sua empresa como afiliada.

![Adicionar nova empresa afiliada](/img/split/partner/add-new-company.png)

Método **API:**

Também temos a possibilidade de associar empresas afiliadas via API, para isso basta acessar a documentação em [parcerias](/docs/category/parcerias) e [partner/api](/api#tag/partner-request-access .

---

## Como calcular divisão com porcentagem

:::info
Para a utilização dessa funcionalidade é necessário possuir uma conta na woovi e a funcionalidade Split, entre em contato com nosso time de suporte para habilitar essa funcionalidade
:::

:::info
Você também precisará de um `appID` também para fazer requisições na nossa API, caso não tenha recomenda-mos fortemente você consultar nossa documenta de [começando uma integração](../apis/api-getting-started.md)
:::

## Como lidar com o calculo de split

Neste exemplo estou considerando um cenário onde quero criar uma cobrança de R$ 100,00 e enviar 20% do valor dessa cobrança para o recebedor (sub-conta) desse split, que no caso seria R$ 20,00

```ts
// função para lidar com calculo do valor split em porcentagem
const calculateSplitPercentage = (value: number, percentage: number) => {
  return value * (percentage / 100)
}

const createCharge = () => {
  // 100 reais em centavos
  const totalValueCharge = 10000
  // a porcentagem que será paga para o recebedor (sub-conta)
  // essa porcentagem pode ser ajustada baseado nas suas necessidades e regras de negócio
  const splitPercentageRecipient = 20
  // calculando o valor que o recebedor deverá receber
  const valueSplitRecipient = calculateSplitPercentage(totalValueCharge, splitPercentageRecipient)

  // agora estou chamando uma abstração de uma chamada para API da woovi
  // nessa requisição o valor total da cobrança e o valor split do recebedor (sub-conta) e as demais informações
  fetchwooviApi('/api/v1/charge', {
    method: 'POST',
    body: {
      "value": totalValueCharge,
      "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
      "splits": [
        {
          "pixKey": "destinatario1@woovi.com.br",
          "value": valueSplitRecipient
        }
      ]
    },
    headers: {
      Authorization: 'MEU_APP_ID'
    }
  })
}
```

---

## Como utilizar o split de transferência entre contas

:::info
Para a utilização dessa funcionalidade é necessário possuir uma conta na woovi e a funcionalidade Split, entre em contato com nosso time de suporte para habilitar essa funcionalidade.
:::

## Split de transferência entre contas (SPLIT_INTERNAL_TRANSFER)

é necessário usar o type no objeto de split `SPLIT_INTERNAL_TRANSFER`

Se a conta destino estiver dentro da sua empresa, você consegue fazer o split utilizando a `pixKey` (chave pix) 

Esse tipo de split só é possível ser feito via API

```curl
curl -X POST "https://api.woovi.com/api/v1/charge" \
  -H "Authorization: MEU_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 10000,
    "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
    "splits": [
      {
        "type": "SPLIT_INTERNAL_TRANSFER",
        "pixKey": "destinatario1@woovi.com.br",
        "value": 6000
      },
      {
        "type": "SPLIT_INTERNAL_TRANSFER",
        "pixKey": "destinatario2@woovi.com.br",
        "value": 4000
      }
    ]
  }'
```
## Exemplo de regra personalizada de split

```ts
// função para lidar com calculo do valor split em porcentagem
const calculateSplitPercentage = (value: number, percentage: number) => {
  return value * (percentage / 100)
}

const createCharge = () => {
  // 100 reais em centavos
  const totalValueCharge = 10000
  // a porcentagem que será paga para o recebedor
  // essa porcentagem pode ser ajustada baseado nas suas necessidades e regras de negócio
  const splitPercentageRecipient = 20
  // calculando o valor que o recebedor deverá receber
  const valueSplitRecipient = calculateSplitPercentage(totalValueCharge, splitPercentageRecipient)

  // nessa requisição o valor total da cobrança e o valor split do recebedor e as demais informações
  fetchwooviApi('/api/v1/charge', {
    method: 'POST',
    body: {
      "value": totalValueCharge,
      "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
      "splits": [
        {
          "type": "SPLIT_INTERNAL_TRANSFER",
          "pixKey": "destinatario1@woovi.com.br",
          "value": valueSplitRecipient
        }
      ]
    },
    headers: {
      Authorization: 'MEU_APP_ID'
    }
  })
}
```

---

## Introdução

:::info
Para a utilização dessa funcionalidade é necessário possuir uma conta na woovi e a funcionalidade Split, entre em contato com nosso time de suporte para habilitar essa funcionalidade.
:::

## Definição de split

O split é uma funcionalidade que permite que o recebimento de uma cobrança seja dividido entre diversas contas.

![Introdução ao Split](__assets__/split-intro.png)

## Como funciona?

A woovi possui diversas funcionalidades de split que permite que o recebimento de uma cobrança seja dividido entre algumas chaves pix via `API`, via plataforma e via `plugin.js`

## Tipos de split

Temos 2 tipos de split, e esses dois tipos de split tem casos de uso diferentes, por isso é necessário antes de utilizar o split entender qual tipo de split utilizar.

### Split de parceiro e afiliado (SPLIT_PARTNER)

O split de parceiro e afiliado é uma funcionalidade que permite que o recebimento de uma cobrança seja dividido entre a conta do parceiro e a conta do afiliado.

Ou seja, parte do valor da cobrança vai para a conta do parceiro e parte do valor da cobrança vai para a conta do afiliado, sendo possível configurar uma porcentagem ou valor fixo do parceiro diretamente pela plataforma para todas as cobranças.

#### Quando utilizar (SPLIT_PARTNER)

O sistema de parceiros permite a empresas registrar outras empresas como afiliados e gerenciar alguns aspectos do seu funcionamento através das API's e plataforma woovi.

Cada afiliado passa pelo processo de abertura de contas na plataforma.

Cada afiliado possui conta virtual na plataforma registrada no CNPJ de sua empresa independente do parceiro.

Cada afiliado recebe valores de cobranças diretamente via pix em sua conta virtual registrada na plataforma.

O parceiro não recebe diretamente valores em sua conta, somente taxa do parceiro perante o uso da feature de `SPLIT_PARTNER`.

Esta feature é indicada para quem quer ter uma relação mais definida entre parceiro e afiliados e pretende envolver parceiros no cadastro completo de uma conta virtual

requisitando assim dados de registro de empresa e sócios como qualquer outra abertura de contas, não recebendo diretamente em suas contas valores relativos a pagamento feitos por afiliados, somente valores relativos a taxa de parceiros.

![Taxa de Parceiro](__assets__/split-fee-partner.png)

### Split de sub-contas (SPLIT_SUB_ACCOUNT)

Sub contas são contas virtuais representadas por uma chave pix que podem transacionar virtualmente valores através do sistema de split de pagamentos. Esses valores podem ser convertidos em transações reais através do saque para a chave pix registrada para a subconta.

Ou seja, parte do valor da cobrança vai para uma chave pix e parte do valor da cobrança vai para outra chave pix, sendo possível definir na hora da criação da cobrança o valor que vai para cada chave pix.

![Split SubAccount](__assets__/split-subaccount.png)

#### Quando utilizar (SPLIT_SUB_ACCOUNT)

O sistema de subcontas permite registrar transações de split em uma subconta a partir de cobranças feitas para uma conta principal.

Subcontas não são contas bancárias reais e somente transacionam valores virtuais permitindo assim a eliminação de etapas burocráticas na abertura da mesma.

Cada subconta só precisa de uma chave pix única para ser aberta, de qualquer tipo, CPF, CNPJ, email, telefone, etc.

Uma empresa pode ter qualquer número de subcontas.

Uma empresa pode a qualquer momento realizar um saque para a chave pix registrada na subconta, tanto via integração de API ou diretamente pela plataforma.

O uso da subconta permite a criação de fluxos menos burocráticos e mais livres dentro da plataforma, os valores sacados só serão debitados da conta principal no momento do saque garantindo total controle ao administrador da empresa dona destas subcontas.

### Split de transferência entre contas (SPLIT_INTERNAL_TRANSFER)

Em casos de empresas, com múltiplas contas bancárias, ou empresas com várias contas de clientes (BAAS) ou mesmo empresas afiliadas, é possível criar um split personalizado via API

![Split SubAccount](__assets__/split_internal_transfer.png)

#### Quando utilizar (SPLIT_INTERNAL_TRANSFER)

Quando o nível de complexidade do split aumenta e é necessário criar regras personalizadas

---

## Endpoints

## Rotas da API de Stablecoin

Você pode ver os detalhes completos na [referência da API Stablecoin](/stable).

Todas as rotas ficam sob `/api/v1/stablecoin/` e exigem autenticação com o seu App (header `Authorization`). Cada rota exige um escopo (`scope`) específico no seu App:

| Escopo | Rotas |
| --- | --- |
| `STABLECOIN_DEPOSIT_CREATE` | `quote`, `deposit`, `deposit/approve` |
| `STABLECOIN_SUBACCOUNT_CREATE` | `subaccount` (POST — solicitar KYB) |
| `STABLECOIN_SUBACCOUNT_LIST` | `subaccount` (listar/detalhe), `wallets`, `subaccount/{id}/wallets`, `subaccount/{id}/balances` |
| `STABLECOIN_PAYOUT_CREATE` | `payout/quote`, `payout` (criar/aprovar/consultar) |

> A URL base de produção é `https://api.woovi.com`. Caso o App não tenha o escopo necessário, a resposta é `401` com `Application is missing required scope: ...`.

### Cotação (Quote)

GET `/api/v1/stablecoin/quote`

Retorna uma cotação BRL → stablecoin **sem criar um depósito**. Use para exibir ao cliente exatamente quanto de stablecoin ele receberia antes de confirmar. A cotação é armazenada em cache por 60 segundos.

Query params:

- `value` (obrigatório) — valor a cotar, **em centavos** de BRL (ex.: `10000` = R$ 100,00)
- `currency` (opcional) — `USDT` | `USDC` (padrão: `USDT`)

```bash
curl --request GET \
  --url 'https://api.woovi.com/api/v1/stablecoin/quote?value=10000&currency=USDT' \
  --header 'Authorization: <SEU_APP_ID>'
```

Resposta:

```json
{
  "status": "ok",
  "quote": {
    "basePrice": 5.25,
    "inputAmount": 100,
    "inputCurrency": "BRL",
    "outputAmount": 19.04,
    "outputCurrency": "USDT",
    "appliedFees": [
      { "type": "In Fee", "amount": 1.5, "currency": "BRL" }
    ],
    "pairName": "BRL/USDT"
  }
}
```

> `inputAmount` e `outputAmount` no retorno da cotação são em unidade de moeda (não em centavos). Caso o provedor não consiga cotar, a resposta é `502` com `{ "status": "error", "error": "Unable to fetch quote" }`.

### Criar um depósito

POST `/api/v1/stablecoin/deposit`

Cria um depósito de stablecoin a partir do saldo em BRL da conta. Retorna `depositId`, `correlationId` e uma cotação com as taxas aplicadas. A aprovação (`/deposit/approve`) é que debita o saldo da conta.

Body:

| campo | tipo | obrigatório | descrição |
| --- | --- | --- | --- |
| `value` | number | sim | valor em **centavos** de BRL (ex.: `10000` = R$ 100,00) |
| `currency` | string | sim | `USDT` \| `USDC` |
| `network` | string | não | `POLYGON` (padrão) \| `ETHEREUM` \| `BASE` \| `CELO` \| `TRON` |
| `subAccountId` | string | não | subconta a usar; resolvida pela empresa quando omitida |
| `correlationId` | string | não | identificador único para idempotência |
| `destinationWalletAddress` | string | não | carteira de destino explícita para a stablecoin |

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/stablecoin/deposit \
  --header 'Authorization: <SEU_APP_ID>' \
  --header 'content-type: application/json' \
  --data '{
    "value": 10000,
    "currency": "USDT",
    "network": "POLYGON",
    "correlationId": "my-unique-id"
  }'
```

Resposta:

```json
{
  "status": "PENDING",
  "depositId": "6650abc1234def567890aaaa",
  "correlationId": "my-unique-id",
  "expiration": "2026-06-05T12:00:00.000Z",
  "quote": {
    "inputAmount": 10000,
    "inputCurrency": "BRL",
    "outputAmount": 18.45,
    "outputCurrency": "USDT",
    "rate": 5.42,
    "fee": 50
  }
}
```

Erros comuns (`400`):

```json
{ "error": "value must be a positive number (in cents)" }
{ "error": "currency must be one of: USDT, USDC" }
{ "error": "USDT is not available on BASE. Supported networks: POLYGON, ETHEREUM, CELO, TRON" }
{ "error": "Nenhuma subconta de stablecoin ativa. É necessário um KYB, entre em contato com o suporte." }
```

### Aprovar (liquidar) um depósito

POST `/api/v1/stablecoin/deposit/approve`

Aprova um depósito já criado, identificado pelo `correlationId`, disparando a liquidação on-chain (pagamento do QR Code stablecoin). O depósito passa para `PROCESSING` enquanto a liquidação está em andamento.

Body:

- `correlationId` (obrigatório) — o `correlationId` informado na criação do depósito

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/stablecoin/deposit/approve \
  --header 'Authorization: <SEU_APP_ID>' \
  --header 'content-type: application/json' \
  --data '{ "correlationId": "my-unique-id" }'
```

Resposta:

```json
{
  "status": "PROCESSING",
  "correlationId": "my-unique-id",
  "depositId": "6650abc1234def567890aaaa"
}
```

A aprovação é rejeitada com `400` quando o depósito não pode ser aprovado, por exemplo: já está `COMPLETED`, já está `PROCESSING`, não há conta de origem para pagar, ou a cotação/pagamento do provedor falhou.

```json
{ "error": "Stablecoin deposit already completed", "correlationId": "my-unique-id", "depositId": "6650abc1234def567890aaaa" }
```

### Acompanhar um depósito

Não há rota de consulta ou listagem de depósitos. O acompanhamento é feito pelos webhooks `STABLECOIN_DEPOSIT_COMPLETED` e `STABLECOIN_DEPOSIT_FAILED` (veja [Webhooks](./stablecoin-webhooks.md)), que trazem o `correlationID` do depósito.

### Carteiras de depósito (INTERNAL float)

GET `/api/v1/stablecoin/wallets`

Retorna os endereços custodiados da subconta ligada ao `companyBankAccount` do AppID. Enviar USDT/USDC/BRLA on-chain para um desses endereços credita o float INTERNAL usado pelo payout.

Exige o escopo `STABLECOIN_SUBACCOUNT_LIST`.

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/stablecoin/wallets \
  --header 'Authorization: <SEU_APP_ID>'
```

```json
{
  "status": "ok",
  "companyBankAccountId": "682b62fe5afc2e15760223c5",
  "subAccountId": "b3e144dd-7d10-457c-9b85-033085722ed1",
  "wallets": [
    { "address": "0xa5A558fedfCeFa9ac2751649Fa21CA0279F216Ce", "currency": "USDT", "network": "POLYGON" },
    { "address": "TR54aGQPQghGDmHVuTQfSShP3ce8a6pCiT", "currency": "USDT", "network": "TRON" }
  ]
}
```

Para um `subAccountId` explícito: `GET /api/v1/stablecoin/subaccount/{subAccountId}/wallets`.

### Saldos do float INTERNAL

GET `/api/v1/stablecoin/subaccount/{subAccountId}/balances`

Retorna o saldo INTERNAL por ativo (unidade da moeda, não centavos). Faça poll após enviar on-chain para as wallets e só então chame o payout.

Exige o escopo `STABLECOIN_SUBACCOUNT_LIST`.

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/stablecoin/subaccount/b3e144dd-7d10-457c-9b85-033085722ed1/balances \
  --header 'Authorization: <SEU_APP_ID>'
```

```json
{
  "status": "ok",
  "subAccountId": "b3e144dd-7d10-457c-9b85-033085722ed1",
  "balances": { "USDT": 0.425458, "USDC": 0, "BRLA": 0 }
}
```

### Cotação de payout (USDT/USDC/BRLA → Pix)

GET `/api/v1/stablecoin/payout/quote`

Cota um **Pix alvo em BRL**, debitando float INTERNAL. `value` é em **centavos de BRL** (ex.: `10000` = R$ 100,00). A resposta traz quanto de `currency` será debitado (`inputAmount`).

Exige o escopo `STABLECOIN_PAYOUT_CREATE`.

```bash
curl --request GET \
  --url 'https://api.woovi.com/api/v1/stablecoin/payout/quote?value=10000&currency=USDT' \
  --header 'Authorization: <SEU_APP_ID>'
```

```json
{
  "status": "ok",
  "quote": {
    "basePrice": 5.12,
    "inputAmount": 19.68,
    "inputCurrency": "USDT",
    "outputAmount": 100,
    "outputCurrency": "BRL",
    "pairName": "USDTBRL"
  }
}
```

### Criar um payout (off-ramp para Pix)

POST `/api/v1/stablecoin/payout`

Cria o payout em `PENDING` (mesmo padrão do depósito): cota o **Pix alvo em BRL**, valida saldo INTERNAL, consome o limite **OUT** e resolve o beneficiário. O ticket do provedor **só é aberto no approve**.

Exige o escopo `STABLECOIN_PAYOUT_CREATE`.

| campo | tipo | obrigatório | descrição |
| --- | --- | --- | --- |
| `value` | number | sim | valor Pix alvo em **centavos de BRL** (ex.: `10000` = R$ 100,00) |
| `currency` | string | sim | `USDT` \| `USDC` \| `BRLA` — ativo INTERNAL a debitar |
| `pixKey` | string | sim | chave Pix de destino |
| `correlationId` | string | não | idempotência |
| `pixMessage` | string | não | mensagem Pix |

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/stablecoin/payout \
  --header 'Authorization: <SEU_APP_ID>' \
  --header 'content-type: application/json' \
  --data '{
    "value": 10000,
    "currency": "USDT",
    "pixKey": "thiago@entria.com.br",
    "correlationId": "payout-001"
  }'
```

```json
{
  "status": "PENDING",
  "payoutId": "6a721b1e3c785acfaebfa01c",
  "correlationId": "payout-001",
  "pixKey": "thiago@entria.com.br",
  "pixKeyOwner": {
    "name": "Marshall Bilderback",
    "taxId": "***.751.185-**",
    "bankName": "SICOOB"
  },
  "quote": {
    "inputAmount": 19.68,
    "inputCurrency": "USDT",
    "outputAmount": 100,
    "outputCurrency": "BRL",
    "rate": 5.12,
    "fee": 0.04
  }
}
```

### Aprovar um payout

POST `/api/v1/stablecoin/payout/approve`

Aprova um payout `PENDING` pelo `correlationId`, abre o ticket no provedor (debita INTERNAL e envia o Pix) e passa para `PROCESSING`.

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/stablecoin/payout/approve \
  --header 'Authorization: <SEU_APP_ID>' \
  --header 'content-type: application/json' \
  --data '{ "correlationId": "payout-001" }'
```

```json
{
  "status": "PROCESSING",
  "correlationId": "payout-001",
  "payoutId": "6a721b1e3c785acfaebfa01c"
}
```

### Consultar um payout

- `GET /api/v1/stablecoin/payout/{payoutId}`
- `GET /api/v1/stablecoin/payout?correlationId={correlationId}`

Enquanto não estiver terminal e já existir ticket, o status no provedor é relido (incluindo `PAID` → `COMPLETED`).

### Solicitar uma subconta (KYB)

POST `/api/v1/stablecoin/subaccount`

Solicita a criação de uma subconta de stablecoin para a empresa autenticada, reaproveitando os dados de KYC já presentes no `accountRegister` informado. A subconta no provedor é criada imediatamente e um registro `StableSubAccount` é persistido com status `IN_REVIEW` enquanto o KYB é processado.

O processamento do KYB é **assíncrono**: quando ele é resolvido, a empresa recebe um webhook `STABLECOIN_SUBACCOUNT_CONFIRMED` ou `STABLECOIN_SUBACCOUNT_REJECTED` (veja [Webhooks](./stablecoin-webhooks.md)). Somente após o `STABLECOIN_SUBACCOUNT_CONFIRMED` a subconta pode ser usada em `POST /api/v1/stablecoin/deposit`.

A rota é **idempotente** por `accountRegisterId`: uma chamada repetida retorna a subconta já existente (HTTP `200`), enquanto a primeira chamada (que cria) retorna HTTP `201`. Exige o escopo `STABLECOIN_SUBACCOUNT_CREATE`.

Body:

| campo | tipo | obrigatório | descrição |
| --- | --- | --- | --- |
| `accountRegisterId` | string | sim | id do `accountRegister` cujos dados de KYC serão usados no KYB |
| `companyBankAccountId` | string | não | conta bancária da empresa a vincular; usa a conta padrão da empresa quando omitida |

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/stablecoin/subaccount \
  --header 'Authorization: <SEU_APP_ID>' \
  --header 'content-type: application/json' \
  --data '{
    "accountRegisterId": "6650abc1234def567890aaaa"
  }'
```

Resposta (`201` na criação, `200` quando a subconta já existia):

```json
{
  "subAccountId": "sub_01HZ...",
  "status": "IN_REVIEW",
  "correlationId": "0f2c8d6a-1b3e-4f5a-9c7d-8e2a1b4c6d8f"
}
```

Erros comuns:

```json
{ "error": "accountRegisterId is required" }
{ "error": "INVALID_ACCOUNT_REGISTER_ID", "correlationId": "..." }
{ "error": "ACCOUNT_REGISTER_NOT_FOUND", "correlationId": "..." }
{ "error": "ACCOUNT_REGISTER_MISSING_OFFICIAL_NAME", "correlationId": "..." }
```

> Erros que o chamador pode corrigir (id inválido, `accountRegister` inexistente ou sem dados obrigatórios) retornam `400`. Falhas no provedor ou na persistência retornam `502` (ex.: `AVENIA_SUBACCOUNT_CREATE_FAILED`), indicando que a chamada pode ser repetida.

### Listar subcontas

GET `/api/v1/stablecoin/subaccount`

Lista as subcontas de stablecoin (registros de KYB) da empresa autenticada.

```json
{
  "status": "ok",
  "subAccounts": [
    {
      "id": "6650abc1234def567890aaaa",
      "subAccountId": "sub_01HZ...",
      "account": "6650def1234abc567890bbbb",
      "createdAt": "2026-06-05T12:00:00.000Z"
    }
  ]
}
```

### Buscar uma subconta

GET `/api/v1/stablecoin/subaccount/{subAccountId}`

```json
{
  "status": "ok",
  "subAccount": {
    "id": "6650abc1234def567890aaaa",
    "subAccountId": "sub_01HZ...",
    "account": "6650def1234abc567890bbbb",
    "createdAt": "2026-06-05T12:00:00.000Z"
  }
}
```

---

## Taxas

## Taxas do Stablecoin

O valor total de taxas de um depósito é composto por:

1. **Taxa Woovi** — por padrão **2%** sobre o valor do depósito.
2. **Taxas do provedor (on-chain / conversão)** — aplicadas pelo provedor de liquidação e detalhadas na cotação, por exemplo `In Fee` (taxa de entrada) e `Conversion Fee` (taxa de conversão).

A taxa Woovi padrão de 2% pode ser personalizada por ativo no contrato da sua subconta, definida como um percentual, com limites mínimo e máximo opcionais.

## Onde ver as taxas

### Na cotação

O endpoint [`GET /api/v1/stablecoin/quote`](./stablecoin-endpoints.md#cotação-quote) retorna a quebra das taxas do provedor em `appliedFees`:

```json
{
  "quote": {
    "basePrice": 5.25,
    "inputAmount": 100,
    "inputCurrency": "BRL",
    "outputAmount": 19.04,
    "outputCurrency": "USDT",
    "appliedFees": [
      { "type": "In Fee", "amount": 1.5, "currency": "BRL" },
      { "type": "Conversion Fee", "amount": 0.5, "currency": "BRL" }
    ],
    "pairName": "BRL/USDT"
  }
}
```

### No depósito

A resposta de [`POST /api/v1/stablecoin/deposit`](./stablecoin-endpoints.md#criar-um-depósito) traz, dentro de `quote`, o campo `fee` com o **total** das taxas (taxa Woovi + taxas do provedor), em centavos de BRL:

```json
{
  "quote": {
    "inputAmount": 10000,
    "inputCurrency": "BRL",
    "outputAmount": 18.45,
    "outputCurrency": "USDT",
    "rate": 5.42,
    "fee": 50
  }
}
```

> O `outputAmount` já é líquido das taxas — ou seja, é exatamente quanto de stablecoin o cliente recebe.

---

## Fluxo de depósito (on-ramp)

O fluxo de stablecoin segue a ideia de **criar um depósito e aprová-lo**: a aprovação debita o saldo em BRL da conta da sua empresa e entrega a stablecoin (USDT) na carteira de destino.

## Fluxograma

```mermaid
sequenceDiagram
    participant E as Sua Empresa
    participant W as Woovi
    participant B as Blockchain
    E->>W: GET /quote (opcional)
    W-->>E: Cotação (outputAmount, taxas)
    E->>W: POST /deposit
    W-->>E: depositId + correlationId + status PENDING
    E->>W: POST /deposit/approve
    Note over W: Debita o saldo BRL da conta da empresa
    W-->>E: status PROCESSING
    W->>B: Liquidação on-chain (entrega da stablecoin)
    B-->>W: txHash
    alt Sucesso
        W->>E: webhook STABLECOIN_DEPOSIT_COMPLETED (txHash)
    else Falha
        W->>E: webhook STABLECOIN_DEPOSIT_FAILED (reason, errorCode)
    end
```

### Contas, subcontas e limites

Cada empresa (**CONTA PJ**) tem uma **subconta de stablecoin** para comprar a stable, e **cada conta tem seus próprios limites**. Precisa de outra conta? Você pode criar uma nova CONTA PJ usando o nosso [**BaaS**](/docs/category/baas).

```mermaid
flowchart LR
  subgraph PJ1["CONTA PJ · limites próprios"]
    SA1["SubAccount<br/>comprar stable"]
  end
  BAAS(["BaaS: criar mais uma conta"])
  subgraph PJ2["CONTA PJ · limites próprios"]
    SA2["SubAccount<br/>comprar stable"]
  end
  PJ1 ==> BAAS ==> PJ2
  click BAAS "/docs/category/baas" "Documentação de BaaS"
```

### Recebendo via cobrança (exemplo)

Usando o fluxo normal de cobrança (charge) para receber o dinheiro do cliente e, em seguida, criar e aprovar o depósito de stablecoin:

```mermaid
flowchart LR
  A["Charge"] --> B["Pagamento recebido"] --> C["Depósito USDT criado"] --> D["Depósito USDT aprovado"] --> E["tx hash"]
```

## Pré-requisitos

1. Sua empresa precisa de uma subconta de stablecoin com status `CONFIRMED` (KYB aprovado). Veja [O que é o Stablecoin?](./stablecoin-what-is-it.md).
2. A conta da empresa precisa de **saldo em BRL** suficiente — a aprovação debita esse saldo para comprar a stablecoin.
3. Configure os [webhooks](./stablecoin-webhooks.md) para ser notificado quando o depósito concluir ou falhar. Os indispensáveis são:
   - `STABLECOIN_DEPOSIT_COMPLETED`
   - `STABLECOIN_DEPOSIT_FAILED`

## Passo a passo

### 1. (Opcional) Cotar o valor

Antes de criar o depósito, você pode consultar quanto de stablecoin o cliente receberá:

GET `/api/v1/stablecoin/quote?value=10000&currency=USDT`

A resposta traz `outputAmount`, `basePrice` e as taxas aplicadas (`appliedFees`). Útil para exibir a cotação na sua interface. A cotação fica em cache por 60 segundos.

### 2. Criar o depósito

POST `/api/v1/stablecoin/deposit`

```json
{
  "value": 10000,
  "currency": "USDT",
  "network": "POLYGON",
  "correlationId": "my-unique-id"
}
```

O depósito é criado com status `PENDING` e retorna `depositId`, `correlationId` e a `quote`. Guarde o `correlationId` — ele identifica o depósito nas próximas etapas.

### 3. Aprovar o depósito (comprar a stablecoin)

POST `/api/v1/stablecoin/deposit/approve`

```json
{ "correlationId": "my-unique-id" }
```

A aprovação **debita o saldo em BRL da conta da sua empresa** (a `companyBankAccount` da subconta), converte para stablecoin e envia para a carteira de destino. O status passa para `PROCESSING`. Não há cobrança Pix para um cliente pagar — o débito acontece na própria conta no momento da aprovação.

### 4. Acompanhar a conclusão

Quando a stablecoin é entregue na blockchain, você recebe o webhook `STABLECOIN_DEPOSIT_COMPLETED` (com o `txHash` da transação on-chain). Em caso de falha, recebe `STABLECOIN_DEPOSIT_FAILED`.

## Estados do depósito

O depósito percorre os seguintes status:

| Status | Significado |
| --- | --- |
| `CREATED` | Depósito recém-criado |
| `PENDING` | Criado; aguardando a aprovação |
| `PROCESSING` | Aprovado; liquidação on-chain em andamento |
| `COMPLETED` | Stablecoin entregue na blockchain (com `txHash`) |
| `FAILED` | Falhou em alguma etapa |

```mermaid
flowchart LR
  CREATED --> PENDING --> PROCESSING --> COMPLETED
  PENDING --> FAILED
  PROCESSING --> FAILED
```

---

## Limites

## Limites do Stablecoin

Os limites de stablecoin estão vinculados ao **KYB** (Know Your Business) da sua empresa e são validados a cada depósito.

## Subconta ativa (KYB)

Para criar qualquer depósito, sua empresa precisa de uma subconta de stablecoin com status `CONFIRMED`. Enquanto o KYB não estiver aprovado, a criação do depósito retorna `400`:

```json
{ "error": "Nenhuma subconta de stablecoin ativa. É necessário um KYB, entre em contato com o suporte." }
```

## Limite padrão

O limite padrão é de **R$ 120.000,00 por mês** (120k BRL/mês). A cada depósito, a Woovi valida o valor contra o limite disponível da sua conta; quando um depósito excede o limite, a requisição é rejeitada e o motivo é retornado na resposta de erro.

## Como aumentar o limite

Para aumentar o limite é necessário comunicar o suporte. Será necessário um **KYC estendido**, com informações referentes à capacidade financeira e comprovantes de endereço.

## Valor mínimo

O campo `value` do depósito deve ser um número positivo, em centavos de BRL. Valores inválidos retornam:

```json
{ "error": "value must be a positive number (in cents)" }
```

> Os valores exatos de limite dependem do nível de KYB da sua empresa. Para aumentar limites, entre em contato com o suporte.

---

## Fluxo de payout (off-ramp)

O fluxo de **payout** segue o mesmo padrão do [depósito](./stablecoin-flow.md): **criar** e depois **aprovar**. Você informa o **valor alvo em BRL**; na aprovação o float **INTERNAL** (USDT/USDC/BRLA) é debitado conforme a cotação e o Pix é enviado.

Ativos suportados na saída: `USDT`, `USDC`, `BRLA`.

## Fluxograma

```mermaid
sequenceDiagram
    participant E as Sua Empresa
    participant W as Woovi
    participant C as Blockchain / custodiante
    participant P as Pix
    E->>W: GET /wallets
    W-->>E: endereços INTERNAL (USDT/USDC/BRLA)
    E->>C: Envia stablecoin on-chain para o endereço
    C-->>W: Credita float INTERNAL
    E->>W: GET /subaccount/{id}/balances (opcional)
    W-->>E: saldo INTERNAL
    E->>W: GET /payout/quote (opcional, value em centavos BRL)
    W-->>E: Cotação (USDT a debitar, taxas)
    E->>W: POST /payout (value = Pix alvo em centavos BRL)
    Note over W: Quote BRL fixo · valida saldo · OUT limit · beneficiário
    W-->>E: payoutId + status PENDING
    E->>W: POST /payout/approve
    Note over W: Abre ticket · debita INTERNAL · envia Pix
    W-->>E: status PROCESSING
    alt Sucesso
        W->>P: Pix pago
        W->>E: webhook STABLECOIN_PAYOUT_COMPLETED
        opt Devolução (depois, se o Pix voltar)
            P->>W: Pix devolvido
            W->>E: webhook STABLECOIN_PAYOUT_REFUND_CONFIRMED / _FAILED
        end
    else Falha
        W->>E: webhook STABLECOIN_PAYOUT_FAILED
    end
```

### Contas, float INTERNAL e limites

Cada empresa (**CONTA PJ**) com KYB `CONFIRMED` tem uma **subconta** de stablecoin. O payout gasta apenas o saldo do float **INTERNAL** (endereços retornados por `GET /wallets`) — não o saldo da carteira smart wallet on-chain usada no depósito.

O valor do payout consome o limite Woovi **OUT** da conta. Precisa de outra conta? Use o [**BaaS**](/docs/category/baas).

```mermaid
flowchart LR
  A["Enviar USDT/USDC/BRLA<br/>para wallet INTERNAL"] --> B["Saldo INTERNAL"]
  B --> C["POST /payout"]
  C --> D["POST /payout/approve"]
  D --> E["Pix na chave destino"]
```

## Pré-requisitos

1. Subconta de stablecoin com status `CONFIRMED` (KYB aprovado). Veja [O que é o Stablecoin?](./stablecoin-what-is-it.md).
2. App com o escopo `STABLECOIN_PAYOUT_CREATE` (criar/consultar payout). Para listar wallets e saldos, também `STABLECOIN_SUBACCOUNT_LIST`.
3. **Saldo INTERNAL** suficiente no ativo que você vai gastar — financie os endereços de `GET /api/v1/stablecoin/wallets` antes.
4. Limite **OUT** disponível na conta.
5. Configure os [webhooks](./stablecoin-webhooks.md):
   - `STABLECOIN_PAYOUT_COMPLETED`
   - `STABLECOIN_PAYOUT_FAILED`
   - `STABLECOIN_PAYOUT_REFUND_CONFIRMED`
   - `STABLECOIN_PAYOUT_REFUND_FAILED`

## Passo a passo

### 1. Obter as carteiras INTERNAL

GET `/api/v1/stablecoin/wallets`

Retorna os endereços custodiados ligados ao `companyBankAccount` do App. Envie USDT/USDC/BRLA on-chain para o endereço da rede/ativo desejado.

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/stablecoin/wallets \
  --header 'Authorization: <SEU_APP_ID>'
```

```json
{
  "status": "ok",
  "companyBankAccountId": "682b62fe5afc2e15760223c5",
  "subAccountId": "b3e144dd-7d10-457c-9b85-033085722ed1",
  "wallets": [
    { "address": "0xa5A558fedfCeFa9ac2751649Fa21CA0279F216Ce", "currency": "USDT", "network": "POLYGON" },
    { "address": "TR54aGQPQghGDmHVuTQfSShP3ce8a6pCiT", "currency": "USDT", "network": "TRON" }
  ]
}
```

Guarde o `subAccountId` para consultar saldos.

### 2. (Opcional) Conferir o saldo

GET `/api/v1/stablecoin/subaccount/{subAccountId}/balances`

Os saldos vêm na **unidade da moeda** (não em centavos). Faça poll após o envio on-chain até o crédito aparecer.

```bash
curl --request GET \
  --url https://api.woovi.com/api/v1/stablecoin/subaccount/b3e144dd-7d10-457c-9b85-033085722ed1/balances \
  --header 'Authorization: <SEU_APP_ID>'
```

```json
{
  "status": "ok",
  "subAccountId": "b3e144dd-7d10-457c-9b85-033085722ed1",
  "balances": { "USDT": 0.425458, "USDC": 0, "BRLA": 0 }
}
```

### 3. (Opcional) Cotar o payout

GET `/api/v1/stablecoin/payout/quote?value=10000&currency=USDT`

`value` é o **Pix alvo em centavos de BRL** (ex.: `10000` = R$ 100,00). A resposta traz quanto de `currency` será debitado do float INTERNAL (`inputAmount`) e as taxas aplicadas.

```bash
curl --request GET \
  --url 'https://api.woovi.com/api/v1/stablecoin/payout/quote?value=10000&currency=USDT' \
  --header 'Authorization: <SEU_APP_ID>'
```

### 4. Criar o payout

POST `/api/v1/stablecoin/payout`

```json
{
  "value": 10000,
  "currency": "USDT",
  "pixKey": "thiago@entria.com.br",
  "correlationId": "payout-001",
  "pixMessage": "pagamento stablecoin"
}
```

Na criação a Woovi: cota com BRL fixo → valida saldo INTERNAL → consome o limite **OUT** (em BRL) → resolve o beneficiário Pix → persiste como `PENDING`. O ticket **ainda não** é aberto.

O `correlationId` é opcional e serve de **idempotência**: reutilizar o mesmo valor devolve o payout já criado.

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/stablecoin/payout \
  --header 'Authorization: <SEU_APP_ID>' \
  --header 'content-type: application/json' \
  --data '{
    "value": 10000,
    "currency": "USDT",
    "pixKey": "thiago@entria.com.br",
    "correlationId": "payout-001"
  }'
```

```json
{
  "status": "PENDING",
  "payoutId": "6a721b1e3c785acfaebfa01c",
  "correlationId": "payout-001",
  "pixKey": "thiago@entria.com.br",
  "pixKeyOwner": {
    "name": "Marshall Bilderback",
    "taxId": "***.751.185-**",
    "bankName": "SICOOB"
  },
  "quote": {
    "inputAmount": 19.68,
    "inputCurrency": "USDT",
    "outputAmount": 100,
    "outputCurrency": "BRL",
    "rate": 5.12,
    "fee": 0.04
  }
}
```

### 5. Aprovar o payout (enviar o Pix)

POST `/api/v1/stablecoin/payout/approve`

```json
{ "correlationId": "payout-001" }
```

A aprovação abre o ticket no provedor (debita o float INTERNAL e envia o Pix). O status passa para `PROCESSING`.

```bash
curl --request POST \
  --url https://api.woovi.com/api/v1/stablecoin/payout/approve \
  --header 'Authorization: <SEU_APP_ID>' \
  --header 'content-type: application/json' \
  --data '{ "correlationId": "payout-001" }'
```

### 6. Acompanhar a conclusão

Quando o Pix é pago, você recebe `STABLECOIN_PAYOUT_COMPLETED` (pode incluir `endToEndId`). Em falha, `STABLECOIN_PAYOUT_FAILED`. Detalhes em [Webhooks](./stablecoin-webhooks.md).

Um payout já liquidado ainda pode ser **devolvido** depois — o `status` continua `COMPLETED` e a devolução chega em `STABLECOIN_PAYOUT_REFUND_CONFIRMED` ou `STABLECOIN_PAYOUT_REFUND_FAILED`. Veja [Webhooks do payout](#webhooks-do-payout) abaixo.

Você também pode consultar a qualquer momento:

- GET `/api/v1/stablecoin/payout/{payoutId}`
- GET `/api/v1/stablecoin/payout?correlationId=payout-001`

Enquanto o payout não estiver terminal, a consulta relê o ticket no provedor e atualiza o status (incluindo `PAID` → `COMPLETED`).

## Webhooks do payout

O payout é **assíncrono**: o `POST /payout/approve` devolve `PROCESSING` e o resultado chega por webhook. Cadastre os quatro eventos — os dois primeiros fecham o payout, os dois últimos existem porque um Pix já pago ainda pode voltar dias depois.

| Evento | O que aconteceu | O que fazer |
| --- | --- | --- |
| `STABLECOIN_PAYOUT_COMPLETED` | O Pix saiu e foi pago | Dar baixa no pedido. `endToEndId` é o comprovante |
| `STABLECOIN_PAYOUT_FAILED` | O Pix **não** saiu | O float INTERNAL não foi gasto; leia `reason` / `errorCode` e reenvie se fizer sentido |
| `STABLECOIN_PAYOUT_REFUND_CONFIRMED` | O Pix saiu, voltou, e o valor está **disponível de novo** no seu saldo de stablecoin | Seguro reembolsar o seu cliente final |
| `STABLECOIN_PAYOUT_REFUND_FAILED` | O Pix saiu, voltou, mas o valor **não** está disponível para você | **Não** credite o cliente final; abra conciliação |

`FAILED` e `REFUND_*` são mutuamente exclusivos no mesmo payout: `FAILED` é o Pix que nunca saiu; `REFUND_*` é o Pix que saiu e voltou.

### Concilie pelo correlationID

Todos os eventos trazem `stablePayout.correlationID` — o mesmo `correlationId` que você enviou no `POST /payout`. É por ele que você acha o pedido do seu lado; o `stablePayout.id` é o id interno da Woovi.

A entrega é **at least once**: um mesmo evento pode chegar mais de uma vez. Trate cada handler como idempotente — nos eventos de devolução, o campo de deduplicação é `refund.providerTicketId` (o ticket da devolução, não o do payout).

### A devolução não muda o status do payout

Quando um payout liquidado volta, o `stablePayout.status` **continua `COMPLETED`** — o Pix realmente saiu, e voltar o status atrás quebraria a máquina de estados que você construiu em cima do `STABLECOIN_PAYOUT_COMPLETED`. O que voltou vem em um bloco `refund` à parte:

```json
{
  "event": "STABLECOIN_PAYOUT_REFUND_CONFIRMED",
  "stablePayout": {
    "id": "6a721b1e3c785acfaebfa01c",
    "status": "COMPLETED",
    "inputAmount": 3379,
    "inputCurrency": "BRLA",
    "outputAmount": 33.73,
    "outputCurrency": "BRL",
    "pixKey": "thiago@entria.com.br",
    "endToEndId": "E123...",
    "correlationID": "payout-001"
  },
  "company": { "name": "Acme Corp" },
  "refund": {
    "status": "CONFIRMED",
    "amount": 3379,
    "currency": "BRLA",
    "destination": "SUBACCOUNT_BALANCE",
    "providerTicketId": "9a1c4f7e-2b83-4d55-9c0e-1f6a2d3b4c5d",
    "refundEndToEndId": "E54811417202608251402",
    "refundedAt": "2026-08-25T14:02:41.318Z"
  }
}
```

Dois campos costumam ser lidos errado:

- **`refund.amount` está em centavos de `refund.currency`** — o ativo de entrada, a mesma unidade do `stablePayout.inputAmount`. Não é o `outputAmount` em BRL.
- **`refund.destination`** diz se o dinheiro é seu de novo: só `SUBACCOUNT_BALANCE` é sacável por você. `MAIN_BALANCE` significa que o crédito caiu fora da sua subconta e precisa de intervenção manual; `NONE`, que nada foi creditado.

Payloads completos de todos os eventos, incluindo o de falha: [Webhooks de Stablecoin](./stablecoin-webhooks.md).

## Estados do payout

| Status | Significado |
| --- | --- |
| `PENDING` | Criado; aguardando aprovação |
| `PROCESSING` | Aprovado; ticket / Pix em andamento |
| `COMPLETED` | Pix pago com sucesso |
| `FAILED` | Falhou em alguma etapa |

A devolução de um payout liquidado **não** é um status: o payout segue `COMPLETED` e o retorno aparece no bloco `refund`. Veja [Webhooks do payout](#webhooks-do-payout).

```mermaid
flowchart LR
  PENDING --> PROCESSING --> COMPLETED
  PENDING --> FAILED
  PROCESSING --> FAILED
```

## Referência rápida

| Etapa | Método | Rota | Escopo |
| --- | --- | --- | --- |
| Carteiras | GET | `/api/v1/stablecoin/wallets` | `STABLECOIN_SUBACCOUNT_LIST` |
| Saldos | GET | `/api/v1/stablecoin/subaccount/{id}/balances` | `STABLECOIN_SUBACCOUNT_LIST` |
| Cotação | GET | `/api/v1/stablecoin/payout/quote` | `STABLECOIN_PAYOUT_CREATE` |
| Criar | POST | `/api/v1/stablecoin/payout` | `STABLECOIN_PAYOUT_CREATE` |
| Aprovar | POST | `/api/v1/stablecoin/payout/approve` | `STABLECOIN_PAYOUT_CREATE` |
| Consultar | GET | `/api/v1/stablecoin/payout/{payoutId}` | `STABLECOIN_PAYOUT_CREATE` |

Detalhes dos payloads: [Endpoints](./stablecoin-endpoints.md).

---

## Webhooks

## Webhooks do Stablecoin

Os webhooks notificam sua aplicação sobre o resultado do depósito e do payout de stablecoin. Caso ainda não saiba como cadastrar webhooks na plataforma, veja o nosso [tutorial](../webhook/platform/webhook-platform-api.mdx).

### Depósito (on-ramp)

| Evento | Quando ocorre |
| --- | --- |
| `STABLECOIN_DEPOSIT_COMPLETED` | A stablecoin foi entregue na blockchain |
| `STABLECOIN_DEPOSIT_FAILED` | O depósito falhou em alguma etapa |

O objeto enviado contém `stableDeposit` (os dados do depósito) e `company` (sua empresa). O campo `correlationID` corresponde ao identificador único que você enviou ao criar o depósito.

### STABLECOIN_DEPOSIT_COMPLETED

Disparado quando a stablecoin é entregue com sucesso na carteira de destino. O campo `txHash` traz o hash da transação on-chain.

```json
{
  "event": "STABLECOIN_DEPOSIT_COMPLETED",
  "stableDeposit": {
    "id": "6650abc1234def567890aaaa",
    "status": "COMPLETED",
    "inputAmount": 10000,
    "inputCurrency": "BRL",
    "outputAmount": 18.45,
    "outputCurrency": "USDT",
    "txHash": "0x587a660fe5349113801ec77fa6f79ae096e53a67bfa7f9098f096d1b9575fa53",
    "correlationID": "my-unique-id",
    "completedAt": "2026-06-05T12:00:00.000Z"
  },
  "company": {
    "name": "Acme Corp"
  }
}
```

### STABLECOIN_DEPOSIT_FAILED

Disparado quando o depósito falha. Os campos `reason` e `errorCode` indicam o motivo.

```json
{
  "event": "STABLECOIN_DEPOSIT_FAILED",
  "stableDeposit": {
    "id": "6650abc1234def567890aaaa",
    "status": "FAILED",
    "inputAmount": 10000,
    "inputCurrency": "BRL",
    "outputCurrency": "USDT",
    "correlationID": "my-unique-id",
    "failedAt": "2026-06-05T12:00:00.000Z"
  },
  "company": {
    "name": "Acme Corp"
  },
  "reason": "Deposit failed",
  "errorCode": "DEPOSIT-FAILED"
}
```

## Webhooks do Payout (off-ramp)

Quando você cria um payout via `POST /api/v1/stablecoin/payout`, o resultado final chega por webhook:

| Evento | Quando ocorre |
| --- | --- |
| `STABLECOIN_PAYOUT_COMPLETED` | O Pix foi pago / ticket do provedor em estado terminal de sucesso |
| `STABLECOIN_PAYOUT_FAILED` | O payout falhou — o Pix **não** saiu |
| `STABLECOIN_PAYOUT_REFUND_CONFIRMED` | O Pix saiu, voltou, e o valor está **disponível de novo** no seu saldo de stablecoin |
| `STABLECOIN_PAYOUT_REFUND_FAILED` | O Pix saiu, voltou, mas o valor **não** está disponível para você |

O objeto enviado contém `stablePayout` e `company`. O campo `correlationID` corresponde ao `correlationId` enviado na criação.

### STABLECOIN_PAYOUT_COMPLETED

```json
{
  "event": "STABLECOIN_PAYOUT_COMPLETED",
  "stablePayout": {
    "id": "6a721b1e3c785acfaebfa01c",
    "status": "COMPLETED",
    "inputAmount": 100,
    "inputCurrency": "USDT",
    "outputAmount": 5.08,
    "outputCurrency": "BRL",
    "pixKey": "thiago@entria.com.br",
    "endToEndId": "E123...",
    "correlationID": "payout-001",
    "completedAt": "2026-08-04T17:10:00.000Z"
  },
  "company": {
    "name": "Acme Corp"
  }
}
```

### STABLECOIN_PAYOUT_FAILED

```json
{
  "event": "STABLECOIN_PAYOUT_FAILED",
  "stablePayout": {
    "id": "6a721b1e3c785acfaebfa01c",
    "status": "FAILED",
    "inputAmount": 100,
    "inputCurrency": "USDT",
    "outputCurrency": "BRL",
    "pixKey": "thiago@entria.com.br",
    "correlationID": "payout-001",
    "failedAt": "2026-08-04T17:10:00.000Z"
  },
  "company": {
    "name": "Acme Corp"
  },
  "reason": "Payout failed",
  "errorCode": "PAYOUT-FAILED"
}
```

### Devolução de um payout já liquidado

Um payout liquidado pode voltar — o recebedor devolve o Pix, ou o banco dele rejeita o crédito. Nesse caso o `status` do payout **continua `COMPLETED`**: o Pix realmente saiu, e reverter o status quebraria a máquina de estados que você já construiu em cima do `STABLECOIN_PAYOUT_COMPLETED`. A devolução chega como um evento novo, com um bloco `refund`.

`FAILED` e `REFUND_*` são mutuamente exclusivos no mesmo payout: `FAILED` significa que o Pix nunca saiu; `REFUND_*` significa que saiu e voltou.

Campos do bloco `refund`:

| Campo | Descrição |
| --- | --- |
| `status` | `CONFIRMED` ou `FAILED` — se o valor devolvido está disponível para você |
| `amount` | Em centavos de `currency`, a mesma unidade do `stablePayout.inputAmount` — **nunca** o `outputAmount` em BRL |
| `currency` | O ativo de entrada do payout, ex.: `BRLA`, `USDT` |
| `destination` | `SUBACCOUNT_BALANCE` (sacável por você), `MAIN_BALANCE` (creditado fora da sua subconta, precisa de intervenção manual) ou `NONE` (nada foi creditado) |
| `providerTicketId` | O ticket **da devolução**, não o do payout original. Use como chave de idempotência: uma reentrega repete o mesmo valor |
| `originalProviderTicketId` | O ticket do payout original, quando o provedor informa |
| `reason` | Motivo informado pelo provedor |
| `refundEndToEndId` | O `endToEndId` da devolução Pix, quando existe |
| `failureReason` | Só em `REFUND_FAILED`: por que o valor não está disponível |
| `refundedAt` | Quando a devolução foi registrada |

### STABLECOIN_PAYOUT_REFUND_CONFIRMED

O valor voltou e está disponível de novo no seu saldo de stablecoin — é seguro reembolsar o seu cliente final.

```json
{
  "event": "STABLECOIN_PAYOUT_REFUND_CONFIRMED",
  "stablePayout": {
    "id": "6a721b1e3c785acfaebfa01c",
    "status": "COMPLETED",
    "inputAmount": 3379,
    "inputCurrency": "BRLA",
    "outputAmount": 33.73,
    "outputCurrency": "BRL",
    "pixKey": "thiago@entria.com.br",
    "endToEndId": "E123...",
    "correlationID": "payout-001"
  },
  "company": {
    "name": "Acme Corp"
  },
  "refund": {
    "status": "CONFIRMED",
    "amount": 3379,
    "currency": "BRLA",
    "destination": "SUBACCOUNT_BALANCE",
    "providerTicketId": "9a1c4f7e-2b83-4d55-9c0e-1f6a2d3b4c5d",
    "originalProviderTicketId": "018f2b2c-9a4d-4a6f-b0d5-7c9f1e2a3b44",
    "reason": "payout reversed - original ticket id: 018f2b2c-9a4d-4a6f-b0d5-7c9f1e2a3b44",
    "refundEndToEndId": "E54811417202608251402",
    "refundedAt": "2026-08-25T14:02:41.318Z"
  }
}
```

### STABLECOIN_PAYOUT_REFUND_FAILED

O valor voltou, mas **não** está disponível para você: ou a própria devolução não se concretizou, ou o crédito caiu fora da sua subconta. **Não credite o seu cliente final** — o caso precisa de conciliação.

```json
{
  "event": "STABLECOIN_PAYOUT_REFUND_FAILED",
  "stablePayout": {
    "id": "6a721b1e3c785acfaebfa01c",
    "status": "COMPLETED",
    "inputAmount": 3379,
    "inputCurrency": "BRLA",
    "outputAmount": 33.73,
    "outputCurrency": "BRL",
    "pixKey": "thiago@entria.com.br",
    "endToEndId": "E123...",
    "correlationID": "payout-001"
  },
  "company": {
    "name": "Acme Corp"
  },
  "refund": {
    "status": "FAILED",
    "amount": 3379,
    "currency": "BRLA",
    "destination": "NONE",
    "providerTicketId": "9a1c4f7e-2b83-4d55-9c0e-1f6a2d3b4c5d",
    "originalProviderTicketId": "018f2b2c-9a4d-4a6f-b0d5-7c9f1e2a3b44",
    "failureReason": "returned funds not available in the sub-account balance",
    "refundedAt": "2026-08-25T14:02:41.318Z"
  }
}
```

## Webhooks da Subconta (KYB)

Quando você solicita uma subconta de stablecoin (KYB) via `POST /api/v1/stablecoin/subaccount`, ela é criada com status `IN_REVIEW` enquanto a análise é processada. O resultado **não é síncrono**: assim que o KYB é resolvido pelo provedor, sua aplicação recebe um destes eventos.

| Evento | Quando ocorre |
| --- | --- |
| `STABLECOIN_SUBACCOUNT_CONFIRMED` | O KYB foi aprovado e a subconta está apta a receber depósitos |
| `STABLECOIN_SUBACCOUNT_REJECTED` | O KYB foi recusado; a subconta não pode operar |

O objeto enviado contém `stableSubAccount` (os dados da subconta) e `company` (sua empresa). Use o campo `stableSubAccount.id` para conciliar com o `subAccountId` retornado na criação.

### STABLECOIN_SUBACCOUNT_CONFIRMED

Disparado quando o KYB é aprovado. A partir deste momento a subconta tem `status: "CONFIRMED"` e pode ser usada em `POST /api/v1/stablecoin/deposit`. O campo `confirmedAt` traz o instante da confirmação.

```json
{
  "event": "STABLECOIN_SUBACCOUNT_CONFIRMED",
  "stableSubAccount": {
    "id": "6650abc1234def567890aaaa",
    "status": "CONFIRMED",
    "subAccountId": "sub_01HZ...",
    "accountRegisterId": "6650def1234abc567890bbbb",
    "confirmedAt": "2026-06-05T12:00:00.000Z"
  },
  "company": {
    "id": "6650aaa1234bbb567890cccc",
    "name": "Acme Corp",
    "taxID": "12345678000199"
  }
}
```

### STABLECOIN_SUBACCOUNT_REJECTED

Disparado quando o KYB é recusado. Os campos opcionais `reason` e `rejectionLabels` indicam o motivo da recusa, quando disponíveis.

```json
{
  "event": "STABLECOIN_SUBACCOUNT_REJECTED",
  "stableSubAccount": {
    "id": "6650abc1234def567890aaaa",
    "status": "REJECTED",
    "subAccountId": "sub_01HZ...",
    "accountRegisterId": "6650def1234abc567890bbbb",
    "rejectedAt": "2026-06-05T12:00:00.000Z"
  },
  "company": {
    "id": "6650aaa1234bbb567890cccc",
    "name": "Acme Corp",
    "taxID": "12345678000199"
  },
  "reason": "Document verification failed",
  "rejectionLabels": ["INVALID_DOCUMENT"]
}
```

---

## O que é o Stablecoin?

O Stablecoin da Woovi permite que sua empresa converta reais (BRL) em stablecoins — como **USDT** e **USDC**. A partir do saldo em BRL da conta da sua empresa, o valor é entregue, já convertido, em stablecoin na carteira de destino, na rede escolhida.

É ideal para quem precisa de saldo em dólar digital de forma simples.

:::warning Aviso importante
Os serviços de ativos virtuais são prestados pelas **PSAVs** (Prestadoras de Serviços de Ativos Virtuais) parceiras da Woovi. A Woovi não realiza custódia ou liquidação de ativos virtuais.

Verifique o endereço da carteira de destino com atenção. Após a confirmação, a operação é **irreversível** e não pode ser reembolsada.
:::

## Funcionamento

O funcionamento é composto por 2 etapas principais:

1. **Criar um depósito**
2. **Aprovar o depósito (compra do USDT)**, que debita o saldo em BRL da conta, dispara a liquidação on-chain e entrega a stablecoin

Resumindo: você cria um depósito e o aprova; a Woovi debita o saldo em BRL da conta da empresa, converte em stablecoin e envia para a carteira de destino na blockchain.

## Stablecoins e redes suportadas

Nem todo ativo está disponível em todas as redes. A matriz suportada é:

| Stablecoin | Redes |
| --- | --- |
| `USDT` | `POLYGON`, `ETHEREUM`, `CELO`, `TRON` |
| `USDC` | `POLYGON`, `ETHEREUM`, `BASE`, `CELO` |

Quando o campo `network` é omitido, o padrão é `POLYGON`. Enviar uma combinação de ativo/rede fora da matriz acima retorna `400`.

## Pré-requisito: KYB

Para criar depósitos, sua empresa precisa ter uma **subconta de stablecoin** com status `CONFIRMED`, ou seja, com o KYB (Know Your Business) aprovado — parte da infraestrutura de [BaaS](/docs/category/baas) da Woovi. Sem uma subconta ativa, a criação do depósito é rejeitada com `400` e a mensagem:

```json
{ "error": "Nenhuma subconta de stablecoin ativa. É necessário um KYB, entre em contato com o suporte." }
```

Para iniciar o processo de KYB, entre em contato com o suporte.

## Próximos passos

- [Endpoints](./stablecoin-endpoints.md) — todas as rotas da API
- [Fluxo passo a passo](./stablecoin-flow.md) — do depósito à entrega on-chain
- [Fluxo de payout (off-ramp)](./stablecoin-payout-flow.md) — do float INTERNAL ao Pix
- [Webhooks](./stablecoin-webhooks.md) — como ser notificado
- [Taxas](./stablecoin-fees.md)
- [Limites](./stablecoin-limits.md)

---

## Como criar uma integração vinculada à uma subconta

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info
Para a utilização desta funcionalidade é necessário possuir a funcionalidade Subconta
:::

Existem algumas situações em que você precisa destinar todo o montante de uma aplicação para uma subconta. Em vez de precisar fazer vários splits ou especificar a subconta de destino nas requisições, você pode criar uma aplicação que fará isso automaticamente para você.

Para isso, basta seguir estes passos:

1. Acesse a seção API / Plugins.

![1](./__assets__/how-to-create-a-integration-with-a-subaccount-1.png)

2. Em seguida, clique em Nova API/Plugin.

![2](./__assets__/how-to-create-a-integration-with-a-subaccount-2.png)

3. Preencha com o nome que você deseja identificar seu integração.

![3](./__assets__/how-to-create-a-integration-with-a-subaccount-3.png)

4. Selecione a subconta que você deseja atrelar ao seu integração.

![4](./__assets__/how-to-create-a-integration-with-a-subaccount-4.png)

Selecione a subconta que você deseja que vincular com essa integração.

![5](./__assets__/how-to-create-a-integration-with-a-subaccount-5.png)

Por último, salve para efetuar a criação da integração.

![6](./__assets__/how-to-create-a-integration-with-a-subaccount-6.png)

Prontinho! Agora você tem um integração vinculada à uma subconta.

---

## Como criar uma subconta

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info
Para a utilização desta funcionalidade é necessário possuir a funcionalidade Subconta
:::

Atualmente a criação de uma subconta é feita apenas via API. Para isso você pode está utilizando o _endpoint_ `/api/v1/subaccount` da API.

Você pode acessar [aqui](/api#tag/subaccount)/paths/~1api~1v1~1subaccount/post)
a documentação referente a esse _endpoint_.

Os campos obrigatórios para criar uma subconta são os seguintes:

- **`name`**: O nome de identificação da subconta.
- **`pixKey`**: A chave PIX da subconta (Não precisa ser necessariamente atrelada a uma conta da woovi).

A chave PIX será checada antes de criar a subconta. Caso a chave não exista, a subconta não será criada e uma mensagem de erro será retornada.

### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/subaccount' -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "Authorization": "app_id"
      --data-binary '{"name":"subaccount#1","pixKey": "destinatario@woovi.com.br"}'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/subaccount', {
  method: 'POST',
  body: JSON.stringify({
    name: "subaccount#1",
    pixKey: "destinatario@woovi.com.br"
  }),
  headers: {
    Authorization: 'app_id',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como usar a API para criar uma cobrança com split para Subconta?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para criar uma cobrança Pix com split para sub conta, você utiliza o _endpoint_ `/api/v1/charge` da API.

Você pode acessar [aqui](/api#tag/charge/POST/api/v1/charge)
a documentação referente a esse _endpoint_.

Os campos obrigatórios para criar uma cobrança Pix com Split são os seguintes:

- **`value`**: O valor em centavos da cobrança Pix a ser criado.
- **`correlationID`**: Um identificador único para a cobrança Pix. [CorrelationID](../concepts/correlation-id)
- **`splits`**: Um array contendo as configurações de split realizado na hora do recebimento.

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "value": 100,
  "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
  "splits": [
    {
      "pixKey": "destinatario@woovi.com.br",
      "value": 15,
      "splitType": "SPLIT_SUB_ACCOUNT"
    }
  ]
}
```

O valor do campo `value` dentro do objeto no array de `splits`, é o valor desejado para a realização do split em **centavos**. O valor do split não será debitado da conta de origem pois transações de split para sub contas são transações virtuais, somente será debitado da conta de origem o valor integral do saldo da sub conta no momento do saque da mesma.

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, além dos campos normais de cobrança criada, retornaremos os seguintes campos:

```json
{
  "charge": {
    ...Charge Payload
    "splits": [
      { "pixKey": "destinatario@woovi.com.br", "value": 15, splitType: "SPLIT_SUB_ACCOUNT" },
    ]
  },
  "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a",
  "brCode": "00020101021226990014br.gov.bcb.pix2577pix-h.bpp.com.br/23114447/qrs1/v2/011Q0PuArnNb5VzolFm8H9X0A7yQb5Ayi6wZ2Koj6RX52040000530398654043.335802BR5911Krusty_Krab6009Sao_Paulo62290525cac964d74db74c479add4eabc63047932"
}
```

### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/charge' -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      -H "Authorization": "app_id"
      --data-binary '{"correlationID":"c782e0ac-833d-4a89-9e73-9b60b2b41d3a","value":100, "splits": [{ "pixKey": "destinatario@woovi.com.br", "value": 15, splitType:"SPLIT_SUB_ACCOUNT"  }]}'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/charge', {
  method: 'POST',
  body: JSON.stringify({
    value: 100,
    correlationID: 'c782e0ac-833d-4a89-9e73-9b60b2b41d3a',
    splits: [
      {
        pixKey: 'destinatario@woovi.com.br',
        value: 15,
        splitType: 'SPLIT_SUB_ACCOUNT',
      },
    ],
  }),
  headers: {
    Authorization: 'app_id',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como usar o Plugin JS para criar uma cobrança com split para Subconta?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info
Para a utilização desta funcionalidade é necessário possuir a funcionalidade Subconta
:::

Para criar uma cobrança Pix com split para sub conta, você precisa informar no plugin.js o array de splits a serem realizados na cobrança.

Os campos obrigatórios para criar uma cobrança Pix com Split são os seguintes:

- **`value`**: O valor em `centavos` da cobrança Pix a ser criado.
- **`correlationID`**: Um identificador único para a cobrança Pix. [CorrelationID](../concepts/correlation-id)
- **`splits`**: Um array contendo as configurações de split realizado na hora do recebimento.

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```javascript
function displaywooviModal() {
  window.$woovi = window.$woovi || [];

  window.$woovi.push([
    'config',
    {
      appID: 'yourwooviAppId',
    },
  ]);

  window.$woovi.push([
    'pix',
    {
      value: 100, // R$ 1,00
      correlationID: 'c782e0ac-833d-4a89-9e73-9b60b2b41d3a',
      splits: [
        {
          pixKey: 'destinatario@woovi.com.br', // chave pix da subconta
          value: 15, // valor a ser splitado em centavos (R$ 0,15)
          splitType: 'SPLIT_SUB_ACCOUNT', // tipo de split (não alterar)
        },
      ],
    },
  ]);
}
```

O valor do campo `value` dentro do objeto no array de `splits`, é o valor desejado para a realização do split em **centavos**. O valor do split não será debitado da conta de origem pois transações de split para sub contas são transações virtuais, somente será debitado da conta de origem o valor integral do saldo da sub conta no momento do saque da mesma.

Após efetuar a requisição, se tudo ocorreu bem, o plugin exibirá normalmente o qrcode. Caso haja algum erro sintático(formato) no array de splits irá exibir um erro no modal do plugin.

### Exemplos em código

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Open Pix</title>
  </head>
  <body>
    <button id="btn">Pagar com pix</button>
    <script
      src="https://plugin.woovi.com.br/v1/woovi.js"
      allow="clipboard-read; clipboard-write"
    ></script>
    <script>
      const appID = 'seuAppId';

      window.$woovi = window.$woovi ?? [];
      window.$woovi.push(['config', { appID }]);

      const correlationID = Math.floor(Math.random() * 1000000000);

      document.getElementById('btn').addEventListener('click', () => {
        window.$woovi.push([
          'pix',
          {
            value: 10000, // R$ 100,00
            correlationID: correlationID, // no seu sistema, use um identificador único
            description: 'woovi Demo',
            splits: [
              {
                value: 5000, // R$ 50,00
                pixKey: 'email@email.com', // chave pix que receberá R$ 50,00
                splitType: 'SPLIT_SUB_ACCOUNT', // tipo do split, não mexer
              },
            ],
          },
        ]);
      });
    </script>
  </body>
</html>
```

---

## Como acessar saldo e detalhes de uma Subconta via API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info
Para a utilização desta funcionalidade é necessário possuir a funcionalidade Subconta
:::

Para acessar o saldo e detalhes de uma subconta, você utiliza o _endpoint_ `/api/v1/subaccount/{ID}` da API.

Você pode acessar aqui
a documentação referente a esse _endpoint_.

A chave pix registrada na subconta deve ser passada na url da requisição como parâmetro.

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, uma objeto contendo os campos de balance, name, pixKey da subconta requisitada.

### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/subaccount/chave-pix-subconta -X GET \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      -H "Authorization": "app_id"
```

  
  

```js
fetch('https://api.woovi.com/api/v1/subaccount/chave-pix-subconta', {
  method: 'GET',
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

  

### Exemplos de resposta

```jsx
{
  "SubAccount": {
    "name": "test-sub-account",
    "pixKey": "c4249323-b4ca-43f2-8139-8232aab09b93",
    "balance": 100
  }
}
```

---

## Como usar a API listar  as Subcontas de uma empresa via API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info
Para a utilização desta funcionalidade é necessário possuir a funcionalidade Subconta
:::

Para listar subcontas de uma empersa, você utiliza o _endpoint_ `/api/v1/subaccount` da API.

Você pode acessar [aqui](/api#tag/subaccount)/paths/~1api~1v1~1subaccount/get)
a documentação referente a esse _endpoint_.

A empresa é identificada a partir do app_id usado no cabeçalho Authorization.

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, uma lista das subcontas pertencentes a empresa
além de detalhes de paginação:

### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/subaccount' -X GET \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      -H "Authorization": "app_id"
```

  
  

```js
fetch('https://api.woovi.com/api/v1/subaccount', {
  method: 'GET',
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

  

### Exemplos de resposta

```jsx
{
  "subAccounts": {
    "subaccount": {
      "name": "test-sub-account",
      "pixKey": "c4249323-b4ca-43f2-8139-8232aab09b93",
    }
  },
  "pageInfo": {
    "skip": 0,
    "limit": 10,
    "totalCount": 20,
    "hasPreviousPage": false,
    "hasNextPage": true
  }
}
```

---

## Como fazer uma transferência entre subcontas?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info
Para a utilização desta funcionalidade é necessário possuir a funcionalidade Subconta
:::

Para realizar uma transferência entre subcontas da mesma empresa, você utiliza o _endpoint_ `/api/v1/subaccount/transfer` da API.

Você pode acessar [aqui](</api#tag/subaccount)/paths/~1api~1v1~1subaccount~1transfer/post>)
a documentação referente a esse _endpoint_.

Os campos obrigatórios para fazer uma transferência entre subcontas são os seguintes:

- **`value`**: O valor em centavos da cobrança Pix a ser criado.
- **`fromPixKey`**: A chave Pix da subconta que irá realizar a transferência.
- **`fromPixKeyType`**: O tipo da chave Pix da subconta que irá realizar a transferência.
- **`toPixKey`**: A chave Pix da subconta que receberá a transferência.
- **`toPixKeyType`**: O tipo da chave Pix da subconta que receberá a transferência.

Existe também a possibilidade de adicionar os seguintes campos (opcionais):

- **`correlationID`**: Um identificador único para cada transferência. [CorrelationID](../concepts/correlation-id)

:::info
Lembrando que o `correlationID` é um campo opcional, caso você não o envie, fazermos a geração internamente.
:::

### Exemplo

O body da sua requisição será semelhante a este exemplo:

```js
{
  value: 65,
  fromPixKey: 'pixKey@pixKey.com',
  fromPixKeyType: 'EMAIL',
  toPixKey: 'mediator@pixKey.com',
  toPixKeyType: 'EMAIL',
}
```

### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/subaccount/transfer' -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      --data-binary '{
        "value": 65,
        "fromPixKey": "pixKey@pixKey.com",
        "fromPixKeyType": "EMAIL",
        "toPixKey": "mediator@pixKey.com",
        "toPixKeyType": "EMAIL"
      }'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/charge', {
  method: 'POST',
  body: JSON.stringify({
    value: 65,
    fromPixKey: 'pixKey@pixKey.com',
    fromPixKeyType: 'EMAIL',
    toPixKey: 'mediator@pixKey.com',
    toPixKeyType: 'EMAIL',
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como reconhecer uma subconta de uma cobrança paga?

:::info
Para a utilização desta funcionalidade é necessário possuir a funcionalidade Subconta
:::

A forma mais recomendada para reconhecer uma subconta de uma cobrança após o pagamento em tempo real é utilizando o nosso Webhook de cobrança paga. Nele é retornado todas as informações da cobrança, inclusive a subconta, caso a cobrança esteja atrelada à uma. Segue o exemplo do payload retornado pelo Webhook de uma cobrança atrelada à uma subconta:

```json
{
  "event": "OPENPIX:CHARGE_COMPLETED",
  "charge": {
    "customer": {
      "name": "CONTA DE PAGAMENTO DE PIX",
      "taxID": {
        "taxID": "74866698000169",
        "type": "BR:CNPJ"
      },
      "correlationID": "<correlationID>"
    },
    "value": 1600,
    "comment": "from-script-api",
    "identifier": "a74f60ba44e54c67b2cb74243971a674",
    "correlationID": "<correlationID>",
    "paymentLinkID": "<paymentLinkID>",
    "transactionID": "a74f60ba44e54c67b2cb74243971a674",
    "status": "COMPLETED",
    "additionalInfo": [],
    "discount": 0,
    "valueWithDiscount": 1600,
    "expiresDate": "2024-03-16T18:19:44.426Z",
    "type": "DYNAMIC",
    "createdAt": "2024-03-15T18:19:50.296Z",
    "updatedAt": "2024-03-15T18:22:04.045Z",
    "paidAt": "2024-03-15T18:19:50.154Z",
    "payer": {
      "name": "CONTA DE PAGAMENTO DE PIX",
      "taxID": {
        "taxID": "74866698000169",
        "type": "BR:CNPJ"
      },
      "correlationID": "<correlationID>"
    },
    "brCode": "<brCode>",
    "subaccount": {
      "name": "mediatorpix@key.com",
      "pixKey": "mediatorpix@key.com"
    },
    "expiresIn": 86400,
    "pixKey": "<pixKey>",
    "paymentLinkUrl": "<paymentLinkUrl>",
    "qrCodeImage": "<qrCodeImage>",
    "globalID": "<globalID>"
  },
  "pix": {
    "customer": {
      "name": "CONTA DE PAGAMENTO DE PIX",
      "taxID": {
        "taxID": "74866698000169",
        "type": "BR:CNPJ"
      },
      "correlationID": "<correlationID>"
    },
    "payer": {
      "name": "CONTA DE PAGAMENTO DE PIX",
      "taxID": {
        "taxID": "74866698000169",
        "type": "BR:CNPJ"
      },
      "correlationID": "<correlationID>"
    },
    "charge": {
      "customer": {
        "name": "CONTA DE PAGAMENTO DE PIX",
        "taxID": {
          "taxID": "74866698000169",
          "type": "BR:CNPJ"
        },
        "correlationID": "<correlationID>"
      },
      "value": 1600,
      "comment": "from-script-api",
      "identifier": "a74f60ba44e54c67b2cb74243971a674",
      "correlationID": "<correlationID>",
      "paymentLinkID": "<paymentLinkID>",
      "transactionID": "a74f60ba44e54c67b2cb74243971a674",
      "status": "COMPLETED",
      "additionalInfo": [],
      "fee": 50,
      "discount": 0,
      "valueWithDiscount": 1600,
      "expiresDate": "2024-03-16T18:19:44.426Z",
      "type": "DYNAMIC",
      "createdAt": "2024-03-15T18:19:50.296Z",
      "updatedAt": "2024-03-15T18:22:04.045Z",
      "paidAt": "2024-03-15T18:19:50.154Z",
      "payer": {
        "name": "CONTA DE PAGAMENTO DE PIX",
        "taxID": {
          "taxID": "74866698000169",
          "type": "BR:CNPJ"
        },
        "correlationID": "<correlationID>"
      },
      "brCode": "<brCode>",
      "subaccount": {
        "name": "mediatorpix@key.com",
        "pixKey": "mediatorpix@key.com"
      },
      "expiresIn": 86400,
      "pixKey": "<pixKey>",
      "paymentLinkUrl": "<paymentLinkUrl>",
      "qrCodeImage": "<qrCodeImage>",
      "globalID": "<globalID>"
    },
    "value": 1600,
    "time": "2024-03-15T18:19:50.154Z",
    "endToEndId": "E231144472024031518218Xb59c4mq1x",
    "transactionID": "a74f60ba44e54c67b2cb74243971a674",
    "type": "PAYMENT",
    "createdAt": "2024-03-15T18:22:03.843Z",
    "globalID": "<globalID>"
  },
  "company": {
    "id": "<companyID>",
    "name": "master",
    "taxID": "<taxID>"
  },
  "account": {
    "clientId": "<clientId>"
  }
}
```

## Exemplo

Vamos imaginar um caso que queremos identificar a subconta pertencente a uma cobrança paga, para realizar uma transferência entre subcontas.

Para isso, vamos precisar está criando um Webhook com o evento `Cobrança paga - OPENPIX:CHARGE_COMPLETED`. Para criar esse Webhook, bastar você entrar na nossa plataforma, e acessar a aba `API/Plugins` via sidebar menu.

![1](./__assets__/how-to-recognize-a-subaccount-of-a-paid-charge-1.png)

E logo em seguida, clicar no botão `Novo Webhook`.

![2](./__assets__/how-to-recognize-a-subaccount-of-a-paid-charge-2.png)

Nesse caso, eu vou está criando o Webhook com as seguintes configurações:

![3](./__assets__/how-to-recognize-a-subaccount-of-a-paid-charge-3.png)

- Nome: `Webhook de Cobrança Paga` (Você pode está escolhendo o nome que quiser)
- Evento: `Cobrança paga - OPENPIX:CHARGE_COMPLETED` (Esse evento é disparado quando uma cobrança é paga)
- URL: `https://wooviteste.com/webhook` (Essa é a URL do meu serviço que estará recebendo as chamadas do Webhook)

Aqui está um exemplo de um servidor HTTP em Node.js utilizando Express, na qual possui apenas a rota que irá receber as chamadas do Webhook.

```js
const express = require('express');
const node-fetch = require('node-fetch');

const app = express();

app.use(express.json());

// Endpoint que estará recebendo as chamadas do Webhook da woovi.
app.post('/webhook', (request, response) => {
  const webhookResponse = request.body;

  // Esse `if` garante que transferência só será feita
  // se a cobrança tiver uma subconta atrelada à ela.
  if (webhookResponse.charge.subaccount) {
    // Valor da transferência, sempre 30% do valor da cobrança.
    const transferValue = webhookResponse.charge.value * 0.3;
    // Chave Pix da subconta que recebeu o pagamento da cobrança
    const fromPixKey = webhookResponse.charge.subaccount.pixKey;

    // Requsição que fará a transferência do valor entre subcontas.
    const response = await fetch(`https://api.woovi.com/api/v1/subaccount/transfer`, {
      method: 'POST',
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "REPLACE_WITH_YOUR_APPID"
      },
      body: JSON.stringify({
        value: transferValue,
        fromPixKey,
        fromPixKeyType: 'EMAIL',
        // Chave Pix da subconta que receberá o valor da transferência.
        toPixKey: 'mediator@pixkey.com',
        toPixKeyType: 'EMAIL',
      });
    });

    const status = await response.status();

    if (status === 200) {
      return response.status(200).json({ success: 'Transfer done!' });
    }

    return response.status(400).json({ error: 'Failed to make the transfer' });
  }

  return response.status(200);
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});
```

Basicamente, quando o payload enviado pelo Webhook tiver o campo `charge.subaccount`, ele irá fazer uma nova requisição para woovi realizando uma transferência de 30% do valor da cobrança para a subconta vinculada a chave Pix `mediator@pixkey.com`. Caso o payload não contenha esse campo, a rota apenas retorna o código de status 200.

Essa é uma forma de reconhecer uma subconta após o pagamento de uma cobrança, e executar uma ação através disso.

---

## Como realizar o saque de uma Subconta via API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info
Para a utilização desta funcionalidade é necessário possuir a funcionalidade Subconta
:::

Para realizar o saque integral de uma subconta, você utiliza o _endpoint_ `/api/v1/subaccount/{ID}/withdraw` da API.

Você pode acessar [aqui](/api#tag/subaccount)/paths/~1api~1v1~1subaccount~1%7Bid%7D~1withdraw/post)
a documentação referente a esse _endpoint_.

A chave pix registrada na subconta deve ser passada na url da requisição como parâmetro.

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, um objeto com os detalhes da transação efetuada para a chave pix registrada na subconta.

### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/subaccount/chave-pix-subconta/withdraw -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      -H "Authorization": "app_id"
```

  
  

```js
fetch(
  'https://api.woovi.com/v1/subaccount/chave-pix-subconta/withdraw',
  {
    method: 'POST',
    headers: {
      Authorization: 'AUTHORIZATION',
      'Content-Type': 'application/json',
    },
  },
).then((res) => res.json());
```

  

### Exemplos de resposta

```jsx
{
  "transaction": {
    "status": "CREATED",
    "value": 100,
    "correlationID": "TESTING1323",
    "destinationAlias": "pixKeyTest@test.com",
    "comment": "testing-transaction"
  }
}
```

### Tratamento de erros

Quando um saque de subconta falha, o webhook `OPENPIX:MOVEMENT_FAILED` é disparado com o código e a descrição específica do erro no campo `error`:

```json
{
  "event": "OPENPIX:MOVEMENT_FAILED",
  "payment": {
    "value": 100,
    "status": "FAILED",
    "destinationAlias": "pixKeyTest@test.com",
    "correlationID": "TESTING1323"
  },
  "error": {
    "code": "PIX_KEY_INFO_NOT_FOUND",
    "description": "A chave pix não está registrada em uma instituição bancária"
  }
}
```

Os principais códigos de erro para saques de subconta são:

| Código do Erro | Descrição |
| --- | --- |
| `NOT_ENOUGH_BALANCE` | A subconta não possui saldo suficiente para realizar o saque |
| `PIX_KEY_INFO_NOT_FOUND` | A chave pix não está registrada em nenhuma instituição bancária |
| `INVALID_PIX_KEY` | A chave pix informada é inválida |
| `ENTRY_ASSOCIATED_WITH_RESTRICTED_ACCOUNT_OR_USER` | A conta associada à chave pix está restrita por fraude pelo Banco Central |

:::info
Para a lista completa de códigos de erro, consulte a [documentação de erros de pagamento](/docs/payment/payment-failed-errors).

Para erros retornados pelo SPI (Sistema de Pagamentos Instantâneos do Banco Central), consulte os [códigos de erro PIX](/docs/flows/error-codes-payment).
:::

:::caution
Quando a chave pix da subconta é inválida ou está associada a uma conta restrita, o campo `withdrawBlocked` da subconta é marcado como `true` e saques futuros serão bloqueados. Veja mais detalhes em [Por que o saque da subconta foi bloqueado?](/docs/subaccount/subaccount-withdraw-blocked).
:::

---

## Casos de uso de split de sub-contas

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info
Para a utilização dessa funcionalidade é necessário possuir a funcionalidade Split
:::

## Casos de uso de split de sub-contas

O split de sub-contas é uma funcionalidade que permite que o recebimento de uma cobrança seja dividido entre chaves pix. Entenda mais aqui: [O que é um split](../splits/split-introduction.md)

:::info
Entenda melhor sobre qual tipo de split utilizar [aqui](../splits/split-introduction.md#tipos-de-split)
:::

### Caso de uso 1 - Dividir o valor entre os sócios da empresa

Imagine que você tem uma empresa com 3 sócios e deseja dividir o valor de uma cobrança entre eles. Para isso, você pode criar uma cobrança pix com split de sub-contas, onde o valor da cobrança será dividido entre as chaves pix dos sócios, isso facilita a divisão do valor entre os sócios, economizando tempo e evitando erros.

#### Como dividir o valor entre os sócios da empresa via API

Para dividir o valor entre os sócios da empresa via API, você deve utilizar o _endpoint_ `/api/v1/charge` da API.

Para a API é necessário enviar o campo `splits` no body da requisição, que é um array contendo as configurações de split realizado na hora do recebimento com os valores fixos já definidos, ou seja, seu sistema deve definir o valor que vai para cada chave pix e informar na api da woovi.

### Caso de uso 2 - Gorjeta

Administradores de empresas do ramo de alimentação como restaurantes e bares podem cadastrar chave pix de garçons e atendentes como uma subconta e configurar valores
por cobrança a serem registrados como crédito, podendo então ser sacado a qualquer momento por integração via API ou diretamente pela plataforma.

### Caso de uso 3 - Comissão para vendedores

Gestores de comércio podem cadastrar vendedores através da chave pix do vendendor como subconta e assim gerenciar cada cobrança, para creditar valroes de comissão automaticamente podendo fazer os saque a qualquer momento por integração via API ou diretamente pela plataforma.

## MarketPlace

Gestores de MarketPlace digitais podem criar cobranças com chave pix cadastrada como subconta, registrando assim em cada cobrança paga o valor da comissão por venda
relacionada a vendas dentro de seu marketplace. Esta integração permite a gestores um gerenciamento de valores automático e facilidade na gestão e no pagamento de valores ao longo do tempo. O saque pode ser feito por integração via api ou diretamente pela plataforma.

---

## Por que o saque da subconta foi bloqueado?

Uma subconta precisa ter uma chave pix válida e existente para que o saque seja realizado. Quando uma tentativa de saque é feita e a chave pix da subconta não é encontrada no DICT (Diretório de Identificadores de Contas Transacionais) do Banco Central, o campo `withdrawBlocked` da subconta é marcado como `true` e todas as tentativas futuras de saque serão bloqueadas imediatamente.

## Por que o bloqueio acontece?

Cada consulta de chave pix no DICT consome tokens do limitador de taxa da sua conta. Quando a chave pix não existe, o custo em tokens é significativamente maior. Para proteger a sua conta de esgotar os tokens disponíveis com tentativas repetidas para chaves inválidas, a subconta é bloqueada automaticamente após a primeira tentativa sem sucesso.

O bloqueio também acontece quando a chave pix está associada a uma conta restrita por fraude pelo Banco Central.

### Códigos de erro que causam o bloqueio

| Código do Erro | Descrição |
| --- | --- |
| `PIX_KEY_INFO_NOT_FOUND` | A chave pix não está registrada em nenhuma instituição bancária |
| `ENTRY_ASSOCIATED_WITH_RESTRICTED_ACCOUNT_OR_USER` | A conta associada à chave pix está restrita por fraude pelo Banco Central |

## Como verificar o status do bloqueio?

O campo `withdrawBlocked` pode ser visualizado tanto pela API quanto pela plataforma.

### Via API

Ao consultar uma subconta pelo endpoint `GET /api/v1/subaccount/{id}`, o campo `withdrawBlocked` será retornado na resposta:

```json
{
  "subAccount": {
    "id": "...",
    "pixKey": "...",
    "withdrawBlocked": true
  }
}
```

O campo também é retornado ao listar todas as subcontas pelo endpoint `GET /api/v1/subaccount`.

### Via Plataforma

O status de bloqueio de saque também pode ser visualizado diretamente na plataforma, nos detalhes da subconta.

## Recomendação

Se você identificar que a chave pix de uma subconta está inválida, retire todo o saldo da subconta. Mesmo após o bloqueio, os endpoints de `/credit` e `/debit` continuam funcionando normalmente — apenas o saque via `/withdraw` é bloqueado.

## Códigos de erro no webhook

Quando um saque falha, o webhook `OPENPIX:MOVEMENT_FAILED` é enviado com o código de erro específico no campo `error`. Isso permite identificar programaticamente o motivo da falha e tomar ações automatizadas.

:::info
Para a lista completa de códigos de erro, consulte a [documentação de erros de pagamento](/docs/payment/payment-failed-errors) e os [códigos de erro PIX](/docs/flows/error-codes-payment).
:::

## Como desbloquear?

Para desbloquear o saque da subconta, é necessário atualizar a chave pix da subconta para uma chave válida e existente e entrar em contato com o suporte técnico.

---

## Como gerar carnê de assinatura usando a API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

O carnê reúne em um único PDF as cobranças da sua assinatura — uma via por parcela,
numeradas como "Parcela N de M", no formato que o seu cliente já conhece.

Para gerar, faça uma chamada GET para o _endpoint_
`/api/v1/subscriptions/{id}/payment-book`. Você pode acessar a
[referência da API](/api) para os detalhes desse _endpoint_.

Você precisa de um AppID com o escopo `SUBSCRIPTION_PAYMENT_BOOK_GET`
([como adicionar escopos](../apis/api-scopes.md)). Ele não é um escopo de leitura:
como a chamada cria cobranças, não o conceda a uma integração que apenas consulta.

:::warning Só para assinatura recorrente

O carnê existe apenas para assinaturas do tipo `RECURRENT` — as que você cria com
`"type": "RECURRENT"`, cobradas por Pix ou por boleto a cada ciclo.

**Pix Automático não tem carnê.** Em uma assinatura `PIX_RECURRING` quem executa a
cobrança é o banco do seu cliente, na data de cada ciclo, então não há como
antecipá-las em um documento. Pedir o carnê de uma assinatura Pix Automático
responde `400`.

:::

## Antes de chamar

As parcelas futuras de uma assinatura ainda não existem como cobrança — cada uma é
criada perto do seu vencimento. Imprimir um carnê antecipa isso.

**A chamada é síncrona e cria todas as cobranças que faltam no período.** Não há fila
nem protocolo para consultar depois: ela percorre as parcelas até o mês/ano que você
pediu, cria a cobrança de cada uma que ainda não tem, e só responde quando o PDF está
pronto. **Por isso o tempo de resposta é bem maior que o de uma chamada comum, e cresce
com o número de cobranças a criar** — um carnê longo pedido pela primeira vez é o pior
caso, porque nenhuma parcela dele existe ainda.

Na prática:

- **Aumente o _timeout_ do seu cliente** antes de pedir um período longo. O padrão da
  maioria das bibliotecas HTTP é curto demais para essa chamada.
- **Peça só o período que você vai entregar ao cliente.** Ampliar depois é rápido e
  cria apenas a diferença (veja [Reimprimir e ampliar](#reimprimir-e-ampliar)).
- As cobranças criadas são reais: aparecem no seu extrato, disparam webhook quando
  pagas e valem as condições comerciais da sua conta — incluindo eventual taxa de
  emissão de boleto, se houver.
- É um GET com efeito. Não coloque essa URL atrás de _retry_ automático, _prefetch_
  de link ou monitoramento.

## Parâmetros

| parâmetro | onde | obrigatório | descrição |
| --- | --- | --- | --- |
| `id` | rota | sim | O `globalID` ou o id da assinatura. Diferente dos outros _endpoints_ de assinatura, esse não aceita `correlationID`. |
| `month` | query | **sim** | Último mês que o carnê alcança, de `1` a `12`. |
| `year` | query | **sim** | Último ano que o carnê alcança. |

`month` e `year` são inclusivos: a parcela do mês informado entra no carnê.

:::info Por que mês e ano são obrigatórios

Em outras plataformas o par é opcional e apenas filtra um documento pronto. Aqui ele
decide quantas cobranças serão criadas, então não existe padrão — quem chama informa
até onde quer ir.

:::

## O teto: 31 de dezembro do ano que vem

`year` aceita o ano atual ou o seguinte. Passar disso **retorna erro, não corta no
limite** — não existe chamada que peça além do teto e gere só até lá:

```json
// GET .../payment-book?month=6&year=2030
{ "error": "O carnê só pode ser gerado até o final do ano que vem" }
```

O limite é só superior. Um mês/ano no passado é aceito e rende poucas ou nenhuma via;
se não sobrar nada no período, a resposta é `400`.

## O que entra no carnê

- **Só assinatura `RECURRENT`.**
- **Com boleto, só frequência mensal ou maior** (`MONTHLY`, `BIMONTHLY`, `QUARTERLY`,
  `SEMIANNUALLY`, `ANNUALLY`). Sem boleto, qualquer frequência vale.
- **Só parcelas em aberto viram via.** Parcela já paga ou expirada fica de fora, para
  o carnê não convidar a pagar duas vezes — por isso o número de vias pode ser menor
  que o número de parcelas do período.

## Exemplo

```sh
curl --request GET \
  --url 'https://api.woovi.com/api/v1/subscriptions/UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=/payment-book?month=12&year=2027' \
  --header 'Authorization: <AUTHORIZATION>' \
  --output carne.pdf
```

Se tudo ocorreu bem o _status code_ é `200` e o corpo é **o PDF**, não um JSON:

```
Content-Type: application/pdf
Content-Disposition: inline; filename="payment-book-63e3b2b773d3d93bcdd32993.pdf"
```

O PDF traz uma via por parcela, numeradas como "Parcela N de M", cada uma com o
recibo do pagador, o código de barras e o QR Code Pix — o seu cliente paga a via
por qualquer um dos dois:

![Carnê gerado pela API, com uma via por parcela](./__assets__/subscription-payment-book-pdf.png)

:::tip No Postman use "Send and Download"

O corpo é binário. Um `Send` normal mostra o PDF como texto embaralhado e parece erro.
Em caso de erro, aí sim o corpo é JSON.

:::

### Exemplos em código

  

```sh
curl --request GET \
  --url 'https://api.woovi.com/api/v1/subscriptions/UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=/payment-book?month=12&year=2027' \
  --header 'Authorization: <AUTHORIZATION>' \
  --output carne.pdf
```

  
  

```js
import { writeFile } from 'node:fs/promises';

const response = await fetch(
  'https://api.woovi.com/api/v1/subscriptions/UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=/payment-book?month=12&year=2027',
  {
    headers: {
      Authorization: '<AUTHORIZATION>',
    },
  },
);

// Em erro o corpo é JSON; no sucesso é o PDF.
if (!response.ok) {
  throw new Error((await response.json()).error);
}

await writeFile('carne.pdf', Buffer.from(await response.arrayBuffer()));
```

  

## Reimprimir e ampliar

Repetir a chamada é seguro: uma parcela que já tem cobrança não ganha outra.

- **Reimprimir não cobra de novo.** O PDF pode vir com menos vias que antes se alguma
  parcela foi paga no intervalo, e isso é o esperado.
- **Ampliar cria só a diferença.** Pedir até 05/2027 e depois até 12/2027 cria apenas
  as parcelas novas do segundo pedido, e o segundo PDF já vem com o carnê inteiro até
  o novo corte.
- **Se vier menos vias do que você esperava, ou o seu cliente deu _timeout_**, chame a
  mesma URL de novo: o que já existe não é cobrado outra vez.

O carnê não avisa o seu cliente — entregar o PDF é com você. As cobranças seguem
disparando os webhooks normais quando forem pagas.

## Erros

| status | mensagem | quando |
| --- | --- | --- |
| `400` | `O carnê exige o mês e o ano até onde gerar` | faltou `month` ou `year` |
| `400` | `Mês inválido` | `month` fora de 1 a 12 |
| `400` | `O carnê só pode ser gerado até o final do ano que vem` | `year` passou do teto |
| `400` | `Carnê está disponível apenas para assinaturas recorrentes` | a assinatura não é `RECURRENT` |
| `400` | `Payment book with boleto is only available for monthly or longer subscriptions` | boleto em frequência menor que mensal |
| `400` | `Nenhuma cobrança pôde ser emitida para este carnê` | nada no período pôde ser cobrado |
| `401` | — | `Authorization` ausente ou inválido, ou IP fora da lista permitida |
| `403` | — | o token não carrega o escopo `SUBSCRIPTION_PAYMENT_BOOK_GET` |
| `404` | `Assinatura não encontrada` | nenhuma assinatura com esse id na sua conta |
| `500` | `Falha ao gerar o carnê` | não foi possível montar o documento |

Os erros de `month`/`year` são verificados antes de qualquer emissão, então não geram
cobrança.

## Conteúdos relacionados

- [Como criar uma Assinatura usando a API?](./subscription-recurrence-create-api.mdx)
- [Como criar uma Assinatura cobrada com Boleto usando a API?](./subscription-with-boleto-create-api.mdx)
- [Cobrança de boleto](../boleto/boleto-api.md)

---

## Como criar uma Assinatura usando a API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para criar uma nova assinatura usando a API, você deverá fazer uma chamada POST para o _endpoint_ `/api/v1/subscriptions`.

Você pode acessar [aqui](/api#tag/subscription/POST/api/v1/subscriptions) a documentação referente a esse _endpoint_.

Como parte do `body` da requisição, esperamos o envio dos seguintes itens:

- **`value`**: O valor em centavos da assinatura a ser criada.
- **`customer`**: O cliente da assinatura a ser cobrado. Este campo é [idempotente](../concepts/idempotence.md), o que significa que se você enviar dados de um cliente que já exista, utilizaremos o existente ao invés de criar um novo.

O body também aceita outros campos **opcionais**:

- **`dayGenerateCharge`**: Dia do mês em que as cobranças serão geradas. Deve ser um valor de 0 a 27.

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "value": 100,
  "customer": {
    "name": "Dan",
    "taxID": "31324227036",
    "email": "email0@example.com",
    "phone": "5511999999999"
  }
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, retornaremos a assinatura criada.

Retornarmeros a seguinte resposta de exemplo:

```json
{
  "subscription": {
    "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=",
    "value": 100,
    "customer": {
      "name": "Dan",
      "email": "email0@example.com",
      "phone": "5511999999999",
      "taxID": {
        "taxID": "31324227036",
        "type": "BR:CPF"
      }
    },
    "dayGenerateCharge": 5
  }
}
```

### Exemplos em código

  

```sh
 curl --request POST \
     --url https://api.woovi.com/api/v1/subscriptions \
     --header 'Authorization: AUTHORIZATION' \
     --header 'content-type: application/json' \
     --data '{"value": 100,"customer": {"name":"Dan","taxID":"31324227036","email":"email0@example.com","phone":"5511999999999"}}'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/subscriptions', {
  method: 'POST',
  body: JSON.stringify({
    value: 100,
    customer: {
      name: 'Dan',
      taxID: '31324227036',
      email: 'email0@example.com',
      phone: '5511999999999',
    },
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como criar uma Assinatura?

Nessa documentação explicaremos, passo a passo, como criar uma Assinatura.

## Criando sua primeira assinatura

Para criar sua primeira Assinatura siga estes passos:

1. Acesse nossa plataforma [https://app.woovi.com/login](https://app.woovi.com/login)
2. Vá em **Assinaturas** na barra lateral
3. Você encontrará nosso o tutorial, clique no botão **Nova Assinatura** para abrir o formulário e criar sua primeira Assinatura

![Tutorial](./__assets__/subscription-recurrence-tutorial.png)

## Criando novas assinaturas

Caso já tenha criado uma Assinatura antes, aparecerá a listagem de assinaturas.

Para criar uma nova clique no botão **Criar Assinatura**.

![Botão de Criar Assinatura](./__assets__/subscription-recurrence-create.png)

## Formulário

Após isso você encontrará nosso formulário para criação de Assinaturas.

Abaixo, explicaremos cada passo deste formulário e o que cada campo significa.

![Formulário](./__assets__/subscription-recurrence-form.png)

### Passo 1: Cliente a ser cobrado

Para criar uma Assinatura é **obrigatório** um cliente, você pode adicionar um:

- Escolhendo um cliente de sua base de clientes já existente
- Criando um novo cliente

![Cliente a ser cobrado](./__assets__/subscription-recurrence-customer.png)

### Passo 2: Dados das cobranças

Neste passo você irá configurar como as cobrança da Assinatura serão geradas:

| Campo                 | Descrição                                                   | Exemplo                |
| --------------------- | ----------------------------------------------------------- | ---------------------- |
| Valor                 | Valor a ser cobrado                                         | **R$ 98,90**           |
| Comentário (opcional) | Comentário que aparecerá no QR Code no momento do pagamento | **Plano A - Academia** |

![Dados das cobranças](./__assets__/subscription-recurrence-charge-data.png)

### Passo 3: Duração e frequência da Assinatura (opcional)

Neste passo você irá configurar a duração e frequência da Assinatura.

Uma Assinatura pode ou não ter uma data de fim.

- Se possuir: será agendada todas as parcelas até a data de fim e as cobranças serão geradas de acordo com a data.
- Se não possuir: será gerada uma cobrança e agendada a próxima de acordo, essas Assinaturas só terão fim se forem desativadas.

| Campo          | Padrão      | Descrição                    | Exemplo        |
| -------------- | ----------- | ---------------------------- | -------------- |
| Início         | _Dia atual_ | Data de início da Assinatura | **06/02/2023** |
| Fim (opcional) |             | Data de fim da Assinatura    | **25/12/2024** |
| Frequência     | Mensal      | Frequência da Assinatura     | **Mensal**     |

![Duração e frequência da Assinatura](./__assets__/subscription-recurrence-duration-frequency.png)

### Passo 4: Dia de criação e expiração da cobranças (opcional)

Neste passo você irá configurar o dia de criação e prazo de pagamento das cobranças.

| Campo              | Padrão | Descrição                                                      | Exemplo    |
| ------------------ | ------ | -------------------------------------------------------------- | ---------- |
| Dia de criação     | Dia 5  | Dia do mês em que as cobranças serão geradas                   | **Dia 20** |
| Prazo de pagamento | 7 dias | Prazo que o cliente terá para pagar após a geração da cobrança | **3 dias** |

![Dia de criação e expiração da cobranças](./__assets__/subscription-recurrence-day-generate-day-due.png)

### Passo 5: Salvar

Após finalizar todos os passos anteriores, é só clicar no botão **Salvar** e você será redirecionado para o detalhe da Assinatura:

![Detalhes da Assinatura](./__assets__/subscription-recurrence-detail.png)

---

## Como buscar uma Assinatura usando a API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para buscar uma assinatura usando a API, você deverá fazer uma chamada GET para o _endpoint_ `/api/v1/subscriptions/<globalID>` usando o `globalID` da assinatura.

Você pode acessar [aqui](/api#tag/subscription/GET/api/v1/subscriptions/{id}) a documentação referente a esse _endpoint_.

## Exemplo

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, retornaremos a assinatura.

Retornarmeros a seguinte resposta de exemplo:

```json
{
  "subscription": {
    "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=",
    "value": 100,
    "customer": {
      "name": "Dan",
      "email": "email0@example.com",
      "phone": "5511999999999",
      "taxID": {
        "taxID": "31324227036",
        "type": "BR:CPF"
      }
    }
  },
  "dayGenerateCharge": 5
}
```

### Exemplos em código

  

```sh
curl --request GET \
  --url https://api.woovi.com/api/v1/subscriptions/UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM= \
  --header 'Authorization: <AUTHORIZATION>'
```

  
  

```js
fetch(
  'https://api.woovi.com/api/v1/subscriptions/UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=',
  {
    headers: {
      Authorization: '<AUTHORIZATION>',
    },
  },
);
```

---

## Assinaturas/Recorrência

Assinaturas/Recorrência permite que você cobre os seus clientes com uma periodicidade predeterminada.

A plataforma gera as cobranças Pix baseado nas configurações da assinatura e enviar email/sms/whatsapp para cobrar o seu cliente de forma automática.

## Casos de Uso

- Assinaturas de SaaS - Software as a Services
- Mensalidades de serviços - como academias, escolas, etc.

---

## Como criar uma Assinatura cobrada com Boleto usando a API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Você pode criar uma assinatura em que **cada parcela é cobrada por Boleto**. A cada
ciclo (mensal, semanal, etc.) geramos automaticamente um novo boleto para o seu
cliente — que também pode ser pago via Pix, pois todo boleto emitido pela Woovi
expõe um QR Code Pix.

:::info Boleto precisa estar habilitado
A cobrança por boleto exige que a funcionalidade esteja ativa na sua conta. Entre
em contato com o nosso time para analisarmos o seu modelo de negócio e habilitar.
:::

Para criar a assinatura você deverá fazer uma chamada POST para o _endpoint_
`/api/v1/subscriptions`.

Você pode acessar [aqui](/api#tag/subscription/POST/api/v1/subscriptions)
a documentação referente a esse _endpoint_.

Como parte do `body` da requisição, esperamos o envio dos seguintes itens:

- **`value`**: O valor em centavos da assinatura a ser criada.
- **`customer`**: O cliente da assinatura a ser cobrado com o endereço. Este campo é [idempotente](../concepts/idempotence.md), o que significa que se você enviar dados de um cliente que já exista, utilizaremos o existente ao invés de criar um novo.
- **`type`**: O tipo da assinatura. Para cobrança por boleto, use `RECURRENT`.
- **`chargeType`**: O método de cobrança de cada parcela. Para gerar boletos, informe o valor `BOLETO`.

O body também aceita outros campos **opcionais**:

- **`frequency`**: A frequência entre as cobranças (`WEEKLY`, `MONTHLY`, `BIMONTHLY`, `QUARTERLY`, `SEMIANNUALLY`, `ANNUALLY`). Quando omitido, o padrão é `MONTHLY`.
- **`dayGenerateCharge`**: Dia do mês em que as cobranças (boletos) serão geradas.
- **`dayDue`**: Prazo, em dias, para o boleto vencer a partir da geração.

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "value": 15000,
  "customer": {
    "name": "Dan",
    "taxID": "31324227036",
    "email": "email0@example.com",
    "phone": "5511999999999",
    "address": {
      "zipcode": "30421322",
      "street": "Street",
      "number": "100",
      "neighborhood": "Neighborhood",
      "city": "Belo Horizonte",
      "state": "MG",
      "complement": "APTO",
      "country": "BR"
    }
  },
  "type": "RECURRENT",
  "chargeType": "BOLETO"
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será
`2xx` e no `body` da resposta, retornaremos a assinatura criada.

Retornaremos a seguinte resposta de exemplo:

```json
{
  "subscription": {
    "customer": {
      "name": "Fernando Silva",
      "email": "fernando@woovi.com",
      "phone": "+5531988472275",
      "taxID": { "taxID": "13225476617", "type": "BR:CPF" },
      "correlationID": "1b112444-6530-46dd-934b-71d50d6c84bc",
      "address": {
        "zipcode": "30421322",
        "street": "Street",
        "number": "100",
        "neighborhood": "Neighborhood",
        "city": "Belo Horizonte",
        "state": "MG",
        "complement": "APTO",
        "country": "BR",
        "location": { "coordinates": [] },
        "_id": "64b7d32db5a5555c9b750bc0"
      }
    },
    "dayGenerateCharge": 5,
    "value": 15000,
    "status": "ACTIVE",
    "correlationID": "My-UniqueID",
    "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM="
  }
}
```

## Ciclo de vida da cobrança

A cada parcela da assinatura geramos uma **cobrança do tipo boleto**. Essa
cobrança segue o mesmo formato da
[cobrança de boleto avulsa](../boleto/boleto-api.md): traz `paymentMethods.boleto`
(com `boletoBarcode` e `boletoDigitable`) e também um Pix, de modo que o cliente
pode quitar por qualquer uma das duas formas.

Quando o boleto de uma parcela é **pago**, disparamos o webhook
`OPENPIX:CHARGE_COMPLETED`, exatamente como no fluxo de boleto avulso. Veja
[Webhook de Boleto pago](../boleto/boleto-webhook.md) para o payload completo e
como validar a assinatura.

:::warning Pagamento não é liquidação
O webhook indica que o boleto foi **pago**, não que o valor já está disponível. A
**liquidação** ocorre depois (tipicamente D+3). Trate o webhook como "parcela
quitada", não como saldo disponível.
:::

### Exemplos em código

  

```sh
 curl --request POST \
     --url https://api.woovi.com/api/v1/subscriptions \
     --header 'Authorization: AUTHORIZATION' \
     --header 'content-type: application/json' \
     --data '{"value": 15000,"type":"RECURRENT","chargeType":"BOLETO","customer": {"name":"Dan","taxID":"31324227036","email":"email0@example.com","phone":"5511999999999", "address":{"zipcode":"30421322","street":"Street","number":"100","neighborhood":"Neighborhood","city":"Belo Horizonte","state":"MG","complement":"APTO","country":"BR"}}}'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/subscriptions', {
  method: 'POST',
  body: JSON.stringify({
    value: 15000,
    type: 'RECURRENT',
    chargeType: 'BOLETO',
    customer: {
      name: 'Dan',
      taxID: '31324227036',
      email: 'email0@example.com',
      phone: '5511999999999',
      address: {
        zipcode: '30421322',
        street: 'Street',
        number: '100',
        neighborhood: 'Neighborhood',
        city: 'Belo Horizonte',
        state: 'MG',
        complement: 'APTO',
        country: 'BR',
      },
    },
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Como criar uma Assinatura com multa e juros usando a API?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Para criar uma nova assinatura com multa e juros usando a API, você deverá fazer uma chamada POST para o _endpoint_ `/api/v1/subscriptions`.

Você pode acessar [aqui](/api#tag/subscription/POST/api/v1/subscriptions) a documentação referente a esse _endpoint_.

Como parte do `body` da requisição, esperamos o envio dos seguintes itens:

- **`value`**: O valor em centavos da assinatura a ser criada.
- **`customer`**: O cliente da assinatura a ser cobrado com o endereço. Este campo é [idempotente](../concepts/idempotence.md), o que significa que se você enviar dados de um cliente que já exista, utilizaremos o existente ao invés de criar um novo.
- **`chargeType`**: O tipo da cobrança que você quer gerar. Nesse caso com multa e juros, você informa o tipo `OVERDUE`.

O body também aceita outros campos **opcionais**:

- **`dayGenerateCharge`**: Dia do mês em que as cobranças serão geradas. Deve ser um valor de 0 a 27.

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "value": 100,
  "customer": {
    "name": "Dan",
    "taxID": "31324227036",
    "email": "email0@example.com",
    "phone": "5511999999999",
    "address": {
      "zipcode": "30421322",
      "street": "Street",
      "number": "100",
      "neighborhood": "Neighborhood",
      "city": "Belo Horizonte",
      "state": "MG",
      "complement": "APTO",
      "country": "BR"
    }
  },
  "chargeType": "OVERDUE"
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, retornaremos a assinatura criada.

Retornarmeros a seguinte resposta de exemplo:

```json
{
  "subscription": {
    "customer": {
      "name": "Fernando Silva",
      "email": "fernando@woovi.com",
      "phone": "+5531988472275",
      "taxID": { "taxID": "13225476617", "type": "BR:CPF" },
      "correlationID": "1b112444-6530-46dd-934b-71d50d6c84bc",
      "address": {
        "zipcode": "30421322",
        "street": "Street",
        "number": "100",
        "neighborhood": "Neighborhood",
        "city": "Belo Horizonte",
        "state": "MG",
        "complement": "APTO",
        "country": "BR",
        "location": { "coordinates": [] },
        "_id": "64b7d32db5a5555c9b750bc0"
      }
    },
    "dayGenerateCharge": 5,
    "value": 1500,
    "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM="
  }
}
```

### Exemplos em código

  

```sh
 curl --request POST \
     --url https://api.woovi.com/api/v1/subscriptions \
     --header 'Authorization: AUTHORIZATION' \
     --header 'content-type: application/json' \
     --data '{"value": 100,"customer": {"name":"Dan","taxID":"31324227036","email":"email0@example.com","phone":"5511999999999", "address":{"zipcode":"30421322","street":"Street","number":"100","neighborhood":"Neighborhood","city":"Belo Horizonte","state":"MG","complement":"APTO","country":"BR"}},"chargeType":"OVERDUE"}'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/subscriptions', {
  method: 'POST',
  body: JSON.stringify({
    value: 100,
    customer: {
      name: 'Dan',
      taxID: '31324227036',
      email: 'email0@example.com',
      phone: '5511999999999',
      address: {
        zipcode: '30421322',
        street: 'Street',
        number: '100',
        neighborhood: 'Neighborhood',
        city: 'Belo Horizonte',
        state: 'MG',
        complement: 'APTO',
        country: 'BR',
      },
    },
    chargeType: 'OVERDUE',
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## Woovi suporta o Advanced Corretora de Câmbio Ltda. ?

Sim.

Com a plataforma é possível definir o Advanced Corretora de Câmbio Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Advanced Corretora de Câmbio Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Advanced Corretora de Câmbio Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Advanced Corretora de Câmbio Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Advanced Corretora de Câmbio Ltda. seja uma conta empresas, ou seja Advanced Corretora de Câmbio Ltda. conta PJ
- Para usar este recurso a conta corrente no Advanced Corretora de Câmbio Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Albatross Corretora de Câmbio e Valores S.A ?

Sim.

Com a plataforma é possível definir o Albatross Corretora de Câmbio e Valores S.A como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Albatross Corretora de Câmbio e Valores S.A.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Albatross Corretora de Câmbio e Valores S.A não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Albatross Corretora de Câmbio e Valores S.A.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Albatross Corretora de Câmbio e Valores S.A seja uma conta empresas, ou seja Albatross Corretora de Câmbio e Valores S.A conta PJ
- Para usar este recurso a conta corrente no Albatross Corretora de Câmbio e Valores S.A tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Ativa Investimentos  Corretora de Títulos Câmbio e Valores ?

Sim.

Com a plataforma é possível definir o Ativa Investimentos  Corretora de Títulos Câmbio e Valores como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Ativa Investimentos  Corretora de Títulos Câmbio e Valores.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Ativa Investimentos  Corretora de Títulos Câmbio e Valores não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Ativa Investimentos  Corretora de Títulos Câmbio e Valores.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Ativa Investimentos  Corretora de Títulos Câmbio e Valores seja uma conta empresas, ou seja Ativa Investimentos  Corretora de Títulos Câmbio e Valores conta PJ
- Para usar este recurso a conta corrente no Ativa Investimentos  Corretora de Títulos Câmbio e Valores tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Avista  Crédito ?

Sim.

Com a plataforma é possível definir o Avista  Crédito como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Avista  Crédito.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Avista  Crédito não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Avista  Crédito.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Avista  Crédito seja uma conta empresas, ou seja Avista  Crédito conta PJ
- Para usar este recurso a conta corrente no Avista  Crédito tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco A. J. Renner ?

Sim.

Com a plataforma é possível definir o Banco A. J. Renner como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco A. J. Renner.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco A. J. Renner não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco A. J. Renner.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco A. J. Renner seja uma conta empresas, ou seja Banco A. J. Renner conta PJ
- Para usar este recurso a conta corrente no Banco A. J. Renner tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco ABC Brasil ?

Sim.

Com a plataforma é possível definir o Banco ABC Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco ABC Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco ABC Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco ABC Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco ABC Brasil seja uma conta empresas, ou seja Banco ABC Brasil conta PJ
- Para usar este recurso a conta corrente no Banco ABC Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco ABN Amro ?

Sim.

Com a plataforma é possível definir o Banco ABN Amro como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco ABN Amro.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco ABN Amro não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco ABN Amro.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco ABN Amro seja uma conta empresas, ou seja Banco ABN Amro conta PJ
- Para usar este recurso a conta corrente no Banco ABN Amro tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Agibank ?

Sim.

Com a plataforma é possível definir o Banco Agibank como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Agibank.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Agibank não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Agibank.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Agibank seja uma conta empresas, ou seja Banco Agibank conta PJ
- Para usar este recurso a conta corrente no Banco Agibank tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Alfa ?

Sim.

Com a plataforma é possível definir o Banco Alfa como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Alfa.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Alfa não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Alfa.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Alfa seja uma conta empresas, ou seja Banco Alfa conta PJ
- Para usar este recurso a conta corrente no Banco Alfa tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Alvorada ?

Sim.

Com a plataforma é possível definir o Banco Alvorada como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Alvorada.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Alvorada não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Alvorada.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Alvorada seja uma conta empresas, ou seja Banco Alvorada conta PJ
- Para usar este recurso a conta corrente no Banco Alvorada tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco AndBank (Brasil) ?

Sim.

Com a plataforma é possível definir o Banco AndBank (Brasil) como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco AndBank (Brasil).

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco AndBank (Brasil) não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco AndBank (Brasil).

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco AndBank (Brasil) seja uma conta empresas, ou seja Banco AndBank (Brasil) conta PJ
- Para usar este recurso a conta corrente no Banco AndBank (Brasil) tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Arbi ?

Sim.

Com a plataforma é possível definir o Banco Arbi como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Arbi.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Arbi não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Arbi.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Arbi seja uma conta empresas, ou seja Banco Arbi conta PJ
- Para usar este recurso a conta corrente no Banco Arbi tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco B3 ?

Sim.

Com a plataforma é possível definir o Banco B3 como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco B3.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco B3 não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco B3.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco B3 seja uma conta empresas, ou seja Banco B3 conta PJ
- Para usar este recurso a conta corrente no Banco B3 tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Bandepe ?

Sim.

Com a plataforma é possível definir o Banco Bandepe como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Bandepe.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Bandepe não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Bandepe.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Bandepe seja uma conta empresas, ou seja Banco Bandepe conta PJ
- Para usar este recurso a conta corrente no Banco Bandepe tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco BMG ?

Sim.

Com a plataforma é possível definir o Banco BMG como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco BMG.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco BMG não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco BMG.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco BMG seja uma conta empresas, ou seja Banco BMG conta PJ
- Para usar este recurso a conta corrente no Banco BMG tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco BNP Paribas Brasil ?

Sim.

Com a plataforma é possível definir o Banco BNP Paribas Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco BNP Paribas Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco BNP Paribas Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco BNP Paribas Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco BNP Paribas Brasil seja uma conta empresas, ou seja Banco BNP Paribas Brasil conta PJ
- Para usar este recurso a conta corrente no Banco BNP Paribas Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Bocom BBM ?

Sim.

Com a plataforma é possível definir o Banco Bocom BBM como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Bocom BBM.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Bocom BBM não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Bocom BBM.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Bocom BBM seja uma conta empresas, ou seja Banco Bocom BBM conta PJ
- Para usar este recurso a conta corrente no Banco Bocom BBM tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Bradescard ?

Sim.

Com a plataforma é possível definir o Banco Bradescard como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Bradescard.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Bradescard não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Bradescard.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Bradescard seja uma conta empresas, ou seja Banco Bradescard conta PJ
- Para usar este recurso a conta corrente no Banco Bradescard tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Bradesco BBI ?

Sim.

Com a plataforma é possível definir o Banco Bradesco BBI como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Bradesco BBI.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Bradesco BBI não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Bradesco BBI.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Bradesco BBI seja uma conta empresas, ou seja Banco Bradesco BBI conta PJ
- Para usar este recurso a conta corrente no Banco Bradesco BBI tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Bradesco BERJ ?

Sim.

Com a plataforma é possível definir o Banco Bradesco BERJ como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Bradesco BERJ.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Bradesco BERJ não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Bradesco BERJ.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Bradesco BERJ seja uma conta empresas, ou seja Banco Bradesco BERJ conta PJ
- Para usar este recurso a conta corrente no Banco Bradesco BERJ tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Bradesco Cartões ?

Sim.

Com a plataforma é possível definir o Banco Bradesco Cartões como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Bradesco Cartões.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Bradesco Cartões não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Bradesco Cartões.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Bradesco Cartões seja uma conta empresas, ou seja Banco Bradesco Cartões conta PJ
- Para usar este recurso a conta corrente no Banco Bradesco Cartões tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Bradesco Financiamentos ?

Sim.

Com a plataforma é possível definir o Banco Bradesco Financiamentos como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Bradesco Financiamentos.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Bradesco Financiamentos não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Bradesco Financiamentos.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Bradesco Financiamentos seja uma conta empresas, ou seja Banco Bradesco Financiamentos conta PJ
- Para usar este recurso a conta corrente no Banco Bradesco Financiamentos tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Bradesco ?

Sim.

Com a plataforma é possível definir o Banco Bradesco como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Bradesco.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Bradesco não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Bradesco.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Bradesco seja uma conta empresas, ou seja Banco Bradesco conta PJ
- Para usar este recurso a conta corrente no Banco Bradesco tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco BS2 ?

Sim.

Com a plataforma é possível definir o Banco BS2 como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco BS2.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco BS2 não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco BS2.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco BS2 seja uma conta empresas, ou seja Banco BS2 conta PJ
- Para usar este recurso a conta corrente no Banco BS2 tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco BTG Pactual ?

Sim.

Com a plataforma é possível definir o Banco BTG Pactual como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco BTG Pactual.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco BTG Pactual não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco BTG Pactual.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco BTG Pactual seja uma conta empresas, ou seja Banco BTG Pactual conta PJ
- Para usar este recurso a conta corrente no Banco BTG Pactual tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Caixa Geral - Brasil ?

Sim.

Com a plataforma é possível definir o Banco Caixa Geral - Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Caixa Geral - Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Caixa Geral - Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Caixa Geral - Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Caixa Geral - Brasil seja uma conta empresas, ou seja Banco Caixa Geral - Brasil conta PJ
- Para usar este recurso a conta corrente no Banco Caixa Geral - Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Capital ?

Sim.

Com a plataforma é possível definir o Banco Capital como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Capital.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Capital não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Capital.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Capital seja uma conta empresas, ou seja Banco Capital conta PJ
- Para usar este recurso a conta corrente no Banco Capital tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Cargill ?

Sim.

Com a plataforma é possível definir o Banco Cargill como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Cargill.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Cargill não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Cargill.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Cargill seja uma conta empresas, ou seja Banco Cargill conta PJ
- Para usar este recurso a conta corrente no Banco Cargill tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Cetelem ?

Sim.

Com a plataforma é possível definir o Banco Cetelem como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Cetelem.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Cetelem não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Cetelem.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Cetelem seja uma conta empresas, ou seja Banco Cetelem conta PJ
- Para usar este recurso a conta corrente no Banco Cetelem tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Cifra ?

Sim.

Com a plataforma é possível definir o Banco Cifra como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Cifra.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Cifra não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Cifra.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Cifra seja uma conta empresas, ou seja Banco Cifra conta PJ
- Para usar este recurso a conta corrente no Banco Cifra tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Citibank ?

Sim.

Com a plataforma é possível definir o Banco Citibank como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Citibank.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Citibank não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Citibank.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Citibank seja uma conta empresas, ou seja Banco Citibank conta PJ
- Para usar este recurso a conta corrente no Banco Citibank tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Clássico ?

Sim.

Com a plataforma é possível definir o Banco Clássico como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Clássico.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Clássico não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Clássico.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Clássico seja uma conta empresas, ou seja Banco Clássico conta PJ
- Para usar este recurso a conta corrente no Banco Clássico tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Confidence de Câmbio ?

Sim.

Com a plataforma é possível definir o Banco Confidence de Câmbio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Confidence de Câmbio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Confidence de Câmbio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Confidence de Câmbio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Confidence de Câmbio seja uma conta empresas, ou seja Banco Confidence de Câmbio conta PJ
- Para usar este recurso a conta corrente no Banco Confidence de Câmbio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Cooperativo do Brasil  - Bancoob ?

Sim.

Com a plataforma é possível definir o Banco Cooperativo do Brasil  - Bancoob como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Cooperativo do Brasil  - Bancoob.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Cooperativo do Brasil  - Bancoob não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Cooperativo do Brasil  - Bancoob.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Cooperativo do Brasil  - Bancoob seja uma conta empresas, ou seja Banco Cooperativo do Brasil  - Bancoob conta PJ
- Para usar este recurso a conta corrente no Banco Cooperativo do Brasil  - Bancoob tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Cooperativo Sicredi ?

Sim.

Com a plataforma é possível definir o Banco Cooperativo Sicredi como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Cooperativo Sicredi.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Cooperativo Sicredi não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Cooperativo Sicredi.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Cooperativo Sicredi seja uma conta empresas, ou seja Banco Cooperativo Sicredi conta PJ
- Para usar este recurso a conta corrente no Banco Cooperativo Sicredi tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Credit Agrícole Brasil ?

Sim.

Com a plataforma é possível definir o Banco Credit Agrícole Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Credit Agrícole Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Credit Agrícole Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Credit Agrícole Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Credit Agrícole Brasil seja uma conta empresas, ou seja Banco Credit Agrícole Brasil conta PJ
- Para usar este recurso a conta corrente no Banco Credit Agrícole Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Credit Suisse (Brasil) ?

Sim.

Com a plataforma é possível definir o Banco Credit Suisse (Brasil) como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Credit Suisse (Brasil).

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Credit Suisse (Brasil) não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Credit Suisse (Brasil).

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Credit Suisse (Brasil) seja uma conta empresas, ou seja Banco Credit Suisse (Brasil) conta PJ
- Para usar este recurso a conta corrente no Banco Credit Suisse (Brasil) tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Crefisa ?

Sim.

Com a plataforma é possível definir o Banco Crefisa como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Crefisa.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Crefisa não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Crefisa.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Crefisa seja uma conta empresas, ou seja Banco Crefisa conta PJ
- Para usar este recurso a conta corrente no Banco Crefisa tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Cédula ?

Sim.

Com a plataforma é possível definir o Banco Cédula como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Cédula.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Cédula não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Cédula.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Cédula seja uma conta empresas, ou seja Banco Cédula conta PJ
- Para usar este recurso a conta corrente no Banco Cédula tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco da Amazônia ?

Sim.

Com a plataforma é possível definir o Banco da Amazônia como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco da Amazônia.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco da Amazônia não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco da Amazônia.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco da Amazônia seja uma conta empresas, ou seja Banco da Amazônia conta PJ
- Para usar este recurso a conta corrente no Banco da Amazônia tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco da China Brasil ?

Sim.

Com a plataforma é possível definir o Banco da China Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco da China Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco da China Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco da China Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco da China Brasil seja uma conta empresas, ou seja Banco da China Brasil conta PJ
- Para usar este recurso a conta corrente no Banco da China Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Daycoval ?

Sim.

Com a plataforma é possível definir o Banco Daycoval como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Daycoval.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Daycoval não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Daycoval.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Daycoval seja uma conta empresas, ou seja Banco Daycoval conta PJ
- Para usar este recurso a conta corrente no Banco Daycoval tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco de Brasília ?

Sim.

Com a plataforma é possível definir o Banco de Brasília como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco de Brasília.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco de Brasília não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco de Brasília.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco de Brasília seja uma conta empresas, ou seja Banco de Brasília conta PJ
- Para usar este recurso a conta corrente no Banco de Brasília tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco de la Nacion Argentina ?

Sim.

Com a plataforma é possível definir o Banco de la Nacion Argentina como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco de la Nacion Argentina.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco de la Nacion Argentina não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco de la Nacion Argentina.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco de la Nacion Argentina seja uma conta empresas, ou seja Banco de la Nacion Argentina conta PJ
- Para usar este recurso a conta corrente no Banco de la Nacion Argentina tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco de La Provincia de Buenos Aires ?

Sim.

Com a plataforma é possível definir o Banco de La Provincia de Buenos Aires como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco de La Provincia de Buenos Aires.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco de La Provincia de Buenos Aires não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco de La Provincia de Buenos Aires.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco de La Provincia de Buenos Aires seja uma conta empresas, ou seja Banco de La Provincia de Buenos Aires conta PJ
- Para usar este recurso a conta corrente no Banco de La Provincia de Buenos Aires tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco de La Republica Oriental del Uruguay ?

Sim.

Com a plataforma é possível definir o Banco de La Republica Oriental del Uruguay como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco de La Republica Oriental del Uruguay.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco de La Republica Oriental del Uruguay não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco de La Republica Oriental del Uruguay.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco de La Republica Oriental del Uruguay seja uma conta empresas, ou seja Banco de La Republica Oriental del Uruguay conta PJ
- Para usar este recurso a conta corrente no Banco de La Republica Oriental del Uruguay tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco do Brasil ?

Sim.

Com a plataforma é possível definir o Banco do Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco do Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco do Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco do Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco do Brasil seja uma conta empresas, ou seja Banco do Brasil conta PJ
- Para usar este recurso a conta corrente no Banco do Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco do Estado de Sergipe ?

Sim.

Com a plataforma é possível definir o Banco do Estado de Sergipe como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco do Estado de Sergipe.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco do Estado de Sergipe não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco do Estado de Sergipe.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco do Estado de Sergipe seja uma conta empresas, ou seja Banco do Estado de Sergipe conta PJ
- Para usar este recurso a conta corrente no Banco do Estado de Sergipe tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco do Estado do Pará ?

Sim.

Com a plataforma é possível definir o Banco do Estado do Pará como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco do Estado do Pará.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco do Estado do Pará não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco do Estado do Pará.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco do Estado do Pará seja uma conta empresas, ou seja Banco do Estado do Pará conta PJ
- Para usar este recurso a conta corrente no Banco do Estado do Pará tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco do Estado do Rio Grande do Sul ?

Sim.

Com a plataforma é possível definir o Banco do Estado do Rio Grande do Sul como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco do Estado do Rio Grande do Sul.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco do Estado do Rio Grande do Sul não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco do Estado do Rio Grande do Sul.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco do Estado do Rio Grande do Sul seja uma conta empresas, ou seja Banco do Estado do Rio Grande do Sul conta PJ
- Para usar este recurso a conta corrente no Banco do Estado do Rio Grande do Sul tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco do Nordeste do Brasil ?

Sim.

Com a plataforma é possível definir o Banco do Nordeste do Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco do Nordeste do Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco do Nordeste do Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco do Nordeste do Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco do Nordeste do Brasil seja uma conta empresas, ou seja Banco do Nordeste do Brasil conta PJ
- Para usar este recurso a conta corrente no Banco do Nordeste do Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Fator ?

Sim.

Com a plataforma é possível definir o Banco Fator como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Fator.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Fator não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Fator.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Fator seja uma conta empresas, ou seja Banco Fator conta PJ
- Para usar este recurso a conta corrente no Banco Fator tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Fibra ?

Sim.

Com a plataforma é possível definir o Banco Fibra como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Fibra.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Fibra não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Fibra.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Fibra seja uma conta empresas, ou seja Banco Fibra conta PJ
- Para usar este recurso a conta corrente no Banco Fibra tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Ficsa ?

Sim.

Com a plataforma é possível definir o Banco Ficsa como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Ficsa.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Ficsa não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Ficsa.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Ficsa seja uma conta empresas, ou seja Banco Ficsa conta PJ
- Para usar este recurso a conta corrente no Banco Ficsa tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Finaxis ?

Sim.

Com a plataforma é possível definir o Banco Finaxis como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Finaxis.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Finaxis não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Finaxis.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Finaxis seja uma conta empresas, ou seja Banco Finaxis conta PJ
- Para usar este recurso a conta corrente no Banco Finaxis tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Guanabara ?

Sim.

Com a plataforma é possível definir o Banco Guanabara como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Guanabara.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Guanabara não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Guanabara.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Guanabara seja uma conta empresas, ou seja Banco Guanabara conta PJ
- Para usar este recurso a conta corrente no Banco Guanabara tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Inbursa ?

Sim.

Com a plataforma é possível definir o Banco Inbursa como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Inbursa.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Inbursa não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Inbursa.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Inbursa seja uma conta empresas, ou seja Banco Inbursa conta PJ
- Para usar este recurso a conta corrente no Banco Inbursa tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Industrial do Brasil ?

Sim.

Com a plataforma é possível definir o Banco Industrial do Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Industrial do Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Industrial do Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Industrial do Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Industrial do Brasil seja uma conta empresas, ou seja Banco Industrial do Brasil conta PJ
- Para usar este recurso a conta corrente no Banco Industrial do Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Indusval ?

Sim.

Com a plataforma é possível definir o Banco Indusval como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Indusval.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Indusval não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Indusval.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Indusval seja uma conta empresas, ou seja Banco Indusval conta PJ
- Para usar este recurso a conta corrente no Banco Indusval tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Inter ?

Sim.

Com a plataforma é possível definir o Banco Inter como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Inter.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Inter não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Inter.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Inter seja uma conta empresas, ou seja Banco Inter conta PJ
- Para usar este recurso a conta corrente no Banco Inter tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Intercap ?

Sim.

Com a plataforma é possível definir o Banco Intercap como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Intercap.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Intercap não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Intercap.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Intercap seja uma conta empresas, ou seja Banco Intercap conta PJ
- Para usar este recurso a conta corrente no Banco Intercap tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Investcred Unibanco ?

Sim.

Com a plataforma é possível definir o Banco Investcred Unibanco como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Investcred Unibanco.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Investcred Unibanco não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Investcred Unibanco.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Investcred Unibanco seja uma conta empresas, ou seja Banco Investcred Unibanco conta PJ
- Para usar este recurso a conta corrente no Banco Investcred Unibanco tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco ItauBank ?

Sim.

Com a plataforma é possível definir o Banco ItauBank como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco ItauBank.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco ItauBank não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco ItauBank.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco ItauBank seja uma conta empresas, ou seja Banco ItauBank conta PJ
- Para usar este recurso a conta corrente no Banco ItauBank tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Itaú BBA ?

Sim.

Com a plataforma é possível definir o Banco Itaú BBA como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Itaú BBA.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Itaú BBA não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Itaú BBA.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Itaú BBA seja uma conta empresas, ou seja Banco Itaú BBA conta PJ
- Para usar este recurso a conta corrente no Banco Itaú BBA tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Itaú Consignado ?

Sim.

Com a plataforma é possível definir o Banco Itaú Consignado como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Itaú Consignado.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Itaú Consignado não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Itaú Consignado.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Itaú Consignado seja uma conta empresas, ou seja Banco Itaú Consignado conta PJ
- Para usar este recurso a conta corrente no Banco Itaú Consignado tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco J. P. Morgan ?

Sim.

Com a plataforma é possível definir o Banco J. P. Morgan como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco J. P. Morgan.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco J. P. Morgan não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco J. P. Morgan.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco J. P. Morgan seja uma conta empresas, ou seja Banco J. P. Morgan conta PJ
- Para usar este recurso a conta corrente no Banco J. P. Morgan tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco J. Safra ?

Sim.

Com a plataforma é possível definir o Banco J. Safra como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco J. Safra.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco J. Safra não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco J. Safra.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco J. Safra seja uma conta empresas, ou seja Banco J. Safra conta PJ
- Para usar este recurso a conta corrente no Banco J. Safra tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco John Deere ?

Sim.

Com a plataforma é possível definir o Banco John Deere como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco John Deere.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco John Deere não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco John Deere.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco John Deere seja uma conta empresas, ou seja Banco John Deere conta PJ
- Para usar este recurso a conta corrente no Banco John Deere tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco KDB do Brasil ?

Sim.

Com a plataforma é possível definir o Banco KDB do Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco KDB do Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco KDB do Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco KDB do Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco KDB do Brasil seja uma conta empresas, ou seja Banco KDB do Brasil conta PJ
- Para usar este recurso a conta corrente no Banco KDB do Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Keb Hana do Brasil ?

Sim.

Com a plataforma é possível definir o Banco Keb Hana do Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Keb Hana do Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Keb Hana do Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Keb Hana do Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Keb Hana do Brasil seja uma conta empresas, ou seja Banco Keb Hana do Brasil conta PJ
- Para usar este recurso a conta corrente no Banco Keb Hana do Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Luso Brasileiro ?

Sim.

Com a plataforma é possível definir o Banco Luso Brasileiro como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Luso Brasileiro.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Luso Brasileiro não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Luso Brasileiro.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Luso Brasileiro seja uma conta empresas, ou seja Banco Luso Brasileiro conta PJ
- Para usar este recurso a conta corrente no Banco Luso Brasileiro tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Mercantil do Brasil ?

Sim.

Com a plataforma é possível definir o Banco Mercantil do Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Mercantil do Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Mercantil do Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Mercantil do Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Mercantil do Brasil seja uma conta empresas, ou seja Banco Mercantil do Brasil conta PJ
- Para usar este recurso a conta corrente no Banco Mercantil do Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Mizuho do Brasil ?

Sim.

Com a plataforma é possível definir o Banco Mizuho do Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Mizuho do Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Mizuho do Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Mizuho do Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Mizuho do Brasil seja uma conta empresas, ou seja Banco Mizuho do Brasil conta PJ
- Para usar este recurso a conta corrente no Banco Mizuho do Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Modal ?

Sim.

Com a plataforma é possível definir o Banco Modal como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Modal.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Modal não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Modal.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Modal seja uma conta empresas, ou seja Banco Modal conta PJ
- Para usar este recurso a conta corrente no Banco Modal tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Morgan Stanley ?

Sim.

Com a plataforma é possível definir o Banco Morgan Stanley como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Morgan Stanley.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Morgan Stanley não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Morgan Stanley.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Morgan Stanley seja uma conta empresas, ou seja Banco Morgan Stanley conta PJ
- Para usar este recurso a conta corrente no Banco Morgan Stanley tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco MUFG Brasil ?

Sim.

Com a plataforma é possível definir o Banco MUFG Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco MUFG Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco MUFG Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco MUFG Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco MUFG Brasil seja uma conta empresas, ou seja Banco MUFG Brasil conta PJ
- Para usar este recurso a conta corrente no Banco MUFG Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Máxima ?

Sim.

Com a plataforma é possível definir o Banco Máxima como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Máxima.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Máxima não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Máxima.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Máxima seja uma conta empresas, ou seja Banco Máxima conta PJ
- Para usar este recurso a conta corrente no Banco Máxima tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Nacional de Desenvolvimento Econômico e Social BNDES ?

Sim.

Com a plataforma é possível definir o Banco Nacional de Desenvolvimento Econômico e Social BNDES como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Nacional de Desenvolvimento Econômico e Social BNDES.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Nacional de Desenvolvimento Econômico e Social BNDES não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Nacional de Desenvolvimento Econômico e Social BNDES.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Nacional de Desenvolvimento Econômico e Social BNDES seja uma conta empresas, ou seja Banco Nacional de Desenvolvimento Econômico e Social BNDES conta PJ
- Para usar este recurso a conta corrente no Banco Nacional de Desenvolvimento Econômico e Social BNDES tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Olé Bonsucesso Consignado ?

Sim.

Com a plataforma é possível definir o Banco Olé Bonsucesso Consignado como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Olé Bonsucesso Consignado.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Olé Bonsucesso Consignado não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Olé Bonsucesso Consignado.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Olé Bonsucesso Consignado seja uma conta empresas, ou seja Banco Olé Bonsucesso Consignado conta PJ
- Para usar este recurso a conta corrente no Banco Olé Bonsucesso Consignado tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Original do Agronegócio ?

Sim.

Com a plataforma é possível definir o Banco Original do Agronegócio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Original do Agronegócio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Original do Agronegócio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Original do Agronegócio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Original do Agronegócio seja uma conta empresas, ou seja Banco Original do Agronegócio conta PJ
- Para usar este recurso a conta corrente no Banco Original do Agronegócio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Original ?

Sim.

Com a plataforma é possível definir o Banco Original como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Original.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Original não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Original.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Original seja uma conta empresas, ou seja Banco Original conta PJ
- Para usar este recurso a conta corrente no Banco Original tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Ourinvest ?

Sim.

Com a plataforma é possível definir o Banco Ourinvest como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Ourinvest.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Ourinvest não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Ourinvest.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Ourinvest seja uma conta empresas, ou seja Banco Ourinvest conta PJ
- Para usar este recurso a conta corrente no Banco Ourinvest tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Pan ?

Sim.

Com a plataforma é possível definir o Banco Pan como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Pan.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Pan não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Pan.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Pan seja uma conta empresas, ou seja Banco Pan conta PJ
- Para usar este recurso a conta corrente no Banco Pan tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Paulista ?

Sim.

Com a plataforma é possível definir o Banco Paulista como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Paulista.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Paulista não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Paulista.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Paulista seja uma conta empresas, ou seja Banco Paulista conta PJ
- Para usar este recurso a conta corrente no Banco Paulista tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Pine ?

Sim.

Com a plataforma é possível definir o Banco Pine como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Pine.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Pine não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Pine.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Pine seja uma conta empresas, ou seja Banco Pine conta PJ
- Para usar este recurso a conta corrente no Banco Pine tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Rabobank International Brasil ?

Sim.

Com a plataforma é possível definir o Banco Rabobank International Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Rabobank International Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Rabobank International Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Rabobank International Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Rabobank International Brasil seja uma conta empresas, ou seja Banco Rabobank International Brasil conta PJ
- Para usar este recurso a conta corrente no Banco Rabobank International Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Rendimento ?

Sim.

Com a plataforma é possível definir o Banco Rendimento como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Rendimento.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Rendimento não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Rendimento.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Rendimento seja uma conta empresas, ou seja Banco Rendimento conta PJ
- Para usar este recurso a conta corrente no Banco Rendimento tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Ribeirão Preto ?

Sim.

Com a plataforma é possível definir o Banco Ribeirão Preto como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Ribeirão Preto.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Ribeirão Preto não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Ribeirão Preto.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Ribeirão Preto seja uma conta empresas, ou seja Banco Ribeirão Preto conta PJ
- Para usar este recurso a conta corrente no Banco Ribeirão Preto tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Rodobens SA ?

Sim.

Com a plataforma é possível definir o Banco Rodobens SA como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Rodobens SA.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Rodobens SA não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Rodobens SA.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Rodobens SA seja uma conta empresas, ou seja Banco Rodobens SA conta PJ
- Para usar este recurso a conta corrente no Banco Rodobens SA tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Safra ?

Sim.

Com a plataforma é possível definir o Banco Safra como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Safra.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Safra não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Safra.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Safra seja uma conta empresas, ou seja Banco Safra conta PJ
- Para usar este recurso a conta corrente no Banco Safra tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Santander (Brasil) ?

Sim.

Com a plataforma é possível definir o Banco Santander (Brasil) como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Santander (Brasil).

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Santander (Brasil) não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Santander (Brasil).

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Santander (Brasil) seja uma conta empresas, ou seja Banco Santander (Brasil) conta PJ
- Para usar este recurso a conta corrente no Banco Santander (Brasil) tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Semear ?

Sim.

Com a plataforma é possível definir o Banco Semear como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Semear.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Semear não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Semear.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Semear seja uma conta empresas, ou seja Banco Semear conta PJ
- Para usar este recurso a conta corrente no Banco Semear tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Sistema ?

Sim.

Com a plataforma é possível definir o Banco Sistema como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Sistema.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Sistema não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Sistema.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Sistema seja uma conta empresas, ou seja Banco Sistema conta PJ
- Para usar este recurso a conta corrente no Banco Sistema tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Société Générale Brasil ?

Sim.

Com a plataforma é possível definir o Banco Société Générale Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Société Générale Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Société Générale Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Société Générale Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Société Générale Brasil seja uma conta empresas, ou seja Banco Société Générale Brasil conta PJ
- Para usar este recurso a conta corrente no Banco Société Générale Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Sofisa ?

Sim.

Com a plataforma é possível definir o Banco Sofisa como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Sofisa.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Sofisa não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Sofisa.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Sofisa seja uma conta empresas, ou seja Banco Sofisa conta PJ
- Para usar este recurso a conta corrente no Banco Sofisa tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Sumitomo Mitsui Brasileiro ?

Sim.

Com a plataforma é possível definir o Banco Sumitomo Mitsui Brasileiro como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Sumitomo Mitsui Brasileiro.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Sumitomo Mitsui Brasileiro não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Sumitomo Mitsui Brasileiro.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Sumitomo Mitsui Brasileiro seja uma conta empresas, ou seja Banco Sumitomo Mitsui Brasileiro conta PJ
- Para usar este recurso a conta corrente no Banco Sumitomo Mitsui Brasileiro tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Topazio ?

Sim.

Com a plataforma é possível definir o Banco Topazio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Topazio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Topazio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Topazio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Topazio seja uma conta empresas, ou seja Banco Topazio conta PJ
- Para usar este recurso a conta corrente no Banco Topazio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Tricury ?

Sim.

Com a plataforma é possível definir o Banco Tricury como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Tricury.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Tricury não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Tricury.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Tricury seja uma conta empresas, ou seja Banco Tricury conta PJ
- Para usar este recurso a conta corrente no Banco Tricury tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Triângulo ?

Sim.

Com a plataforma é possível definir o Banco Triângulo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Triângulo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Triângulo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Triângulo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Triângulo seja uma conta empresas, ou seja Banco Triângulo conta PJ
- Para usar este recurso a conta corrente no Banco Triângulo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Votorantim ?

Sim.

Com a plataforma é possível definir o Banco Votorantim como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Votorantim.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Votorantim não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Votorantim.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Votorantim seja uma conta empresas, ou seja Banco Votorantim conta PJ
- Para usar este recurso a conta corrente no Banco Votorantim tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco VR ?

Sim.

Com a plataforma é possível definir o Banco VR como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco VR.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco VR não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco VR.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco VR seja uma conta empresas, ou seja Banco VR conta PJ
- Para usar este recurso a conta corrente no Banco VR tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Western Union do Brasil ?

Sim.

Com a plataforma é possível definir o Banco Western Union do Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Western Union do Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Western Union do Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Western Union do Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Western Union do Brasil seja uma conta empresas, ou seja Banco Western Union do Brasil conta PJ
- Para usar este recurso a conta corrente no Banco Western Union do Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banco Woori Bank do Brasil ?

Sim.

Com a plataforma é possível definir o Banco Woori Bank do Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banco Woori Bank do Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banco Woori Bank do Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banco Woori Bank do Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banco Woori Bank do Brasil seja uma conta empresas, ou seja Banco Woori Bank do Brasil conta PJ
- Para usar este recurso a conta corrente no Banco Woori Bank do Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Banestes  Banco do Estado do Espírito Santo ?

Sim.

Com a plataforma é possível definir o Banestes  Banco do Estado do Espírito Santo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Banestes  Banco do Estado do Espírito Santo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Banestes  Banco do Estado do Espírito Santo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Banestes  Banco do Estado do Espírito Santo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Banestes  Banco do Estado do Espírito Santo seja uma conta empresas, ou seja Banestes  Banco do Estado do Espírito Santo conta PJ
- Para usar este recurso a conta corrente no Banestes  Banco do Estado do Espírito Santo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Bank of America Merrill Lynch Banco Múltiplo ?

Sim.

Com a plataforma é possível definir o Bank of America Merrill Lynch Banco Múltiplo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Bank of America Merrill Lynch Banco Múltiplo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Bank of America Merrill Lynch Banco Múltiplo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Bank of America Merrill Lynch Banco Múltiplo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Bank of America Merrill Lynch Banco Múltiplo seja uma conta empresas, ou seja Bank of America Merrill Lynch Banco Múltiplo conta PJ
- Para usar este recurso a conta corrente no Bank of America Merrill Lynch Banco Múltiplo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Barigui Companhia Hipotecária ?

Sim.

Com a plataforma é possível definir o Barigui Companhia Hipotecária como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Barigui Companhia Hipotecária.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Barigui Companhia Hipotecária não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Barigui Companhia Hipotecária.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Barigui Companhia Hipotecária seja uma conta empresas, ou seja Barigui Companhia Hipotecária conta PJ
- Para usar este recurso a conta corrente no Barigui Companhia Hipotecária tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o BBN Banco Brasileiro de Negocios ?

Sim.

Com a plataforma é possível definir o BBN Banco Brasileiro de Negocios como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta BBN Banco Brasileiro de Negocios.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ BBN Banco Brasileiro de Negocios não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no BBN Banco Brasileiro de Negocios.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no BBN Banco Brasileiro de Negocios seja uma conta empresas, ou seja BBN Banco Brasileiro de Negocios conta PJ
- Para usar este recurso a conta corrente no BBN Banco Brasileiro de Negocios tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o BCV - Banco de Crédito e Varejo ?

Sim.

Com a plataforma é possível definir o BCV - Banco de Crédito e Varejo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta BCV - Banco de Crédito e Varejo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ BCV - Banco de Crédito e Varejo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no BCV - Banco de Crédito e Varejo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no BCV - Banco de Crédito e Varejo seja uma conta empresas, ou seja BCV - Banco de Crédito e Varejo conta PJ
- Para usar este recurso a conta corrente no BCV - Banco de Crédito e Varejo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Bexs Banco de Câmbio ?

Sim.

Com a plataforma é possível definir o Bexs Banco de Câmbio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Bexs Banco de Câmbio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Bexs Banco de Câmbio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Bexs Banco de Câmbio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Bexs Banco de Câmbio seja uma conta empresas, ou seja Bexs Banco de Câmbio conta PJ
- Para usar este recurso a conta corrente no Bexs Banco de Câmbio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Bexs Corretora de Câmbio ?

Sim.

Com a plataforma é possível definir o Bexs Corretora de Câmbio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Bexs Corretora de Câmbio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Bexs Corretora de Câmbio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Bexs Corretora de Câmbio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Bexs Corretora de Câmbio seja uma conta empresas, ou seja Bexs Corretora de Câmbio conta PJ
- Para usar este recurso a conta corrente no Bexs Corretora de Câmbio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o BGC Liquidez Distribuidora de Títulos e Valores Mobiliários Ltda. ?

Sim.

Com a plataforma é possível definir o BGC Liquidez Distribuidora de Títulos e Valores Mobiliários Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta BGC Liquidez Distribuidora de Títulos e Valores Mobiliários Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ BGC Liquidez Distribuidora de Títulos e Valores Mobiliários Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no BGC Liquidez Distribuidora de Títulos e Valores Mobiliários Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no BGC Liquidez Distribuidora de Títulos e Valores Mobiliários Ltda. seja uma conta empresas, ou seja BGC Liquidez Distribuidora de Títulos e Valores Mobiliários Ltda. conta PJ
- Para usar este recurso a conta corrente no BGC Liquidez Distribuidora de Títulos e Valores Mobiliários Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o BNY Mellon Banco ?

Sim.

Com a plataforma é possível definir o BNY Mellon Banco como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta BNY Mellon Banco.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ BNY Mellon Banco não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no BNY Mellon Banco.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no BNY Mellon Banco seja uma conta empresas, ou seja BNY Mellon Banco conta PJ
- Para usar este recurso a conta corrente no BNY Mellon Banco tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o BPP Instituição de Pagamento ?

Sim.

Com a plataforma é possível definir o BPP Instituição de Pagamento como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta BPP Instituição de Pagamento.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ BPP Instituição de Pagamento não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no BPP Instituição de Pagamento.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no BPP Instituição de Pagamento seja uma conta empresas, ou seja BPP Instituição de Pagamento conta PJ
- Para usar este recurso a conta corrente no BPP Instituição de Pagamento tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o BR Partners Banco de Investimento ?

Sim.

Com a plataforma é possível definir o BR Partners Banco de Investimento como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta BR Partners Banco de Investimento.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ BR Partners Banco de Investimento não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no BR Partners Banco de Investimento.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no BR Partners Banco de Investimento seja uma conta empresas, ou seja BR Partners Banco de Investimento conta PJ
- Para usar este recurso a conta corrente no BR Partners Banco de Investimento tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Brasil Plural  Banco Múltiplo ?

Sim.

Com a plataforma é possível definir o Brasil Plural  Banco Múltiplo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Brasil Plural  Banco Múltiplo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Brasil Plural  Banco Múltiplo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Brasil Plural  Banco Múltiplo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Brasil Plural  Banco Múltiplo seja uma conta empresas, ou seja Brasil Plural  Banco Múltiplo conta PJ
- Para usar este recurso a conta corrente no Brasil Plural  Banco Múltiplo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o BRK  Crédito ?

Sim.

Com a plataforma é possível definir o BRK  Crédito como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta BRK  Crédito.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ BRK  Crédito não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no BRK  Crédito.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no BRK  Crédito seja uma conta empresas, ou seja BRK  Crédito conta PJ
- Para usar este recurso a conta corrente no BRK  Crédito tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o BRL Trust Distribuidora de Títulos e Valores Mobiliários ?

Sim.

Com a plataforma é possível definir o BRL Trust Distribuidora de Títulos e Valores Mobiliários como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta BRL Trust Distribuidora de Títulos e Valores Mobiliários.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ BRL Trust Distribuidora de Títulos e Valores Mobiliários não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no BRL Trust Distribuidora de Títulos e Valores Mobiliários.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no BRL Trust Distribuidora de Títulos e Valores Mobiliários seja uma conta empresas, ou seja BRL Trust Distribuidora de Títulos e Valores Mobiliários conta PJ
- Para usar este recurso a conta corrente no BRL Trust Distribuidora de Títulos e Valores Mobiliários tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Broker Brasil Corretora de Câmbio Ltda. ?

Sim.

Com a plataforma é possível definir o Broker Brasil Corretora de Câmbio Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Broker Brasil Corretora de Câmbio Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Broker Brasil Corretora de Câmbio Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Broker Brasil Corretora de Câmbio Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Broker Brasil Corretora de Câmbio Ltda. seja uma conta empresas, ou seja Broker Brasil Corretora de Câmbio Ltda. conta PJ
- Para usar este recurso a conta corrente no Broker Brasil Corretora de Câmbio Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o BS2 Distribuidora de Títulos e Valores Mobiliários ?

Sim.

Com a plataforma é possível definir o BS2 Distribuidora de Títulos e Valores Mobiliários como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta BS2 Distribuidora de Títulos e Valores Mobiliários.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ BS2 Distribuidora de Títulos e Valores Mobiliários não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no BS2 Distribuidora de Títulos e Valores Mobiliários.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no BS2 Distribuidora de Títulos e Valores Mobiliários seja uma conta empresas, ou seja BS2 Distribuidora de Títulos e Valores Mobiliários conta PJ
- Para usar este recurso a conta corrente no BS2 Distribuidora de Títulos e Valores Mobiliários tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o BT Corretora de Câmbio Ltda. ?

Sim.

Com a plataforma é possível definir o BT Corretora de Câmbio Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta BT Corretora de Câmbio Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ BT Corretora de Câmbio Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no BT Corretora de Câmbio Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no BT Corretora de Câmbio Ltda. seja uma conta empresas, ou seja BT Corretora de Câmbio Ltda. conta PJ
- Para usar este recurso a conta corrente no BT Corretora de Câmbio Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Caixa Econômica Federal ?

Sim.

Com a plataforma é possível definir o Caixa Econômica Federal como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Caixa Econômica Federal.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Caixa Econômica Federal não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Caixa Econômica Federal.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Caixa Econômica Federal seja uma conta empresas, ou seja Caixa Econômica Federal conta PJ
- Para usar este recurso a conta corrente no Caixa Econômica Federal tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Carol Distribuidora de Títulos e Valores Mobiliários Ltda. ?

Sim.

Com a plataforma é possível definir o Carol Distribuidora de Títulos e Valores Mobiliários Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Carol Distribuidora de Títulos e Valores Mobiliários Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Carol Distribuidora de Títulos e Valores Mobiliários Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Carol Distribuidora de Títulos e Valores Mobiliários Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Carol Distribuidora de Títulos e Valores Mobiliários Ltda. seja uma conta empresas, ou seja Carol Distribuidora de Títulos e Valores Mobiliários Ltda. conta PJ
- Para usar este recurso a conta corrente no Carol Distribuidora de Títulos e Valores Mobiliários Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Caruana  Sociedade de Crédito ?

Sim.

Com a plataforma é possível definir o Caruana  Sociedade de Crédito como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Caruana  Sociedade de Crédito.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Caruana  Sociedade de Crédito não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Caruana  Sociedade de Crédito.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Caruana  Sociedade de Crédito seja uma conta empresas, ou seja Caruana  Sociedade de Crédito conta PJ
- Para usar este recurso a conta corrente no Caruana  Sociedade de Crédito tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Casa do Crédito  Sociedade de Crédito ao Microempreendedor ?

Sim.

Com a plataforma é possível definir o Casa do Crédito  Sociedade de Crédito ao Microempreendedor como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Casa do Crédito  Sociedade de Crédito ao Microempreendedor.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Casa do Crédito  Sociedade de Crédito ao Microempreendedor não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Casa do Crédito  Sociedade de Crédito ao Microempreendedor.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Casa do Crédito  Sociedade de Crédito ao Microempreendedor seja uma conta empresas, ou seja Casa do Crédito  Sociedade de Crédito ao Microempreendedor conta PJ
- Para usar este recurso a conta corrente no Casa do Crédito  Sociedade de Crédito ao Microempreendedor tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Central Cooperativa de Crédito no Estado do Espírito Santo - CECOOP ?

Sim.

Com a plataforma é possível definir o Central Cooperativa de Crédito no Estado do Espírito Santo - CECOOP como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Central Cooperativa de Crédito no Estado do Espírito Santo - CECOOP.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Central Cooperativa de Crédito no Estado do Espírito Santo - CECOOP não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Central Cooperativa de Crédito no Estado do Espírito Santo - CECOOP.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Central Cooperativa de Crédito no Estado do Espírito Santo - CECOOP seja uma conta empresas, ou seja Central Cooperativa de Crédito no Estado do Espírito Santo - CECOOP conta PJ
- Para usar este recurso a conta corrente no Central Cooperativa de Crédito no Estado do Espírito Santo - CECOOP tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Central de Cooperativas de Economia e Crédito Mútuo do Est RS - Unicred ?

Sim.

Com a plataforma é possível definir o Central de Cooperativas de Economia e Crédito Mútuo do Est RS - Unicred como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Central de Cooperativas de Economia e Crédito Mútuo do Est RS - Unicred.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Central de Cooperativas de Economia e Crédito Mútuo do Est RS - Unicred não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Central de Cooperativas de Economia e Crédito Mútuo do Est RS - Unicred.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Central de Cooperativas de Economia e Crédito Mútuo do Est RS - Unicred seja uma conta empresas, ou seja Central de Cooperativas de Economia e Crédito Mútuo do Est RS - Unicred conta PJ
- Para usar este recurso a conta corrente no Central de Cooperativas de Economia e Crédito Mútuo do Est RS - Unicred tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o China Construction Bank (Brasil) Banco Múltiplo ?

Sim.

Com a plataforma é possível definir o China Construction Bank (Brasil) Banco Múltiplo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta China Construction Bank (Brasil) Banco Múltiplo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ China Construction Bank (Brasil) Banco Múltiplo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no China Construction Bank (Brasil) Banco Múltiplo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no China Construction Bank (Brasil) Banco Múltiplo seja uma conta empresas, ou seja China Construction Bank (Brasil) Banco Múltiplo conta PJ
- Para usar este recurso a conta corrente no China Construction Bank (Brasil) Banco Múltiplo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Citibank N.A. ?

Sim.

Com a plataforma é possível definir o Citibank N.A. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Citibank N.A..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Citibank N.A. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Citibank N.A..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Citibank N.A. seja uma conta empresas, ou seja Citibank N.A. conta PJ
- Para usar este recurso a conta corrente no Citibank N.A. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o CM Capital Markets Corretora de Câmbio ?

Sim.

Com a plataforma é possível definir o CM Capital Markets Corretora de Câmbio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta CM Capital Markets Corretora de Câmbio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ CM Capital Markets Corretora de Câmbio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no CM Capital Markets Corretora de Câmbio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no CM Capital Markets Corretora de Câmbio seja uma conta empresas, ou seja CM Capital Markets Corretora de Câmbio conta PJ
- Para usar este recurso a conta corrente no CM Capital Markets Corretora de Câmbio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Commerzbank Brasil  - Banco Múltiplo ?

Sim.

Com a plataforma é possível definir o Commerzbank Brasil  - Banco Múltiplo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Commerzbank Brasil  - Banco Múltiplo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Commerzbank Brasil  - Banco Múltiplo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Commerzbank Brasil  - Banco Múltiplo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Commerzbank Brasil  - Banco Múltiplo seja uma conta empresas, ou seja Commerzbank Brasil  - Banco Múltiplo conta PJ
- Para usar este recurso a conta corrente no Commerzbank Brasil  - Banco Múltiplo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Confederação Nacional das Cooperativas Centrais de Crédito e Economia Familiar e ?

Sim.

Com a plataforma é possível definir o Confederação Nacional das Cooperativas Centrais de Crédito e Economia Familiar e como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Confederação Nacional das Cooperativas Centrais de Crédito e Economia Familiar e.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Confederação Nacional das Cooperativas Centrais de Crédito e Economia Familiar e não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Confederação Nacional das Cooperativas Centrais de Crédito e Economia Familiar e.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Confederação Nacional das Cooperativas Centrais de Crédito e Economia Familiar e seja uma conta empresas, ou seja Confederação Nacional das Cooperativas Centrais de Crédito e Economia Familiar e conta PJ
- Para usar este recurso a conta corrente no Confederação Nacional das Cooperativas Centrais de Crédito e Economia Familiar e tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Confederação Nacional das Cooperativas Centrais Unicred Ltda – Unicred do Brasil ?

Sim.

Com a plataforma é possível definir o Confederação Nacional das Cooperativas Centrais Unicred Ltda – Unicred do Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Confederação Nacional das Cooperativas Centrais Unicred Ltda – Unicred do Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Confederação Nacional das Cooperativas Centrais Unicred Ltda – Unicred do Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Confederação Nacional das Cooperativas Centrais Unicred Ltda – Unicred do Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Confederação Nacional das Cooperativas Centrais Unicred Ltda – Unicred do Brasil seja uma conta empresas, ou seja Confederação Nacional das Cooperativas Centrais Unicred Ltda – Unicred do Brasil conta PJ
- Para usar este recurso a conta corrente no Confederação Nacional das Cooperativas Centrais Unicred Ltda – Unicred do Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Confidence Corretora de Câmbio ?

Sim.

Com a plataforma é possível definir o Confidence Corretora de Câmbio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Confidence Corretora de Câmbio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Confidence Corretora de Câmbio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Confidence Corretora de Câmbio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Confidence Corretora de Câmbio seja uma conta empresas, ou seja Confidence Corretora de Câmbio conta PJ
- Para usar este recurso a conta corrente no Confidence Corretora de Câmbio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Coop de Créd. Mútuo dos Despachantes de Trânsito de SC e Rio Grande do Sul ?

Sim.

Com a plataforma é possível definir o Coop de Créd. Mútuo dos Despachantes de Trânsito de SC e Rio Grande do Sul como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Coop de Créd. Mútuo dos Despachantes de Trânsito de SC e Rio Grande do Sul.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Coop de Créd. Mútuo dos Despachantes de Trânsito de SC e Rio Grande do Sul não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Coop de Créd. Mútuo dos Despachantes de Trânsito de SC e Rio Grande do Sul.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Coop de Créd. Mútuo dos Despachantes de Trânsito de SC e Rio Grande do Sul seja uma conta empresas, ou seja Coop de Créd. Mútuo dos Despachantes de Trânsito de SC e Rio Grande do Sul conta PJ
- Para usar este recurso a conta corrente no Coop de Créd. Mútuo dos Despachantes de Trânsito de SC e Rio Grande do Sul tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Cooperativa Central de Crédito - Ailos ?

Sim.

Com a plataforma é possível definir o Cooperativa Central de Crédito - Ailos como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Cooperativa Central de Crédito - Ailos.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Cooperativa Central de Crédito - Ailos não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Cooperativa Central de Crédito - Ailos.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Cooperativa Central de Crédito - Ailos seja uma conta empresas, ou seja Cooperativa Central de Crédito - Ailos conta PJ
- Para usar este recurso a conta corrente no Cooperativa Central de Crédito - Ailos tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Cooperativa Central de Crédito Noroeste Brasileiro Ltda - CentralCredi ?

Sim.

Com a plataforma é possível definir o Cooperativa Central de Crédito Noroeste Brasileiro Ltda - CentralCredi como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Cooperativa Central de Crédito Noroeste Brasileiro Ltda - CentralCredi.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Cooperativa Central de Crédito Noroeste Brasileiro Ltda - CentralCredi não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Cooperativa Central de Crédito Noroeste Brasileiro Ltda - CentralCredi.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Cooperativa Central de Crédito Noroeste Brasileiro Ltda - CentralCredi seja uma conta empresas, ou seja Cooperativa Central de Crédito Noroeste Brasileiro Ltda - CentralCredi conta PJ
- Para usar este recurso a conta corrente no Cooperativa Central de Crédito Noroeste Brasileiro Ltda - CentralCredi tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Cooperativa de Crédito Rural Coopavel ?

Sim.

Com a plataforma é possível definir o Cooperativa de Crédito Rural Coopavel como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Cooperativa de Crédito Rural Coopavel.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Cooperativa de Crédito Rural Coopavel não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Cooperativa de Crédito Rural Coopavel.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Cooperativa de Crédito Rural Coopavel seja uma conta empresas, ou seja Cooperativa de Crédito Rural Coopavel conta PJ
- Para usar este recurso a conta corrente no Cooperativa de Crédito Rural Coopavel tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Cooperativa de Crédito Rural da Região da Mogiana ?

Sim.

Com a plataforma é possível definir o Cooperativa de Crédito Rural da Região da Mogiana como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Cooperativa de Crédito Rural da Região da Mogiana.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Cooperativa de Crédito Rural da Região da Mogiana não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Cooperativa de Crédito Rural da Região da Mogiana.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Cooperativa de Crédito Rural da Região da Mogiana seja uma conta empresas, ou seja Cooperativa de Crédito Rural da Região da Mogiana conta PJ
- Para usar este recurso a conta corrente no Cooperativa de Crédito Rural da Região da Mogiana tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Cooperativa de Crédito Rural de Ouro Sulcredi/Ouro ?

Sim.

Com a plataforma é possível definir o Cooperativa de Crédito Rural de Ouro Sulcredi/Ouro como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Cooperativa de Crédito Rural de Ouro Sulcredi/Ouro.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Cooperativa de Crédito Rural de Ouro Sulcredi/Ouro não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Cooperativa de Crédito Rural de Ouro Sulcredi/Ouro.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Cooperativa de Crédito Rural de Ouro Sulcredi/Ouro seja uma conta empresas, ou seja Cooperativa de Crédito Rural de Ouro Sulcredi/Ouro conta PJ
- Para usar este recurso a conta corrente no Cooperativa de Crédito Rural de Ouro Sulcredi/Ouro tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Cooperativa de Crédito Rural de Primavera do Leste ?

Sim.

Com a plataforma é possível definir o Cooperativa de Crédito Rural de Primavera do Leste como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Cooperativa de Crédito Rural de Primavera do Leste.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Cooperativa de Crédito Rural de Primavera do Leste não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Cooperativa de Crédito Rural de Primavera do Leste.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Cooperativa de Crédito Rural de Primavera do Leste seja uma conta empresas, ou seja Cooperativa de Crédito Rural de Primavera do Leste conta PJ
- Para usar este recurso a conta corrente no Cooperativa de Crédito Rural de Primavera do Leste tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Cooperativa de Crédito Rural de São Miguel do Oeste - Sulcredi/São Miguel ?

Sim.

Com a plataforma é possível definir o Cooperativa de Crédito Rural de São Miguel do Oeste - Sulcredi/São Miguel como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Cooperativa de Crédito Rural de São Miguel do Oeste - Sulcredi/São Miguel.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Cooperativa de Crédito Rural de São Miguel do Oeste - Sulcredi/São Miguel não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Cooperativa de Crédito Rural de São Miguel do Oeste - Sulcredi/São Miguel.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Cooperativa de Crédito Rural de São Miguel do Oeste - Sulcredi/São Miguel seja uma conta empresas, ou seja Cooperativa de Crédito Rural de São Miguel do Oeste - Sulcredi/São Miguel conta PJ
- Para usar este recurso a conta corrente no Cooperativa de Crédito Rural de São Miguel do Oeste - Sulcredi/São Miguel tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Cooperativa de Economia e Crédito Mútuo dos Servidores Públicos Estaduais do Rio ?

Sim.

Com a plataforma é possível definir o Cooperativa de Economia e Crédito Mútuo dos Servidores Públicos Estaduais do Rio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Cooperativa de Economia e Crédito Mútuo dos Servidores Públicos Estaduais do Rio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Cooperativa de Economia e Crédito Mútuo dos Servidores Públicos Estaduais do Rio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Cooperativa de Economia e Crédito Mútuo dos Servidores Públicos Estaduais do Rio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Cooperativa de Economia e Crédito Mútuo dos Servidores Públicos Estaduais do Rio seja uma conta empresas, ou seja Cooperativa de Economia e Crédito Mútuo dos Servidores Públicos Estaduais do Rio conta PJ
- Para usar este recurso a conta corrente no Cooperativa de Economia e Crédito Mútuo dos Servidores Públicos Estaduais do Rio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Credialiança Cooperativa de Crédito Rural ?

Sim.

Com a plataforma é possível definir o Credialiança Cooperativa de Crédito Rural como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Credialiança Cooperativa de Crédito Rural.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Credialiança Cooperativa de Crédito Rural não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Credialiança Cooperativa de Crédito Rural.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Credialiança Cooperativa de Crédito Rural seja uma conta empresas, ou seja Credialiança Cooperativa de Crédito Rural conta PJ
- Para usar este recurso a conta corrente no Credialiança Cooperativa de Crédito Rural tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Credicoamo Crédito Rural Cooperativa ?

Sim.

Com a plataforma é possível definir o Credicoamo Crédito Rural Cooperativa como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Credicoamo Crédito Rural Cooperativa.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Credicoamo Crédito Rural Cooperativa não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Credicoamo Crédito Rural Cooperativa.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Credicoamo Crédito Rural Cooperativa seja uma conta empresas, ou seja Credicoamo Crédito Rural Cooperativa conta PJ
- Para usar este recurso a conta corrente no Credicoamo Crédito Rural Cooperativa tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Credit Suisse Hedging-Griffo Corretora de Valores ?

Sim.

Com a plataforma é possível definir o Credit Suisse Hedging-Griffo Corretora de Valores como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Credit Suisse Hedging-Griffo Corretora de Valores.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Credit Suisse Hedging-Griffo Corretora de Valores não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Credit Suisse Hedging-Griffo Corretora de Valores.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Credit Suisse Hedging-Griffo Corretora de Valores seja uma conta empresas, ou seja Credit Suisse Hedging-Griffo Corretora de Valores conta PJ
- Para usar este recurso a conta corrente no Credit Suisse Hedging-Griffo Corretora de Valores tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Dacasa Financeira  - Sociedade de Crédito ?

Sim.

Com a plataforma é possível definir o Dacasa Financeira  - Sociedade de Crédito como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Dacasa Financeira  - Sociedade de Crédito.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Dacasa Financeira  - Sociedade de Crédito não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Dacasa Financeira  - Sociedade de Crédito.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Dacasa Financeira  - Sociedade de Crédito seja uma conta empresas, ou seja Dacasa Financeira  - Sociedade de Crédito conta PJ
- Para usar este recurso a conta corrente no Dacasa Financeira  - Sociedade de Crédito tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Deutsche Bank  - Banco Alemão ?

Sim.

Com a plataforma é possível definir o Deutsche Bank  - Banco Alemão como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Deutsche Bank  - Banco Alemão.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Deutsche Bank  - Banco Alemão não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Deutsche Bank  - Banco Alemão.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Deutsche Bank  - Banco Alemão seja uma conta empresas, ou seja Deutsche Bank  - Banco Alemão conta PJ
- Para usar este recurso a conta corrente no Deutsche Bank  - Banco Alemão tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Easynvest - Título Corretora de Valores SA ?

Sim.

Com a plataforma é possível definir o Easynvest - Título Corretora de Valores SA como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Easynvest - Título Corretora de Valores SA.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Easynvest - Título Corretora de Valores SA não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Easynvest - Título Corretora de Valores SA.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Easynvest - Título Corretora de Valores SA seja uma conta empresas, ou seja Easynvest - Título Corretora de Valores SA conta PJ
- Para usar este recurso a conta corrente no Easynvest - Título Corretora de Valores SA tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Facta Financeira  - Crédito Financiamento e Investimento ?

Sim.

Com a plataforma é possível definir o Facta Financeira  - Crédito Financiamento e Investimento como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Facta Financeira  - Crédito Financiamento e Investimento.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Facta Financeira  - Crédito Financiamento e Investimento não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Facta Financeira  - Crédito Financiamento e Investimento.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Facta Financeira  - Crédito Financiamento e Investimento seja uma conta empresas, ou seja Facta Financeira  - Crédito Financiamento e Investimento conta PJ
- Para usar este recurso a conta corrente no Facta Financeira  - Crédito Financiamento e Investimento tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Fair Corretora de Câmbio ?

Sim.

Com a plataforma é possível definir o Fair Corretora de Câmbio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Fair Corretora de Câmbio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Fair Corretora de Câmbio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Fair Corretora de Câmbio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Fair Corretora de Câmbio seja uma conta empresas, ou seja Fair Corretora de Câmbio conta PJ
- Para usar este recurso a conta corrente no Fair Corretora de Câmbio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Financiamento e Investimento ?

Sim.

Com a plataforma é possível definir o Financiamento e Investimento como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Financiamento e Investimento.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Financiamento e Investimento não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Financiamento e Investimento.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Financiamento e Investimento seja uma conta empresas, ou seja Financiamento e Investimento conta PJ
- Para usar este recurso a conta corrente no Financiamento e Investimento tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Financiamento e Investimentos ?

Sim.

Com a plataforma é possível definir o Financiamento e Investimentos como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Financiamento e Investimentos.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Financiamento e Investimentos não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Financiamento e Investimentos.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Financiamento e Investimentos seja uma conta empresas, ou seja Financiamento e Investimentos conta PJ
- Para usar este recurso a conta corrente no Financiamento e Investimentos tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Frente Corretora de Câmbio Ltda. ?

Sim.

Com a plataforma é possível definir o Frente Corretora de Câmbio Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Frente Corretora de Câmbio Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Frente Corretora de Câmbio Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Frente Corretora de Câmbio Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Frente Corretora de Câmbio Ltda. seja uma conta empresas, ou seja Frente Corretora de Câmbio Ltda. conta PJ
- Para usar este recurso a conta corrente no Frente Corretora de Câmbio Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Genial Investimentos Corretora de Valores Mobiliários ?

Sim.

Com a plataforma é possível definir o Genial Investimentos Corretora de Valores Mobiliários como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Genial Investimentos Corretora de Valores Mobiliários.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Genial Investimentos Corretora de Valores Mobiliários não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Genial Investimentos Corretora de Valores Mobiliários.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Genial Investimentos Corretora de Valores Mobiliários seja uma conta empresas, ou seja Genial Investimentos Corretora de Valores Mobiliários conta PJ
- Para usar este recurso a conta corrente no Genial Investimentos Corretora de Valores Mobiliários tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Get Money Corretora de Câmbio ?

Sim.

Com a plataforma é possível definir o Get Money Corretora de Câmbio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Get Money Corretora de Câmbio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Get Money Corretora de Câmbio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Get Money Corretora de Câmbio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Get Money Corretora de Câmbio seja uma conta empresas, ou seja Get Money Corretora de Câmbio conta PJ
- Para usar este recurso a conta corrente no Get Money Corretora de Câmbio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Goldman Sachs do Brasil Banco Múltiplo ?

Sim.

Com a plataforma é possível definir o Goldman Sachs do Brasil Banco Múltiplo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Goldman Sachs do Brasil Banco Múltiplo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Goldman Sachs do Brasil Banco Múltiplo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Goldman Sachs do Brasil Banco Múltiplo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Goldman Sachs do Brasil Banco Múltiplo seja uma conta empresas, ou seja Goldman Sachs do Brasil Banco Múltiplo conta PJ
- Para usar este recurso a conta corrente no Goldman Sachs do Brasil Banco Múltiplo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Guide Investimentos  Corretora de Valores ?

Sim.

Com a plataforma é possível definir o Guide Investimentos  Corretora de Valores como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Guide Investimentos  Corretora de Valores.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Guide Investimentos  Corretora de Valores não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Guide Investimentos  Corretora de Valores.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Guide Investimentos  Corretora de Valores seja uma conta empresas, ou seja Guide Investimentos  Corretora de Valores conta PJ
- Para usar este recurso a conta corrente no Guide Investimentos  Corretora de Valores tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Guitta Corretora de Câmbio Ltda. ?

Sim.

Com a plataforma é possível definir o Guitta Corretora de Câmbio Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Guitta Corretora de Câmbio Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Guitta Corretora de Câmbio Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Guitta Corretora de Câmbio Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Guitta Corretora de Câmbio Ltda. seja uma conta empresas, ou seja Guitta Corretora de Câmbio Ltda. conta PJ
- Para usar este recurso a conta corrente no Guitta Corretora de Câmbio Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Haitong Banco de Investimento do Brasil ?

Sim.

Com a plataforma é possível definir o Haitong Banco de Investimento do Brasil como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Haitong Banco de Investimento do Brasil.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Haitong Banco de Investimento do Brasil não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Haitong Banco de Investimento do Brasil.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Haitong Banco de Investimento do Brasil seja uma conta empresas, ou seja Haitong Banco de Investimento do Brasil conta PJ
- Para usar este recurso a conta corrente no Haitong Banco de Investimento do Brasil tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Hipercard Banco Múltiplo ?

Sim.

Com a plataforma é possível definir o Hipercard Banco Múltiplo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Hipercard Banco Múltiplo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Hipercard Banco Múltiplo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Hipercard Banco Múltiplo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Hipercard Banco Múltiplo seja uma conta empresas, ou seja Hipercard Banco Múltiplo conta PJ
- Para usar este recurso a conta corrente no Hipercard Banco Múltiplo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o HS Financeira  Crédito ?

Sim.

Com a plataforma é possível definir o HS Financeira  Crédito como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta HS Financeira  Crédito.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ HS Financeira  Crédito não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no HS Financeira  Crédito.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no HS Financeira  Crédito seja uma conta empresas, ou seja HS Financeira  Crédito conta PJ
- Para usar este recurso a conta corrente no HS Financeira  Crédito tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o HSBC Brasil  Banco de Investimento ?

Sim.

Com a plataforma é possível definir o HSBC Brasil  Banco de Investimento como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta HSBC Brasil  Banco de Investimento.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ HSBC Brasil  Banco de Investimento não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no HSBC Brasil  Banco de Investimento.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no HSBC Brasil  Banco de Investimento seja uma conta empresas, ou seja HSBC Brasil  Banco de Investimento conta PJ
- Para usar este recurso a conta corrente no HSBC Brasil  Banco de Investimento tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o IB Corretora de Câmbio ?

Sim.

Com a plataforma é possível definir o IB Corretora de Câmbio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta IB Corretora de Câmbio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ IB Corretora de Câmbio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no IB Corretora de Câmbio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no IB Corretora de Câmbio seja uma conta empresas, ou seja IB Corretora de Câmbio conta PJ
- Para usar este recurso a conta corrente no IB Corretora de Câmbio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o ICAP do Brasil Corretora de Títulos e Valores Mobiliários Ltda. ?

Sim.

Com a plataforma é possível definir o ICAP do Brasil Corretora de Títulos e Valores Mobiliários Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta ICAP do Brasil Corretora de Títulos e Valores Mobiliários Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ ICAP do Brasil Corretora de Títulos e Valores Mobiliários Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no ICAP do Brasil Corretora de Títulos e Valores Mobiliários Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no ICAP do Brasil Corretora de Títulos e Valores Mobiliários Ltda. seja uma conta empresas, ou seja ICAP do Brasil Corretora de Títulos e Valores Mobiliários Ltda. conta PJ
- Para usar este recurso a conta corrente no ICAP do Brasil Corretora de Títulos e Valores Mobiliários Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o ICBC do Brasil Banco Múltiplo ?

Sim.

Com a plataforma é possível definir o ICBC do Brasil Banco Múltiplo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta ICBC do Brasil Banco Múltiplo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ ICBC do Brasil Banco Múltiplo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no ICBC do Brasil Banco Múltiplo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no ICBC do Brasil Banco Múltiplo seja uma conta empresas, ou seja ICBC do Brasil Banco Múltiplo conta PJ
- Para usar este recurso a conta corrente no ICBC do Brasil Banco Múltiplo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o ING Bank N.V. ?

Sim.

Com a plataforma é possível definir o ING Bank N.V. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta ING Bank N.V..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ ING Bank N.V. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no ING Bank N.V..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no ING Bank N.V. seja uma conta empresas, ou seja ING Bank N.V. conta PJ
- Para usar este recurso a conta corrente no ING Bank N.V. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Intesa Sanpaolo Brasil  - Banco Múltiplo ?

Sim.

Com a plataforma é possível definir o Intesa Sanpaolo Brasil  - Banco Múltiplo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Intesa Sanpaolo Brasil  - Banco Múltiplo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Intesa Sanpaolo Brasil  - Banco Múltiplo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Intesa Sanpaolo Brasil  - Banco Múltiplo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Intesa Sanpaolo Brasil  - Banco Múltiplo seja uma conta empresas, ou seja Intesa Sanpaolo Brasil  - Banco Múltiplo conta PJ
- Para usar este recurso a conta corrente no Intesa Sanpaolo Brasil  - Banco Múltiplo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Itaú Unibanco Holding ?

Sim.

Com a plataforma é possível definir o Itaú Unibanco Holding como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Itaú Unibanco Holding.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Itaú Unibanco Holding não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Itaú Unibanco Holding.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Itaú Unibanco Holding seja uma conta empresas, ou seja Itaú Unibanco Holding conta PJ
- Para usar este recurso a conta corrente no Itaú Unibanco Holding tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Itaú Unibanco ?

Sim.

Com a plataforma é possível definir o Itaú Unibanco como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Itaú Unibanco.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Itaú Unibanco não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Itaú Unibanco.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Itaú Unibanco seja uma conta empresas, ou seja Itaú Unibanco conta PJ
- Para usar este recurso a conta corrente no Itaú Unibanco tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o JPMorgan Chase Bank ?

Sim.

Com a plataforma é possível definir o JPMorgan Chase Bank como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta JPMorgan Chase Bank.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ JPMorgan Chase Bank não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no JPMorgan Chase Bank.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no JPMorgan Chase Bank seja uma conta empresas, ou seja JPMorgan Chase Bank conta PJ
- Para usar este recurso a conta corrente no JPMorgan Chase Bank tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Kirton Bank  - Banco Múltiplo ?

Sim.

Com a plataforma é possível definir o Kirton Bank  - Banco Múltiplo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Kirton Bank  - Banco Múltiplo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Kirton Bank  - Banco Múltiplo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Kirton Bank  - Banco Múltiplo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Kirton Bank  - Banco Múltiplo seja uma conta empresas, ou seja Kirton Bank  - Banco Múltiplo conta PJ
- Para usar este recurso a conta corrente no Kirton Bank  - Banco Múltiplo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Lastro RDV Distribuidora de Títulos e Valores Mobiliários Ltda. ?

Sim.

Com a plataforma é possível definir o Lastro RDV Distribuidora de Títulos e Valores Mobiliários Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Lastro RDV Distribuidora de Títulos e Valores Mobiliários Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Lastro RDV Distribuidora de Títulos e Valores Mobiliários Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Lastro RDV Distribuidora de Títulos e Valores Mobiliários Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Lastro RDV Distribuidora de Títulos e Valores Mobiliários Ltda. seja uma conta empresas, ou seja Lastro RDV Distribuidora de Títulos e Valores Mobiliários Ltda. conta PJ
- Para usar este recurso a conta corrente no Lastro RDV Distribuidora de Títulos e Valores Mobiliários Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Lecca Crédito ?

Sim.

Com a plataforma é possível definir o Lecca Crédito como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Lecca Crédito.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Lecca Crédito não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Lecca Crédito.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Lecca Crédito seja uma conta empresas, ou seja Lecca Crédito conta PJ
- Para usar este recurso a conta corrente no Lecca Crédito tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Levycam - Corretora de Câmbio e Valores Ltda. ?

Sim.

Com a plataforma é possível definir o Levycam - Corretora de Câmbio e Valores Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Levycam - Corretora de Câmbio e Valores Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Levycam - Corretora de Câmbio e Valores Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Levycam - Corretora de Câmbio e Valores Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Levycam - Corretora de Câmbio e Valores Ltda. seja uma conta empresas, ou seja Levycam - Corretora de Câmbio e Valores Ltda. conta PJ
- Para usar este recurso a conta corrente no Levycam - Corretora de Câmbio e Valores Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Magliano  Corretora de Cambio e Valores Mobiliarios ?

Sim.

Com a plataforma é possível definir o Magliano  Corretora de Cambio e Valores Mobiliarios como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Magliano  Corretora de Cambio e Valores Mobiliarios.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Magliano  Corretora de Cambio e Valores Mobiliarios não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Magliano  Corretora de Cambio e Valores Mobiliarios.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Magliano  Corretora de Cambio e Valores Mobiliarios seja uma conta empresas, ou seja Magliano  Corretora de Cambio e Valores Mobiliarios conta PJ
- Para usar este recurso a conta corrente no Magliano  Corretora de Cambio e Valores Mobiliarios tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o MS Bank  Banco de Câmbio ?

Sim.

Com a plataforma é possível definir o MS Bank  Banco de Câmbio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta MS Bank  Banco de Câmbio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ MS Bank  Banco de Câmbio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no MS Bank  Banco de Câmbio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no MS Bank  Banco de Câmbio seja uma conta empresas, ou seja MS Bank  Banco de Câmbio conta PJ
- Para usar este recurso a conta corrente no MS Bank  Banco de Câmbio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Multimoney Corretora de Câmbio Ltda ?

Sim.

Com a plataforma é possível definir o Multimoney Corretora de Câmbio Ltda como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Multimoney Corretora de Câmbio Ltda.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Multimoney Corretora de Câmbio Ltda não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Multimoney Corretora de Câmbio Ltda.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Multimoney Corretora de Câmbio Ltda seja uma conta empresas, ou seja Multimoney Corretora de Câmbio Ltda conta PJ
- Para usar este recurso a conta corrente no Multimoney Corretora de Câmbio Ltda tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o National Association ?

Sim.

Com a plataforma é possível definir o National Association como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta National Association.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ National Association não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no National Association.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no National Association seja uma conta empresas, ou seja National Association conta PJ
- Para usar este recurso a conta corrente no National Association tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Natixis Brasil  Banco Múltiplo ?

Sim.

Com a plataforma é possível definir o Natixis Brasil  Banco Múltiplo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Natixis Brasil  Banco Múltiplo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Natixis Brasil  Banco Múltiplo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Natixis Brasil  Banco Múltiplo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Natixis Brasil  Banco Múltiplo seja uma conta empresas, ou seja Natixis Brasil  Banco Múltiplo conta PJ
- Para usar este recurso a conta corrente no Natixis Brasil  Banco Múltiplo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Nova Futura Corretora de Títulos e Valores Mobiliários Ltda. ?

Sim.

Com a plataforma é possível definir o Nova Futura Corretora de Títulos e Valores Mobiliários Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Nova Futura Corretora de Títulos e Valores Mobiliários Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Nova Futura Corretora de Títulos e Valores Mobiliários Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Nova Futura Corretora de Títulos e Valores Mobiliários Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Nova Futura Corretora de Títulos e Valores Mobiliários Ltda. seja uma conta empresas, ou seja Nova Futura Corretora de Títulos e Valores Mobiliários Ltda. conta PJ
- Para usar este recurso a conta corrente no Nova Futura Corretora de Títulos e Valores Mobiliários Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Novo Banco Continental  - Banco Múltiplo ?

Sim.

Com a plataforma é possível definir o Novo Banco Continental  - Banco Múltiplo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Novo Banco Continental  - Banco Múltiplo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Novo Banco Continental  - Banco Múltiplo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Novo Banco Continental  - Banco Múltiplo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Novo Banco Continental  - Banco Múltiplo seja uma conta empresas, ou seja Novo Banco Continental  - Banco Múltiplo conta PJ
- Para usar este recurso a conta corrente no Novo Banco Continental  - Banco Múltiplo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Nu Pagamentos ?

Sim.

Com a plataforma é possível definir o Nu Pagamentos como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Nu Pagamentos.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Nu Pagamentos não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Nu Pagamentos.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Nu Pagamentos seja uma conta empresas, ou seja Nu Pagamentos conta PJ
- Para usar este recurso a conta corrente no Nu Pagamentos tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Oliveira Trust Distribuidora de Títulos e Valores Mobiliários ?

Sim.

Com a plataforma é possível definir o Oliveira Trust Distribuidora de Títulos e Valores Mobiliários como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Oliveira Trust Distribuidora de Títulos e Valores Mobiliários.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Oliveira Trust Distribuidora de Títulos e Valores Mobiliários não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Oliveira Trust Distribuidora de Títulos e Valores Mobiliários.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Oliveira Trust Distribuidora de Títulos e Valores Mobiliários seja uma conta empresas, ou seja Oliveira Trust Distribuidora de Títulos e Valores Mobiliários conta PJ
- Para usar este recurso a conta corrente no Oliveira Trust Distribuidora de Títulos e Valores Mobiliários tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Omni Banco ?

Sim.

Com a plataforma é possível definir o Omni Banco como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Omni Banco.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Omni Banco não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Omni Banco.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Omni Banco seja uma conta empresas, ou seja Omni Banco conta PJ
- Para usar este recurso a conta corrente no Omni Banco tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Parana Banco ?

Sim.

Com a plataforma é possível definir o Parana Banco como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Parana Banco.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Parana Banco não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Parana Banco.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Parana Banco seja uma conta empresas, ou seja Parana Banco conta PJ
- Para usar este recurso a conta corrente no Parana Banco tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Parmetal Distribuidora de Títulos e Valores Mobiliários Ltda. ?

Sim.

Com a plataforma é possível definir o Parmetal Distribuidora de Títulos e Valores Mobiliários Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Parmetal Distribuidora de Títulos e Valores Mobiliários Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Parmetal Distribuidora de Títulos e Valores Mobiliários Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Parmetal Distribuidora de Títulos e Valores Mobiliários Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Parmetal Distribuidora de Títulos e Valores Mobiliários Ltda. seja uma conta empresas, ou seja Parmetal Distribuidora de Títulos e Valores Mobiliários Ltda. conta PJ
- Para usar este recurso a conta corrente no Parmetal Distribuidora de Títulos e Valores Mobiliários Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Pernambucanas Financiadora  Crédito ?

Sim.

Com a plataforma é possível definir o Pernambucanas Financiadora  Crédito como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Pernambucanas Financiadora  Crédito.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Pernambucanas Financiadora  Crédito não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Pernambucanas Financiadora  Crédito.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Pernambucanas Financiadora  Crédito seja uma conta empresas, ou seja Pernambucanas Financiadora  Crédito conta PJ
- Para usar este recurso a conta corrente no Pernambucanas Financiadora  Crédito tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Planner Corretora de Valores ?

Sim.

Com a plataforma é possível definir o Planner Corretora de Valores como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Planner Corretora de Valores.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Planner Corretora de Valores não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Planner Corretora de Valores.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Planner Corretora de Valores seja uma conta empresas, ou seja Planner Corretora de Valores conta PJ
- Para usar este recurso a conta corrente no Planner Corretora de Valores tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o PortoCred  Crédito ?

Sim.

Com a plataforma é possível definir o PortoCred  Crédito como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta PortoCred  Crédito.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ PortoCred  Crédito não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no PortoCred  Crédito.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no PortoCred  Crédito seja uma conta empresas, ou seja PortoCred  Crédito conta PJ
- Para usar este recurso a conta corrente no PortoCred  Crédito tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Pólocred Sociedade de Crédito ao Microempreendedor e à Empresa de Pequeno Porte ?

Sim.

Com a plataforma é possível definir o Pólocred Sociedade de Crédito ao Microempreendedor e à Empresa de Pequeno Porte como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Pólocred Sociedade de Crédito ao Microempreendedor e à Empresa de Pequeno Porte.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Pólocred Sociedade de Crédito ao Microempreendedor e à Empresa de Pequeno Porte não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Pólocred Sociedade de Crédito ao Microempreendedor e à Empresa de Pequeno Porte.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Pólocred Sociedade de Crédito ao Microempreendedor e à Empresa de Pequeno Porte seja uma conta empresas, ou seja Pólocred Sociedade de Crédito ao Microempreendedor e à Empresa de Pequeno Porte conta PJ
- Para usar este recurso a conta corrente no Pólocred Sociedade de Crédito ao Microempreendedor e à Empresa de Pequeno Porte tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o RB Capital Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda. ?

Sim.

Com a plataforma é possível definir o RB Capital Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta RB Capital Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ RB Capital Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no RB Capital Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no RB Capital Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda. seja uma conta empresas, ou seja RB Capital Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda. conta PJ
- Para usar este recurso a conta corrente no RB Capital Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Renascença Distribuidora de Títulos e Valores Mobiliários Ltda. ?

Sim.

Com a plataforma é possível definir o Renascença Distribuidora de Títulos e Valores Mobiliários Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Renascença Distribuidora de Títulos e Valores Mobiliários Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Renascença Distribuidora de Títulos e Valores Mobiliários Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Renascença Distribuidora de Títulos e Valores Mobiliários Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Renascença Distribuidora de Títulos e Valores Mobiliários Ltda. seja uma conta empresas, ou seja Renascença Distribuidora de Títulos e Valores Mobiliários Ltda. conta PJ
- Para usar este recurso a conta corrente no Renascença Distribuidora de Títulos e Valores Mobiliários Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Sagitur Corretora de Câmbio Ltda. ?

Sim.

Com a plataforma é possível definir o Sagitur Corretora de Câmbio Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Sagitur Corretora de Câmbio Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Sagitur Corretora de Câmbio Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Sagitur Corretora de Câmbio Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Sagitur Corretora de Câmbio Ltda. seja uma conta empresas, ou seja Sagitur Corretora de Câmbio Ltda. conta PJ
- Para usar este recurso a conta corrente no Sagitur Corretora de Câmbio Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Scotiabank Brasil  Banco Múltiplo ?

Sim.

Com a plataforma é possível definir o Scotiabank Brasil  Banco Múltiplo como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Scotiabank Brasil  Banco Múltiplo.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Scotiabank Brasil  Banco Múltiplo não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Scotiabank Brasil  Banco Múltiplo.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Scotiabank Brasil  Banco Múltiplo seja uma conta empresas, ou seja Scotiabank Brasil  Banco Múltiplo conta PJ
- Para usar este recurso a conta corrente no Scotiabank Brasil  Banco Múltiplo tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Senff  - Crédito ?

Sim.

Com a plataforma é possível definir o Senff  - Crédito como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Senff  - Crédito.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Senff  - Crédito não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Senff  - Crédito.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Senff  - Crédito seja uma conta empresas, ou seja Senff  - Crédito conta PJ
- Para usar este recurso a conta corrente no Senff  - Crédito tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Senso Corretora de Câmbio e Valores Mobiliários ?

Sim.

Com a plataforma é possível definir o Senso Corretora de Câmbio e Valores Mobiliários como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Senso Corretora de Câmbio e Valores Mobiliários.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Senso Corretora de Câmbio e Valores Mobiliários não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Senso Corretora de Câmbio e Valores Mobiliários.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Senso Corretora de Câmbio e Valores Mobiliários seja uma conta empresas, ou seja Senso Corretora de Câmbio e Valores Mobiliários conta PJ
- Para usar este recurso a conta corrente no Senso Corretora de Câmbio e Valores Mobiliários tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Socred  - Sociedade de Crédito ao Microempreendedor ?

Sim.

Com a plataforma é possível definir o Socred  - Sociedade de Crédito ao Microempreendedor como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Socred  - Sociedade de Crédito ao Microempreendedor.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Socred  - Sociedade de Crédito ao Microempreendedor não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Socred  - Sociedade de Crédito ao Microempreendedor.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Socred  - Sociedade de Crédito ao Microempreendedor seja uma conta empresas, ou seja Socred  - Sociedade de Crédito ao Microempreendedor conta PJ
- Para usar este recurso a conta corrente no Socred  - Sociedade de Crédito ao Microempreendedor tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Standard Chartered Bank (Brasil)  Banco de Investimento ?

Sim.

Com a plataforma é possível definir o Standard Chartered Bank (Brasil)  Banco de Investimento como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Standard Chartered Bank (Brasil)  Banco de Investimento.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Standard Chartered Bank (Brasil)  Banco de Investimento não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Standard Chartered Bank (Brasil)  Banco de Investimento.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Standard Chartered Bank (Brasil)  Banco de Investimento seja uma conta empresas, ou seja Standard Chartered Bank (Brasil)  Banco de Investimento conta PJ
- Para usar este recurso a conta corrente no Standard Chartered Bank (Brasil)  Banco de Investimento tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Stone Pagamentos ?

Sim.

Com a plataforma é possível definir o Stone Pagamentos como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Stone Pagamentos.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Stone Pagamentos não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Stone Pagamentos.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Stone Pagamentos seja uma conta empresas, ou seja Stone Pagamentos conta PJ
- Para usar este recurso a conta corrente no Stone Pagamentos tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Terra Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda. ?

Sim.

Com a plataforma é possível definir o Terra Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Terra Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Terra Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Terra Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Terra Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda. seja uma conta empresas, ou seja Terra Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda. conta PJ
- Para usar este recurso a conta corrente no Terra Investimentos Distribuidora de Títulos e Valores Mobiliários Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Treviso Corretora de Câmbio ?

Sim.

Com a plataforma é possível definir o Treviso Corretora de Câmbio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Treviso Corretora de Câmbio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Treviso Corretora de Câmbio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Treviso Corretora de Câmbio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Treviso Corretora de Câmbio seja uma conta empresas, ou seja Treviso Corretora de Câmbio conta PJ
- Para usar este recurso a conta corrente no Treviso Corretora de Câmbio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Tullett Prebon Brasil Corretora de Valores e Câmbio Ltda. ?

Sim.

Com a plataforma é possível definir o Tullett Prebon Brasil Corretora de Valores e Câmbio Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Tullett Prebon Brasil Corretora de Valores e Câmbio Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Tullett Prebon Brasil Corretora de Valores e Câmbio Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Tullett Prebon Brasil Corretora de Valores e Câmbio Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Tullett Prebon Brasil Corretora de Valores e Câmbio Ltda. seja uma conta empresas, ou seja Tullett Prebon Brasil Corretora de Valores e Câmbio Ltda. conta PJ
- Para usar este recurso a conta corrente no Tullett Prebon Brasil Corretora de Valores e Câmbio Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Títulos e Valores Mobiliários Ltda. ?

Sim.

Com a plataforma é possível definir o Títulos e Valores Mobiliários Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Títulos e Valores Mobiliários Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Títulos e Valores Mobiliários Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Títulos e Valores Mobiliários Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Títulos e Valores Mobiliários Ltda. seja uma conta empresas, ou seja Títulos e Valores Mobiliários Ltda. conta PJ
- Para usar este recurso a conta corrente no Títulos e Valores Mobiliários Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Títulos e Valores Mobiliários ?

Sim.

Com a plataforma é possível definir o Títulos e Valores Mobiliários como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Títulos e Valores Mobiliários.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Títulos e Valores Mobiliários não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Títulos e Valores Mobiliários.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Títulos e Valores Mobiliários seja uma conta empresas, ou seja Títulos e Valores Mobiliários conta PJ
- Para usar este recurso a conta corrente no Títulos e Valores Mobiliários tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o UBS Brasil Banco de Investimento ?

Sim.

Com a plataforma é possível definir o UBS Brasil Banco de Investimento como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta UBS Brasil Banco de Investimento.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ UBS Brasil Banco de Investimento não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no UBS Brasil Banco de Investimento.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no UBS Brasil Banco de Investimento seja uma conta empresas, ou seja UBS Brasil Banco de Investimento conta PJ
- Para usar este recurso a conta corrente no UBS Brasil Banco de Investimento tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o UBS Brasil Corretora de Câmbio ?

Sim.

Com a plataforma é possível definir o UBS Brasil Corretora de Câmbio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta UBS Brasil Corretora de Câmbio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ UBS Brasil Corretora de Câmbio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no UBS Brasil Corretora de Câmbio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no UBS Brasil Corretora de Câmbio seja uma conta empresas, ou seja UBS Brasil Corretora de Câmbio conta PJ
- Para usar este recurso a conta corrente no UBS Brasil Corretora de Câmbio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Uniprime Central – Central Interestadual de Cooperativas de Crédito Ltda. ?

Sim.

Com a plataforma é possível definir o Uniprime Central – Central Interestadual de Cooperativas de Crédito Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Uniprime Central – Central Interestadual de Cooperativas de Crédito Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Uniprime Central – Central Interestadual de Cooperativas de Crédito Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Uniprime Central – Central Interestadual de Cooperativas de Crédito Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Uniprime Central – Central Interestadual de Cooperativas de Crédito Ltda. seja uma conta empresas, ou seja Uniprime Central – Central Interestadual de Cooperativas de Crédito Ltda. conta PJ
- Para usar este recurso a conta corrente no Uniprime Central – Central Interestadual de Cooperativas de Crédito Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Uniprime Norte do Paraná - Cooperativa de Crédito Ltda. ?

Sim.

Com a plataforma é possível definir o Uniprime Norte do Paraná - Cooperativa de Crédito Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Uniprime Norte do Paraná - Cooperativa de Crédito Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Uniprime Norte do Paraná - Cooperativa de Crédito Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Uniprime Norte do Paraná - Cooperativa de Crédito Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Uniprime Norte do Paraná - Cooperativa de Crédito Ltda. seja uma conta empresas, ou seja Uniprime Norte do Paraná - Cooperativa de Crédito Ltda. conta PJ
- Para usar este recurso a conta corrente no Uniprime Norte do Paraná - Cooperativa de Crédito Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o valuepe Corretora de Valores e Câmbio ?

Sim.

Com a plataforma é possível definir o valuepe Corretora de Valores e Câmbio como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta valuepe Corretora de Valores e Câmbio.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ valuepe Corretora de Valores e Câmbio não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no valuepe Corretora de Valores e Câmbio.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no valuepe Corretora de Valores e Câmbio seja uma conta empresas, ou seja valuepe Corretora de Valores e Câmbio conta PJ
- Para usar este recurso a conta corrente no valuepe Corretora de Valores e Câmbio tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Vip s Corretora de Câmbio Ltda. ?

Sim.

Com a plataforma é possível definir o Vip s Corretora de Câmbio Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Vip s Corretora de Câmbio Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Vip s Corretora de Câmbio Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Vip s Corretora de Câmbio Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Vip s Corretora de Câmbio Ltda. seja uma conta empresas, ou seja Vip s Corretora de Câmbio Ltda. conta PJ
- Para usar este recurso a conta corrente no Vip s Corretora de Câmbio Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o Vortx Distribuidora de Títulos e Valores Mobiliários Ltda. ?

Sim.

Com a plataforma é possível definir o Vortx Distribuidora de Títulos e Valores Mobiliários Ltda. como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta Vortx Distribuidora de Títulos e Valores Mobiliários Ltda..

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ Vortx Distribuidora de Títulos e Valores Mobiliários Ltda. não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no Vortx Distribuidora de Títulos e Valores Mobiliários Ltda..

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no Vortx Distribuidora de Títulos e Valores Mobiliários Ltda. seja uma conta empresas, ou seja Vortx Distribuidora de Títulos e Valores Mobiliários Ltda. conta PJ
- Para usar este recurso a conta corrente no Vortx Distribuidora de Títulos e Valores Mobiliários Ltda. tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Woovi suporta o XP Investimentos Corretora de Câmbio Títulos e Valores Mobiliários ?

Sim.

Com a plataforma é possível definir o XP Investimentos Corretora de Câmbio Títulos e Valores Mobiliários como sua conta de depósito. Desta forma o saldo da plataforma é depositado automaticamente na sua conta XP Investimentos Corretora de Câmbio Títulos e Valores Mobiliários.

Se sua empresa já tem a chave Pix CNPJ já defindo na sua conta PJ XP Investimentos Corretora de Câmbio Títulos e Valores Mobiliários não precisa realizar nenhum ajuste. Para ativar basta configurar como chave de depósito a chave Pix que está associada a conta corrente da sua empresa no XP Investimentos Corretora de Câmbio Títulos e Valores Mobiliários.

Você também pode configurar webhooks, nesta modalidade para cada pagamento recebido você pode configurar webhooks para ser notificado de pagamentos.

Dicas Importantes:

- Para usar este recurso é necessário que a sua conta corrente no XP Investimentos Corretora de Câmbio Títulos e Valores Mobiliários seja uma conta empresas, ou seja XP Investimentos Corretora de Câmbio Títulos e Valores Mobiliários conta PJ
- Para usar este recurso a conta corrente no XP Investimentos Corretora de Câmbio Títulos e Valores Mobiliários tem que ter o mesmo CNPJ que a conta corrente da sua empresa cadastrada na plataforma.

---

## Adicionando saldo na conta de teste

Para adicionar saldo na conta de teste, você precisará criar uma cobraça de testes e simular seu pagamento. O valor que foi simulado o pagamento será adicionado na conta de testes.

Para criar uma cobraça de testes, vá até o menu de `Cobranças` e clique em `Nova Cobrança`, no canto superior direito da tela, lembre-se de ter a conta de testes como conta bancária padrão.

Você poderá preencher o valor que deseja simular o pagamento, os outros campos são opcionais. Após isso clique em `Criar cobrança`.

A cobrança estará disponível para ser paga, você seria redirecionado para a tela de detalhes da cobrança, onde poderá simular o pagamento.

![simulate-charge-payment](./__assets__/simulate-charge-payment.png)

Após simulado o pagamento, você pode checar que o saldo da conta de testes foi atualizado, adicionando o valor da cobrança criada.

---

## Testando Pix sem dinheiro real

Para gerar novas cobranças na woovi, você precisa criar sua conta virtual.

Para evitar custos ao testar a woovi, temos uma conta bancária especial para testes. Cada cobrança criada usando o teste da mesma não irá gerar custos em seu banco e você também não gastará nenhum dinheiro.

## Como criar uma Conta Bancária para testes

Clique em `Ajustes -> Pix -> Ir para Configurações avançadas`

Veja em [https://app.woovi.com/home/settings/company-bank-acccount/list](https://app.woovi.com/home/settings/company-bank-acccount/list)

Para adicionar uma conta de teste basta clicar no botão `Criar uma conta bancária de teste`

![Company Bank Test](__assets__/test_account_create.png)

Marque esta Conta Bancária como sua conta bancária padrão, conforme abaixo:

![Company Bank Default](__assets__/set_default_account.png)

Depois disso, você pode criar uma nova Cobrança e escanear o QRCode usando a câmera do seu celular

## Como promover seu ambiente de testes para produção

Para promover seu ambiente de testes para produção, você precisa ter sua conta virtual aprovada.

### Como limpar os dados de testes

1. Acesse a [listagem de API's](https://app.woovi.com/home/applications/tab/list) e escolha qual você deseja promover para produção
2. Dentro dos detalhes da API, selecione a conta bancária atrelada desejada
![Select_account](__assets__/select_account.png)

## Dúvidas frequentes

- O QRCode não é um BRCode EMV válido, mas uma url que simula o pagamento
- Para pagar utilizando a conta bancária de teste, veja essa [documentação](pay-pix-test.md)

---

## Introdução a conta de teste

A conta de teste é uma conta que pode ser usada para testar as funcionalidades da plataforma sem a necessidade de usar uma conta bancária real. Sua empresa sempre terá uma conta de teste disponível para usar.

A conta de teste não utiliza nenhum dado real, como por exemplo, o nome do titular da conta, o saldo da conta, os reembolsos, etc...

Veja abaixo a lista de funcionalidades que podem ser testadas na conta de teste:

| Funcionalidade                         | Disponibilidade |
| -------------------------------------- | --------------- |
| Cobrança com autocadastro              | Sim             |
| Cobrança em e-commerce                 | Sim             |
| Cobrança com solicitação de cadastro   | Sim             |
| Cobrança com cliente                   | Sim             |
| Cobrança com vencimento, multa e juros | Sim             |
| Assinatura                             | Sim             |
| Qr code estático                       | Sim             |
| Pix crediário                          | Sim             |
| Reembolso                              | Sim             |
| Reembolso parcial                      | Sim             |
| Pagamento de chave pix                 | Sim             |
| Pagamento de qr code pix               | Sim             |
| Saque                                  | Não             |

---

## Pagando um Pix QRCode de teste

Pagar um Pix QRCode com uma conta bancaria de teste permite testar se o Webhook cadastrado está funcionando.

Para pagar um Pix QRCode você precisa pegar o identificador do QRCode que você encontra no detalhe do mesmo.

Exemplo:

![Identifier Example QRCode](/img/identifier-ex-qrcode.png)

E também copiar o código do seu AppID, você irá encontrá-lo em `menu Administrador > API/Plugins`, clicar em seu respectivo `API/Plugin` criado e copiar o `AppID` no detalhe da aplicação.

Mais infomações sobre o AppID aqui: /docs/plugin/app-id/

Exemplo:

![App Id Example](/img/app-id-ex.png)

E por fim já com todos os dados recolhidos você poderá rodar esse comando abaixo preenchido com os dados indicados já citados a cima e gerar uma transação de pagamento!

```jsx
curl 'https://api.woovi.com/woovi/testing?identifier=<identifier>' -H 'Authorization: <appID>'
```

Para ver as transações geradas clique em `transações` para ver a transação do Pix QRCode do pagamento teste recebida. 

![Identifier Example QRCode](/img/transaction-ex.png)

---

## Pagando uma Cobrança Pix de Teste

Pagar uma cobrança Pix no modo teste permite testar se o Webhook cadastrado está funcionando.

Para pagar uma cobrança Pix você precisa pegar o identificador da cobrança que você encontra no detalhe da mesma.

Exemplo:

![Identifier Example](/img/identifier-example.png)

E também copiar o código do seu AppID, você irá encontrá-lo em `menu Administrador > API/Plugins`, clicar em seu respectivo `API/Plugin` criado e copiar o `AppID` no detalhe da aplicação.

Mais infomações sobre o AppID aqui: [/docs/plugin/app-id/](/docs/plugin/app-id/)

Exemplo:

![App Id Example](/img/app-id-ex.png)

E por fim já com todos os dados recolhidos você poderá rodar esse comando abaixo preenchido com os dados indicados já citados a cima e efetuar o pagamento !

```jsx
curl 'https://api.woovi.com/woovi/testing?transactionID=<identifier>' -H 'Authorization: <appID>' \
```

---

## Pagando uma chave pix com a conta de teste

Pagar uma chave pix possibilita testar se o Webhook cadastrado está funcionando, alem de testar as funcionalidades de pagamento.

Para pagar uma chave pix usando a conta de testes, primeiro vá até o menu de `Saques/Pagamentos` e clique em `Novo Pagamento`, no canto superior direito da tela.

Você poderá preencher a chave pix que deseja simular um pagamento, o valor e o comentário do pagamento (opcional). Após isso clique em `Solicitar`.

O pagamento estará disponível para ser aprovado, você seria redirecionado para a tela de detalhes do pagamento, onde poderá aprovar o pagamento.

![payment-requested](./__assets__/payment-requested.png)

Todos os pagamentos feitos na conta de testes aparecerão um banner de aviso no topo da tela, indicando que o pagamento foi feito na conta de testes.

Por fim, você pode aprovar o pagamento clicando em `Aprovar Pagamento` no canto superior direito da tela e depois em `Aprovar`.

### Chaves Pix disponíveis para teste

Possuimos algumas chaves pix disponíveis para teste, para simular alguns casos de uso, essas chaves pix estão disponíveis para serem usadas em qualquer conta de teste.

| Chave Pix                   | Caso de uso                                                  |
| --------------------------- | ------------------------------------------------------------ |
| pix-key-not-found@woovi.com | Simular quando uma chave pix não esta cadastrada em um banco |
| bank-error@woovi.com        | Simular quando a instituição de destino esta fora do ar      |

---

## Conta Bancária de Teste

## Conta de Teste

Para gerar novas cobranças na woovi, você precisa criar sua conta virtual.

Para evitar custos ao testar a woovi, temos uma conta bancária especial para testes. Cada cobrança criada usando o teste da mesma não irá gerar custos em seu banco e você também não gastará nenhum dinheiro.

## Como criar uma Conta Bancária para testes

Clique em `Ajustes -> Pix -> Ir para Configurações avançadas`

Veja em [https://app.woovi.com/home/settings/company-bank-acccount/list](https://app.woovi.com/home/settings/company-bank-acccount/list)

Para adicionar uma conta de teste basta clicar no botão `Criar uma conta bancária de teste`

![Company Bank Test](__assets__/test_account_create.png)

Marque esta Conta Bancária como sua conta bancária padrão, conforme abaixo:

![Company Bank Default](__assets__/set_default_account.png)

Depois disso, você pode criar uma nova Cobrança e escanear o QRCode usando a câmera do seu celular

## Como promover seu ambiente de testes para produção

Para promover seu ambiente de testes para produção, você precisa ter sua conta virtual aprovada.

1. Acesse a [listagem de API's](https://app.woovi.com/home/applications/tab/list) e escolha qual você deseja promover para produção
2. Dentro dos detalhes da API, selecione a conta bancária atrelada desejada
![Select_account](__assets__/select_account.png)

## Dúvidas frequentes

<details>
  <summary>Não Consigo Scanear o QRcode de teste</summary>
  
    O QRCode não é um BRCode EMV válido, portanto você não consegue scanear em seu banco
    
  
</details>

<details>
  <summary>Como pagar um QRCode de teste?</summary>
  
    Para pagar um QRCode de teste você precisa acessar o detalhe da cobrança, e clicar em simular pagamento
    
  
</details>

---

## Pix Automatico em sandbox

## Pix Automátio Em sandbox

Para criar um pix automatico em sandbox você tera que seguir os seguintes passos:
* Cria um pix automatico (api ou plataforma)
* Simular assinatura e gerar parcelas
* Simular pagamento de parcelas

### Criar uma novo pix automático

Acesse a pagina: https://app.woovi-sandbox.com/home/subscription/tab/pixAutomatic/list e clique em "Novo Pix automático"

![Onde criar um novo Pix Automático](/img/pix-automatic/sandbox-new-button.png)

Um formulário será aberto para você definir o cliente, o valor das cobranças e as configurações da assinatura.

![Formulário de novo Pix Automático](/img/pix-automatic/sandbox-form-empty.png)

prencha os dados nescessarios e clique em salvar

![Formulário de Pix Automático preenchido](/img/pix-automatic/sandbox-form-filled.png)

### Simular assinatura e gerar parcelas

Logo após salvar o pix automatico você será redirecionado para os detalhe do pix automatico, clique em simular assinatura

![Botão simular assinatura de Pix Automático](/img/pix-automatic/sandbox-simulate-subscription.png)

Ele cria a assinatura e já gera as parecelas

OBS: se tiver webhook do evento `PIX_AUTOMATIC_APPROVED` configurado, a plataforma irá emiti-lo neste momento

### Simular pagamento de parcelas

Acesse a pagina: https://app.woovi-sandbox.com/home/subscription/tab/pixAutomatic/installments/list, aqui aparecerão as parecelas que foram geradas
para pagar basta clicar no botão simular pagamento

![Botão simular pagamento de parcela](/img/pix-automatic/sandbox-simulate-payment.png)

OBS: se tiver webhook do evento `PIX_AUTOMATIC_COBR_COMPLETED` configurado, a plataforma irá emiti-lo neste momento

---

## Adicionando saldo na conta de teste(Test-account)

Para adicionar saldo na conta de teste, você precisará criar uma cobraça de testes e simular seu pagamento. O valor que foi simulado o pagamento será adicionado na conta de testes.

Para criar uma cobraça de testes, vá até o menu de `Cobranças` e clique em `Nova Cobrança`, no canto superior direito da tela, lembre-se de ter a conta de testes como conta bancária padrão.

Você poderá preencher o valor que deseja simular o pagamento, os outros campos são opcionais. Após isso clique em `Criar cobrança`.

A cobrança estará disponível para ser paga, você seria redirecionado para a tela de detalhes da cobrança, onde poderá simular o pagamento.

![simulate-charge-payment](./__assets__/simulate-charge-payment.png)

Após simulado o pagamento, você pode checar que o saldo da conta de testes foi atualizado, adicionando o valor da cobrança criada.

---

## Testando Pix sem dinheiro real(Test-account)

Para gerar novas cobranças na Woovi, você precisa criar uma conta bancária que represente o provedor do seu banco Pix.

Para evitar custos ao testar a Woovi, temos uma conta bancária especial para testes. Cada cobrança criada usando o teste da mesma não irá gerar custos em seu banco e você também não gastará nenhum dinheiro.

## Como criar uma Conta Bancária para testes

Clique em `Ajustes -> Pix -> Ir para Configurações avançadas`

Veja em [https://yourcompany.woovi.com/home/accounts/list](https://yourcompany.woovi.com/home/accounts/list)

Para adicionar uma conta de teste basta clicar no botão `Criar uma conta bancária de teste`

![Company Bank Test](/img/test/cba-test-create.png)

Marque esta Conta Bancária como sua conta bancária padrão, conforme abaixo:

![Company Bank Default](/img/test/cba-test-default.png)

Depois disso, você pode criar uma nova Cobrança e escanear o QRCode usando a câmera do seu celular

O QRCode não é um BRCode EMV válido, mas uma url que simula o pagamento

---

## Introdução a conta de teste(Test-account)

A conta de teste é uma conta que pode ser usada para testar as funcionalidades da plataforma sem a necessidade de usar uma conta bancária real. Sua empresa sempre terá uma conta de teste disponível para usar.

A conta de teste não utiliza nenhum dado real, como por exemplo, o nome do titular da conta, o saldo da conta, os reembolsos, etc...

Veja abaixo a lista de funcionalidades que podem ser testadas na conta de teste:

| Funcionalidade                         | Disponibilidade |
| -------------------------------------- | --------------- |
| Cobrança com autocadastro              | Sim             |
| Cobrança em e-commerce                 | Sim             |
| Cobrança com solicitação de cadastro   | Sim             |
| Cobrança com cliente                   | Sim             |
| Cobrança com vencimento, multa e juros | Sim             |
| Assinatura                             | Sim             |
| Qr code estático                       | Sim             |
| Pix crediário                          | Sim             |
| Reembolso                              | Sim             |
| Reembolso parcial                      | Sim             |
| Pagamento de chave pix                 | Sim             |
| Pagamento de qr code pix               | Sim             |
| Saque                                  | Não             |

---

## Pagando um Pix QRCode de teste(Test-account)

Pagar um Pix QRCode com uma conta bancaria de teste permite testar se o Webhook cadastrado está funcionando.

Para pagar um Pix QRCode você precisa pegar o identificador do QRCode que você encontra no detalhe do mesmo.

Exemplo:

![Identifier Example QRCode](/img/identifier-ex-qrcode.png)

E também copiar o código do seu AppID, você irá encontrá-lo em `menu Administrador > API/Plugins`, clicar em seu respectivo `API/Plugin` criado e copiar o `AppID` no detalhe da aplicação.

Mais infomações sobre o AppID aqui: /docs/plugin/app-id/

Exemplo:

![App Id Example](/img/app-id-ex.png)

E por fim já com todos os dados recolhidos você poderá rodar esse comando abaixo preenchido com os dados indicados já citados a cima e gerar uma transação de pagamento!

```jsx
curl 'https://api.woovi.com/openpix/testing?identifier=<identifier>' -H 'Authorization: <appID>'
```

Para ver as transações geradas clique em `transações` para ver a transação do Pix QRCode do pagamento teste recebida. 

![Identifier Example QRCode](/img/transaction-ex.png)

---

## Pagando uma Cobrança Pix de Teste(Test-account)

Pagar uma cobrança Pix no modo teste permite testar se o Webhook cadastrado está funcionando.

Para pagar uma cobrança Pix você precisa pegar o identificador da cobrança que você encontra no detalhe da mesma.

Exemplo:

![Identifier Example](/img/identifier-example.png)

E também copiar o código do seu AppID, você irá encontrá-lo em `menu Administrador > API/Plugins`, clicar em seu respectivo `API/Plugin` criado e copiar o `AppID` no detalhe da aplicação.

Mais infomações sobre o AppID aqui: /docs/plugin/app-id/

Exemplo:

![App Id Example](/img/app-id-ex.png)

E por fim já com todos os dados recolhidos você poderá rodar esse comando abaixo preenchido com os dados indicados já citados a cima e efetuar o pagamento !

```jsx
curl 'https://api.woovi.com/openpix/testing?transactionID=<identifier>' -H 'Authorization: <appID>' \
```

---

## Pagando uma chave pix com a conta de teste(Test-account)

Pagar uma chave pix possibilita testar se o Webhook cadastrado está funcionando, alem de testar as funcionalidades de pagamento.

Para pagar uma chave pix usando a conta de testes, primeiro vá até o menu de `Saques/Pagamentos` e clique em `Novo Pagamento`, no canto superior direito da tela.

Você poderá preencher a chave pix que deseja simular um pagamento, o valor e o comentário do pagamento (opcional). Após isso clique em `Solicitar`.

O pagamento estará disponível para ser aprovado, você seria redirecionado para a tela de detalhes do pagamento, onde poderá aprovar o pagamento.

![payment-requested](./__assets__/payment-requested.png)

Todos os pagamentos feitos na conta de testes aparecerão um banner de aviso no topo da tela, indicando que o pagamento foi feito na conta de testes.

Por fim, você pode aprovar o pagamento clicando em `Aprovar Pagamento` no canto superior direito da tela e depois em `Aprovar`.

### Chaves Pix disponíveis para teste

Possuimos algumas chaves pix disponíveis para teste, para simular alguns casos de uso, essas chaves pix estão disponíveis para serem usadas em qualquer conta de teste.

| Chave Pix                   | Caso de uso                                                  |
| --------------------------- | ------------------------------------------------------------ |
| pix-key-not-found@woovi.com | Simular quando uma chave pix não esta cadastrada em um banco |
| bank-error@woovi.com        | Simular quando a instituição de destino esta fora do ar      |

---

## Acessando o Ambiente de teste Woovi(Test-environment)

A plataforma Woovi foi desenvolvida com o objetivo de simplificar e gerenciar totalmente geração, cobrança, liquidação e conciliação em tempo real de pagamentos instantâneos usando Pix. Proporcionando ao mesmo tempo ótima experiência de programção atentendo requisitos de máximos de segurança. Esta documentação visa auxiliar os programadores e administradores de sistemas na configuração adequada da plataforma, especialmente em relação ao método de pagamento Pix.

*Utilizar métodos automatizados tais como Single-Sign-On e APIs são preferenciais, uma vez que proporcionam uma melhor experiência ao usuário, aumentam a segurança e automatizam os processos.*

## Começando

:::caution

Os dados de produção não funcionam no ambiente de testes.

Para acessar o ambiente de testes, 

Registre-se novamente através da seguinte URL:

👉 https://app.woovi-sandbox.com/

:::

Após se registrar no ambiente de testes, você terá acesso a todas as funcionalidades do ambiente de produção, mas em um ambiente seguro para testes.

Você poderá:

- Convidar outros usuários para a plataforma;

- Configurar métodos de login;

- Gerar cobranças individuais ou em lote;

- Utilizar APIs e integrações;

- Importar usuários via arquivos Excel.

## Configurando o Single Sign-On (SSO)

A Woovi suporta múltiplos SSO identity providers (IdP). Um Identity Provider é um servidor que pode fornecer informações de identidade sobre os usuários da sua empresa. Por exemplo, o Google pode ser um fornecedor de identidade para empresas que utilizam a solução G Suite. Se a sua empresa está utilizando a solução G Suite, pode entrar automaticamente na Woovi utilizando a sua conta Google. então um servidor Google enviará a sua informação de identidade para esse site.

### Azure Single Sign On

Se a sua empresa utiliza o Azure Single Sign On, poderá entrar automaticamente na Woovi utilizando o Azure como IdP. Para utilizar esta estratégia de login, é preciso ativar esta opção no menu de definições.

### Google Single Sign On

Se a sua empresa utiliza a G Suite, poderá iniciar automaticamente uma sessão na Woovi utilizando o Google como IdP.

### SAML Single Sign on

Se a sua empresa utiliza SAML, poderá entrar automaticamente no Woovi SAML Servers como IdP.

## Segurança e Firewall

### Lista de Domínios Woovi permitidos

A fim de operar corretamente os usuários da sua empresa precisam ter acesso aos servidores da Woovi. A Woovi utiliza tecnologias web padrão e aplica a encriptação em todas as comunicações, na maioria dos casos a sua configuração deve funcionar fora da caixa, sem requisitos adicionais.

Se você se deparar com problemas utilizando a plataforma, por favor verifique os seguintes requisitos:

- Certifique-se que os domínios da Woovi estão liberados seu servidor proxy ou firewall. Além disso seus clientes também devem ter poder acessar todos os domínios e subdomínios.
  
  > Permitir todo tráfego para OpenPix *.openpix.com.br 
  > Permitir todo tráfego para OpenPix *.openpix.com

- Certifique-se de que não está bloqueando os e-mails do domínio da Woovi.
  
  > Permitir emails da Openpix *.openpix.com.br em seu fornecedor de e-mail
  > Permitir emails da Openpix *.openpix.com em seu fornecedor de e-mail
  
- Não armazenar em cache

    > Não alterar ou impor novas políticas de cache para conteúdo estático Woovi ou endereço IP. 
    > A Woovi utiliza uma rede CDN global e proteções adicionais de servidor para que os IPs mudem frequentemente e sem aviso prévio.

---

## Como pegar o Relatório de Saque pela a API?

## Relatório de Saque pela a API

Nós disponibilizamos o _endpoint_ `/api/v1/transaction` para que você possa pegar
_transactions_ da respectiva empresa afiliada.

Você pode acessar [aqui](/api#tag/transactions/GET/api/v1/transaction)
a documentação referente a esse _endpoint_.

Utilizando o endpoint, é muito simples acessar o relatório de saque, basta informar o `endToEndId` do saque que deseja o relatório no parâmetro `withdrawal`

Exemplo: `withdrawal=E18236120202012032010s01345689XBY`

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta,
você receberá uma lista com todas as transações que pertecem ao saque informado.

Num exemplo, essa será a nossa resposta:

```json
{
  "pageInfo": {
    "skip": 0,
    "limit": 10,
    "totalCount": 20,
    "hasPreviousPage": false,
    "hasNextPage": true
  },
  "transactions": [
    {
      "customer": {
        "name": "Dan",
        "email": "email0@example.com",
        "phone": "5511999999999",
        "taxID": {
          "taxID": "31324227036",
          "type": "BR:CPF"
        },
        "correlationID": "9134e286-6f71-427a-bf00-241681624586"
      },
      "payer": {
        "name": "Dan",
        "email": "email0@example.com",
        "phone": "5511999999999",
        "taxID": {
          "taxID": "31324227036",
          "type": "BR:CPF"
        },
        "correlationID": "9134e286-6f71-427a-bf00-241681624586"
      },
      "charge": {
        "status": "ACTIVE",
        "customer": "603f81fcc6bccc24326ffb43",
        "correlationID": "9134e286-6f71-427a-bf00-241681624586",
        "createdAt": "2021-03-03T12:33:00.546Z",
        "updatedAt": "2021-03-03T12:33:00.546Z"
      },
      "withdraw": {
        "value": 100,
        "time": "2021-03-03T12:33:00.536Z",
        "infoPagador": "payer info 1",
        "endToEndId": "E18236120202012032010s01345689XBY"
      },
      "type": "PAYMENT",
      "infoPagador": "payer info 0",
      "value": 100,
      "time": "2021-03-03T12:33:00.536Z",
      "transactionID": "transactionID",
      "endToEndId": "E18236120202012032010s0133872GZA"
    }
  ]
}
```

---

## Como Paginar pela a API de Transações?

## Paginação pela API de Transações

Nós disponibilizamos o _endpoint_ `/api/v1/transaction` para que você possa visualizar
_transactions_ de sua empresa.

Você pode acessar [aqui](/api#tag/transactions/GET/api/v1/transaction)
a documentação referente a esse _endpoint_.

O endpoint limita a 100 transações por request, porém é possível visualizar outras transações paginando a API.

Após efetuar a primeira requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, junto da lista de transações você receberá um objeto nomeado de `pageInfo`.

Num exemplo, essa será a nossa resposta:

```json
{
  "pageInfo": {
    "skip": 0,
    "limit": 100,
    "totalCount": 200,
    "hasPreviousPage": false,
    "hasNextPage": true
  },
  "transactions": [
    ...transactions,
  ]
}
```

É possível enviar o parametro `skip` na query string da requisição, para visualizar a próxima página, podemos retornar o valor do skip sendo `pageInfo.skip` + `pageInfo.limit`.

Nesse exemplo, essa seria a url da próxima requisição:

`/api/v1/transaction?skip=100`

Também é possível fácilmente saber se existe uma nova página a ser requisitada, isso pode ser verificado usando o campo `hasNextPage` enviado dentro do objeto de `pageInfo`.

---

## Como usar a API para Transferir Valores entre Contas?

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info
Para a utilização dessa funcionalidade é necessário possuir a funcionalidade BETA
:::

Para transferir valores entre suas contas você por utilizar o _endpoint_ `/api/v1/transfer` da API.

Os campos obrigatórios para criar uma transferência entre contas são os seguintes:

- **`value`**: O valor em centavos a ser transferido.
- **`fromPixKey`**: A chave pix da conta de origem
- **`toPixKey`**: A chave pix da conta de destino

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "value": 100,
  "fromPixKey": "from@woovi.com.br",
  "toPixKey": "to@woovi.com.br"
}
```

O valor do campo `value` é o valor desejado para a transferência em **centavos**.

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, será retornado os seguintes campos:

```json
{
  "transaction": {
    "value": 100,
    "time": "2023-06-22T15:33:27.165Z",
    "correlationID": "c782e0ac-833d-4a89-9e73-9b60b2b41d3a"
  }
}
```

### Exemplos em código

  

```sh
  curl 'https://api.woovi.com/api/v1/transfer' -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      --data-binary '{"value": 100, "fromPixKey": "from@woovi.com.br", "toPixKey": "to@woovi.com.br"}'
```

  
  

```js
fetch('https://api.woovi.com/api/v1/transfer', {
  method: 'POST',
  body: JSON.stringify({
    value: 100,
    fromPixKey: 'from@woovi.com.br',
    toPixKey: 'to@woovi.com.br',
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());
```

---

## O que é uma conta Mediator?

## Conta Mediator

A conta `Mediator` é responsável por receber todos os valores relacionados a receitas de tarifas, dentro do sistema de Wallets do Parceiro. Além de receber receitas, essa conta também é onde será debitado o valor das tarifas da plataforma.

### Exemplos

Nesse exemplo, uma Wallet de um affiliado recebe um valor de uma Cobrança, e logo em seguida realiza o pagamento de sua tarifa para a Mediator do parceiro, e então é realizada a cobrança da tarifa da plataforma dentro da Mediator.

![Exemplo de como funciona uma Wallet Mediator](./__assets__/partner-wallet-mediator-example.png)

---

## Payload de Registro Conta aprovado

## Registro de conta aprovado

Os webhooks de `ACCOUNT_REGISTER_APPROVED` enviam objetos com os seguintes campos no seu payload:

- `accountRegister`: Detalhes do registro de contas
- `account`: Detalhes da conta que o resgistro pertence

## Exemplo

```json
{
   "event":"ACCOUNT_REGISTER_APPROVED",
   "accountRegister":{
      "officialName":"Test Company",
      "taxID":{
         "taxID":"12345678901234",
         "type":"BR:CNPJ"
      },
      "status":"APPROVED"
   },
   "account":{
      "status":"OPEN",
      "accountId":"68dbe391ee9fce4ba2b0b4ec",
      "account":"123456",
      "branch":"0001"
   }
}
```

---

## Payload de Registro de Conta Pendente

## Registro de conta pendente

Os webhooks de `ACCOUNT_REGISTER_PENDING` enviam objetos com os seguintes campos no seu payload:

- `accountRegister`: Detalhes do registro de conta
  - `officialName`: Nome oficial/razão social da conta
  - `taxID`: Objeto contendo o documento de identificação
    - `taxID`: Número do CPF ou CNPJ
    - `type`: Tipo do taxID (`BR:CPF` ou `BR:CNPJ`)
  - `status`: Status do registro (sempre `PENDING` para este evento)
  - `requestDocuments`: Lista de documentos solicitados para análise
  - `requestReason`: Comunicado sobre as pendências
  - `requestDocumentsRepresentatives`: Lista de documentos solicitados para os representantes legais

## Quando é enviado

Este evento é enviado quando um registro de subconta está em análise pelo compliance. Isso pode ocorrer quando:

- Uma nova conta é criada, entra em processo de análise mas algun documento é rejeitado e tem que ser reenviado
- Documentos adicionais são solicitados para a conta

## Exemplo

```json
{
  "event": "ACCOUNT_REGISTER_PENDING",
  "accountRegister": {
    "officialName": "Test Company",
    "taxID": {
      "taxID": "12345678901234",
      "type": "BR:CNPJ"
    },
    "status": "PENDING",
    "requestDocuments": [],
    "requestReason": "",
    "requestDocumentsRepresentatives": []
  }
}
```

## Exemplo com documentos solicitados

```json
{
  "event": "ACCOUNT_REGISTER_PENDING",
  "accountRegister": {
    "officialName": "Empresa Exemplo LTDA",
    "taxID": {
      "taxID": "12345678000199",
      "type": "BR:CNPJ"
    },
    "status": "PENDING",
    "requestDocuments": ["SOCIAL_CONTRACT", "ADDRESS_PROOF"],
    "requestReason": "Faltou contrato social e comprovante de endereço",
    "requestDocumentsRepresentatives": [
      {
        "taxId": {
          "taxID": "12345678901",
          "type": "BR:CPF"
        },
        "requestDocuments": ["RG", "ADDRESS_PROOF"]
      }
    ]
  }
}
```

---

## Payload de Registro de Conta Rejeitado

## Registro de conta rejeitado

Os webhooks de `ACCOUNT_REGISTER_REJECTED` enviam objetos com os seguintes campos no seu payload:

- `accountRegister`: Detalhes do registro de conta
  - `officialName`: Nome oficial/razão social da conta
  - `taxID`: Objeto contendo o documento de identificação
    - `taxID`: Numero do CPF ou CNPJ
    - `type`: Tipo do taxID (`BR:CPF` ou `BR:CNPJ`)
  - `status`: Status do registro (sempre `REJECTED` para este evento)
  - `rejectedReason`: Motivo da rejeicao do registro

## Quando é enviado

Este evento é enviado quando um registro de subconta é rejeitado pelo compliance. Isso pode ocorrer quando:

- A documentação enviada não atende aos requisitos de compliance
- Informações inconsistentes ou incorretas foram fornecidas
- A análise de risco identificou problemas com o cadastro
- O solicitante não atendeu às pendências dentro do prazo estabelecido

## Exemplo

```json
{
  "event": "ACCOUNT_REGISTER_REJECTED",
  "accountRegister": {
    "officialName": "Empresa Exemplo LTDA",
    "taxID": {
      "taxID": "12345678000199",
      "type": "BR:CNPJ"
    },
    "status": "REJECTED",
    "rejectedReason": "Documentação não atende aos requisitos de compliance. Contrato social apresenta inconsistências com os dados cadastrais."
  }
}
```

---

## Como verificar qual o tipo da conta em que recebeu um webhook?

## Como verificar qual o tipo da conta que recebi o webhook?

Dentro do webhook de charge mandamos o tipo da conta em `account`, isto é, notificamos para que você veja qual o tipo da conta e recusar ou aceitar aquele webhook.

Caso seja uma conta de teste é retornado `"TESTING"` caso seja uma conta de produção é retornado `"PRODUCTION"`

## Exemplo

```json
{
  "event": "OPENPIX:CHARGE_COMPLETED",
  "charge": {},
  "pix": {},
  "company": {
    "id": "6384cca8cecc7a26b98c49fd",
    "name": "Eduardo",
    "taxID": "45036856000155"
  },
  "account": {
    "environment": "TESTING"
  }
}
```

---

## Payload de Cobrança Pix Paga com um payer diferente do customer.

## Pix Cobrança Paga com um payer diferente do customer.

Os webhooks de `CHARGE_COMPLETED_NOT_SAME_CUSTOMER_PAYER` enviam objetos com os seguintes campos no seu payload:

- `pix`: Objeto com detalhes da transação Pix
- `company`: Empresa a que a Transação pertence
- `account`: Detalhes da conta que a Transação pertence

## Exemplo

```json
{
   "event":"OPENPIX:CHARGE_COMPLETED_NOT_SAME_CUSTOMER_PAYER",
   "charge":{
      "customer":{
         "name":"Jão",
         "email":"email0@entria.com.br",
         "phone":"119912345670",
         "taxID":{
            "taxID":"29094848074",
            "type":"BR:CPF"
         },
         "correlationID":"9134e286-6f71-427a-bf00-100000000001"
      },
      "value":100,
      "status":"COMPLETED",
      "payer":{
         "name":"Ana",
         "email":"email1@entria.com.br",
         "phone":"119912345671",
         "taxID":{
            "taxID":"29094848074",
            "type":"BR:CPF"
         },
         "correlationID":"9134e286-6f71-427a-bf00-100000000002"
      },
      "discount":0,
      "valueWithDiscount":100,
      "type":"DYNAMIC",
      "identifier":"9134e2866f71427abf0010000",
      "correlationID":"9134e286-6f71-427a-bf00-100000000005",
      "paymentLinkID":"9134e286-6f71-427a-bf00-100000000006",
      "transactionID":"9134e2866f71427abf00100000000007",
      "additionalInfo":[
         
      ],
      "createdAt":"2025-09-30T13:50:56.065Z",
      "updatedAt":"2025-09-30T13:50:56.065Z",
      "ensureSameTaxID":false,
      "brCode":"00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-42665544000052040000530398654041.005802BR5915Call_me_Awesome6009Sao_Paulo622905259134e2866f71427abf001000063047029",
      "expiresIn":86400,
      "pixKey":"123e4567-e12b-12d1-a456-426655440000",
      "paymentLinkUrl":"https://woovi.com/pay/9134e286-6f71-427a-bf00-100000000006",
      "qrCodeImage":"https://api.woovi.com/openpix/charge/brcode/image/9134e286-6f71-427a-bf00-100000000006.png",
      "globalID":"Q2hhcmdlOjY4ZGJlMDQwZGNkOTlmNzM1NDhmYjllOQ==",
      "paymentMethods":{
         
      }
   },
   "pix":{
      "customer":{
         "name":"Jão",
         "email":"email0@entria.com.br",
         "phone":"119912345670",
         "taxID":{
            "taxID":"29094848074",
            "type":"BR:CPF"
         },
         "correlationID":"9134e286-6f71-427a-bf00-100000000001"
      },
      "payer":{
         "name":"Jão",
         "email":"email0@entria.com.br",
         "phone":"119912345670",
         "taxID":{
            "taxID":"29094848074",
            "type":"BR:CPF"
         },
         "correlationID":"9134e286-6f71-427a-bf00-100000000001"
      },
      "charge":{
         "customer":{
            "name":"Jão",
            "email":"email0@entria.com.br",
            "phone":"119912345670",
            "taxID":{
               "taxID":"29094848074",
               "type":"BR:CPF"
            },
            "correlationID":"9134e286-6f71-427a-bf00-100000000001"
         },
         "value":100,
         "status":"COMPLETED",
         "payer":{
            "name":"Ana",
            "email":"email1@entria.com.br",
            "phone":"119912345671",
            "taxID":{
               "taxID":"29094848074",
               "type":"BR:CPF"
            },
            "correlationID":"9134e286-6f71-427a-bf00-100000000002"
         },
         "discount":0,
         "valueWithDiscount":100,
         "type":"DYNAMIC",
         "identifier":"9134e2866f71427abf0010000",
         "correlationID":"9134e286-6f71-427a-bf00-100000000005",
         "paymentLinkID":"9134e286-6f71-427a-bf00-100000000006",
         "transactionID":"9134e2866f71427abf00100000000007",
         "additionalInfo":[
            
         ],
         "createdAt":"2025-09-30T13:50:56.065Z",
         "updatedAt":"2025-09-30T13:50:56.065Z",
         "ensureSameTaxID":false,
         "brCode":"00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-42665544000052040000530398654041.005802BR5915Call_me_Awesome6009Sao_Paulo622905259134e2866f71427abf001000063047029",
         "expiresIn":86400,
         "pixKey":"123e4567-e12b-12d1-a456-426655440000",
         "paymentLinkUrl":"https://woovi.com/pay/9134e286-6f71-427a-bf00-100000000006",
         "qrCodeImage":"https://api.woovi.com/openpix/charge/brcode/image/9134e286-6f71-427a-bf00-100000000006.png",
         "globalID":"Q2hhcmdlOjY4ZGJlMDQwZGNkOTlmNzM1NDhmYjllOQ=="
      },
      "value":100,
      "time":"2022-09-05T11:05:11.000Z",
      "endToEndId":"endToEndId#0",
      "infoPagador":"payer info 0",
      "status":"CONFIRMED",
      "type":"PAYMENT",
      "createdAt":"2025-09-30T13:50:56.075Z",
      "globalID":"UGl4VHJhbnNhY3Rpb246NjhkYmUwNDBkY2Q5OWY3MzU0OGZiOWVl"
   },
   "company":{
      "id":"68dbe03fdcd99f73548fb8f3",
      "name":"Awesome Company 1"
   },
   "account":{
      "clientId":"clientId",
      "environment":"TESTING"
   },
   "payer":{
      "name":"Ana",
      "email":"email1@entria.com.br",
      "phone":"119912345671",
      "taxID":{
         "taxID":"29094848074",
         "type":"BR:CPF"
      }
   }
}
```

---

## Payload de Cobrança Criada


Os webhooks do tipo `Cobrança Criada` enviam objetos com os seguintes campos no seu payload:

- `event`: O tipo de evento realizado que neste caso seria `OPENPIX:CHARGE_CREATED`.
- `charge`: A cobrança que foi criada.
- `company`: Empresa a que a cobrança pertence.

## Exemplo

```json
{
   "event":"OPENPIX:CHARGE_CREATED",
   "charge":{
      "customer":{
         "name":"customer#0",
         "email":"email0@entria.com.br",
         "phone":"119912345670",
         "taxID":{
            "taxID":"29094848074",
            "type":"BR:CPF"
         },
         "correlationID":"9134e286-6f71-427a-bf00-100000000001"
      },
      "value":100,
      "identifier":"9134e2866f71427abf0010000",
      "correlationID":"9134e286-6f71-427a-bf00-100000000004",
      "paymentLinkID":"9134e286-6f71-427a-bf00-100000000005",
      "transactionID":"9134e2866f71427abf00100000000006",
      "status":"ACTIVE",
      "additionalInfo":[
         { "key":"amount", "value":"100" }
      ],
      "discount":0,
      "valueWithDiscount":100,
      "type":"DYNAMIC",
      "createdAt":"2025-09-30T15:35:13.607Z",
      "updatedAt":"2025-09-30T15:35:13.607Z",
      "ensureSameTaxID":false,
      "brCode":"00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-42665544000052040000530398654041.005802BR5915Call_me_Awesome6009Sao_Paulo622905259134e2866f71427abf001000063047029",
      "expiresIn":86400,
      "pixKey":"123e4567-e12b-12d1-a456-426655440000",
      "paymentLinkUrl":"https://woovi.com/pay/9134e286-6f71-427a-bf00-100000000005",
      "qrCodeImage":"https://api.woovi.com/openpix/charge/brcode/image/9134e286-6f71-427a-bf00-100000000005.png",
      "globalID":"Q2hhcmdlOjY4ZGJmOGIxNDc5YjhhNDYyNDAxNjIyNg==",
      "paymentMethods":{
         "pix":{
            "method":"PIX_COB",
            "status":"ACTIVE",
            "brCode":"00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-42665544000052040000530398654041.005802BR5915Call_me_Awesome6009Sao_Paulo622905259134e2866f71427abf001000063047029",
            "qrCodeImage":"https://api.woovi.com/openpix/charge/brcode/image/9134e286-6f71-427a-bf00-100000000005.png"
         }
      }
   },
   "company":{
      "id":"68dbf8b0479b8a46240160e9",
      "name":"Awesome Company 1",
      "taxID":"00988776655"
   },
   "account":{
     "environment": "PRODUCTION"
   }
}
```

---

## Payload de Cobrança Expirada


Os webhooks do tipo `Cobrança Expirada` enviam objetos com os seguintes campos no seu payload:

- `event`: O tipo de evento realizado que neste caso seria `OPENPIX:CHARGE_EXPIRED`.
- `charge`: A cobrança que foi expirada.
- `company`: Empresa a que a cobrança pertence.

## Exemplo

```json
{
  "event": "OPENPIX:CHARGE_EXPIRED",
  "charge": {
    "value": 1,
    "comment": "",
    "identifier": "0c0ddb5e24764191a8fa6c9afeaa26aa",
    "transactionID": "0c0ddb5e24764191a8fa6c9afeaa26aa",
    "status": "EXPIRED",
    "additionalInfo": [],
    "fee": 85,
    "discount": 0,
    "valueWithDiscount": 1,
    "expiresDate": "2025-09-24T15:08:00.368Z",
    "type": "DYNAMIC",
    "correlationID": "4bfa04e1-b807-4833-b714-dfa7c8877f29",
    "paymentLinkID": "4ceb0a22-d87d-46d1-b699-cf74e171386d",
    "createdAt": "2025-09-24T15:03:38.922Z",
    "updatedAt": "2025-09-24T15:09:00.042Z",
    "ensureSameTaxID": false,
    "brCode": "00020101021226870014br.gov.bcb.pix2565qr-h.woovi.digital/qr/v2/cob/92b4992a-92de-423b-938e-0b0b6e534a0052040000530398654040.015802BR592357419727_WOOVI_IP_6009Sao_Paulo622905250c0ddb5e24764191a8fa6c9af6304C6D5",
    "expiresIn": 300,
    "paymentLinkUrl": "undefined/4ceb0a22-d87d-46d1-b699-cf74e171386d",
    "qrCodeImage": "https://api.woovi.dev/openpix/charge/brcode/image/4ceb0a22-d87d-46d1-b699-cf74e171386d.png",
    "globalID": "Q2hhcmdlOjY4ZDQwODRhZjNmMjk2YTY1MGM5OWNjMg==",
    "paymentMethods": {
      "pix": {
        "method": "PIX_COB",
        "status": "ACTIVE",
        "value": 1,
        "txId": "0c0ddb5e24764191a8fa6c9afeaa26aa",
        "fee": 85,
        "brCode": "00020101021226870014br.gov.bcb.pix2565qr-h.woovi.digital/qr/v2/cob/92b4992a-92de-423b-938e-0b0b6e534a0052040000530398654040.015802BR592357419727_WOOVI_IP_6009Sao_Paulo622905250c0ddb5e24764191a8fa6c9af6304C6D5",
        "transactionID": "0c0ddb5e24764191a8fa6c9afeaa26aa",
        "identifier": "0c0ddb5e24764191a8fa6c9afeaa26aa",
        "qrCodeImage": "https://api.woovi.dev/openpix/charge/brcode/image/4ceb0a22-d87d-46d1-b699-cf74e171386d.png"
      }
    }
  },
  "company": {
    "id": "67b87652d865a18620c53604",
    "name": "WOOVI-IP",
    "taxID": "44720743000101"
  },
  "account": {
    "environment": "PRODUCTION"
  }
}
```

---

## Payload de Cobrança Pix Paga

## Pix Cobrança Paga

Os webhooks de `CHARGE_COMPLETED` enviam objetos com os seguintes campos no seu payload:

- `pix`: Objeto com detalhes da transação Pix
- `company`: Empresa a que a Transação pertence
- `account`: Detalhes da conta que a Transação pertence

## Exemplo

```json
{
  "event": "OPENPIX:CHARGE_COMPLETED",
  "charge": {
    "value": 1,
    "comment": "",
    "identifier": "d983a07836cf48ed9a65764d3c184273",
    "transactionID": "d983a07836cf48ed9a65764d3c184273",
    "status": "COMPLETED",
    "additionalInfo": [],
    "fee": 85,
    "discount": 0,
    "valueWithDiscount": 1,
    "expiresDate": "2025-09-25T15:08:12.278Z",
    "type": "DYNAMIC",
    "correlationID": "3f2a2690-8224-4aae-a1ba-ed26d4d61f81",
    "paymentLinkID": "788c8d0d-182b-468e-942e-546be6a621c2",
    "createdAt": "2025-09-24T15:07:47.334Z",
    "updatedAt": "2025-09-24T15:08:13.578Z",
    "customer": {
      "name": "Cliente Teste",
      "taxID": {
        "taxID": "44720743000101",
        "type": "BR:CNPJ"
      },
      "correlationID": "ecd41c3b-487c-4719-b9f7-53b6dd6759cb"
    },
    "paidAt": "2025-09-24T15:07:50.891Z",
    "payer": null,
    "ensureSameTaxID": false,
    "brCode": "00020101021226980014br.gov.bcb.pix2576api.woovi-sandbox.com/api/testaccount/qr/v1/d983a07836cf48ed9a65764d3c18427352040000530398654040.015802BR5921Lucas_Aprigio_Sandbox6009Sao_Paulo62290525d983a07836cf48ed9a65764d363046759",
    "expiresIn": 86424,
    "pixKey": "67856db0-ac6e-4276-8309-503a22a896dc",
    "paymentLinkUrl": "https://woovi-sandbox.com/pay/788c8d0d-182b-468e-942e-546be6a621c2",
    "qrCodeImage": "https://api.woovi-sandbox.com/openpix/charge/brcode/image/788c8d0d-182b-468e-942e-546be6a621c2.png",
    "globalID": "Q2hhcmdlOjY4ZDQwOTQzMDY5YTI4ZjgzMTEzOTVkZA==",
    "paymentMethods": {
      "pix": {
        "method": "PIX_COB",
        "txId": "d983a07836cf48ed9a65764d3c184273",
        "value": 1,
        "status": "COMPLETED",
        "fee": 85,
        "brCode": "00020101021226980014br.gov.bcb.pix2576api.woovi-sandbox.com/api/testaccount/qr/v1/d983a07836cf48ed9a65764d3c18427352040000530398654040.015802BR5921Lucas_Aprigio_Sandbox6009Sao_Paulo62290525d983a07836cf48ed9a65764d363046759",
        "transactionID": "d983a07836cf48ed9a65764d3c184273",
        "identifier": "d983a07836cf48ed9a65764d3c184273",
        "qrCodeImage": "https://api.woovi-sandbox.com/openpix/charge/brcode/image/788c8d0d-182b-468e-942e-546be6a621c2.png"
      }
    }
  },
  "pix": {
    "customer": {
      "name": "Cliente Teste",
      "taxID": {
        "taxID": "44720743000101",
        "type": "BR:CNPJ"
      },
      "correlationID": "ecd41c3b-487c-4719-b9f7-53b6dd6759cb"
    },
    "payer": {
      "name": "Cliente Teste",
      "taxID": {
        "taxID": "44720743000101",
        "type": "BR:CNPJ"
      },
      "correlationID": "ecd41c3b-487c-4719-b9f7-53b6dd6759cb"
    },
    "charge": {
      "value": 1,
      "comment": "",
      "identifier": "d983a07836cf48ed9a65764d3c184273",
      "transactionID": "d983a07836cf48ed9a65764d3c184273",
      "status": "COMPLETED",
      "additionalInfo": [],
      "fee": 85,
      "discount": 0,
      "valueWithDiscount": 1,
      "expiresDate": "2025-09-25T15:08:12.278Z",
      "type": "DYNAMIC",
      "correlationID": "3f2a2690-8224-4aae-a1ba-ed26d4d61f81",
      "paymentLinkID": "788c8d0d-182b-468e-942e-546be6a621c2",
      "createdAt": "2025-09-24T15:07:47.334Z",
      "updatedAt": "2025-09-24T15:08:13.578Z",
      "customer": {
        "name": "Cliente Teste",
        "taxID": {
          "taxID": "44720743000101",
          "type": "BR:CNPJ"
        },
        "correlationID": "ecd41c3b-487c-4719-b9f7-53b6dd6759cb"
      },
      "paidAt": "2025-09-24T15:07:50.891Z",
      "payer": null,
      "ensureSameTaxID": false,
      "brCode": "00020101021226980014br.gov.bcb.pix2576api.woovi-sandbox.com/api/testaccount/qr/v1/d983a07836cf48ed9a65764d3c18427352040000530398654040.015802BR5921Lucas_Aprigio_Sandbox6009Sao_Paulo62290525d983a07836cf48ed9a65764d363046759",
      "expiresIn": 86424,
      "pixKey": "67856db0-ac6e-4276-8309-503a22a896dc",
      "paymentLinkUrl": "https://woovi-sandbox.com/pay/788c8d0d-182b-468e-942e-546be6a621c2",
      "qrCodeImage": "https://api.woovi-sandbox.com/openpix/charge/brcode/image/788c8d0d-182b-468e-942e-546be6a621c2.png",
      "globalID": "Q2hhcmdlOjY4ZDQwOTQzMDY5YTI4ZjgzMTEzOTVkZA=="
    },
    "value": 1,
    "time": "2025-09-24T15:07:50.891Z",
    "endToEndId": "Efa8df7c628cf43d2af424696ea0c6444",
    "transactionID": "d983a07836cf48ed9a65764d3c184273",
    "infoPagador": "OpenPix testing",
    "status": "CONFIRMED",
    "type": "PAYMENT",
    "createdAt": "2025-09-24T15:07:50.915Z",
    "globalID": "UGl4VHJhbnNhY3Rpb246NjhkNDA5NDYwNjlhMjhmODMxMTM5NjU4"
  },
  "company": {
    "id": "6810ce3b892866f103d77ef2",
    "name": "Lucas Aprigio Sandbox",
    "taxID": "57437573000102"
  },
  "account": {
    "environment": "TESTING"
  }
}
```

---

## Payload de Disputa aceita

## Disputa (DISPUTE_ACCEPTED)

Os webhooks de `Disputa` enviam objetos com os seguintes campos no seu payload:

- `disputa`: Detalhes da disputa

## Exemplo 

```json
{
  "event": "OPENPIX:DISPUTE_ACCEPTED",
  "dispute": {
    "status": "ACCEPTED",
    "endToEndId": "E3524a995bbd54034b6d07c1c36014557",
    "name": "Seu jorge",
    "email": "test@email.com.br",
    "phoneNumber": "+5519989673846",
    "value": 1000,
    "disputeReason": "Golpe"
  }
}
```

---

## Payload de Disputa Cancelada

## Disputa (DISPUTE_CANCELED)

Os webhooks de `Disputa` enviam objetos com os seguintes campos no seu payload:

- `disputa`: Detalhes da disputa

## Exemplo

```json
{
  "event": "OPENPIX:DISPUTE_CANCELED",
  "dispute": {
    "status": "CANCELED",
    "endToEndId": "E3524a995bbd54034b6d07c1c36014557",
    "name": "Seu jorge",
    "email": "test@email.com.br",
    "phoneNumber": "+5519989673846",
    "value": 1000,
    "disputeReason": "Golpe"
  }
}
```

---

## Payload de Disputa criada

## Disputa (DISPUTE_CREATE)

Os webhooks de `Disputa` enviam objetos com os seguintes campos no seu payload:

- `disputa`: Detalhes da disputa

Disputas criadas podem ter alguns status: `Em revisão` e `Aberta`

Em revisão é uma disputa em análise, essa ainda não foi `Criada`.

Uma disputa `Aberta` é considerada como uma disputa `Criada`

## Exemplo

```json
{
  "event": "OPENPIX:DISPUTE_CREATED",
  "dispute": {
    "status": "OPENED",
    "endToEndId": "E3524a995bbd54034b6d07c1c36014557",
    "name": "Seu jorge",
    "email": "test@email.com.br",
    "phoneNumber": "+5519989673846",
    "value": 1000,
    "disputeReason": "Golpe"
  }
}
```

---

## Payload de Disputa Rejeitada

## Disputa (DISPUTE_REJECTED)

Os webhooks de `Disputa` enviam objetos com os seguintes campos no seu payload:

- `disputa`: Detalhes da disputa

## Exemplo

```json
{
  "event": "OPENPIX:DISPUTE_REJECTED",
  "dispute": {
    "status": "REJECTED",
    "endToEndId": "E3524a995bbd54034b6d07c1c36014557",
    "name": "Seu jorge",
    "email": "test@email.com.br",
    "phoneNumber": "+5519989673846",
    "value": 1000,
    "disputeReason": "Golpe"
  }
}
```

---

## Como identificar de qual API veio a cobrança


Quando você cria uma cobrança, você pode informar um padrão de `correlationID` para identificar de qual API veio a cobrança.

Por exemplo, você pode criar uma cobrança com o `correlationID` igual a `api-1` e, quando receber o evento de cobrança paga, você pode verificar o `correlationID` para saber de qual API veio a cobrança.

### Criando a cobrança

```json
{
  "value": 1000,
  "correlationID": "api1-1",
  "comment": "Cobrança da API 1"
}
```

### Recebendo o evento de cobrança paga

```json
{
  "event": "OPENPIX:CHARGE_COMPLETED",
  "charge": {
    "value": 1000,
    "correlationID": "api1-1",
    "comment": "Cobrança da API 1"
  }
}
```

Ao receber o evento de cobrança paga, você pode verificar o `correlationID` para saber de qual API veio a cobrança.

```js
if(event.charge.correlationID === 'api1-1') {
  // Cobrança da API 1
} else if(event.charge.correlationID === 'api2-2') {
  // Cobrança da API 2
} else {
  // Cobrança de uma API desconhecida
}
```

---

## Como interceptar um Pix utilizando um webhook

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Com a Woovi é possível criar webhooks para interceptar quando um Pix for realizado.

Neste tutorial iremos descrever como criar um webhook para informar o recebimento de um novo Pix e devolvê-lo em uma API registrada.

## Step 1 - Crie o seu webhook apontando para o seu endpoint

Para criar um webhook via API basta seguir os passos desse tutorial: [Criando um webhook para interceptar um Pix Via API](/docs/webhook/webhook-api).

Para criar um webhook via plataforma basta seguir os passos desse tutorial: [Criando um webhook para interceptar um Pix e chamar uma API](/docs/webhook/platform/webhook-platform-api.mdx).

## Step 2 - Crie o seu endpoint

Agora que você já tem o seu webhook criado, é necessário criar o seu endpoint para receber o webhook.

Há diversas linguagens em que você pode criar o seu endpoint, abaixo iremos descrever como criar o seu endpoint em PHP.

  

```php
<?php

  // Get the JSON input data
  $input = file_get_contents('php://input');

  // Decode the JSON data into an associative array
  $data = json_decode($input, true);

  // Access the charge object
  $charge = $data['charge'];

  // Now you can use the $charge object as needed
  print_r($charge);

  echo 'correlationID: ' . $charge['correlationID'];

?>

```

---

## Payload de Pagamentos

## Pagamento confirmado

Os webhooks de `Pagamento Externo Confirmado (Pix Out)` enviam objetos com os seguintes campos no seu payload:

- `payment`: Objeto com detalhes do Pagamento
- `transaction`: Objeto com detalhes da Transação Pix

## Exemplo

```json
{
  "event": "OPENPIX:MOVEMENT_CONFIRMED",
  "payment": {
    "value": 30,
    "status": "CONFIRMED",
    "destinationAlias": "06882328684",
    "comment": "",
    "correlationID": "222a1750-de17-406c-bd0c-25af9a5a5d08"
  },
  "transaction": {
    "value": 30,
    "endToEndId": "E23114447202303161242u80lZNR7nQZ",
    "time": "2023-03-16T12:42:47.526Z"
  }
}
```

## Falha no pagamento

Os webhooks de `Pagamento Externo com Falha (Pix Out)` enviam objetos com os seguintes campos no seu payload:

- `payment`: Objeto com detalhes do Pagamento
- `transaction`: Objeto com detalhes da Transação Pix se ela existir
- `error`:  Objeto com o código e descrição do motivo da falha.

:::info
Veja mais detalhes sobre erros relacionados a um Pagamento externo na [documentação](/docs/payment/payment-failed-errors)
:::

## Exemplo

```json
{
  "event": "OPENPIX:MOVEMENT_FAILED",
  "payment": {
    "value": 30,
    "status": "FAILED",
    "destinationAlias": "06882328684",
    "comment": "",
    "correlationID": "222a1750-de17-406c-bd0c-25af9a5a5d08"
  },
  "transaction": {
    "value": 30,
    "endToEndId": "E23114447202303161242u80lZNR7nQZ",
    "time": "2023-03-16T12:42:47.526Z"
  },
  "error": {
    "code":"PAY_PIX_KEY_ERROR",
    "description":"Falha ao Pagar Chave Pix"
  }
}
```

## Pagamento removido

Os webhooks de `Pagamento Externo Removido (Pix Out)` enviam objetos com os seguintes campos no seu payload:

- `payment`: Objeto com o correlationID do pagamento removido

```json
{
  "event": "OPENPIX:MOVEMENT_REMOVED",
  "payment": {
    "correlationID": "222a1750-de17-406c-bd0c-25af9a5a5d08"
  }
}
```

---

## Payload de Pix QR Code

## Pix QR Code

Os webhooks de `Pix QR Code` enviam objetos com os seguintes campos no seu payload:

- `pixQrCode`: Objeto com detalhes do QR Code
- `pix`: Objeto com detalhes da transação Pix
- `company`: Empresa a que a Transação pertence
- `account`: Detalhes da conta que a Transação pertence

## Exemplo

```json
{
  "pixQrCode": {
    "name": "Pix QrCode",
    "value": 1000,
    "comment": "Pagamento Woovi",
    "identifier": "ea83401ed4834b3ea6f1f283b389af29",
    "correlationID": "417bae21-3d08-4cdb-9c2d-fee63c89e9e4",
    "paymentLinkID": "34697ed2-3790-4b60-8512-e7465b142d84",
    "createdAt": "2021-03-12T12:43:54.528Z",
    "updatedAt": "2021-03-12T12:44:09.360Z",
    "brCode": "https://api.woovi.com/openpix/openpix/testing?idenfifier=ea83401ed4834b3ea6f1f283b389af29"
  },
  "charge": null,
  "pix": {
    "charge": null,
    "pixQrCode": {
      "name": "Pix QrCode",
      "value": 1000,
      "comment": "Pagamento Woovi",
      "identifier": "ea83401ed4834b3ea6f1f283b389af29",
      "correlationID": "417bae21-3d08-4cdb-9c2d-fee63c89e9e4",
      "paymentLinkID": "34697ed2-3790-4b60-8512-e7465b142d84",
      "createdAt": "2021-03-12T12:43:54.528Z",
      "updatedAt": "2021-03-12T12:44:09.360Z",
      "brCode": "https://api.woovi.com/openpix/openpix/testing?idenfifier=ea83401ed4834b3ea6f1f283b389af29"
    },
    "customer": {
      "correlationID": "9134e286-6f71-427a-bf00-241681624586",
      "email": "email1@example.com",
      "name": "Loma",
      "phone": "+5511999999999",
      "taxID": {
        "taxID": "47043622050",
        "type": "BR:CPF"
      }
    },
    "payer": {
      "correlationID": "9134e286-6f71-427a-bf00-241681624586",
      "email": "email1@example.com",
      "name": "Loma",
      "phone": "+5511999999999",
      "taxID": {
        "taxID": "47043622050",
        "type": "BR:CPF"
      }
    },
    "time": "2021-03-12T12:44:09.269Z",
    "value": 1,
    "transactionID": "ea83401ed4834b3ea6f1f283b389af29",
    "infoPagador": "Woovi testing"
  },
  "company": {
    "id": "624f46f9e93f9f521c8308d7",
    "name": "Pizzaria do José",
    "taxID": "4722767300014"
  },
  "account": {
    "clientId": "ZOJ64B9B-ZM1W-89MI-4UCI-OP2LVIU6NY75"
  }
}
```

---

## Payload de Reembolso

## Payloads de Reembolso

Os webhooks do tipo `Reembolso Recebido` enviam objetos com os seguintes campos no seu payload:

- `event`: O tipo de Evento realizado
- `charge`: A cobrança, se existir, que a transação original desse reembolso pertence
- `pixQrCode`: O QR Code, se existir, que a transação original desse reembolso pertence
- `pix`: Objeto com detalhes do reembolso Pix
- `company`: Empresa a que a Transação pertence
- `account`: Detalhes da conta que a Transação pertence

Você pode identificar se o tipo de Reembolso é **Parcial** ou **Completo** pelo campo `partial` dentro do objeto `pix`

Note que o objeto `pix` pertence ao Reembolso em si, não a transação original.

## Exemplo

```json
{
  "event": "OPENPIX:TRANSACTION_REFUND_RECEIVED",
  "charge": {
    "customer": null,
    "value": 151,
    "comment": "",
    "identifier": "c37368e176894eea9b35fe0ea8ef2b7d",
    "transactionID": "c37368e176894eea9b35fe0ea8ef2b7d",
    "status": "COMPLETED",
    "additionalInfo": [],
    "giftbackAppliedValue": 0,
    "discount": 0,
    "valueWithDiscount": 151,
    "createdAt": "2022-09-16T13:57:26.300Z",
    "correlationID": "5e1f0740-4a18-4030-a5a7-686d3d8ec419",
    "paymentLinkID": "47478762-f0fb-4996-a972-519edae95681",
    "updatedAt": "2022-09-16T14:02:59.159Z",
    "expiresIn": 2591999,
    "pixKey": "c4249323-b4ca-43f2-8139-874baab09b93",
    "brCode": "00020101021226990014br.gov.bcb.pix2577pix-h.bpp.com.br/23114447/qrs1/v2/01jAVrYybMRhanrjbpgCDIxFrHxa7zdBSdcIinjmXbp52040000530398654041.515802BR5912Your_Company6009Sao_Paulo62290525c37368e176894eea9b35fe0ea63047E32",
    "paymentLinkUrl": "http://localhost:8777/pay/47478762-f0fb-4996-a972-519edae95681",
    "qrCodeImage": "https://api.woovi.com/openpix/openpix/charge/brcode/image/47478762-f0fb-4996-a972-519edae95681.png",
    "globalID": "Q2hhcmdlOjYzMjQ4MGM4MDIxM2I4YTA2Y2FlYjAxZg=="
  },
  "pixQrCode": null,
  "pix": {
    "customer": null,
    "charge": {
      "customer": null,
      "value": 151,
      "comment": "",
      "identifier": "c37368e176894eea9b35fe0ea8ef2b7d",
      "transactionID": "c37368e176894eea9b35fe0ea8ef2b7d",
      "status": "COMPLETED",
      "additionalInfo": [],
      "giftbackAppliedValue": 0,
      "discount": 0,
      "valueWithDiscount": 151,
      "createdAt": "2022-09-16T13:57:26.300Z",
      "correlationID": "5e1f0740-4a18-4030-a5a7-686d3d8ec419",
      "paymentLinkID": "47478762-f0fb-4996-a972-519edae95681",
      "updatedAt": "2022-09-16T14:02:59.159Z",
      "expiresIn": 2591999,
      "brCode": "00020101021226990014br.gov.bcb.pix2577pix-h.bpp.com.br/23114447/qrs1/v2/01jAVrYybMRhanrjbpgCDIxFrHxa7zdBSdcIinjmXbp52040000530398654041.515802BR5912Your_Company6009Sao_Paulo62290525c37368e176894eea9b35fe0ea63047E32",
      "paymentLinkUrl": "http://localhost:8777/pay/47478762-f0fb-4996-a972-519edae95681",
      "qrCodeImage": "https://api.woovi.com/openpix/openpix/charge/brcode/image/47478762-f0fb-4996-a972-519edae95681.png",
      "globalID": "Q2hhcmdlOjYzMjQ4MGM4MDIxM2I4YTA2Y2FlYjAxZg=="
    },
    "value": 151,
    "time": "2022-09-16T14:15:39.597Z",
    "endToEndId": "D23114447202209161415HPf0GiKMeR4",
    "createdAt": "2022-09-16T14:15:41.909Z",
    "pixKey": "c4249323-b4ca-43f2-8139-874baab09b93",
    "partial": false,
    "globalID": "UGl4VHJhbnNhY3Rpb246NjMyNDg1MGQ3OTE4NTgxZDczOGNkZjg0"
  },
  "company": {
    "id": "61240394529a1b71ee70d855",
    "name": "CASAS AMERICANAS",
    "taxID": "05460236000124"
  },
  "account": {
    "clientId": "71034651-61E0-1FAD-4688-D967F095CFBF"
  },
  "refunds": []
}
```

---

## Payload de Confirmação de Reembolso Pix Recebido

## Payloads de Reembolso

Os webhooks do tipo `PIX_TRANSACTION_REFUND_RECEIVED_CONFIRMED` enviam objetos com os seguintes campos no seu payload:

- `event`: O tipo de Evento realizado
- `refundTransaction`: Detalhes da transação de reembolso enviada
- `originalTransaction`: Detalhes da transação original que está sendo reembolsada
- `company`: Empresa a que a Transação pertence
- `account`: Detalhes da conta que a Transação pertence

## Exemplo

```json
{
  "event": "PIX_TRANSACTION_REFUND_RECEIVED_CONFIRMED",
  "refundTransaction": {
    "value": 10001,
    "time": "2025-08-14T21:31:49.755Z",
    "endToEndId": "D548114172025081421318FbVaF2LTWr",
    "status": "CONFIRMED",
    "type": "REFUND",
    "debitParty": {
      "pixKey": {
        "pixKey": "swap.homolog@contaswap.com",
        "type": "EMAIL"
      },
      "account": {
        "branch": "0001",
        "account": "00000000000000000221",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "54811417",
        "name": "WOOVI IP LTDA."
      },
      "holder": {
        "taxID": {
          "taxID": "47960950000121",
          "type": "BR:CNPJ"
        }
      }
    },
    "creditParty": {
      "account": {
        "branch": "001",
        "account": "73519",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "31680151",
        "name": "SWAP IP S.A."
      },
      "holder": {
        "name": "Sapataria Xiq Bom",
        "taxID": {
          "taxID": "06888687000120",
          "type": "BR:CNPJ"
        }
      }
    },
    "createdAt": "2025-08-14T21:31:49.821Z",
    "partial": false,
    "globalID": "UGl4VHJhbnNhY3Rpb246Njg5ZTU1YzVkNDEzYTJhYzZmMWRlMDcz"
  },
  "originalTransaction": {
    "payer": {
      "name": "Sapataria Xiq Bom",
      "taxID": {
        "taxID": "06888687000120",
        "type": "BR:CNPJ"
      },
      "correlationID": "862adf9d-aae6-407e-86ba-5948d87ed591"
    },
    "value": 10001,
    "time": "2025-08-14T15:43:33.000Z",
    "endToEndId": "E31680151202508141543GVL7OCT44VU",
    "status": "CONFIRMED",
    "type": "PAYMENT",
    "debitParty": {
      "account": {
        "branch": "001",
        "account": "73519",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "31680151",
        "name": "SWAP IP S.A."
      },
      "holder": {
        "name": "Sapataria Xiq Bom",
        "taxID": {
          "taxID": "06888687000120",
          "type": "BR:CNPJ"
        }
      }
    },
    "creditParty": {
      "pixKey": {
        "pixKey": "swap.homolog@contaswap.com",
        "type": "EMAIL"
      },
      "account": {
        "branch": "0001",
        "account": "00000000000000000221",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "54811417",
        "name": "WOOVI IP LTDA."
      },
      "holder": {
        "taxID": {
          "taxID": "47960950000121",
          "type": "BR:CNPJ"
        }
      }
    },
    "createdAt": "2025-08-14T15:43:33.396Z",
    "globalID": "UGl4VHJhbnNhY3Rpb246Njg5ZTA0MjVmMzE2MmMzZjE4MzVmMmM5"
  },
  "company": {
    "id": "6762e45c55eb2e0a3b3cbc44",
    "name": "MAGAZINE LUIZA S/A",
    "nameFriendly": "MAGAZINE LUIZA",
    "correlationID": "f7b21ff8-a0b0-4e6a-929c-c5c483174578"
  },
  "account": {
    "id": "67a4bb7a7c9720a18b10648a",
    "name": "Conta 8084",
    "status": "OPEN",
    "code": "54811417",
    "branch": "0001",
    "account": "00000000000000000221"
  }
}
```

---

## Payload de Rejeição de Reembolso Pix Recebido

## Payloads de Reembolso

Os webhooks do tipo `PIX_TRANSACTION_REFUND_RECEIVED_REJECTED` enviam objetos com os seguintes campos no seu payload:

- `event`: O tipo de Evento realizado
- `refundTransaction`: Detalhes da transação de reembolso enviada
- `originalTransaction`: Detalhes da transação original que está sendo reembolsada
- `company`: Empresa a que a Transação pertence
- `account`: Detalhes da conta que a Transação pertence
- `error`: Detalhes do motivo pela qual o Estorno foi rejeitado - [Códigos de erro de pagamento](/docs/flows/error-codes-payment)

## Exemplo

```json
{
  "event": "PIX_TRANSACTION_REFUND_RECEIVED_REJECTED",
  "refundTransaction": {
    "value": 11111,
    "time": "2025-09-02T19:26:14.000Z",
    "endToEndId": "D316801512025090219260S5HQTVTM3L",
    "status": "REJECTED",
    "type": "REFUND",
    "debitParty": {
      "pixKey": {
        "pixKey": "+5518996879998",
        "type": "PHONE"
      },
      "account": {
        "branch": "001",
        "account": "73519",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "31680151",
        "name": "SWAP IP S.A."
      },
      "holder": {
        "taxID": {
          "taxID": "06888687000120",
          "type": "BR:CNPJ"
        }
      }
    },
    "creditParty": {
      "account": {
        "branch": "001",
        "account": "00000000000000000221",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "54811417",
        "name": "WOOVI IP LTDA."
      },
      "holder": {
        "name": "MAGAZINE LUIZA SA",
        "taxID": {
          "taxID": "47960950000121",
          "type": "BR:CNPJ"
        }
      }
    },
    "createdAt": "2025-09-02T19:26:14.754Z",
    "partial": false,
    "globalID": "UGl4VHJhbnNhY3Rpb246NjhiNzQ0ZDZlNjRhMmIwYzQzNTUyNTlj"
  },
  "originalTransaction": {
    "value": 11111,
    "time": "2025-09-01T22:02:51.018Z",
    "endToEndId": "E54811417202509012202ylo4UjIp2hq",
    "status": "CONFIRMED",
    "type": "WITHDRAW",
    "debitParty": {
      "account": {
        "branch": "0001",
        "account": "00000000000000000221",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "54811417",
        "name": "WOOVI IP LTDA",
        "code": "54811417"
      },
      "holder": {
        "name": "MAGAZINE LUIZA S/A",
        "nameFriendly": "MAGAZINE LUIZA",
        "taxID": {
          "taxID": "47960950000121",
          "type": "BR:CNPJ"
        }
      }
    },
    "creditParty": {
      "pixKey": {
        "pixKey": "+5518996879998",
        "type": "PHONE"
      },
      "account": {
        "branch": "001",
        "account": "73519",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "31680151",
        "name": "SWAP IP S.A."
      },
      "holder": {
        "name": "Sapataria Xiq Bom LTDA",
        "nameFriendly": "Sapataria Xiq Bom LTDA",
        "taxID": {
          "taxID": "06888687000120",
          "type": "BR:CNPJ"
        }
      }
    },
    "createdAt": "2025-09-01T22:02:51.087Z",
    "globalID": "UGl4VHJhbnNhY3Rpb246NjhiNjE4MGIyNDk4YjdkM2MyMDA0MDVl"
  },
  "company": {
    "id": "6762e45c55eb2e0a3b3cbc44",
    "name": "MAGAZINE LUIZA S/A",
    "nameFriendly": "MAGAZINE LUIZA",
    "correlationID": "f7b21ff8-a0b0-4e6a-929c-c5c483174578"
  },
  "account": {
    "id": "67a4bb7a7c9720a18b10648a",
    "name": "Conta 8084",
    "status": "OPEN",
    "code": "54811417",
    "branch": "0001",
    "account": "00000000000000000221"
  },
  "error": "AC06 - Conta bloqueada do Pix"
}
```

---

## Payload de Confirmação de Reembolso Pix Enviado

## Payloads de Reembolso

Os webhooks do tipo `PIX_TRANSACTION_REFUND_SENT_CONFIRMED` enviam objetos com os seguintes campos no seu payload:

- `event`: O tipo de Evento realizado
- `refundTransaction`: Detalhes da transação de reembolso enviada
- `originalTransaction`: Detalhes da transação original que está sendo reembolsada
- `company`: Empresa a que a Transação pertence
- `account`: Detalhes da conta que a Transação pertence

## Exemplo

```json
{
  "event": "PIX_TRANSACTION_REFUND_SENT_CONFIRMED",
  "refundTransaction": {
    "value": 10001,
    "time": "2025-08-14T21:31:49.755Z",
    "endToEndId": "D548114172025081421318FbVaF2LTWr",
    "status": "CONFIRMED",
    "type": "REFUND",
    "debitParty": {
      "pixKey": {
        "pixKey": "swap.homolog@contaswap.com",
        "type": "EMAIL"
      },
      "account": {
        "branch": "0001",
        "account": "00000000000000000221",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "54811417",
        "name": "WOOVI IP LTDA."
      },
      "holder": {
        "taxID": {
          "taxID": "47960950000121",
          "type": "BR:CNPJ"
        }
      }
    },
    "creditParty": {
      "account": {
        "branch": "001",
        "account": "73519",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "31680151",
        "name": "SWAP IP S.A."
      },
      "holder": {
        "name": "Sapataria Xiq Bom",
        "taxID": {
          "taxID": "06888687000120",
          "type": "BR:CNPJ"
        }
      }
    },
    "createdAt": "2025-08-14T21:31:49.821Z",
    "partial": false,
    "globalID": "UGl4VHJhbnNhY3Rpb246Njg5ZTU1YzVkNDEzYTJhYzZmMWRlMDcz"
  },
  "originalTransaction": {
    "payer": {
      "name": "Sapataria Xiq Bom",
      "taxID": {
        "taxID": "06888687000120",
        "type": "BR:CNPJ"
      },
      "correlationID": "862adf9d-aae6-407e-86ba-5948d87ed591"
    },
    "value": 10001,
    "time": "2025-08-14T15:43:33.000Z",
    "endToEndId": "E31680151202508141543GVL7OCT44VU",
    "status": "CONFIRMED",
    "type": "PAYMENT",
    "debitParty": {
      "account": {
        "branch": "001",
        "account": "73519",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "31680151",
        "name": "SWAP IP S.A."
      },
      "holder": {
        "name": "Sapataria Xiq Bom",
        "taxID": {
          "taxID": "06888687000120",
          "type": "BR:CNPJ"
        }
      }
    },
    "creditParty": {
      "pixKey": {
        "pixKey": "swap.homolog@contaswap.com",
        "type": "EMAIL"
      },
      "account": {
        "branch": "0001",
        "account": "00000000000000000221",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "54811417",
        "name": "WOOVI IP LTDA."
      },
      "holder": {
        "taxID": {
          "taxID": "47960950000121",
          "type": "BR:CNPJ"
        }
      }
    },
    "createdAt": "2025-08-14T15:43:33.396Z",
    "globalID": "UGl4VHJhbnNhY3Rpb246Njg5ZTA0MjVmMzE2MmMzZjE4MzVmMmM5"
  },
  "company": {
    "id": "6762e45c55eb2e0a3b3cbc44",
    "name": "MAGAZINE LUIZA S/A",
    "nameFriendly": "MAGAZINE LUIZA",
    "correlationID": "f7b21ff8-a0b0-4e6a-929c-c5c483174578"
  },
  "account": {
    "id": "67a4bb7a7c9720a18b10648a",
    "name": "Conta 8084",
    "status": "OPEN",
    "code": "54811417",
    "branch": "0001",
    "account": "00000000000000000221"
  }
}
```

---

## Payload de Rejeição de Reembolso Pix Enviado

## Payloads de Reembolso

Os webhooks do tipo `PIX_TRANSACTION_REFUND_SENT_REJECTED` enviam objetos com os seguintes campos no seu payload:

- `event`: O tipo de Evento realizado
- `refundTransaction`: Detalhes da transação de reembolso enviada
- `originalTransaction`: Detalhes da transação original que está sendo reembolsada
- `company`: Empresa a que a Transação pertence
- `account`: Detalhes da conta que a Transação pertence
- `error`: Detalhes do motivo pela qual o Estorno foi rejeitado - [Códigos de erro de pagamento](/docs/flows/error-codes-payment)

## Exemplo

```json
{
  "event": "PIX_TRANSACTION_REFUND_SENT_REJECTED",
  "refundTransaction": {
    "value": 10001,
    "time": "2025-08-22T16:47:46.719Z",
    "endToEndId": "D54811417202508221647qjsBFT3ArbQ",
    "infoPagador": "test",
    "status": "REJECTED",
    "type": "REFUND",
    "debitParty": {
      "pixKey": {
        "pixKey": "fd569fbc-a0cb-410a-9ec1-45bf3c869407",
        "type": "RANDOM"
      },
      "account": {
        "branch": "0001",
        "account": "00000000000000000221",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "54811417",
        "name": "WOOVI IP LTDA."
      },
      "holder": {
        "taxID": {
          "taxID": "47960950000121",
          "type": "BR:CNPJ"
        }
      }
    },
    "creditParty": {
      "account": {
        "branch": "001",
        "account": "73519",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "31680151",
        "name": "SWAP IP S.A."
      },
      "holder": {
        "name": "Sapataria Xiq Bom",
        "taxID": {
          "taxID": "06888687000120",
          "type": "BR:CNPJ"
        }
      }
    },
    "createdAt": "2025-08-22T16:47:46.846Z",
    "partial": false,
    "globalID": "UGl4VHJhbnNhY3Rpb246NjhhODlmMzI4Mjc1MzViODY1ODUyMTlm"
  },
  "originalTransaction": {
    "payer": {
      "name": "Sapataria Xiq Bom",
      "taxID": {
        "taxID": "06888687000120",
        "type": "BR:CNPJ"
      },
      "correlationID": "862adf9d-aae6-407e-86ba-5948d87ed591"
    },
    "value": 10001,
    "time": "2025-08-22T16:30:42.000Z",
    "endToEndId": "E31680151202508221630EG1PB3VBC54",
    "status": "CONFIRMED",
    "type": "PAYMENT",
    "debitParty": {
      "account": {
        "branch": "001",
        "account": "73519",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "31680151",
        "name": "SWAP IP S.A."
      },
      "holder": {
        "name": "Sapataria Xiq Bom",
        "taxID": {
          "taxID": "06888687000120",
          "type": "BR:CNPJ"
        }
      }
    },
    "creditParty": {
      "pixKey": {
        "pixKey": "fd569fbc-a0cb-410a-9ec1-45bf3c869407",
        "type": "RANDOM"
      },
      "account": {
        "branch": "0001",
        "account": "00000000000000000221",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "54811417",
        "name": "WOOVI IP LTDA."
      },
      "holder": {
        "taxID": {
          "taxID": "47960950000121",
          "type": "BR:CNPJ"
        }
      }
    },
    "createdAt": "2025-08-22T16:30:42.970Z",
    "globalID": "UGl4VHJhbnNhY3Rpb246NjhhODliMzJlNzY0NDc3YTE1MGNkMzI1"
  },
  "company": {
    "id": "6762e45c55eb2e0a3b3cbc44",
    "name": "MAGAZINE LUIZA S/A",
    "nameFriendly": "MAGAZINE LUIZA",
    "correlationID": "f7b21ff8-a0b0-4e6a-929c-c5c483174578"
  },
  "account": {
    "id": "67a4bb7a7c9720a18b10648a",
    "name": "Conta 8084",
    "status": "OPEN",
    "code": "54811417",
    "branch": "0001",
    "account": "00000000000000000221"
  },
  "error": "ED05 - Pagamento rejeitado pelo PSP do recebedor"
}
```

---

## Payload de transação recebida


Os webhooks do tipo `Transação recebida` enviam objetos com os seguintes campos no seu payload:

- `event`: O tipo de evento realizado que neste caso seria `OPENPIX:CHARGE_EXPIRED`.
- `charge`: A cobrança que foi expirada.
- `type` : Dependendo da transação elas podem vir seguintes tipos: `DYNAMIC` ,`STATIC` ou `PAYMENT`. Onde `PAYMENT` seria o [pix avulso](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/o-que-e-um-pix-avulso). 
- `company`: Empresa a que a cobrança pertence.

## Exemplo

```json
{
  "event": "OPENPIX:TRANSACTION_RECEIVED",
  "charge": null,
  "pixQrCode": null,
  "pix": {
    "debitParty": {
      "account": {
        "branch": "1",
        "account": "123456789",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "12345678",
        "name": "BANCO PAGAMENTOS - IP"
      },
      "holder": {
        "taxID": {
          "taxID": "12345678901",
          "type": "BR:CPF"
        },
        "name": "Name Sobrenome"
      }
    },
    "creditParty": {
      "pixKey": {
        "pixKey": "1ed81f30-1654-5eaf3-b911-074449bad07e",
        "type": "RANDOM"
      },
      "account": {
        "branch": "1",
        "account": "1234567",
        "accountType": "TRAN"
      },
      "psp": {
        "id": "54811417",
        "name": "WOOVI IP LTDA."
      },
      "holder": {
        "taxID": {
          "taxID": "01123456000199",
          "type": "BR:CNPJ"
        }
      }
    },
    "payer": {
      "name": "Nome Sobrenome",
      "email": "email@email.com",
      "phone": "+5500988776655",
      "taxID": {
        "taxID": "98765432100",
        "type": "BR:CPF"
      },
      "correlationID": "2566b5bd-2e1a-463d-b21c-ec7717cf2df4"
    },
    "value": 200,
    "time": "2025-09-23T18:10:56.000Z",
    "endToEndId": "E18236120202509231810s56149dd987",
    "fee": 80,
    "status": "CONFIRMED",
    "type": "PAYMENT",
    "createdAt": "2025-09-23T18:10:56.657Z",
    "pixKey": "617126ef-3c13-4a4e-a8a4-05de07f3d8af",
    "globalID": "UGl4VHJhbnNhY3Rdf246NjhkMmUyYjB5OGI5ZjZkODYwNDVjMjg2"
  },
  "company": {
    "id": "66f98ce2acbb5dffa956ff60",
    "name": "company name",
    "taxID": "12123456000199"
  },
  "account": {
    "accountId": "68b999668bdbfg18agcca244",
    "branch": "0001",
    "account": "000000000000012345678",
    "taxID": "00123456000198"
  },
  "refunds": []
}
```

---

## Verificando se o Webhook está chamando corretamente o endpoint configurado

1. Acesse `API/Plugins` via sidebar menu.

![1](./__assets__/webhook-check-work-1.png)

2. Acesse a aba `API/Plugins`.

![2](./__assets__/webhook-check-work-2.png)

3. Acesse o detalhe do Webhook que você deseja verificar se está funcionando corretamente, no meu caso o Webhook que quero verificar possui o nome de `bot conversa`.

![3](./__assets__/webhook-check-work-3.png)

4. Já dentro do detalhe do Webhook, acesse a aba `Logs`.

![4](./__assets__/webhook-check-work-4.png)

Neste cenário, todas as requisições feitas pelo Webhook ao endpoint configurado retornaram o código de status 200, indicando sucesso (Saiba mais sobre códigos de status nesse [link](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Status)). No entanto, caso a chamada resulte em outros códigos de status, essas informações também serão registradas no log.

Por exemplo, se ocorreu uma chamada para o mesmo Webhook que resultou em um código 404 (Not Found), nosso serviço indicará que essa chamada não foi bem-sucedida, apresentando também o código de erro correspondente.

![5](./__assets__/webhook-check-work-5.png)

Outro ponto importante é que também salvamos o corpo da requisição (Request Body) enviado para o endpoint, assim como o corpo da resposta (Response Body) recebido. Para consultar essas informações, basta clicar no log correspondente, o que abrirá uma janela exibindo todos esses detalhes. Veja um exemplo:

![6](./__assets__/webhook-check-work-6.png)

---

## Criando um webhook para interceptar um Pix e chamar uma API

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Pela Woovi é possível criar webhooks para interceptar quando um pix for realizado. Hoje, há duas maneiras de realizar a criação do mesmo: via plataforma ou API.

Neste tutorial iremos descrever como criar um webhook para informar o recebimento de um novo Pix e devolvê-lo em uma API registrada.

Para criar um webhook via plataforma basta seguir os passos abaixo:

### Step 1 - Ajustes

Vá até o Menu Administrador e procure por `API/Plugins`.

![AdminPanel](/img/apis/admin-panel.png)

Clique em `Novo Webhook`.

![NewWebhook](/img/webhook/new-webhook.png)

Após o clique será aberta a tela de crição para um novo webhook:

![CreateWebhook](/img/webhook/create-new-webhook.png)

Campos:

- **Nome** - nome do webhook.
- **Ativo** - se o webhook esta ativo ou inativo.
- **Evento** - evento a ser ouvido (exemplo: transação pix recebida).
- **URL** - o endpoint na qual o webhook irá chamar.
  - Observação: É importante salientar, que nosso webhook sempre fará uma requisição `POST` no seu endpoint.
- **Ação** existem dois tipos de ação: chamar api e enviar email. Dependendo de qual decidir será disponibilizado os campos paramêtros obrigatórios.

#### Ação

Ao escolher um tipo de ação, de acordo com a escolhida será obrigatório informar os paramêtros necessários para tal.

![CreateWebhook](/img/webhook/create-new-webhook-api.png)

Campos:

- url: obrigatório, necessário ser uma url válida e disponível para um teste de chamada no momento de salvar.
- authorization: opcional

![CreateWebhookEmail](/img/webhook/create-new-webhook-email.png)

Campos:

- email: obrigatório

[Exemplos de payload do Webhook](/docs/category/exemplos)

---

## Adicionando um usuário para ter acesso as funcionalidades de API e Webhook

Pela Woovi é possível criar webhooks para interceptar quando um pix for realizado. Hoje, há duas maneiras de realizar a criação do mesmo: via plataforma ou API.

Para adicionar um novo usuário através da plataforma para ter acesso as funcionalidades de API e Webhook siga o seguinte passo a passo:

### Step 1 - Crie um novo usuário

- Procure no menu de administrador por `permissões`

![AdminPanel](/img/webhook/menu-admin-permissions.png)

- Clique em `Adicionar usuário`

![Add user](/img/webhook/add-user.png)

- Preencha todos os campos e clique em salvar

![Add user form](/img/webhook/add-user-form.png)

### Step 2 - Adicione a permissão `OPEN_PIX::API_WEBHOOK` para dar acesso ao usuário

- Depois de criado você irá nos detalhes do respectivo usuário e clique em `Permissões`

![User list](/img/webhook/user-list.png)

![User detail](/img/webhook/user-detail.png)

- Selecione a permissão `OPEN_PIX::API_WEBHOOK`

![Webhook role](/img/webhook/webhook-role.png)

## Step 3 - Visão do usuário com permissão `OPEN_PIX::API_WEBHOOK`

- Depois de adicionado a permissão ao usuário ele terá acesso ao menu administrador com `API/Plugins` onde será possível criar novos webhooks

![Menu webhook](/img/webhook/menu-webhook.png)

---

## Validando Webhook payload usando HMAC-SHA1 (Depreciado)

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Validação HMAC (Depreciado)

A validação HMAC é o **Primeiro método** para validar webhooks da Woovi.

## Qual a diferença entre X-OpenPix-Signature (HMAC) e x-webhook-signature?

Existem dois métodos de validação de webhook disponíveis:

| Método | Header | O que valida | Chave utilizada |
|--------|--------|--------------|-----------------|
| **HMAC** | `X-OpenPix-Signature` | Valida que o webhook veio da **sua configuração específica de webhook** | Secret key do seu webhook |
| **x-webhook-signature** | `x-webhook-signature` | Valida que o webhook veio da **Woovi** (valida o remetente) | Chave pública da Woovi |

# Como consultar o Secret Key do HMAC?

Vá até o Menu Administrador e procure por `API/Plugins` e clique no Webhook que você gostaria de consultar o Secret Key do HMAC.

![WebhookDetail](/img/webhook/webhook-hmac.png)

# Como validar o HMAC Signature?

Toda request do Webhook possui o header `X-OpenPix-Signature` que é a assinatura gerada com a **secret key do seu Webhook** e o payload do Webhook.
Ao receber o header você pode validar se o HMAC é válido e dar continuidade no fluxo do Webhook.

Exemplo: `'X-OpenPix-Signature': 'jgR2XF0PKDiAwHP1s+TryvxMySQ='`

## Exemplo de validação

```php
  <?php 
    $headers['X-OpenPix-Signature'] = 'jgR2XF0PKDiAwHP1s+TryvxMySQ='; // vira da chamada do webhook
    $body = '{"data_criacao":"2021-08-10T20:32:14.429Z","evento":"teste_webhook","event":"OPENPIX:CHARGE_COMPLETED"}'; // vira da chamada do webhook

    $secretKeyOnOpenpixPlatform = 'hmac-secret-key'; // secret key da chave de acesso do OpenPix

    $algorithm = 'sha1'; // algoritmo de hash

    $hmac = base64_encode(hash_hmac($algorithm, $body, $secretKeyOnOpenpixPlatform, true));

    if($hmac === $headers['X-OpenPix-Signature']) {
        echo 'Valid HMAC';
    } else {
        echo 'Invalid HMAC';
    }
  ?>

```

```jsx

  const createHmac = require('crypto').createHmac;

  const hmacCalculateSignature = (
    key,
    body,
    encoding,
  ) => createHmac('sha1', key).update(body).digest(encoding);

  const hmacVerifySignature = () => {

    const openpixSignatureHeader = 'jgR2XF0PKDiAwHP1s+TryvxMySQ='; // vem da chamada do webhook

    const body = '{"data_criacao":"2021-08-10T20:32:14.429Z","evento":"teste_webhook","event":"OPENPIX:CHARGE_COMPLETED"}'; // vem da chamada do webhook

    const key = 'hmac-secret-key'; // secret key da chave de acesso do OpenPix

    const signature = hmacCalculateSignature(key, body, 'base64');

    if(signature === openpixSignatureHeader) {
      console.log('valid HMAC');
    }
  };

  hmacVerifySignature();
  
```

  ```bash

  echo -n '{"data_criacao":"2021-08-10T20:32:14.429Z","evento":"teste_webhook","event":"OPENPIX:CHARGE_COMPLETED"}' | openssl dgst -sha1 -hmac "hmac-secret-key" -binary | base64

  ```

:::info

O campo `event` enviado junto ao payload do webhook tem seu valor conforme o tipo de evento que você escolheu no momento em que criou o webhook.
Para saber mais sobre os tipos de eventos, acesse a [documentação de eventos](../webhook-events-type.md).

:::

Nesse link temos um exemplo de validação do HMAC usando JavaScript
[WebhookPost](https://github.com/Open-Pix/node-backend-integration/blob/master/src/webhook/webhookPost.ts)

---

## Webhook IPs

Esta página lista os endereços IP que a Woovi usa para enviar webhooks.

**Para obter uma lista dos IPs que a Woovi Usa para enviar Webhooks basta entrar em contato com o time de suporte diretamente pelo chat da plataforma**

Você pode usar a lista de IPs para adicionar regras no seu firewall e restrigir os seus Webhooks para somente aceitarem requests desses IPs

---

## Buscando a chave pública da Woovi via API

A Woovi assina todo webhook que envia. A chave pública que verifica essa assinatura
está publicada num endpoint aberto, para você buscá-la programaticamente em vez de
deixá-la fixa no seu código:

```
GET https://api.woovi.com/api/v1/webhook/public-keys
```

O mesmo endpoint responde em todos os domínios da API:

| Ambiente | URL |
|----------|-----|
| Produção (Woovi) | `https://api.woovi.com/api/v1/webhook/public-keys` |
| Produção (OpenPix) | `https://api.openpix.com.br/api/v1/webhook/public-keys` |
| Sandbox | `https://api.woovi-sandbox.com/api/v1/webhook/public-keys` |

**Não é preciso autenticação.** A chave é pública por definição, e quem recebe webhook
normalmente valida a assinatura num contexto que não tem o AppID em mãos.

## A resposta

```json
{
  "public_keys": [
    {
      "key_identifier": "9dce618794f8986c603915a51b7029126c260e5cfdb2aa47e131d837fd62311c",
      "is_current": true,
      "key": "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC/+NtIkjzevvqD+I3MMv3bLXDt\npvxBjY4BsRrSdca3rtAwMcRYYvxSnd7jagVLpctMiOxQO8ieUCKLSWHpsMAjO/zZ\nWMKbqoG8MNpi/u3fp6zz0mcHCOSqYsPUUG19buW8bis5ZZ2IZgBObWSpTvJ0cnj6\nHKBAA82Jln+lGwS1MwIDAQAB\n-----END PUBLIC KEY-----\n"
    }
  ]
}
```

| Campo | O que é |
|-------|---------|
| `key` | A chave pública em PEM, pronta para uso |
| `key_identifier` | SHA-256 da chave em DER — identifica a chave de forma estável |
| `is_current` | `true` na chave que está assinando os webhooks agora |

## Por que é uma lista

Hoje há uma chave só. A resposta é uma lista para que a chave possa ser trocada sem
quebrar sua integração: durante uma rotação publicamos a chave antiga e a nova ao mesmo
tempo, e `is_current` indica qual está assinando.

**Aceite qualquer chave da lista ao verificar.** Se você aceitar apenas a `is_current`,
volta a ter o mesmo problema da chave fixa no código — os webhooks assinados com a chave
anterior, ainda em trânsito ou em retry, falham na validação.

## Como a assinatura funciona

Todo webhook chega com o header `x-webhook-signature`. Ele é:

```
base64( RSA-SHA256( corpo bruto da request, chave privada da Woovi ) )
```

Dois detalhes que costumam derrubar a validação:

1. **Assine o corpo bruto.** Verifique antes de fazer o parse do JSON. Se você fizer
   `JSON.parse` e depois `JSON.stringify` para reconstruir o corpo, a ordem das chaves e
   o espaçamento mudam, os bytes mudam, e a assinatura não bate mais. A maioria dos
   frameworks tem uma forma de guardar o corpo cru (`express.json({ verify })`,
   `php://input`, etc.).
2. **A assinatura vem em Base64**, não em hexadecimal.

## Exemplo

Buscando a chave e validando o webhook:

```js
import crypto from 'crypto';

// Busque uma vez e mantenha em cache — a resposta traz Cache-Control de 1 hora.
// Não busque a cada webhook recebido.
let cachedKeys = null;

const getPublicKeys = async () => {
  if (cachedKeys) return cachedKeys;

  const response = await fetch('https://api.woovi.com/api/v1/webhook/public-keys');
  const { public_keys } = await response.json();

  cachedKeys = public_keys.map((entry) => entry.key);

  return cachedKeys;
};

// `rawBody` precisa ser o corpo exatamente como chegou (Buffer ou string),
// nunca o objeto já parseado e reserializado.
export const verifyWebhook = async ({ rawBody, signature }) => {
  const keys = await getPublicKeys();

  return keys.some((publicKey) => {
    const verify = crypto.createVerify('sha256');

    verify.write(Buffer.from(rawBody));
    verify.end();

    return verify.verify(publicKey, signature, 'base64');
  });
};
```

Recebendo no Express, preservando o corpo bruto:

```js
import express from 'express';

const app = express();

app.use(
  express.json({
    verify: (req, res, buf) => {
      req.rawBody = buf;
    },
  }),
);

app.post('/webhook', async (req, res) => {
  const isValid = await verifyWebhook({
    rawBody: req.rawBody,
    signature: req.headers['x-webhook-signature'],
  });

  if (!isValid) {
    return res.status(401).send('assinatura inválida');
  }

  // a partir daqui o payload é confiável
  res.status(200).send('ok');
});
```

## Cache

A resposta vem com `Cache-Control: public, max-age=3600`. Busque a chave na inicialização
da aplicação ou em cache com TTL de 1 hora — não faça uma request a este endpoint a cada
webhook recebido.

Se a busca falhar, prefira continuar usando a chave que você já tem em cache a rejeitar o
webhook: uma indisponibilidade temporária deste endpoint não significa que o webhook é
inválido.

## E o HMAC?

São mecanismos diferentes e complementares:

| Método | Header | O que prova |
|--------|--------|-------------|
| Assinatura | `x-webhook-signature` | Que o webhook veio **da Woovi** — chave pública da Woovi |
| HMAC | `x-openpix-signature` | Que o webhook veio **da sua configuração específica de webhook** — secret que você definiu |

A assinatura é o método recomendado. Veja
[Validando Webhook payload usando x-webhook-signature](./webhook-signature-validation)
para mais exemplos, e [Webhook IPs](./webhook-ips) para restringir por origem no firewall.

---

## Validando Webhook payload usando x-webhook-signature (Recomendado)

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Como validar o Webhook Signature? (Recomendado)

Toda request do Webhook possui o header `x-webhook-signature` que é a assinatura gerada com a **chave privada da Woovi** e o payload do Webhook.

## Qual a diferença entre x-webhook-signature e X-OpenPix-Signature (HMAC)?

Existem dois métodos de validação de webhook disponíveis:

| Método | Header | O que valida | Chave utilizada |
|--------|--------|--------------|-----------------|
| **x-webhook-signature** | `x-webhook-signature` | Valida que o webhook veio da **Woovi** (valida o remetente) | Chave pública da Woovi |
| **HMAC** | `X-OpenPix-Signature` | Valida que o webhook veio da **sua configuração específica de webhook** | Secret key do seu webhook |

## Chave Pública da Woovi

:::tip Obtenha a chave pública via API
A chave também está disponível num endpoint aberto:
[GET /api/v1/webhook/public-keys](/api#tag/webhook/GET/api/v1/webhook/public-keys).

Buscar a chave em vez de deixá-la fixa no código é o caminho recomendado: quando a chave
for trocada, sua integração acompanha a troca sozinha. Veja
[Buscando a chave pública da Woovi via API](./webhook-public-keys).
:::

```
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC/+NtIkjzevvqD+I3MMv3bLXDt
pvxBjY4BsRrSdca3rtAwMcRYYvxSnd7jagVLpctMiOxQO8ieUCKLSWHpsMAjO/zZ
WMKbqoG8MNpi/u3fp6zz0mcHCOSqYsPUUG19buW8bis5ZZ2IZgBObWSpTvJ0cnj6
HKBAA82Jln+lGwS1MwIDAQAB
-----END PUBLIC KEY-----
```

Para validar o `x-webhook-signature`, você deve usar a **chave pública da Woovi (em Base64)**:

```
LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlHZk1BMEdDU3FHU0liM0RRRUJBUVVBQTRHTkFEQ0JpUUtCZ1FDLytOdElranpldnZxRCtJM01NdjNiTFhEdApwdnhCalk0QnNSclNkY2EzcnRBd01jUllZdnhTbmQ3amFnVkxwY3RNaU94UU84aWVVQ0tMU1dIcHNNQWpPL3paCldNS2Jxb0c4TU5waS91M2ZwNnp6MG1jSENPU3FZc1BVVUcxOWJ1VzhiaXM1WloySVpnQk9iV1NwVHZKMGNuajYKSEtCQUE4MkpsbitsR3dTMU13SURBUUFCCi0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLQo=
```

Esta chave é a mesma para todos os webhooks da Woovi.

Exemplo: `'x-webhook-signature': 'lL2nnXgmLFGgxJ8+jCDguqouU4ucrIxYJcU5SPrJFaNcJajTJHYVldqc/z4YFIjAjtPEALe699WosgPY08W7CLpidvtm06Qwa4YMB0l/DcTS93O91NdSH/adjugEKiOb76Zj/0jB8mqOmWCFYbweOBa17bssuEkd5Lw7Q5L314Y='`

## Exemplo de validação

```php
<?php

function verifyPayload($payload, $signature) {
  $publicKeyBase64 = 'LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlHZk1BMEdDU3FHU0liM0RRRUJBUVVBQTRHTkFEQ0JpUUtCZ1FDLytOdElranpldnZxRCtJM01NdjNiTFhEdApwdnhCalk0QnNSclNkY2EzcnRBd01jUllZdnhTbmQ3amFnVkxwY3RNaU94UU84aWVVQ0tMU1dIcHNNQWpPL3paCldNS2Jxb0c4TU5waS91M2ZwNnp6MG1jSENPU3FZc1BVVUcxOWJ1VzhiaXM1WloySVpnQk9iV1NwVHZKMGNuajYKSEtCQUE4MkpsbitsR3dTMU13SURBUUFCCi0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLQo=';

  $publicKey = base64_decode($publicKeyBase64);

  $verify = openssl_verify($payload, base64_decode($signature), $publicKey, "sha256WithRSAEncryption");

  return $verify;
}
// replace to the payload received
$payload = '{ "pixQrCode": null, "charge": { "status": "COMPLETED", "customer": { "name": "Antonio Victor", "taxID": { "taxID": "12345678976", "type": "BR:CPF" }, "email": "antoniocliente@example.com", "correlationID": "4979ceba-2132-4292-bd90-bee7fb2125e4" }, "value": 1000, "comment": "Pagamento OpenPix", "transactionID": "ea83401ed4834b3ea6f1f283b389af29", "correlationID": "417bae21-3d08-4cdb-9c2d-fee63c89e9e4", "paymentLinkID": "34697ed2-3790-4b60-8512-e7465b142d84", "createdAt": "2021-03-12T12:43:54.528Z", "updatedAt": "2021-03-12T12:44:09.360Z", "brCode": "https://api.openpix.com.br/openpix/openpix/testing?transactionID=ea83401ed4834b3ea6f1f283b389af29" }, "pix": { "charge": { "status": "COMPLETED", "customer": { "name": "Antonio Victor", "taxID": { "taxID": "12345678976", "type": "BR:CPF" }, "email": "antoniocliente@example.com", "correlationID": "4979ceba-2132-4292-bd90-bee7fb2125e4" }, "value": 1000, "comment": "Pagamento OpenPix", "transactionID": "ea83401ed4834b3ea6f1f283b389af29", "correlationID": "417bae21-3d08-4cdb-9c2d-fee63c89e9e4", "paymentLinkID": "34697ed2-3790-4b60-8512-e7465b142d84", "createdAt": "2021-03-12T12:43:54.528Z", "updatedAt": "2021-03-12T12:44:09.360Z" }, "customer": { "correlationID": "9134e286-6f71-427a-bf00-241681624586", "email": "email1@example.com", "name": "Loma", "phone": "+5511999999999", "taxID": { "taxID": "47043622050", "type": "BR:CPF" } }, "payer": { "correlationID": "9134e286-6f71-427a-bf00-241681624586", "email": "email1@example.com", "name": "Loma", "phone": "+5511999999999", "taxID": { "taxID": "47043622050", "type": "BR:CPF" } }, "time": "2021-03-12T12:44:09.269Z", "value": 1, "transactionID": "ea83401ed4834b3ea6f1f283b389af29", "infoPagador": "OpenPix testing" }, "company": { "id": "624f46f9e93f9f521c8308d7", "name": "Pizzaria do José", "taxID": "4722767300014" }, "account": { "clientId": "ZOJ64B9B-ZM1W-89MI-4UCI-OP2LVIU6NY75" } }';

// replace to the header signature received into x-webhook-signature
$signature = 'lL2nnXgmLFGgxJ8+jCDguqouU4ucrIxYJcU5SPrJFaNcJajTJHYVldqc/z4YFIjAjtPEALe699WosgPY08W7CLpidvtm06Qwa4YMB0l/DcTS93O91NdSH/adjugEKiOb76Zj/0jB8mqOmWCFYbweOBa17bssuEkd5Lw7Q5L314Y=';

$isValid = verifyPayload($payload, $signature);

if ($isValid) {
  echo "Valid signature\n";
} else {
  echo "Invalid signature\n";
}

```

```jsx
import crypto from 'crypto';

type VerifyPayloadType = {
  payload: string;
  signature: string;
};

const algorithm = 'sha256';
const signatureFormat = 'base64';

export const verifyPayload = ({ payload, signature }: VerifyPayloadType) => {
  const publicKeyBase64 =
    'LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlHZk1BMEdDU3FHU0liM0RRRUJBUVVBQTRHTkFEQ0JpUUtCZ1FDLytOdElranpldnZxRCtJM01NdjNiTFhEdApwdnhCalk0QnNSclNkY2EzcnRBd01jUllZdnhTbmQ3amFnVkxwY3RNaU94UU84aWVVQ0tMU1dIcHNNQWpPL3paCldNS2Jxb0c4TU5waS91M2ZwNnp6MG1jSENPU3FZc1BVVUcxOWJ1VzhiaXM1WloySVpnQk9iV1NwVHZKMGNuajYKSEtCQUE4MkpsbitsR3dTMU13SURBUUFCCi0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLQo=';

  const publicKey = Buffer.from(publicKeyBase64, 'base64').toString('ascii');

  const verify = crypto.createVerify(algorithm);

  verify.write(Buffer.from(payload));
  verify.end();

  const isValid = verify.verify(publicKey, signature, signatureFormat);

  return isValid;
};

// replace to the payload received into body
const payload =
  '{ "pixQrCode": null, "charge": { "status": "COMPLETED", "customer": { "name": "Antonio Victor", "taxID": { "taxID": "12345678976", "type": "BR:CPF" }, "email": "antoniocliente@example.com", "correlationID": "4979ceba-2132-4292-bd90-bee7fb2125e4" }, "value": 1000, "comment": "Pagamento OpenPix", "transactionID": "ea83401ed4834b3ea6f1f283b389af29", "correlationID": "417bae21-3d08-4cdb-9c2d-fee63c89e9e4", "paymentLinkID": "34697ed2-3790-4b60-8512-e7465b142d84", "createdAt": "2021-03-12T12:43:54.528Z", "updatedAt": "2021-03-12T12:44:09.360Z", "brCode": "https://api.openpix.com.br/openpix/openpix/testing?transactionID=ea83401ed4834b3ea6f1f283b389af29" }, "pix": { "charge": { "status": "COMPLETED", "customer": { "name": "Antonio Victor", "taxID": { "taxID": "12345678976", "type": "BR:CPF" }, "email": "antoniocliente@example.com", "correlationID": "4979ceba-2132-4292-bd90-bee7fb2125e4" }, "value": 1000, "comment": "Pagamento OpenPix", "transactionID": "ea83401ed4834b3ea6f1f283b389af29", "correlationID": "417bae21-3d08-4cdb-9c2d-fee63c89e9e4", "paymentLinkID": "34697ed2-3790-4b60-8512-e7465b142d84", "createdAt": "2021-03-12T12:43:54.528Z", "updatedAt": "2021-03-12T12:44:09.360Z" }, "customer": { "correlationID": "9134e286-6f71-427a-bf00-241681624586", "email": "email1@example.com", "name": "Loma", "phone": "+5511999999999", "taxID": { "taxID": "47043622050", "type": "BR:CPF" } }, "payer": { "correlationID": "9134e286-6f71-427a-bf00-241681624586", "email": "email1@example.com", "name": "Loma", "phone": "+5511999999999", "taxID": { "taxID": "47043622050", "type": "BR:CPF" } }, "time": "2021-03-12T12:44:09.269Z", "value": 1, "transactionID": "ea83401ed4834b3ea6f1f283b389af29", "infoPagador": "OpenPix testing" }, "company": { "id": "624f46f9e93f9f521c8308d7", "name": "Pizzaria do José", "taxID": "4722767300014" }, "account": { "clientId": "ZOJ64B9B-ZM1W-89MI-4UCI-OP2LVIU6NY75" } }';

// replace to the payload received into x-webhook-signature header
const signature =
  'lL2nnXgmLFGgxJ8+jCDguqouU4ucrIxYJcU5SPrJFaNcJajTJHYVldqc/z4YFIjAjtPEALe699WosgPY08W7CLpidvtm06Qwa4YMB0l/DcTS93O91NdSH/adjugEKiOb76Zj/0jB8mqOmWCFYbweOBa17bssuEkd5Lw7Q5L314Y=';

const isValid = verifyPayload({ payload, signature });

if (isValid) {
  console.log('Valid signature');
} else {
  console.log('Invalid signature');
}
```

---

## Criando um webhook para interceptar um Pix via API

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Pela Woovi é possível criar webhooks para interceptar quando um pix for realizado. Hoje, há duas maneiras de realizar a criação do mesmo: via plataforma ou API.

Neste tutorial iremos descrever como criar um webhook para interceptar a chegada de um novo Pix via uma chamada API.

Para cadastrar o webhook via API basta seguir nossa especifição para realizar um POST na [api de Webhook](/api#tag/webhook/POST/api/v1/webhook).

```jsx
curl --location --request POST 'https://api.woovi.com/api/openpix/v1/webhook' \
--header 'Content-Type: application/json' \
--header 'Authorization: <appID>' \
--data-raw '{
    "webhook": {
    "name": "webhook via api",
    "url": "https://minhaurl.test/webhook",
    "authorization": "auth_key",
    "isActive": true
}
}'
```

```jsx
const createWebhook = async () => {
  const payload = {
    webhook: {
      name: 'webhook via api',
      url: 'https://minhaurl.test/webhook',
      authorization: 'auth_key',
      isActive: true,
    },
  };

  const response = await fetch(
    'https://api.woovi.com/api/openpix/v1/webhook',
    {
      method: 'POST',
      headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json',
        Authorization: 'appID',
      },
      body: JSON.stringify(payload),
    },
  );

  const data = await response.json();
  console.log({
    data,
  });
};
```

[Exemplos de payload do Webhook](/docs/category/exemplos)

---

## Explorador de eventos

import BrowserOnly from '@docusaurus/BrowserOnly';
import WebhookEventExplorer from '@site/src/components/WebhookEventExplorer/WebhookEventExplorer';

# Explorador de eventos de webhook

Selecione um tipo de evento na barra lateral e copie o payload em **JSON**, **TypeScript types**, **JSON Schema**, **Yup** ou **Zod**.
Os tipos e schemas são inferidos automaticamente a partir do payload de exemplo.

  {() => }

---

## Tipos de eventos do Webhook


O Webhook é um recurso que permite que a Woovi envie notificações para sua aplicação quando um evento ocorre. 
Por exemplo, quando uma cobrança é paga, a Woovi envia uma notificação para o seu servidor.

Abaixo, você pode ver uma lista de todos os eventos que a Woovi envia para sua aplicação.

:::tip Obtenha a lista de eventos via API
Você também pode obter a lista completa de eventos disponíveis programaticamente através da nossa API. 
Consulte o endpoint [GET /api/v1/webhook/events](/api#tag/webhook/GET/api/v1/webhook/events) na referência da API.
:::

## Eventos de cobrança

Os eventos de cobrança são enviados quando uma cobrança é paga.

### OPENPIX:CHARGE_COMPLETED

Esse evento é enviado quando uma cobrança é paga.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-charge-payload)

### OPENPIX:CHARGE_EXPIRED

Esse evento é enviado quando uma cobrança expira.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-charge-expired)

### OPENPIX:CHARGE_CREATED

Esse evento é enviado quando uma cobrança é criada.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-charge-created)

### OPENPIX:CHARGE_COMPLETED_NOT_SAME_CUSTOMER_PAYER

Esse evento é enviado quando uma cobrança é paga com um `payer` diferente do `customer`.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-charge-completed-not-same-payer-payload)

## Eventos de transação

Os eventos de transação são enviados quando uma transação é recebida.

### OPENPIX:TRANSACTION_RECEIVED

Esse evento é enviado quando uma transação é recebida, seja ela de uma cobrança ou de um QR code estático.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-transaction-received)

### OPENPIX:TRANSACTION_REFUND_RECEIVED (DEPRECATED)

Esse evento é enviado quando é realizado o reembolso de uma transação.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-refund-payload)

### PIX_TRANSACTION_REFUND_RECEIVED_CONFIRMED

Esse evento é enviado quando uma transação de reembolso é recebida e confirmada.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-refund-received-confirmed)

### PIX_TRANSACTION_REFUND_RECEIVED_REJECTED

Esse evento é enviado quando uma transação de reembolso é recebida mas é rejeitada.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-refund-received-rejected)

### PIX_TRANSACTION_REFUND_SENT_CONFIRMED

Esse evento é enviado quando uma transação de reembolso é enviada e confirmada.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-refund-sent-confirmed)

### PIX_TRANSACTION_REFUND_SENT_REJECTED

Esse evento é enviado quando uma transação de reembolso é enviada mas é rejeitada.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-refund-sent-rejected)

## Eventos de Pagamento Instantâneo

### OPENPIX:MOVEMENT_CONFIRMED

Esse evento é enviado quando um pagamento é confirmado.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-payment-payload#pagamento-confirmado)

### OPENPIX:MOVEMENT_FAILED

Esse evento é enviado quando um pagamento confirmado falha.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-payment-payload#falha-no-pagamento)

### OPENPIX:MOVEMENT_REMOVED

Esse evento é enviado quando um pagamento é removido.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-payment-payload#pagamento-removido)

## Eventos de Movimentos

### OPENPIX:DISPUTE_CREATED
Esse evento é enviado quando uma disputa é criada

[Ver exemplo de payload →](/docs/webhook/examples/webhook-created-payload)

### OPENPIX:DISPUTE_ACCEPTED
Esse evento é enviado quando uma disputa é aceita 

[Ver exemplo de payload →](/docs/webhook/examples/webhook-accepted-payload)

### OPENPIX:DISPUTE_REJECTED
Esse evento é enviado quando uma disputa é rejeitada

[Ver exemplo de payload →](/docs/webhook/examples/webhook-rejected-payload)

### OPENPIX:DISPUTE_CANCELED
Esse evento é enviado quando uma disputa é cancelada

[Ver exemplo de payload →](/docs/webhook/examples/webhook-canceled-payload)

## Eventos de boleto

### BOLETO_SETTLED
Esse evento é enviado quando um boleto é **liquidado**, ou seja quando o valor é creditado na sua conta — o que acontece em até 3 dias úteis após o pagamento, e não no ato dele. O pagamento em si é notificado pelo `OPENPIX:CHARGE_COMPLETED`.

O corpo repete os blocos `charge` e `boleto` do evento de cobrança paga e acrescenta o `boleto.settledAt`, além do `boleto.boletoTransactionID`, que é o id usado para consultar a transação na API.

[Ver como conciliar →](/docs/boleto/boleto-reconciliation)

## Eventos de Registro de contas 

### ACCOUNT_REGISTER_APPROVED
Esse evento é enviado quando um registro de subconta é aprovado no compliance.

[Ver exemplo de payload →](./examples/account-register-approved-payload.mdx)

### ACCOUNT_REGISTER_REJECTED
Esse evento é enviado quando um registro de subconta é reprovado no compliance.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-account-register-rejected-payload)

### ACCOUNT_REGISTER_PENDING
Esse evento é enviado quando um registro de subconta está em análise.

[Ver exemplo de payload →](/docs/webhook/examples/webhook-account-register-pending-payload)

### ACCOUNT_REGISTER_STEP_UPDATED
Esse evento é enviado a cada passo do onboarding concluído pelo cliente final — dados da empresa, contrato social, sócios, selfie, BC Protege+, termos. O passo vem no payload, nos campos `step`, `stepScope` e `stepStatus`.

[Ver o ciclo de vida completo →](../baas/kyc/webhooks-ciclo-de-vida.mdx)

### ACCOUNT_REGISTER_IN_REVIEW
Esse evento é enviado quando o registro entra em análise, seja porque o cliente final enviou o cadastro, seja porque um operador o promoveu de volta para análise.

[Ver o ciclo de vida completo →](../baas/kyc/webhooks-ciclo-de-vida.mdx)

### ACCOUNT_REGISTER_DOCUMENTS_REQUESTED
Esse evento é enviado quando a análise solicita documentos novos (RFI). O payload lista os documentos pedidos para a empresa e para cada sócio, e quais passos voltaram a ficar pendentes.

[Ver o ciclo de vida completo →](../baas/kyc/webhooks-ciclo-de-vida.mdx)

### ACCOUNT_REGISTER_RFI_RESOLVED
Esse evento é enviado quando o cliente final envia todos os documentos que haviam sido solicitados e a RFI é fechada.

[Ver o ciclo de vida completo →](../baas/kyc/webhooks-ciclo-de-vida.mdx)

## Eventos de Pix Automatico

### PIX_AUTOMATIC_APPROVED
Esse evento é enviado quando um pix automatico é aprovado

[Ver exemplo de payload →](/docs/pix-automatic/webhooks/pix-automatic-webhooks#pix_automatic_approved)

### PIX_AUTOMATIC_REJECTED
Esse evento é enviado quando um pix automatico é rejeitado

[Ver exemplo de payload →](/docs/pix-automatic/webhooks/pix-automatic-webhooks#pix_automatic_rejected)

### PIX_AUTOMATIC_COBR_CREATED
Esse evento é enviado quando uma cobrança de pix automatico é criada

[Ver exemplo de payload →](/docs/pix-automatic/webhooks/pix-automatic-webhooks#pix_automatic_cobr_created)

### PIX_AUTOMATIC_COBR_APPROVED
Esse evento é enviado quando uma cobrança de pix automatico é aprovada

[Ver exemplo de payload →](/docs/pix-automatic/webhooks/pix-automatic-webhooks#pix_automatic_cobr_approved)

### PIX_AUTOMATIC_COBR_REJECTED
Esse evento é enviado quando uma cobrança de pix automatico é rejeitada

[Ver exemplo de payload →](/docs/pix-automatic/webhooks/pix-automatic-webhooks#pix_automatic_cobr_rejected)

### PIX_AUTOMATIC_COBR_COMPLETED
Esse evento é enviado quando uma cobrança de pix automatico é paga

[Ver exemplo de payload →](/docs/pix-automatic/webhooks/pix-automatic-webhooks#pix_automatic_cobr_completed)

### PIX_AUTOMATIC_COBR_TRY_REJECTED
Esse evento é enviado quando uma tentativa de cobrança é rejeitada

[Ver exemplo de payload →](/docs/pix-automatic/webhooks/pix-automatic-webhooks#pix_automatic_cobr_try_rejected)

### PIX_AUTOMATIC_COBR_TRY_REQUESTED
Esse evento é enviado quando uma tentativa de cobrança é realizada

[Ver exemplo de payload →](/docs/pix-automatic/webhooks/pix-automatic-webhooks#pix_automatic_cobr_try_requested)

---

## Configurando os cabeçalhos HTTP do meu webhook

## Criando um novo cabeçalho HTTP pro meu webhook

Primeiro de tudo, é necessário acessar a rota para criar um novo webhook. Você
consegue acessar ela [aqui](https://app.woovi.com/home/openpix/webhook-create).

O que você vai ver é algo assim:

![Novo webhook com os inputs de headers customizados](/img/webhook/create-new-webhook-custom-headers.png)

A segunda seção, como pode perceber, é referente aos cabeçalhos da sua requisição HTTP (headers),
ali você pode colocar qualquer valor customizado que queira. Referente a autenticação, como o `Authorization` header,
do seu webhook, ou outra informação que queira utilizar no futuro.

Os 3 primeiros valores presentes ali são valores que são enviados em **TODAS**
as requisições feitas a partir do nosso webhook, não é possível alterá-las.

### Referências

- [Cabeçalhos HTTP - MDN](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Headers)

## Editando os cabeçalhos de um webhook já criado

Caso você queira editar os cabeçalhos de um webhook já criado, você precisará seguir o seguinte fluxo:

Inicialmente, acesse a lista contendo os itens referentes a `API/Plugins` e `Webhooks`.
Você consegue acessar por [aqui](https://app.woovi.com/home/api/list).

Acessando a lista de webhooks já criados, clique em uma dessas linhas para acessar os detalhes dela.

Quando acessado os detalhes de um webhook, o que você vai ver é algo semelhante a isto:

![Detalhes de um webhook já criado](/img/webhook/webhook-details.png)

Na seção de `Cabeçalhos HTTP`, clique nela para expandir. Expandido-a, o que você vai ver é os
inputs semelhantes ao que você tem no fluxo de criação do webhook, contendo os 3 cabeçalhos padronizados
de toda requsição.

![Customizar os cabeçalhos da requisição HTTP](/img/webhook/webhook-details-custom-headers.png)

Aqui, nessa seção, você consegue alterar os headers de cada webhook da forma que desejar.

---

## Vinculando o webhook à API

## Como vincular o webhook à API?

Além dos webhooks que são disparados ao realizar ações na plataforma, é possível vincular um webhook a uma API.

Primeiro, tenha uma api já configurada na plataforma.

![api-screen](./assets/api-screen.png)

Agora, crie um novo webhook.

![webhook-screen](./assets/webhook-screen.png)

Atualmente só é possível vincular um webhook a uma api nos eventos de charge. 

Clique em vincular a aplicação

![api-with-webhook](./assets/api-with-webhook.png)

Ao salvar, os eventos selecionados de cobranças serão enviados para o endereço do webhook com base nas ações da API.

---

## Reenviando webhooks na plataforma

## Como reenviar um webhook na plataforma?

É possível reenviar os webhooks na plataforma

Primeiro, acesse no menu lateral esquerdo a opção API/PLUGINS.

![api-plugins](./assets/api-plugins.png)

Depois, selecione o botão de reenviar.

![reenviar](./assets/reenviar.png)

O webhook será reenviado para o endpoint configurado. Você pode acompanhar o status do reenvio nos logs da plataforma.

![details](./assets/details.png)

---

## Regras de Retentativa do Webhook

## O que são retentativas de Webhooks?

É comum que, em sistemas distribuídos, ocorram falhas temporárias na entrega de mensagens. Para garantir que as mensagens sejam entregues, a woovi realiza retentativas de Webhooks em caso de falha na entrega.

## Quais são as regras para que um Webhook seja retentado?

1. Caso a URL do Webhook retorne um código de erro HTTP acima de 400, a woovi retentará o Webhook.
2. Caso a URL do Webhook não esteja disponível, a woovi retentará o Webhook.
3. Caso ocorra algum erro interno na woovi, a woovi retentará o Webhook.

## Retentativa de Webhooks

São feitas 8 tentativas de chamada do webhook.

A primeira tentativa é feita no momento em que o evento do webhook é disparado, caso ela falhe seguindo as regras acimas, as demais retentativas são feitas em intervalos de tempo exponenciais, de acordo com a seguinte fórmula:

```
intervalo = 10 * 2 ^ tentativa
```

Sendo assim, essa é a tabela de retentativas:

| Tentativa | Intervalo (segundos) |
| --------- | -------------------- |
| 1         | 10                   |
| 2         | 20                   |
| 3         | 40                   |
| 4         | 80                   |
| 5         | 160                  |
| 6         | 320                  |
| 7         | 640                  |
| 8         | 1280                 |

Caso todas as tentativas falhem, o webhook não será mais retentado.

Porém ainda sim é possível retentar manualmente via plataforma.

---

## Validando o webhook de teste


Quando é criado um novo webhook, a Woovi envia uma requisição de teste para o seu endpoint. 
Essa requisição é enviada para garantir que o seu endpoint está funcionando corretamente.

### 1. Recebendo o webhook de teste

Quando a Woovi envia um webhook de teste, o corpo da requisição é:

```json
{
  "data_criacao":"2024-01-23T20:32:14.429Z",
  "event":"OPENPIX:CHARGE_COMPLETED",
}
```

:::info

O campo `event` é o tipo de evento que está sendo enviado. Ele é escolhido conforme o evento selecionado na plataforma.
Você pode olhar os tipos de eventos disponíveis [aqui](./webhook-events-type.md).

:::

### 2. Respondendo o webhook de teste

Para responder o webhook de teste, basta retornar o status code `200` e o corpo da resposta vazio.

```php
return response()->json([], 200);
```

---

## Tempo de timeout do Webhook

## Timeout

A prática de Timeout é uma prática comum em sistemas distribuídos, onde um serviço espera por uma resposta de outro serviço por um determinado tempo. Se a resposta não chegar dentro desse tempo, o serviço que fez a requisição para de esperar, e cancela a requisição.

O tempo de timeout do nosso Webhook é de 100 segundos. Ou seja, se a url do serviço que recebe o Webhook não responder em até 100 segundos, a woovi cancela a requisição.

---

## Como ativar o WhatsApp?

Para ativar o WhatsApp em sua empresa siga os passos abaixo:

## 1. Abra a seção de integrações

Acesse `Api/Plugins` via sidemenu

![Api/Plugins item](./__assets__/whatsapp-how-to-activate-api-plugins.png)

## 2. Abra o tutorial de WhatsApp

Clique na botão de **Adicionar** na integração do WhatsApp

![Integração do WhatsApp](./__assets__/whatsapp-how-to-activate-integration.png)

## 3. Ative o WhatsApp

Clique em **Ativado** para ativar o WhatsApp

![Ativar WhatsApp](./__assets__/whatsapp-how-to-activate-activate.png)

## 4. Configure quais notifiações enviar

Por padrão, ao ativar o WhatsApp, todas as notifiações de WhatsApp são ativadas, para saber mais sobre cada uma, leia os artigos abaixo:

- [Como enviar cobranças por WhatsApp](./whatsapp-how-to-send-charges.md)
- [Como enviar recibos por WhatsApp](./whatsapp-how-to-send-receipts.md)

---

## Como enviar cobranças por WhatsApp

Para enviar cobranças por WhatsApp siga os passos abaixo:

![Mensagem de cobrança no WhatsApp](./__assets__/whatsapp-how-to-send-charges-message.png)

## 1. Ative o WhatsApp

Para ativar o WhatsApp, siga [esta documentação](./whatsapp-how-to-activate.md).

## 2. Ative a notificação

Por padrão, ao ativar o WhatsApp, esta notificação estará ativada, mas para ativar separadamente, vá ao ajustes de cobranças:

![Configurações de cobranças](./__assets__/whatsapp-charge-settings.png)

Desça até a seção de **Notificações para clientes** e clique em **Ativado** para ativar as notifiações de nova cobrança:

![Configuração de notificação de nova cobrança](./__assets__/whatsapp-how-to-send-charges-setting.png)

## 3. Crie uma cobrança e envie por WhatsApp

Parar criar uma cobrança e envia-lá por WhatsApp selecione um cliente e certifique-se que a opção **Enviar cobrança por WhatsApp** esteja ativa:

![Criação da cobrança](./__assets__/whatsapp-how-to-send-charges-charge.png)

---

## Como enviar recibos por WhatsApp

Para enviar recibos por WhatsApp siga os passos abaixo:

![Mensagem de recibo no WhatsApp](./__assets__/whatsapp-how-to-send-receipts-message.png)

## 1. Ative o WhatsApp

Para ativar o WhatsApp, siga [esta documentação](./whatsapp-how-to-activate.md).

## 2. Ative a notificação

Por padrão, ao ativar o WhatsApp, esta notificação estará ativada, mas para ativar separadamente, vá ao ajustes de cobranças:

![Configurações de cobranças](./__assets__/whatsapp-charge-settings.png)

Desça até a seção de **Notificações para clientes** e clique em **Ativado** para ativar as notifiações de  recibo:

![Configuração de notificação de recibo](./__assets__/whatsapp-how-to-send-receipts-setting.png)

## 3. Crie uma cobrança e envie o recibo por WhatsApp

Parar criar uma cobrança e enviar o recibo por WhatsApp selecione um cliente e certifique-se que a opção **Enviar recibo por WhatsApp** esteja ativa:

![Criação da cobrança](./__assets__/whatsapp-how-to-send-receipts-charge.png)

---

## Como funciona o fluxo de autorização de um WooviApp?

## Fluxo de autorização

Depois de [criar seu WooviApp](./woovi-apps-how-to-create.md) e obter `clientId`/`clientSecret`, seu app pode solicitar acesso à conta Woovi de uma empresa através de um fluxo de autorização no estilo OAuth 2.0 (_authorization code_).

## 1. Redirecionando a empresa para a tela de consentimento

Redirecione a empresa (a merchant que vai autorizar seu app) para:

```
https://store.woovi.com/authorize?client_id={clientId}&redirect_uri={redirectUri}&scope={scopes}&company_id={companyId}
```

Parâmetros de query:

- **`client_id`** _(obrigatório)_: o Client ID do seu WooviApp.
- **`redirect_uri`** _(obrigatório)_: uma das URIs cadastradas na criação do app. Se não corresponder a nenhuma URI registrada, a tela de consentimento retorna erro e a autorização não prossegue.
- **`scope`** _(opcional)_: lista de permissões separadas por espaço ou vírgula, restrita às permissões **opcionais** declaradas pelo app. As permissões obrigatórias são sempre solicitadas, independente deste parâmetro. Quando omitido, todas as permissões opcionais do app vêm pré-selecionadas na tela.
- **`company_id`** _(opcional)_: identificador da empresa que está autorizando. Quando omitido, a Woovi usa a empresa da sessão autenticada no momento.

:::info
A empresa precisa estar autenticada na Woovi (sessão via cookie) para chegar à tela de consentimento. Sem sessão ativa e sem `company_id` na URL, a tela exibe o aviso "nenhum contexto de empresa encontrado".
:::

## 2. Comportamento da tela de consentimento

A tela exibe o nome, logo, site e descrição do app, além de duas listas de permissões:

- **Obrigatórias**: sempre marcadas, sem opção de desativar.
- **Opcionais**: cada uma com um _toggle_ individual, iniciando marcada ou não conforme o parâmetro `scope` recebido.

Se a empresa já havia autorizado esse app anteriormente, a tela mostra um estado de "app já autorizado", oferecendo apenas as opções de reautorizar ou cancelar.

## 3. Aprovação ou negação

- **Autorizar**: ao confirmar, a Woovi valida que todas as permissões solicitadas fazem parte do que o app declarou (obrigatórias + opcionais), gera um `authorizationCode` de uso único e redireciona a empresa para:

  ```
  {redirect_uri}?code={authorizationCode}
  ```

- **Negar**: redireciona a empresa para:

  ```
  {redirect_uri}?error=access_denied
  ```

:::caution
O `authorizationCode` expira em **10 minutos** e só pode ser trocado por uma aplicação da API da Woovi uma única vez. Se as permissões solicitadas excederem o que o app declarou na criação, a autorização é rejeitada com o erro `Requested scopes exceed what the app declared`.
:::

## 4. Trocando o código por uma aplicação da API da Woovi

Com o `code` recebido no `redirect_uri`, seu backend cria diretamente uma aplicação da API da Woovi (com `clientId`/`clientSecret` próprios, escopados pelas permissões concedidas) para consumir a [API pública da Woovi](https://api.woovi.com). A troca do `code` pelo token de acesso acontece internamente, servidor a servidor — você não precisa (nem consegue) chamar esse passo intermediário diretamente:

```
POST https://api.woovi.com/api/v1/woovi-apps/application
Content-Type: application/json
Authorization: {seu appID}
```

Authorization: Você precisa de um appID da sua empresa com o escopo WOOVI_APP_APPLICATION_POST para poder fazer essa troca.

```json
{
  "code": "authorization-code-recebido",
  "client_id": "seu-client-id",
  "client_secret": "seu-client-secret"
}
```

- **`code`**, **`client_id`**, **`client_secret`** _(obrigatórios)_: o código de autorização recebido no callback e as credenciais do seu WooviApp. A Woovi valida essas informações antes de prosseguir.

O nome da aplicação criada é gerado automaticamente a partir da empresa dona do WooviApp, o tipo é sempre `API`, e os escopos são exatamente os que a empresa concedeu na tela de autorização — não há como sobrescrever nenhum desses valores por esta rota.

Resposta (`201`):

```json
{
  "application": {
    "name": "WooviApp - Minha Empresa",
    "isActive": true,
    "type": "API",
    "clientId": "a1b2c3d4e5f6...",
    "clientSecret": "9f8e7d6c5b4a...",
    "appID": "...",
    "scopes": ["CHARGE_GET", "CHARGE_GET_LIST"]
  }
}
```

Possíveis erros: `invalid_request` (faltam `code`, `client_id` ou `client_secret`), `invalid_client` (client_id/secret inválidos), `invalid_grant` (código inexistente, expirado ou já utilizado) e `unsupported_grant_type` (não deveria ocorrer neste fluxo, mas é retornado por completude caso o tipo de concessão internamente usado não seja suportado).

:::caution
O `clientSecret` desta aplicação também é exibido apenas nesta resposta — armazene-o com segurança. Use `clientId`/`clientSecret` (ou o `appID`) para autenticar as próximas chamadas na [API pública da Woovi](https://api.woovi.com), já restritas aos escopos concedidos pela empresa.
:::

## Revogação

A empresa pode revogar o acesso concedido a um app a qualquer momento pela tela de apps autorizados em [store.woovi.com/authorized-apps](https://store.woovi.com/authorized-apps). A revogação invalida o _access token_ imediatamente.

---

## Como criar um WooviApp?

## Criando um WooviApp

Para integrar sua aplicação à conta Woovi de outras empresas via OAuth, você precisa primeiro registrar um WooviApp na loja de apps.

Acesse [store.woovi.com/create](https://store.woovi.com/create) (opção "Novo" dentro de "Meus apps") para cadastrar um novo aplicativo.

## Campos do formulário

- **Nome do app** — obrigatório.
- **Descrição** — opcional, exibida na tela de consentimento.
- **Site** — opcional.
- **Categoria** — opcional: `Automação`, `Vendas`, `Financeiro`, `Analytics`, `Conteúdo & IA` ou `Segurança`.
- **URL do logo** — opcional. Quando não informada, o avatar exibe a inicial do nome do app sobre a cor escolhida.
- **Cor do avatar** — opcional, usada como fallback quando não há logo.

## Redirect URIs

É obrigatório cadastrar ao menos uma URI de redirecionamento. É para essas URLs que a empresa será redirecionada após autorizar (ou negar) o acesso do seu app, com o parâmetro `code` (ou `error`) anexado à query string.

> Somente URIs cadastradas aqui podem ser usadas no fluxo de autorização. Veja [Como funciona o fluxo de autorização de um WooviApp](./woovi-apps-how-to-authorize.md).

### Dados enviados no callback

Ao final do fluxo de autorização, a Woovi redireciona a empresa de volta para a `redirect_uri` com um dos seguintes formatos de query string:

- **Autorização concedida**:

  ```
  {redirect_uri}?code={authorizationCode}
  ```

  - **`code`**: um código de autorização de uso único, que expira em 10 minutos. Seu backend deve trocá-lo por uma aplicação da API da Woovi via `POST https://api.woovi.com/api/v1/woovi-apps/application`. Veja [Como funciona o fluxo de autorização de um WooviApp](./woovi-apps-how-to-authorize.md).

- **Autorização negada**:

  ```
  {redirect_uri}?error=access_denied
  ```

  - **`error`**: sempre `access_denied` quando a empresa nega o consentimento explicitamente.

Nenhum outro dado (como `client_id`, escopos ou informações da empresa) é enviado no callback — apenas `code` ou `error`. A identificação da empresa só fica disponível depois de trocar o `code` pela aplicação da API da Woovi (veja a resposta da troca em [Como funciona o fluxo de autorização de um WooviApp](./woovi-apps-how-to-authorize.md)).

## Permissões (scopes)

As permissões disponíveis fazem parte de um catálogo fixo, agrupado por recurso (`ACCOUNT`, `CHARGE`, `PAYMENT`, `PIX_KEY`, `SUBACCOUNT`, `WEBHOOK`, entre outros). Para cada permissão do catálogo, você escolhe um dos três níveis:

- **Obrigatória**: sempre concedida quando a empresa autoriza o app, sem opção de recusa individual pela empresa.
- **Opcional**: a empresa pode optar por conceder ou não no momento da autorização.
- **Nenhum** (padrão): a permissão não é solicitada pelo app.

O app precisa declarar ao menos uma permissão, obrigatória ou opcional, para ser criado. Se alguma permissão declarada não existir no catálogo, a criação falha com o erro `Scope not permitted: "<scope>"`.

### Permissões bloqueadas

As seguintes permissões não fazem parte do catálogo e não podem ser solicitadas por nenhum WooviApp, nem como obrigatórias nem como opcionais, por permitirem ações sensíveis como movimentação de fundos, exclusão de recursos ou escalonamento de privilégios:

- `ACCOUNT_WITHDRAW_POST`
- `ACCOUNT_DELETE`
- `ACCOUNT_REGISTER_DELETE`
- `APPLICATION_POST`
- `APPLICATION_DELETE`
- `PARTNER_COMPANY_POST`
- `PARTNER_APPLICATION_POST`
- `PAYMENT_POST`
- `PAYMENT_APPROVE_POST`
- `SUBACCOUNT_WITHDRAW_POST`
- `SUBACCOUNT_DELETE`
- `SUBACCOUNT_TRANSFER_POST`
- `SUBACCOUNT_DEBIT_POST`
- `SUBACCOUNT_CREDIT_POST`
- `TRANSFER_POST`
- `KYC_ONBOARDING_POST`

Num exemplo prático, os dados enviados na criação seguiriam semelhante a este:

```json
{
  "name": "Meu Integrador",
  "description": "Sincroniza pagamentos com meu ERP",
  "redirectUris": ["https://meuapp.com/callback"],
  "requiredScopes": ["CHARGE_GET", "CHARGE_GET_LIST"],
  "optionalScopes": ["PAYMENT_GET"],
  "category": "AUTOMATION",
  "website": "https://meuapp.com"
}
```

## Resposta: Client ID e Client Secret

Ao criar o app com sucesso, a resposta traz o `clientId` do app e o `clientSecret` gerado:

```json
{
  "wooviApp": {
    "clientId": "a1b2c3d4e5f6...",
    "name": "Meu Integrador"
  },
  "clientSecret": "9f8e7d6c5b4a..."
}
```

:::caution
O `clientSecret` é exibido **apenas uma vez**, no momento da criação. A Woovi armazena apenas o hash (SHA-256) do secret — se você perdê-lo, não há como recuperá-lo, sendo necessário cadastrar um novo app. Salve as credenciais em local seguro antes de fechar a tela de confirmação.
:::

## Próximos passos

Com o `clientId` e o `clientSecret` em mãos, seu app está pronto para iniciar o fluxo de autorização e solicitar acesso à conta de uma empresa. Veja [Como funciona o fluxo de autorização de um WooviApp](./woovi-apps-how-to-authorize.md).

---

## Woovi Prompts

[Woovi Prompts](https://github.com/woovibr/woovi-prompts) é um repositório
público com prompts prontos para usar com LLMs e agentes (como Claude Code,
Cursor, Copilot e similares) ao integrar com a plataforma Woovi.

Use os prompts para acelerar:

- Geração de cobranças via API Woovi
- Integração com Pix, cobv, boleto e subscriptions
- Tratamento de webhooks
- Setup de plugins e SDKs

## Acesse o repositório

👉 [github.com/woovibr/woovi-prompts](https://github.com/woovibr/woovi-prompts)