# Detalhar MED
Source: https://docs.plowf.com/api-reference/meds/get

GET /api/v1/meds/{medUuid}

Retorna os detalhes completos de um MED (Mecanismo Especial de Devolução) específico.

<RequestExample>
  ```bash theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/meds/550e8400-e29b-41d4-a716-446655440000' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Path Parameters

<ParamField type="string">
  UUID do MED que deseja consultar
</ParamField>

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "pix_in_transaction": {
        "uuid": "660e8400-e29b-41d4-a716-446655440001",
        "initiation": {
          "sender": {
            "name": "João Silva",
            "document": "12345678900",
            "account_number": "12345678",
            "account_agency": "0001",
            "bank": {
              "code": "001",
              "name": "Banco Exemplo",
              "ispb": "00000000"
            },
            "account_type": "PAYMENT"
          },
          "receiver": {
            "name": "Empresa Exemplo LTDA",
            "document": "12345678000199",
            "account_number": "87654321",
            "account_agency": "0001",
            "bank": {
              "code": "002",
              "name": "Banco Recebedor",
              "ispb": "00000001"
            },
            "account_type": "CHECKING"
          },
          "txid": "txid123456789abcdef",
          "value": "150.00",
          "type": "QR_DYNAMIC",
          "pix_key": "770e8400-e29b-41d4-a716-446655440002",
          "additional_info": [
            {
              "name": "ID do pagamento",
              "value": "880e8400-e29b-41d4-a716-446655440003"
            }
          ],
          "status": "COMPLETED",
          "expires_at": "2024-01-02T23:59:59.000000Z",
          "created_at": "2024-01-01T10:00:00.000000Z",
          "updated_at": "2024-01-01T10:05:00.000000Z"
        },
        "value": "150.00",
        "movement_type": "IN",
        "type": "EXTERNAL_TRANSFER",
        "status": "SETTLED",
        "end_to_end": "E00000000202401011000abcdef12345",
        "settled_at": "2024-01-01T10:05:00.000000Z",
        "created_at": "2024-01-01T10:05:00.000000Z",
        "updated_at": "2024-01-01T10:05:00.000000Z"
      },
      "attachments": [
        {
          "uuid": "990e8400-e29b-41d4-a716-446655440004",
          "url": "https://app.plowf.com/attachments/meds/550e8400-e29b-41d4-a716-446655440000/990e8400-e29b-41d4-a716-446655440004.jpg"
        }
      ],
      "med_type": "RECEIVED_MED",
      "dispute_type": "UNDEFINED",
      "status": "PROCESSING",
      "details": "01",
      "analysis": "Texto de análise do MED",
      "resolved": false,
      "created_at": "2024-01-01T12:00:00.000000Z",
      "updated_at": "2024-01-02T14:30:00.000000Z"
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object">
  Dados completos do MED

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único do MED
    </ResponseField>

    <ResponsePixTransaction name="pix_in_transaction" />

    <ResponseField name="attachments" type="object[]">
      Anexos do MED (comprovantes, documentos)

      <Expandable title="atributos">
        <ResponseField name="uuid" type="string">
          UUID do anexo
        </ResponseField>

        <ResponseField name="url" type="string">
          URL do anexo
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="med_type" type="string">
      Tipo do MED (RECEIVED\_MED, REQUESTED\_MED)
    </ResponseField>

    <ResponseField name="dispute_type" type="string">
      Tipo da disputa (UNDEFINED, SCAM, WRONG\_TRANSACTION, COERCION\_CRIME, UNAUTHORIZED\_ACCESS)
    </ResponseField>

    <ResponseField name="status" type="string">
      Status do MED (PENDING, PROCESSING, ACCEPTED, REJECTED, CANCELLED)
    </ResponseField>

    <ResponseField name="details" type="string">
      Detalhes do MED
    </ResponseField>

    <ResponseField name="analysis" type="string">
      Análise do MED
    </ResponseField>

    <ResponseField name="resolved" type="boolean">
      Indica se o MED foi resolvido
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação
    </ResponseField>

    <ResponseField name="updated_at" type="datetime">
      Data e hora da última atualização
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="404">
  MED não encontrado. Verifique se o UUID está correto e se você tem permissão para acessá-lo.
</ErrorField>


# Listar MEDs
Source: https://docs.plowf.com/api-reference/meds/list

GET /api/v1/meds

Lista todos os MEDs (Mecanismo Especial de Devolução) da conta autenticada com paginação e filtros.

<RequestExample>
  ```bash theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/meds?status=PROCESSING&per_page=20' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Parâmetros de Query

Todos os parâmetros são opcionais.

<ParamField type="string">
  Filtrar por UUID específico do MED
</ParamField>

<ParamField type="string">
  Status do MED. Valores possíveis:

  * `PENDING` - Pendente
  * `PROCESSING` - Em processamento
  * `ACCEPTED` - Aceito
  * `REJECTED` - Rejeitado
  * `CANCELLED` - Cancelado
</ParamField>

<ParamField type="string">
  Tipo do MED. Valores possíveis:

  * `RECEIVED_MED` - MED recebido
  * `REQUESTED_MED` - MED enviado
</ParamField>

<ParamField type="string">
  Tipo da disputa. Valores possíveis:

  * `UNDEFINED` - Não definido
  * `SCAM` - Fraude
  * `WRONG_TRANSACTION` - Transação incorreta
  * `COERCION_CRIME` - Crime de coação
  * `UNAUTHORIZED_ACCESS` - Acesso não autorizado
</ParamField>

<ParamField type="boolean">
  Filtrar por MEDs resolvidos ou não resolvidos
</ParamField>

<ParamField type="date">
  Data inicial para filtro (formato: YYYY-MM-DD)
</ParamField>

<ParamField type="date">
  Data final para filtro (formato: YYYY-MM-DD)
</ParamField>

<ParamField type="integer">
  Número de itens por página (mínimo: 1, máximo: 100)
</ParamField>

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "pix_in_transaction": {
          "uuid": "660e8400-e29b-41d4-a716-446655440001",
          "initiation": {
            "sender": {
              "name": "João Silva",
              "document": "12345678900",
              "account_number": "12345678",
              "account_agency": "0001",
              "bank": {
                "code": "001",
                "name": "Banco Exemplo",
                "ispb": "00000000"
              },
              "account_type": "PAYMENT"
            },
            "receiver": {
              "name": "Empresa Exemplo LTDA",
              "document": "12345678000199",
              "account_number": "87654321",
              "account_agency": "0001",
              "bank": {
                "code": "002",
                "name": "Banco Recebedor",
                "ispb": "00000001"
              },
              "account_type": "CHECKING"
            },
            "txid": "txid123456789abcdef",
            "value": "150.00",
            "type": "QR_DYNAMIC",
            "pix_key": "770e8400-e29b-41d4-a716-446655440002",
            "additional_info": [
              {
                "name": "ID do pagamento",
                "value": "880e8400-e29b-41d4-a716-446655440003"
              }
            ],
            "status": "COMPLETED",
            "expires_at": "2024-01-02T23:59:59.000000Z",
            "created_at": "2024-01-01T10:00:00.000000Z",
            "updated_at": "2024-01-01T10:05:00.000000Z"
          },
          "value": "150.00",
          "movement_type": "IN",
          "type": "EXTERNAL_TRANSFER",
          "status": "SETTLED",
          "end_to_end": "E00000000202401011000abcdef12345",
          "settled_at": "2024-01-01T10:05:00.000000Z",
          "created_at": "2024-01-01T10:05:00.000000Z",
          "updated_at": "2024-01-01T10:05:00.000000Z"
        },
        "attachments": [
          {
            "uuid": "990e8400-e29b-41d4-a716-446655440004",
            "url": "https://app.plowf.com/attachments/meds/550e8400-e29b-41d4-a716-446655440000/990e8400-e29b-41d4-a716-446655440004.jpg"
          }
        ],
        "med_type": "RECEIVED_MED",
        "dispute_type": "UNDEFINED",
        "status": "PROCESSING",
        "details": "01",
        "analysis": "Texto de análise do MED",
        "resolved": false,
        "created_at": "2024-01-01T12:00:00.000000Z",
        "updated_at": "2024-01-02T14:30:00.000000Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "from": 1,
      "last_page": 5,
      "per_page": 10,
      "to": 10,
      "total": 50
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object[]">
  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único do MED
    </ResponseField>

    <ResponsePixTransaction name="pix_in_transaction" />

    <ResponseField name="attachments" type="object[]">
      Anexos do MED (comprovantes, documentos)

      <Expandable title="atributos">
        <ResponseField name="uuid" type="string">
          UUID do anexo
        </ResponseField>

        <ResponseField name="url" type="string">
          URL do anexo
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="med_type" type="string">
      Tipo do MED (RECEIVED\_MED, REQUESTED\_MED)
    </ResponseField>

    <ResponseField name="dispute_type" type="string">
      Tipo da disputa (UNDEFINED, SCAM, WRONG\_TRANSACTION, COERCION\_CRIME, UNAUTHORIZED\_ACCESS)
    </ResponseField>

    <ResponseField name="status" type="string">
      Status do MED (PENDING, PROCESSING, ACCEPTED, REJECTED, CANCELLED)
    </ResponseField>

    <ResponseField name="details" type="string">
      Detalhes do MED
    </ResponseField>

    <ResponseField name="analysis" type="string">
      Análise do MED
    </ResponseField>

    <ResponseField name="resolved" type="boolean">
      Indica se o MED foi resolvido
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação
    </ResponseField>

    <ResponseField name="updated_at" type="datetime">
      Data e hora da última atualização
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Metadados de paginação

  <Expandable title="atributos">
    <ResponseField name="current_page" type="number">
      Página atual
    </ResponseField>

    <ResponseField name="from" type="number">
      Índice do primeiro item da página
    </ResponseField>

    <ResponseField name="last_page" type="number">
      Última página disponível
    </ResponseField>

    <ResponseField name="per_page" type="number">
      Itens por página
    </ResponseField>

    <ResponseField name="to" type="number">
      Índice do último item da página
    </ResponseField>

    <ResponseField name="total" type="number">
      Total de itens
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>


# Responder MED
Source: https://docs.plowf.com/api-reference/meds/reply

POST /api/v1/meds/{medUuid}/reply

Envia uma resposta para um MED (Mecanismo Especial de Devolução) específico, incluindo análise e anexos.

<RequestExample>
  ```bash theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/meds/550e8400-e29b-41d4-a716-446655440000/reply' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: multipart/form-data' \
    -F 'accept=0' \
    -F 'analysis=Análise detalhada da contestação do MED' \
    -F 'attachments[0][file]=@/caminho/para/comprovante.png'
  ```
</RequestExample>

## Path Parameters

<ParamField type="string">
  UUID do MED que deseja responder
</ParamField>

## Body Parameters

<ParamField type="boolean">
  Indica se aceita ou rejeita o MED.

  * `1` ou `true` - Aceita o MED
  * `0` ou `false` - Rejeita o MED
</ParamField>

<ParamField type="string">
  Texto de análise/justificativa da resposta ao MED
</ParamField>

<ParamField type="array">
  Array de anexos (comprovantes, documentos) para suportar a resposta

  <Expandable title="atributos">
    <ParamField type="file">
      Arquivo de anexo (imagem ou documento)
    </ParamField>
  </Expandable>
</ParamField>

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "pix_in_transaction": {
        "uuid": "660e8400-e29b-41d4-a716-446655440001",
        "initiation": {
          "sender": {
            "name": "João Silva",
            "document": "12345678900",
            "account_number": "12345678",
            "account_agency": "0001",
            "bank": {
              "code": "001",
              "name": "Banco Exemplo",
              "ispb": "00000000"
            },
            "account_type": "PAYMENT"
          },
          "receiver": {
            "name": "Empresa Exemplo LTDA",
            "document": "12345678000199",
            "account_number": "87654321",
            "account_agency": "0001",
            "bank": {
              "code": "002",
              "name": "Banco Recebedor",
              "ispb": "00000001"
            },
            "account_type": "CHECKING"
          },
          "txid": "txid123456789abcdef",
          "value": "150.00",
          "type": "QR_DYNAMIC",
          "pix_key": "770e8400-e29b-41d4-a716-446655440002",
          "additional_info": [
            {
              "name": "ID do pagamento",
              "value": "880e8400-e29b-41d4-a716-446655440003"
            }
          ],
          "status": "COMPLETED",
          "expires_at": "2024-01-02T23:59:59.000000Z",
          "created_at": "2024-01-01T10:00:00.000000Z",
          "updated_at": "2024-01-01T10:05:00.000000Z"
        },
        "value": "150.00",
        "movement_type": "IN",
        "type": "EXTERNAL_TRANSFER",
        "status": "SETTLED",
        "end_to_end": "E00000000202401011000abcdef12345",
        "settled_at": "2024-01-01T10:05:00.000000Z",
        "created_at": "2024-01-01T10:05:00.000000Z",
        "updated_at": "2024-01-01T10:05:00.000000Z"
      },
      "attachments": [
        {
          "uuid": "990e8400-e29b-41d4-a716-446655440004",
          "url": "https://app.plowf.com/attachments/meds/550e8400-e29b-41d4-a716-446655440000/990e8400-e29b-41d4-a716-446655440004.jpg"
        },
        {
          "uuid": "aa0e8400-e29b-41d4-a716-446655440005",
          "url": "https://app.plowf.com/attachments/meds/550e8400-e29b-41d4-a716-446655440000/aa0e8400-e29b-41d4-a716-446655440005.png"
        }
      ],
      "med_type": "RECEIVED_MED",
      "dispute_type": "UNDEFINED",
      "status": "PROCESSING",
      "details": "Detalhes do MED",
      "analysis": "Análise detalhada da contestação do MED",
      "resolved": false,
      "created_at": "2024-01-01T12:00:00.000000Z",
      "updated_at": "2024-01-02T15:30:00.000000Z"
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object">
  Dados completos do MED após a resposta

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único do MED
    </ResponseField>

    <ResponsePixTransaction name="pix_in_transaction" />

    <ResponseField name="attachments" type="object[]">
      Anexos do MED (comprovantes, documentos)

      <Expandable title="atributos">
        <ResponseField name="uuid" type="string">
          UUID do anexo
        </ResponseField>

        <ResponseField name="url" type="string">
          URL do anexo
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="med_type" type="string">
      Tipo do MED (RECEIVED\_MED, REQUESTED\_MED)
    </ResponseField>

    <ResponseField name="dispute_type" type="string">
      Tipo da disputa (UNDEFINED, SCAM, WRONG\_TRANSACTION, COERCION\_CRIME, UNAUTHORIZED\_ACCESS)
    </ResponseField>

    <ResponseField name="status" type="string">
      Status do MED (PENDING, PROCESSING, ACCEPTED, REJECTED, CANCELLED)
    </ResponseField>

    <ResponseField name="details" type="string">
      Detalhes do MED
    </ResponseField>

    <ResponseField name="analysis" type="string">
      Análise/justificativa da resposta ao MED
    </ResponseField>

    <ResponseField name="resolved" type="boolean">
      Indica se o MED foi resolvido
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação
    </ResponseField>

    <ResponseField name="updated_at" type="datetime">
      Data e hora da última atualização
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="400">
  MED já foi respondido ou não está em status que permita resposta.
</ErrorField>

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="404">
  MED não encontrado. Verifique se o UUID está correto e se você tem permissão para acessá-lo.
</ErrorField>

<ErrorField name="422">
  Erro de validação. Verifique se os campos obrigatórios foram enviados corretamente.
</ErrorField>


# Criar Cobrança
Source: https://docs.plowf.com/api-reference/payments/create

POST /api/v1/payments

Cria um nova cobrança PIX In (gera QR Code/Copia e Cola para recebimento).

<RequestExample>
  ```bash Default theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/payments' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{
      "value": 250.00,
      "type": "pix",
      "external_ref": "PED-001",
      "final_beneficiary": {
        "name": "Maria Santos",
        "document": "98765432100"
      },
      "splits": [
        {
          "type": "percentage",
          "value": 10,
          "recipient_account_uuid": "550e8400-e29b-41d4-a716-446655440000"
        },
        {
          "type": "fixed",
          "value": 5.00,
          "recipient_account_uuid": "660e8400-e29b-41d4-a716-446655440001"
        }
      ]
    }'
  ```

  ```bash Provedor específico theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/payments' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{
      "value": 250.00,
      "type": "pix",
      "provider_uuid": "9f1c0a30-3b8c-4a82-a4d7-2b8e93b1f001"
    }'
  ```
</RequestExample>

## Body Parameters

<ParamField type="number">
  Valor da cobrança. Mínimo: 0
</ParamField>

<ParamField type="string">
  Tipo da cobrança. Deve ser exatamente `"PIX"`
</ParamField>

<ParamField type="object">
  Dados do beneficiário final (seller)

  <Expandable title="atributos">
    <ParamField type="string">
      Nome do beneficiário final
    </ParamField>

    <ParamField type="string">
      Documento do beneficiário final - CPF ou CNPJ válido
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Referência externa para identificação da cobrança
</ParamField>

<ParamField type="string">
  UUID do provedor que receberá a cobrança. Quando omitido, a Plowf escolhe o provedor padrão da conta para PIX (configurável em [`PUT /providers/defaults`](/api-reference/providers/defaults-set)). Liste os UUIDs disponíveis em [`GET /providers`](/api-reference/providers/list).

  Ignorado quando o token está [vinculado a um provedor](/guides/intro/provider-scoped-tokens) — neste caso, o provedor do token sempre prevalece.
</ParamField>

<ParamField type="object[]">
  Lista de regras de split para distribuição do valor recebido entre outras contas

  <Expandable title="atributos">
    <ParamField type="string">
      Tipo do split. Valores aceitos: `PERCENTAGE` ou `FIXED`
    </ParamField>

    <ParamField type="number">
      Valor do split. Para `PERCENTAGE`, representa o percentual (ex: `10` para 10%). Para `FIXED`, representa o valor em reais (ex: `5.00`)
    </ParamField>

    <ParamField type="string">
      UUID da conta destinatária que receberá o split
    </ParamField>
  </Expandable>
</ParamField>

## Validações

* `type` deve ser exatamente **"pix"**
* `value` deve ser maior ou igual a **0**
* Se `final_beneficiary` for enviado, ambos `name` e `document` são **obrigatórios**
* `document` deve ser um **CPF ou CNPJ válido** se informado
* Para splits do tipo `percentage`, o valor não pode exceder **100%**
* A soma de todos os splits percentuais não pode exceder **100%**
* A soma de todos os splits (percentual + fixo) não pode ser maior que o **valor total da cobrança**
* A combinação de `recipient_account_uuid` e `type` deve ser **única** por cobrança (não é possível ter dois splits do mesmo tipo para a mesma conta)
* `provider_uuid`, se informado, deve referenciar um provedor existente na conta. Se omitido, o provedor padrão de PIX da conta é usado.

## Resposta de Sucesso

A resposta retorna o objeto da cobrança criado com o QR Code/Copia e Cola no campo `payment.payload`.

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "uuid": "770e8400-e29b-41d4-a716-446655440000",
      "value": 250,
      "total_value": 255,
      "fees": 5,
      "currency": "BRL",
      "status": "PENDING",
      "type": "PIX",
      "payment": {
        "uuid": "880e8400-e29b-41d4-a716-446655440001",
        "value": 250,
        "type": "PIX",
        "status": "PENDING",
        "payload": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-4266554400005204000053039865802BR5913FULANO DE TAL6008BRASILIA62070503***63041D3D",
        "pix": {
          "sender": null,
          "receiver": {
            "name": "Empresa Demo LTDA",
            "document": "12345678000190",
            "account_number": "9876543",
            "account_agency": "0001",
            "bank": {
              "code": "",
              "name": "PLOWF IP LTDA.",
              "ispb": "00000000"
            },
            "account_type": "CHECKING"
          },
          "txid": "770e8400e29b41d4a716446655440000",
          "value": 250,
          "type": "QR_DYNAMIC",
          "pix_key": "1234567890",
          "additional_info": [
            {
              "name": "ID da cobrança",
              "value": "770e8400-e29b-41d4-a716-446655440000"
            }
          ],
          "transaction": null,
          "status": "PENDING",
          "expires_at": "2024-01-01T23:59:59Z",
          "created_at": "2024-01-01T10:00:00Z",
          "updated_at": "2024-01-01T10:00:00Z"
        },
        "expires_at": "2024-01-01T23:59:59Z",
        "created_at": "2024-01-01T10:00:00Z",
        "updated_at": "2024-01-01T10:00:00Z"
      },
      "external_ref": "PED-001",
      "final_beneficiary": {
        "name": "Maria Santos",
        "document": "98765432100"
      },
      "splits": [
        {
          "uuid": "990e8400-e29b-41d4-a716-446655440002",
          "type": "PERCENTAGE",
          "value": 10,
          "status": "PENDING",
          "recipient_account": {
            "uuid": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Empresa Parceira LTDA"
          }
        },
        {
          "uuid": "aa0e8400-e29b-41d4-a716-446655440003",
          "type": "FIXED",
          "value": 5,
          "status": "PENDING",
          "recipient_account": {
            "uuid": "660e8400-e29b-41d4-a716-446655440001",
            "name": "Taxa Plataforma"
          }
        }
      ],
      "history": [
        {
          "status": "PENDING",
          "created_at": "2024-01-01T10:00:00Z"
        }
      ],
      "created_at": "2024-01-01T10:00:00Z",
      "updated_at": "2024-01-01T10:00:00Z"
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object">
  Dados da cobrança criado

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único da cobrança
    </ResponseField>

    <ResponseField name="value" type="number">
      Valor da cobrança
    </ResponseField>

    <ResponseField name="total_value" type="number">
      Valor total (incluindo taxas)
    </ResponseField>

    <ResponseField name="fees" type="number">
      Taxas aplicadas
    </ResponseField>

    <ResponseField name="currency" type="string">
      Moeda (ex: BRL)
    </ResponseField>

    <ResponseField name="status" type="string">
      Status inicial (geralmente "PENDING")
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo da cobrança (ex: PIX)
    </ResponseField>

    <ResponsePixCharge />

    <ResponseField name="external_ref" type="string">
      Referência externa (opcional)
    </ResponseField>

    <ResponseField name="final_beneficiary" type="object">
      Beneficiário final da cobrança (seller)

      <Expandable title="atributos">
        <ResponseField name="name" type="string">
          Nome do beneficiário final
        </ResponseField>

        <ResponseField name="document" type="string">
          Documento do beneficiário final (CPF ou CNPJ)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="splits" type="object[]">
      Lista de splits aplicados à cobrança

      <Expandable title="atributos">
        <ResponseField name="uuid" type="string">
          UUID único do split
        </ResponseField>

        <ResponseField name="type" type="string">
          Tipo do split: `PERCENTAGE` ou `FIXED`
        </ResponseField>

        <ResponseField name="value" type="number">
          Valor do split. Para `PERCENTAGE`, representa o percentual. Para `FIXED`, o valor em reais
        </ResponseField>

        <ResponseField name="status" type="string">
          Status do split: `PENDING`, `CREDITED` ou `FAILED`
        </ResponseField>

        <ResponseField name="recipient_account" type="object">
          Conta destinatária do split

          <Expandable title="atributos">
            <ResponseField name="uuid" type="string">
              UUID da conta destinatária
            </ResponseField>

            <ResponseField name="name" type="string">
              Nome da conta destinatária
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="history" type="object[]">
      Histórico de mudanças de status

      <Expandable title="atributos">
        <ResponseField name="status" type="string">
          Status no histórico
        </ResponseField>

        <ResponseField name="created_at" type="datetime">
          Data e hora do status
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação da cobrança
    </ResponseField>

    <ResponseField name="updated_at" type="datetime">
      Data e hora da última atualização
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  O campo `payment.payload` contém o código Copia e Cola do PIX. Você pode usar este código para gerar um QR Code usando bibliotecas como `qrcode` (Node.js) ou `qrcode` (Python). O QR Code expira na data indicada em `payment.expires_at`.
</Note>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="422">
  Erro de validação. Possíveis causas:

  * Tipo diferente de "pix"
  * Valor negativo
  * Beneficiário final incompleto
  * Documento inválido
  * Valor percentual do split maior que 100%
  * Soma dos splits percentuais excede 100%
  * Soma total dos splits supera o valor da cobrança
  * Combinação duplicada de `recipient_account_uuid` e `type` nos splits
  * `provider_uuid` não pertence à conta ou está inativo
</ErrorField>


# Detalhar Cobrança
Source: https://docs.plowf.com/api-reference/payments/get

GET /api/v1/payments/{paymentUuid}

Retorna os detalhes completos de um cobrança específica.

<RequestExample>
  ```bash theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/payments/770e8400-e29b-41d4-a716-446655440000' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Path Parameters

<ParamField type="string">
  UUID da cobrança que deseja consultar
</ParamField>

## Resposta de Sucesso

A resposta retorna o objeto completo da cobrança com a mesma estrutura do endpoint de listagem.

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "uuid": "770e8400-e29b-41d4-a716-446655440000",
      "value": 250,
      "total_value": 255,
      "fees": 5,
      "currency": "BRL",
      "status": "PAID",
      "type": "PIX",
      "payment": {
        "uuid": "880e8400-e29b-41d4-a716-446655440001",
        "value": "250.00",
        "type": "QR_DYNAMIC",
        "status": "COMPLETED",
        "payload": "00020101021226570014br.gov.bcb.pix2535qr.plowf.com/qr/v2/cob/770e8400-e29b-41d4-a71652040000530398654062500.005802BR5912Empresa_Demo6009Sao_Paulo62290525770e8400e29b41d4a716446663041A2B",
        "pix": {
          "sender": {
            "name": "João Silva",
            "document": "12345678901",
            "account_number": "00123456",
            "account_agency": "0001",
            "bank": {
              "code": "341",
              "name": "ITAÚ UNIBANCO S.A.",
              "ispb": "60701190"
            },
            "account_type": "CHECKING"
          },
          "receiver": {
            "name": "Empresa Demo LTDA",
            "document": "12345678000190",
            "account_number": "9876543",
            "account_agency": "0001",
            "bank": {
              "code": "",
              "name": "PLOWF IP LTDA.",
              "ispb": "00000000"
            },
            "account_type": "CHECKING"
          },
          "txid": "770e8400e29b41d4a716446655440000",
          "value": "250.00",
          "type": "QR_DYNAMIC",
          "pix_key": "1234567890",
          "transaction": {
            "uuid": "990e8400-e29b-41d4-a716-446655440002",
            "value": "250.00",
            "movement_type": "IN",
            "type": "EXTERNAL_TRANSFER",
            "status": "SETTLED",
            "end_to_end": "E6070119020240101100500000000001",
            "settled_at": "2024-01-01T10:05:00.000000Z",
            "created_at": "2024-01-01T10:02:00.000000Z",
            "updated_at": "2024-01-01T10:05:00.000000Z"
          },
          "status": "COMPLETED",
          "expires_at": "2024-03-01T10:00:00.000000Z",
          "created_at": "2024-01-01T10:00:00.000000Z",
          "updated_at": "2024-01-01T10:05:00.000000Z"
        },
        "verify_sender": false,
        "expires_at": "2024-03-01T10:00:00.000000Z",
        "created_at": "2024-01-01T10:00:00.000000Z",
        "updated_at": "2024-01-01T10:05:00.000000Z"
      },
      "external_ref": "PED-001",
      "final_beneficiary": {
        "name": "Maria Santos",
        "document": "98765432100"
      },
      "splits": [
        {
          "uuid": "990e8400-e29b-41d4-a716-446655440002",
          "type": "PERCENTAGE",
          "value": 10,
          "status": "CREDITED",
          "recipient_account": {
            "uuid": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Empresa Parceira LTDA"
          }
        }
      ],
      "history": [
        {
          "status": "PENDING",
          "created_at": "2024-01-01T10:00:00Z"
        },
        {
          "status": "PROCESSING",
          "created_at": "2024-01-01T10:02:00Z"
        },
        {
          "status": "PAID",
          "created_at": "2024-01-01T10:05:00Z"
        }
      ],
      "created_at": "2024-01-01T10:00:00Z",
      "updated_at": "2024-01-01T10:05:00Z"
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object">
  Dados completos da cobrança

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único da cobrança
    </ResponseField>

    <ResponseField name="value" type="number">
      Valor da cobrança
    </ResponseField>

    <ResponseField name="total_value" type="number">
      Valor total (incluindo taxas)
    </ResponseField>

    <ResponseField name="fees" type="number">
      Taxas aplicadas
    </ResponseField>

    <ResponseField name="currency" type="string">
      Moeda (ex: BRL)
    </ResponseField>

    <ResponseField name="status" type="string">
      Status atual da cobrança
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo da cobrança (ex: PIX)
    </ResponseField>

    <ResponsePixCharge />

    <ResponseField name="external_ref" type="string">
      Referência externa (opcional)
    </ResponseField>

    <ResponseField name="final_beneficiary" type="object">
      Beneficiário final da cobrança (seller)

      <Expandable title="atributos">
        <ResponseField name="name" type="string">
          Nome do beneficiário final
        </ResponseField>

        <ResponseField name="document" type="string">
          Documento do beneficiário final (CPF ou CNPJ)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="splits" type="object[]">
      Lista de splits aplicados à cobrança

      <Expandable title="atributos">
        <ResponseField name="uuid" type="string">
          UUID único do split
        </ResponseField>

        <ResponseField name="type" type="string">
          Tipo do split: `PERCENTAGE` ou `FIXED`
        </ResponseField>

        <ResponseField name="value" type="number">
          Valor do split. Para `PERCENTAGE`, representa o percentual. Para `FIXED`, o valor em reais
        </ResponseField>

        <ResponseField name="status" type="string">
          Status do split: `PENDING`, `CREDITED` ou `FAILED`
        </ResponseField>

        <ResponseField name="recipient_account" type="object">
          Conta destinatária do split

          <Expandable title="atributos">
            <ResponseField name="uuid" type="string">
              UUID da conta destinatária
            </ResponseField>

            <ResponseField name="name" type="string">
              Nome da conta destinatária
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="history" type="object[]">
      Histórico de mudanças de status

      <Expandable title="atributos">
        <ResponseField name="status" type="string">
          Status no histórico
        </ResponseField>

        <ResponseField name="created_at" type="datetime">
          Data e hora do status
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação
    </ResponseField>

    <ResponseField name="updated_at" type="datetime">
      Data e hora da última atualização
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="404">
  Cobrança não encontrada. Verifique se o UUID está correto e se você tem permissão para acessá-la.
</ErrorField>


# Listar Cobranças
Source: https://docs.plowf.com/api-reference/payments/list

GET /api/v1/payments

Lista todos as cobranças PIX In (recebimentos) da conta autenticada com paginação e filtros avançados.

<RequestExample>
  ```bash theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/payments?status=PAID&per_page=20' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Parâmetros de Query

Todos os parâmetros são opcionais.

<ParamField type="string">
  Filtrar por UUID específico da cobrança
</ParamField>

<ParamField type="string">
  Status da cobrança. Valores possíveis: - `UNDEFINED` - `PENDING` - `PAID` -
  `FAILED` - `REFUNDED` - `PARTIALLY_REFUNDED` - `CANCELLED` - `EXPIRED` -
  `PROCESSING`
</ParamField>

<ParamField type="string">
  Tipo da cobrança. Valores possíveis: - `UNDEFINED` - `PIX`
</ParamField>

<ParamField type="string">
  End-to-end ID do PIX
</ParamField>

<ParamField type="date">
  Data de cobrança inicial (formato: YYYY-MM-DD)
</ParamField>

<ParamField type="date">
  Data de cobrança final (formato: YYYY-MM-DD)
</ParamField>

<ParamField type="date">
  Data inicial para filtro (formato: YYYY-MM-DD)
</ParamField>

<ParamField type="date">
  Data final para filtro (formato: YYYY-MM-DD)
</ParamField>

<ParamField type="integer">
  Número de itens por página (mínimo: 1, máximo: 100)
</ParamField>

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "uuid": "770e8400-e29b-41d4-a716-446655440000",
        "value": 250,
        "total_value": 255,
        "fees": 5,
        "currency": "BRL",
        "status": "PAID",
        "type": "PIX",
        "payment": {
          "uuid": "880e8400-e29b-41d4-a716-446655440001",
          "value": "250.00",
          "type": "QR_DYNAMIC",
          "status": "COMPLETED",
          "payload": "00020101021226570014br.gov.bcb.pix2535qr.plowf.com/qr/v2/cob/770e8400-e29b-41d4-a71652040000530398654062500.005802BR5912Empresa_Demo6009Sao_Paulo62290525770e8400e29b41d4a716446663041A2B",
          "pix": {
            "sender": {
              "name": "João Silva",
              "document": "12345678901",
              "account_number": "00123456",
              "account_agency": "0001",
              "bank": {
                "code": "341",
                "name": "ITAÚ UNIBANCO S.A.",
                "ispb": "60701190"
              },
              "account_type": "CHECKING"
            },
            "receiver": {
              "name": "Empresa Demo LTDA",
              "document": "12345678000190",
              "account_number": "9876543",
              "account_agency": "0001",
              "bank": {
                "code": "",
                "name": "PLOWF IP LTDA.",
                "ispb": "00000000"
              },
              "account_type": "CHECKING"
            },
            "txid": "770e8400e29b41d4a716446655440000",
            "value": "250.00",
            "type": "QR_DYNAMIC",
            "pix_key": "1234567890",
            "transaction": {
              "uuid": "990e8400-e29b-41d4-a716-446655440002",
              "value": "250.00",
              "movement_type": "IN",
              "type": "EXTERNAL_TRANSFER",
              "status": "SETTLED",
              "end_to_end": "E6070119020240101100500000000001",
              "settled_at": "2024-01-01T10:05:00.000000Z",
              "created_at": "2024-01-01T10:02:00.000000Z",
              "updated_at": "2024-01-01T10:05:00.000000Z"
            },
            "status": "COMPLETED",
            "expires_at": "2024-03-01T10:00:00.000000Z",
            "created_at": "2024-01-01T10:00:00.000000Z",
            "updated_at": "2024-01-01T10:05:00.000000Z"
          },
          "verify_sender": false,
          "expires_at": "2024-03-01T10:00:00.000000Z",
          "created_at": "2024-01-01T10:00:00.000000Z",
          "updated_at": "2024-01-01T10:05:00.000000Z"
        },
        "external_ref": "PED-001",
        "final_beneficiary": {
          "name": "Maria Santos",
          "document": "98765432100"
        },
        "splits": [
          {
            "uuid": "990e8400-e29b-41d4-a716-446655440002",
            "type": "PERCENTAGE",
            "value": 10,
            "status": "CREDITED",
            "recipient_account": {
              "uuid": "550e8400-e29b-41d4-a716-446655440000",
              "name": "Empresa Parceira LTDA"
            }
          }
        ],
        "history": [
          {
            "status": "PENDING",
            "created_at": "2024-01-01T10:00:00Z"
          },
          {
            "status": "PAID",
            "created_at": "2024-01-01T10:05:00Z"
          }
        ],
        "created_at": "2024-01-01T10:00:00Z",
        "updated_at": "2024-01-01T10:05:00Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "from": 1,
      "last_page": 5,
      "per_page": 10,
      "to": 10,
      "total": 50
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object[]">
  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único da cobrança
    </ResponseField>

    <ResponseField name="value" type="number">
      Valor da cobrança
    </ResponseField>

    <ResponseField name="total_value" type="number">
      Valor total (incluindo taxas)
    </ResponseField>

    <ResponseField name="fees" type="number">
      Taxas aplicadas
    </ResponseField>

    <ResponseField name="currency" type="string">
      Moeda (ex: BRL)
    </ResponseField>

    <ResponseField name="status" type="string">
      Status atual da cobrança
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo da cobrança (ex: PIX)
    </ResponseField>

    <ResponsePixCharge />

    <ResponseField name="external_ref" type="string">
      Referência externa (opcional)
    </ResponseField>

    <ResponseField name="final_beneficiary" type="object">
      Beneficiário final da cobrança (seller)

      <Expandable title="atributos">
        <ResponseField name="name" type="string">
          Nome do beneficiário final
        </ResponseField>

        <ResponseField name="document" type="string">
          Documento do beneficiário final (CPF ou CNPJ)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="splits" type="object[]">
      Lista de splits aplicados à cobrança

      <Expandable title="atributos">
        <ResponseField name="uuid" type="string">
          UUID único do split
        </ResponseField>

        <ResponseField name="type" type="string">
          Tipo do split: `PERCENTAGE` ou `FIXED`
        </ResponseField>

        <ResponseField name="value" type="number">
          Valor do split. Para `PERCENTAGE`, representa o percentual. Para `FIXED`, o valor em reais
        </ResponseField>

        <ResponseField name="status" type="string">
          Status do split: `PENDING`, `CREDITED` ou `FAILED`
        </ResponseField>

        <ResponseField name="recipient_account" type="object">
          Conta destinatária do split

          <Expandable title="atributos">
            <ResponseField name="uuid" type="string">
              UUID da conta destinatária
            </ResponseField>

            <ResponseField name="name" type="string">
              Nome da conta destinatária
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="history" type="object[]">
      Histórico de mudanças de status

      <Expandable title="atributos">
        <ResponseField name="status" type="string">
          Status no histórico
        </ResponseField>

        <ResponseField name="created_at" type="datetime">
          Data e hora do status
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação da cobrança
    </ResponseField>

    <ResponseField name="updated_at" type="datetime">
      Data e hora da última atualização
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Metadados de paginação

  <Expandable title="atributos">
    <ResponseField name="current_page" type="number">
      Página atual
    </ResponseField>

    <ResponseField name="from" type="number">
      Índice do primeiro item da página
    </ResponseField>

    <ResponseField name="last_page" type="number">
      Última página disponível
    </ResponseField>

    <ResponseField name="per_page" type="number">
      Itens por página
    </ResponseField>

    <ResponseField name="to" type="number">
      Índice do último item da página
    </ResponseField>

    <ResponseField name="total" type="number">
      Total de itens
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ResponseErrorAuth />


# Estornar Cobrança
Source: https://docs.plowf.com/api-reference/payments/refund

POST /api/v1/payments/{paymentUuid}/refund

Estorna uma cobrança (total ou parcial). Se o valor não for informado, estorna o valor total da cobrança.

<RequestExample>
  ```bash theme={null}
  # Estorno total (sem informar valor)
  curl -X POST 'https://app.plowf.com/api/v1/payments/770e8400-e29b-41d4-a716-446655440000/refund' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json'

  # Estorno parcial (informando valor)
  curl -X POST 'https://app.plowf.com/api/v1/payments/770e8400-e29b-41d4-a716-446655440000/refund' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{
      "value": 100.00
    }'
  ```
</RequestExample>

## Path Parameters

<ParamField type="string">
  UUID da cobrança a ser estornado
</ParamField>

## Body Parameters

<ParamField type="number">
  Valor a ser estornado. Se não informado, estorna o valor total da cobrança. Deve ser entre 0 e o `total_value` da cobrança.
</ParamField>

## Validações

* Se `value` não for enviado, estorna o **valor total** da cobrança
* Se `value` for enviado, deve ser entre **0** e o `total_value` da cobrança
* O cobrança deve estar em um status que permita estorno (geralmente `PAID`)

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "message": "Reembolso iniciado",
    "data": {
      "uuid": "770e8400-e29b-41d4-a716-446655440000",
      "status": "PROCESSING",
      "value": 247.99,
      "fees": 0.5,
      "refund": {
        "status": "PROCESSING",
        "value": 247.99,
        "fees": 0.5,
        "pix_original": {
          "uuid": "880e8400-e29b-41d4-a716-446655440001",
          "initiation": {
            "sender": {
              "name": "João Silva",
              "document": "12345678901",
              "account_number": "00123456",
              "account_agency": "0001",
              "bank": {
                "code": "341",
                "name": "ITAÚ UNIBANCO S.A.",
                "ispb": "60701190"
              },
              "account_type": "CHECKING"
            },
            "receiver": {
              "name": "Empresa Demo LTDA",
              "document": "12345678000190",
              "account_number": "9876543",
              "account_agency": "0001",
              "bank": {
                "code": "",
                "name": "PLOWF IP LTDA.",
                "ispb": "00000000"
              },
              "account_type": "CHECKING"
            },
            "txid": "770e8400e29b41d4a716446655440000",
            "value": "247.99",
            "type": "QR_DYNAMIC",
            "pix_key": "550e8400-e29b-41d4-a716-446655440000",
            "additional_info": [
              {
                "name": "ID do pagamento",
                "value": "990e8400-e29b-41d4-a716-446655440002"
              }
            ],
            "status": "COMPLETED",
            "expires_at": "2024-01-02T10:00:00.000000Z",
            "created_at": "2024-01-01T10:00:00.000000Z",
            "updated_at": "2024-01-01T10:05:00.000000Z"
          },
          "value": "247.99",
          "movement_type": "IN",
          "type": "EXTERNAL_TRANSFER",
          "status": "SETTLED",
          "end_to_end": "E6070119020240101100500000000001",
          "settled_at": "2024-01-01T10:05:00.000000Z",
          "created_at": "2024-01-01T10:05:00.000000Z",
          "updated_at": "2024-01-01T10:05:00.000000Z"
        },
        "pix_refund": {
          "uuid": "990e8400-e29b-41d4-a716-446655440002",
          "initiation": {
            "sender": {
              "name": "Empresa Demo LTDA",
              "document": "12345678000190",
              "account_number": "9876543",
              "account_agency": "0001",
              "bank": {
                "code": "",
                "name": "PLOWF IP LTDA.",
                "ispb": "00000000"
              },
              "account_type": "CHECKING"
            },
            "receiver": {
              "name": "João Silva",
              "document": "12345678901",
              "account_number": "00123456",
              "account_agency": "0001",
              "bank": {
                "code": "341",
                "name": "ITAÚ UNIBANCO S.A.",
                "ispb": "60701190"
              },
              "account_type": "CHECKING"
            },
            "txid": null,
            "value": 247.99,
            "type": "REFUND",
            "status": "COMPLETED",
            "expires_at": null,
            "created_at": "2024-01-02T10:00:00.000000Z",
            "updated_at": "2024-01-02T10:00:00.000000Z"
          },
          "value": 247.99,
          "movement_type": "OUT",
          "type": "EXTERNAL_REFUND",
          "status": "PENDING",
          "end_to_end": "D0000000020240102100000000000001",
          "settled_at": null,
          "created_at": "2024-01-02T10:00:00.000000Z",
          "updated_at": "2024-01-02T10:00:00.000000Z"
        },
        "created_at": "2024-01-02T10:00:00.000000Z",
        "updated_at": "2024-01-02T10:00:00.000000Z"
      },
      "history": [
        {
          "status": "PENDING",
          "created_at": "2024-01-01T10:00:00Z"
        },
        {
          "status": "PAID",
          "created_at": "2024-01-01T10:05:00Z"
        }
      ],
      "created_at": "2024-01-02T10:00:00.000000Z",
      "updated_at": "2024-01-02T10:00:00.000000Z"
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object">
  Dados do estorno realizado

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID do estorno realizado
    </ResponseField>

    <ResponseField name="status" type="string">
      Status do estorno (PENDING, PROCESSING, SUCCESS, FAILED)
    </ResponseField>

    <ResponseField name="value" type="number">
      Valor estornado
    </ResponseField>

    <ResponseField name="fees" type="number">
      Taxas aplicadas
    </ResponseField>

    <ResponseField name="refund" type="object">
      Dados do estorno PIX realizado

      <Expandable title="atributos">
        <ResponseField name="value" type="number">
          Valor do estorno pix
        </ResponseField>

        <ResponseField name="status" type="string">
          Status do estorno pix (PENDING, PROCESSING, SETTLED, FAILED, CANCELED)
        </ResponseField>

        <ResponsePixTransaction name="pix_original" description="Dados do PIX original que foi estornado" />

        <ResponsePixTransaction name="pix_refund" description="Dados do PIX de estorno processado" />

        <ResponseField name="created_at" type="datetime">
          Data e hora de criação do estorno pix
        </ResponseField>

        <ResponseField name="updated_at" type="datetime">
          Data e hora da última atualização do estorno pix
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="history" type="object[]">
      Histórico de mudanças de status

      <Expandable title="atributos">
        <ResponseField name="status" type="string">
          Status no histórico
        </ResponseField>

        <ResponseField name="created_at" type="datetime">
          Data e hora do status
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação da cobrança original
    </ResponseField>

    <ResponseField name="updated_at" type="datetime">
      Data e hora da última atualização (após o estorno)
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="404">
  Cobrança não encontrada. Verifique se o UUID está correto.
</ErrorField>

<ErrorField name="422">
  Erro de validação. Possíveis causas:

  * Valor de estorno maior que o `total_value` da cobrança
  * Valor de estorno negativo
  * Cobrança não está em status que permita estorno
</ErrorField>

<Note>
  Após um estorno parcial, o status da cobrança será `PARTIALLY_REFUNDED`. Após um estorno total, o status será `REFUNDED`.
</Note>


# Solicitar Código de Autenticação
Source: https://docs.plowf.com/api-reference/pix-keys/auth-code

POST /api/v1/pix-keys/auth-code

Envia um código de verificação por SMS ou e-mail. Obrigatório antes de criar chaves do tipo `PHONE` ou `EMAIL`.

<RequestExample>
  ```bash Telefone theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/pix-keys/auth-code' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{ "key": "+5511999999999" }'
  ```

  ```bash Email theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/pix-keys/auth-code' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{ "key": "user@email.com" }'
  ```

  ```bash Provedor específico theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/pix-keys/auth-code' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{
      "key": "+5511999999999",
      "provider_uuid": "9f1c0a30-3b8c-4a82-a4d7-2b8e93b1f001"
    }'
  ```
</RequestExample>

## Validações

* Rate limit: **3 tentativas por 60 segundos** por conta

## Body Parameters

<ParamField type="string">
  Valor da chave que receberá o código de verificação:

  * **E-mail**: endereço válido (ex: `user@email.com`)
  * **Telefone**: número com código do país (ex: `+5511999999999`)
</ParamField>

<ParamField type="string">
  UUID do provedor que enviará o código. Apenas provedores do tipo `NOMINAL` (conta dedicada) suportam chaves PIX — provedores `POOL` são rejeitados. Liste os UUIDs em [`GET /providers`](/api-reference/providers/list).

  Quando omitido, o código é solicitado ao provedor padrão de PIX da conta. Ignorado quando o token está [vinculado a um provedor](/guides/intro/provider-scoped-tokens) — o provedor do token prevalece.

  Use o **mesmo `provider_uuid`** na chamada subsequente a [`POST /pix-keys`](/api-reference/pix-keys/create), caso contrário o `auth_code_id` retornado aqui não será válido.
</ParamField>

## Validações

* Rate limit: **3 tentativas por 60 segundos** por conta

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "message": "Código de autenticação enviado com sucesso.",
    "data": {
      "auth_code_id": "abc123xyz"
    }
  }
  ```
</ResponseExample>

<ResponseField name="message" type="string">
  Mensagem de confirmação do envio
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="atributos">
    <ResponseField name="auth_code_id" type="string">
      Identificador do código enviado. Use este valor no campo `auth_code_id` ao criar a chave PIX.
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="422">
  Erro de validação. Possíveis causas:

  * `key` inválida ou não suportada pelo provedor (ex: `EMAIL`/`PHONE` em provedor incompatível)
  * `provider_uuid` informado não pertence à conta, está inativo ou é de uma integração `POOL`
</ErrorField>

<ErrorField name="429">
  Rate limit excedido. Máximo de 3 tentativas por 60 segundos por conta.
</ErrorField>


# Criar Chave PIX
Source: https://docs.plowf.com/api-reference/pix-keys/create

POST /api/v1/pix-keys

Cria uma nova chave PIX na conta autenticada.

<RequestExample>
  ```bash DOCUMENT theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/pix-keys' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{ "type": "DOCUMENT" }'
  ```

  ```bash RANDOM theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/pix-keys' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{ "type": "RANDOM" }'
  ```

  ```bash PHONE theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/pix-keys' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{
      "type": "PHONE",
      "auth_code_id": "abc123xyz",
      "auth_code": "123456"
    }'
  ```

  ```bash EMAIL theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/pix-keys' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{
      "type": "EMAIL",
      "auth_code_id": "abc123xyz",
      "auth_code": "123456"
    }'
  ```

  ```bash Provedor específico theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/pix-keys' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{
      "type": "DOCUMENT",
      "provider_uuid": "9f1c0a30-3b8c-4a82-a4d7-2b8e93b1f001"
    }'
  ```
</RequestExample>

## Validações

* Para `PHONE` e `EMAIL`, `auth_code_id` e `auth_code` são **obrigatórios** — solicite o código antes via [auth-code](/api-reference/pix-keys/auth-code)
* Máximo de **3 chaves por tipo** por conta
* Rate limit: **3 tentativas por 60 segundos** por conta
* `provider_uuid`, se informado, deve referenciar um provedor `NOMINAL` existente na conta. Se omitido, o provedor padrão de PIX é usado.

## Body Parameters

<ParamField type="string">
  Tipo da chave PIX. Valores aceitos: `DOCUMENT`, `EMAIL`, `PHONE`, `RANDOM`
</ParamField>

<ParamField type="string">
  Identificador retornado pelo endpoint de [código de autenticação](/api-reference/pix-keys/auth-code). Obrigatório para `PHONE` e `EMAIL`.
</ParamField>

<ParamField type="string">
  Código de 6 dígitos recebido por SMS ou e-mail. Obrigatório para `PHONE` e `EMAIL`.
</ParamField>

<ParamField type="string">
  UUID do provedor onde a chave será criada. Apenas provedores do tipo `NOMINAL` (conta dedicada) suportam chaves PIX — provedores `POOL` são rejeitados. Liste os UUIDs em [`GET /providers`](/api-reference/providers/list).

  Quando omitido, a chave é criada no provedor padrão de PIX da conta. Ignorado quando o token está [vinculado a um provedor](/guides/intro/provider-scoped-tokens) — o provedor do token prevalece.
</ParamField>

## Validações

* Para `PHONE` e `EMAIL`, `auth_code_id` e `auth_code` são **obrigatórios** — solicite o código antes via [auth-code](/api-reference/pix-keys/auth-code)
* Máximo de **3 chaves por tipo** por conta
* Rate limit: **3 tentativas por 60 segundos** por conta
* `provider_uuid`, se informado, deve referenciar um provedor `NOMINAL` existente na conta. Se omitido, o provedor padrão de PIX é usado.

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "message": "Chave PIX criada com sucesso.",
    "data": {
      "key": "+5511999999999",
      "type": "PHONE",
      "is_active": true,
      "created_at": "2026-01-19T19:32:14.000000Z"
    }
  }
  ```
</ResponseExample>

<ResponseField name="message" type="string">
  Mensagem de confirmação da criação
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="atributos">
    <ResponseField name="key" type="string">
      Valor da chave PIX
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo da chave: `DOCUMENT`, `EMAIL`, `PHONE` ou `RANDOM`
    </ResponseField>

    <ResponseField name="is_active" type="boolean">
      Indica se a chave está ativa
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação da chave
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="403">
  Conta virtual não está ativa para realizar operações!
</ErrorField>

<ErrorField name="422">
  Erro de validação. Possíveis causas:

  * Você atingiu o limite de chaves PIX para este tipo.
  * Esta chave PIX já está sendo utilizada em outra conta.
  * Código de autenticação inválido.
  * O provedor não suporta chaves do tipo `PHONE` ou `EMAIL`.
  * `provider_uuid` informado não pertence à conta, está inativo ou é de uma integração `POOL`.
</ErrorField>

<ErrorField name="429">
  Rate limit excedido. Máximo de 3 tentativas por 60 segundos por conta.
</ErrorField>


# Remover Chave PIX
Source: https://docs.plowf.com/api-reference/pix-keys/delete

DELETE /api/v1/pix-keys/{key}

Remove uma chave PIX da conta autenticada.

<RequestExample>
  ```bash Email theme={null}
  curl -X DELETE 'https://app.plowf.com/api/v1/pix-keys/user%40email.com' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```

  ```bash CPF theme={null}
  curl -X DELETE 'https://app.plowf.com/api/v1/pix-keys/52998224725' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Path Parameters

<ParamField type="string">
  Valor da chave PIX a ser removida, URL-encoded quando necessário:

  * **DOCUMENT** — CPF (11 dígitos, ex: `52998224725`) ou CNPJ (14 dígitos, ex: `12345678000100`)
  * **EMAIL** — endereço de e-mail; encode `@` como `%40` (ex: `user%40email.com`)
  * **PHONE** — número com código do país; encode `+` como `%2B` (ex: `%2B5511999999999`)
  * **RANDOM** — UUID (ex: `550e8400-e29b-41d4-a716-446655440000`)
</ParamField>

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "message": "Chave PIX removida com sucesso."
  }
  ```
</ResponseExample>

<ResponseField name="message" type="string">
  Mensagem de confirmação da remoção
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="404">
  Chave PIX não encontrada ou pertence a outra conta.
</ErrorField>


# Buscar Chave PIX
Source: https://docs.plowf.com/api-reference/pix-keys/get

GET /api/v1/pix-keys/{key}

Retorna os detalhes de uma chave PIX específica.

<RequestExample>
  ```bash Email theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/pix-keys/user%40email.com' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```

  ```bash Telefone theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/pix-keys/%2B5511999999999' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```

  ```bash CPF theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/pix-keys/52998224725' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```

  ```bash Chave aleatória theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/pix-keys/550e8400-e29b-41d4-a716-446655440000' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Path Parameters

<ParamField type="string">
  Valor da chave PIX, URL-encoded quando necessário:

  * **DOCUMENT** — CPF (11 dígitos, ex: `52998224725`) ou CNPJ (14 dígitos, ex: `12345678000100`)
  * **EMAIL** — endereço de e-mail; encode `@` como `%40` (ex: `user%40email.com`)
  * **PHONE** — número com código do país; encode `+` como `%2B` (ex: `%2B5511999999999`)
  * **RANDOM** — UUID (ex: `550e8400-e29b-41d4-a716-446655440000`)
</ParamField>

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "key": "user@email.com",
      "type": "EMAIL",
      "is_active": true,
      "created_at": "2026-01-19T19:32:14.000000Z"
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object">
  <Expandable title="atributos">
    <ResponseField name="key" type="string">
      Valor da chave PIX
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo da chave: `DOCUMENT`, `EMAIL`, `PHONE` ou `RANDOM`
    </ResponseField>

    <ResponseField name="is_active" type="boolean">
      Indica se a chave está ativa
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação da chave
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="404">
  Entidade não encontrada!
</ErrorField>


# Listar Chaves PIX
Source: https://docs.plowf.com/api-reference/pix-keys/list

GET /api/v1/pix-keys

Lista todas as chaves PIX da conta autenticada com suporte a filtros e paginação.

<RequestExample>
  ```bash theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/pix-keys?type=EMAIL&is_active=true' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Parâmetros de Query

Todos os parâmetros são opcionais.

<ParamField type="string">
  Tipo da chave PIX. Valores possíveis: `DOCUMENT`, `EMAIL`, `PHONE`, `RANDOM`
</ParamField>

<ParamField type="boolean">
  Filtrar por status da chave. `true` para ativas, `false` para inativas.
</ParamField>

<ParamField type="integer">
  Número de itens por página (mínimo: 1, máximo: 100)
</ParamField>

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "key": "user@email.com",
        "type": "EMAIL",
        "is_active": true,
        "created_at": "2026-01-19T19:32:14.000000Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "last_page": 1,
      "from": 1,
      "to": 1,
      "total": 1,
      "per_page": 10
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object[]">
  <Expandable title="atributos">
    <ResponseField name="key" type="string">
      Valor da chave PIX (e-mail, telefone, CPF/CNPJ ou chave aleatória)
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo da chave: `DOCUMENT`, `EMAIL`, `PHONE` ou `RANDOM`
    </ResponseField>

    <ResponseField name="is_active" type="boolean">
      Indica se a chave está ativa
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação da chave
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Metadados de paginação

  <Expandable title="atributos">
    <ResponseField name="current_page" type="number">
      Página atual
    </ResponseField>

    <ResponseField name="from" type="number">
      Índice do primeiro item da página
    </ResponseField>

    <ResponseField name="last_page" type="number">
      Última página disponível
    </ResponseField>

    <ResponseField name="per_page" type="number">
      Itens por página
    </ResponseField>

    <ResponseField name="to" type="number">
      Índice do último item da página
    </ResponseField>

    <ResponseField name="total" type="number">
      Total de itens
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>


# Listar Provedores Padrão
Source: https://docs.plowf.com/api-reference/providers/defaults-get

GET /api/v1/providers/defaults

Retorna os provedores padrão configurados para cada tipo de pagamento. Quando uma operação é criada sem `provider_uuid` no body, a plataforma escolhe automaticamente um provedor a partir desta lista, respeitando a ordem de prioridade.

A resposta agrupa os provedores por tipo de pagamento — atualmente apenas `PIX`.

<Note>
  Quando o token está [vinculado a um provedor](/guides/intro/provider-scoped-tokens), a resposta retorna apenas aquele provedor nas listas dos `payment_type` em que ele estiver configurado como padrão. Os outros aparecem como array vazio.
</Note>

<RequestExample>
  ```bash theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/providers/defaults' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "PIX": [
        {
          "uuid": "9f1c0a30-3b8c-4a82-a4d7-2b8e93b1f001",
          "status": "ACTIVE",
          "provider": "DELFINANCE",
          "type": "NOMINAL",
          "is_operational": true,
          "is_public": true,
          "virtual_account": {
            "type": "NOMINAL",
            "name": "Empresa Demo LTDA",
            "document": "12345678000190",
            "account_number": "9876543",
            "account_agency": "0001",
            "bank": {
              "code": "",
              "name": "PLOWF IP LTDA.",
              "ispb": "00000000"
            },
            "account_type": "CHECKING"
          }
        },
        {
          "uuid": "9f1c0a30-3b8c-4a82-a4d7-2b8e93b1f002",
          "status": "ACTIVE",
          "provider": "WOOVI",
          "type": "POOL",
          "is_operational": true,
          "is_public": false,
          "virtual_account": null
        }
      ]
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object">
  Mapa chaveado por tipo de pagamento. Cada valor é a lista priorizada de provedores utilizados como padrão para aquele tipo.

  <Expandable title="atributos">
    <ResponseField name="PIX" type="object[]">
      Lista priorizada de provedores usados para operações PIX. O primeiro item é o padrão; os seguintes são fallbacks na ordem fornecida quando você chama [`PUT /providers/defaults`](/api-reference/providers/defaults-set).

      Cada item segue o mesmo formato do endpoint de [listagem de provedores](/api-reference/providers/list). Apenas provedores em estado operacional são retornados.
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>


# Definir Provedores Padrão
Source: https://docs.plowf.com/api-reference/providers/defaults-set

PUT /api/v1/providers/defaults

Atualiza a lista priorizada de provedores usados como padrão para um tipo de pagamento. A ordem do array define a prioridade: o primeiro UUID é o provedor preferencial; os seguintes são fallbacks acionados quando o anterior falha.

A chamada substitui a configuração anterior para o `payment_type` informado — provedores ausentes do array são removidos da lista de defaults.

<Warning>
  Este endpoint **não é permitido** para tokens [vinculados a um provedor](/guides/intro/provider-scoped-tokens). Use um token sem escopo de provedor para alterar a configuração de defaults da conta.
</Warning>

<RequestExample>
  ```bash theme={null}
  curl -X PUT 'https://app.plowf.com/api/v1/providers/defaults' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{
      "payment_type": "PIX",
      "provider_uuids": [
        "9f1c0a30-3b8c-4a82-a4d7-2b8e93b1f001",
        "9f1c0a30-3b8c-4a82-a4d7-2b8e93b1f002"
      ]
    }'
  ```
</RequestExample>

## Body Parameters

<ParamField type="string">
  Tipo de pagamento para o qual a configuração se aplica. Valores aceitos: `PIX`.
</ParamField>

<ParamField type="string[]">
  Lista ordenada de UUIDs dos provedores (1 a 10 itens, sem duplicatas). Use [`GET /providers`](/api-reference/providers/list) para descobrir os UUIDs disponíveis na conta. Todos os UUIDs devem pertencer a provedores com status `ACTIVE`.
</ParamField>

## Validações

* `payment_type` deve ser um dos valores válidos (`PIX`)
* `provider_uuids` deve conter entre **1 e 10** UUIDs, todos válidos e sem repetição
* Cada UUID deve pertencer à conta autenticada **e** referenciar um provedor com `status = ACTIVE`

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "message": "Provedores padrão atualizados com sucesso."
  }
  ```
</ResponseExample>

<ResponseField name="message" type="string">
  Mensagem de confirmação da atualização
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="400">
  Um ou mais provedores não foram encontrados ou não estão ativos. Verifique se todos os UUIDs em `provider_uuids` pertencem à conta e estão com `status = ACTIVE`.
</ErrorField>

<ErrorField name="403">
  Operação não permitida para tokens vinculados a um provedor. Use um token sem escopo de provedor.
</ErrorField>

<ErrorField name="422">
  Erro de validação. Possíveis causas:

  * `payment_type` ausente ou inválido
  * `provider_uuids` vazio, com mais de 10 itens ou contendo duplicatas
  * Algum item de `provider_uuids` não é um UUID válido
</ErrorField>


# Detalhar Provedor
Source: https://docs.plowf.com/api-reference/providers/get

GET /api/v1/providers/{providerUuid}

Retorna os detalhes de um provedor específico.

<Note>
  Quando o token está [vinculado a um provedor](/guides/intro/provider-scoped-tokens) diferente do informado em `{providerUuid}`, a API responde com **404**.
</Note>

<RequestExample>
  ```bash theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/providers/9f1c0a30-3b8c-4a82-a4d7-2b8e93b1f001' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Path Parameters

<ParamField type="string">
  UUID do provedor
</ParamField>

## Resposta de Sucesso

A resposta tem a mesma estrutura de cada item do endpoint de [listagem](/api-reference/providers/list).

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "uuid": "9f1c0a30-3b8c-4a82-a4d7-2b8e93b1f001",
      "status": "ACTIVE",
      "provider": "DELFINANCE",
      "type": "NOMINAL",
      "is_operational": true,
      "is_public": true,
      "virtual_account": {
        "type": "NOMINAL",
        "name": "Empresa Demo LTDA",
        "document": "12345678000190",
        "account_number": "9876543",
        "account_agency": "0001",
        "bank": {
          "code": "",
          "name": "PLOWF IP LTDA.",
          "ispb": "00000000"
        },
        "account_type": "CHECKING"
      },
      "balances": [
        {
          "available_balance": 1500.00,
          "pending_balance": 0,
          "blocked_balance": 0,
          "retained_balance": 0,
          "provisioned_balance": 0,
          "currency": "BRL"
        }
      ]
    }
  }
  ```
</ResponseExample>

Para a descrição de cada campo, consulte a página de [listagem](/api-reference/providers/list).

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="404">
  Provedor não encontrado. Verifique se o UUID está correto e se ele pertence à conta autenticada.
</ErrorField>


# Listar Provedores
Source: https://docs.plowf.com/api-reference/providers/list

GET /api/v1/providers

Lista os provedores disponíveis na conta autenticada. Cada provedor representa uma integração ativa da conta com um provedor financeiro — você pode ter mais de um ativo simultaneamente, com saldos e limites próprios.

<Note>
  Quando o token está [vinculado a um provedor](/guides/intro/provider-scoped-tokens), a resposta retorna apenas aquele provedor.
</Note>

<RequestExample>
  ```bash theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/providers?per_page=20' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Parâmetros de Query

Todos os parâmetros são opcionais.

<ParamField type="integer">
  Número de itens por página (mínimo: 1, máximo: 100)
</ParamField>

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "uuid": "9f1c0a30-3b8c-4a82-a4d7-2b8e93b1f001",
        "status": "ACTIVE",
        "provider": "DELFINANCE",
        "type": "NOMINAL",
        "is_operational": true,
        "is_public": true,
        "virtual_account": {
          "type": "NOMINAL",
          "name": "Empresa Demo LTDA",
          "document": "12345678000190",
          "account_number": "9876543",
          "account_agency": "0001",
          "bank": {
            "code": "",
            "name": "PLOWF IP LTDA.",
            "ispb": "00000000"
          },
          "account_type": "CHECKING"
        },
        "balances": [
          {
            "available_balance": 1500.00,
            "pending_balance": 0,
            "blocked_balance": 0,
            "retained_balance": 0,
            "provisioned_balance": 0,
            "currency": "BRL"
          }
        ]
      },
      {
        "uuid": "9f1c0a30-3b8c-4a82-a4d7-2b8e93b1f002",
        "status": "ACTIVE",
        "provider": "WOOVI",
        "type": "POOL",
        "is_operational": true,
        "is_public": false,
        "virtual_account": null,
        "balances": [
          {
            "available_balance": 250.50,
            "pending_balance": 0,
            "blocked_balance": 0,
            "retained_balance": 0,
            "provisioned_balance": 0,
            "currency": "BRL"
          }
        ]
      }
    ],
    "meta": {
      "current_page": 1,
      "last_page": 1,
      "from": 1,
      "to": 2,
      "total": 2,
      "per_page": 10
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object[]">
  Lista de provedores

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID do provedor. Use este valor em `provider_uuid` ao [criar uma transferência](/api-reference/transfers/create) ou ao [definir um provedor padrão](/api-reference/providers/defaults-set).
    </ResponseField>

    <ResponseField name="status" type="string">
      Status do provedor. Valores possíveis: `UNDEFINED`, `ACTIVE`, `INFORMATION_PENDING`, `KYC_PENDING`, `KYC_ANALYSIS`, `KYC_REJECTED`, `LIVENESS_PENDING`, `LIVENESS_APPROVED`, `LIVENESS_REJECTED`, `CONFIGURATION_PENDING`, `BLOCKED`, `INACTIVE`.
    </ResponseField>

    <ResponseField name="provider" type="string">
      Nome do provedor por trás da integração. Valores possíveis: `DELFINANCE`, `WOOVI`, `MINHA_KONTA`, `A55`.
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo da integração. `NOMINAL` representa uma conta dedicada da sua empresa no provedor (suporta criação de chaves PIX). `POOL` representa uma conta compartilhada/pool gerenciada pela Plowf.
    </ResponseField>

    <ResponseField name="is_operational" type="boolean">
      Indica se o provedor está apto para movimentações no momento. Combina `status = ACTIVE` com a saúde da integração.
    </ResponseField>

    <ResponseField name="is_public" type="boolean">
      Indica se a integração pode ser referenciada publicamente pela conta (selecionável em chamadas).
    </ResponseField>

    <ResponseField name="virtual_account" type="object">
      Dados bancários da conta virtual associada ao provedor (presente para integrações `NOMINAL`).

      <Expandable title="atributos">
        <ResponseField name="type" type="string">Tipo da conta virtual (`NOMINAL` ou `POOL`)</ResponseField>
        <ResponseField name="name" type="string">Razão social ou nome do titular</ResponseField>
        <ResponseField name="document" type="string">CPF ou CNPJ do titular</ResponseField>
        <ResponseField name="account_number" type="string">Número da conta</ResponseField>
        <ResponseField name="account_agency" type="string">Agência</ResponseField>

        <ResponseField name="bank" type="object">
          <Expandable title="atributos">
            <ResponseField name="code" type="string">Código COMPE do banco</ResponseField>
            <ResponseField name="name" type="string">Nome do banco</ResponseField>
            <ResponseField name="ispb" type="string">ISPB do banco</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="account_type" type="string">Tipo da conta (ex: `CHECKING`)</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="balances" type="object[]">
      Saldos do provedor por moeda.

      <Expandable title="atributos">
        <ResponseField name="available_balance" type="number">Saldo disponível para movimentação</ResponseField>
        <ResponseField name="pending_balance" type="number">Saldo pendente de liquidação</ResponseField>
        <ResponseField name="blocked_balance" type="number">Saldo bloqueado</ResponseField>
        <ResponseField name="retained_balance" type="number">Saldo retido</ResponseField>
        <ResponseField name="provisioned_balance" type="number">Saldo provisionado para débitos futuros</ResponseField>
        <ResponseField name="currency" type="string">Moeda (ex: `BRL`)</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Metadados de paginação

  <Expandable title="atributos">
    <ResponseField name="current_page" type="number">
      Página atual
    </ResponseField>

    <ResponseField name="from" type="number">
      Índice do primeiro item da página
    </ResponseField>

    <ResponseField name="last_page" type="number">
      Última página disponível
    </ResponseField>

    <ResponseField name="per_page" type="number">
      Itens por página
    </ResponseField>

    <ResponseField name="to" type="number">
      Índice do último item da página
    </ResponseField>

    <ResponseField name="total" type="number">
      Total de itens
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>


# Criar Transferência
Source: https://docs.plowf.com/api-reference/transfers/create

POST /api/v1/transfers

Cria uma nova transferência PIX Out (envio de dinheiro).

<RequestExample>
  ```bash Default theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/transfers' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{
      "value": 100.50,
      "pix_key": "12345678900",
      "document": "98765432100",
      "external_ref": "REF-001",
      "final_beneficiary": {
        "name": "João Silva",
        "document": "12345678900"
      }
    }'
  ```

  ```bash Provedor específico theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/transfers' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{
      "value": 100.50,
      "pix_key": "12345678900",
      "provider_uuid": "9f1c0a30-3b8c-4a82-a4d7-2b8e93b1f001"
    }'
  ```
</RequestExample>

## Body Parameters

<ParamField type="number">
  Valor da transferência. Mínimo: 0.01
</ParamField>

<ParamField type="string">
  Chave PIX do destinatário. Formatos aceitos:

  * **CPF**: 11 dígitos sem formatação (ex: `52998224725`)
  * **CNPJ**: 14 dígitos sem formatação (ex: `12345678000100`)
  * **E-mail**: endereço válido (ex: `user@email.com`)
  * **Telefone**: número com código do país (ex: `+5511999999999`)
  * **Chave aleatória**: UUID (ex: `550e8400-e29b-41d4-a716-446655440000`)
</ParamField>

<ParamField type="string">
  Documento do destinatário (CPF ou CNPJ). Deve ser válido se informado.
</ParamField>

<ParamField type="string">
  Referência externa para identificação da transferência
</ParamField>

<ParamField type="string">
  UUID do provedor a ser usado como origem da transferência. Quando omitido, a Plowf escolhe o provedor padrão da conta para PIX (configurável em [`PUT /providers/defaults`](/api-reference/providers/defaults-set)). Liste os UUIDs disponíveis em [`GET /providers`](/api-reference/providers/list).

  Ignorado quando o token está [vinculado a um provedor](/guides/intro/provider-scoped-tokens) — neste caso, o provedor do token sempre prevalece.
</ParamField>

<ParamField type="object">
  Dados do beneficiário final (seller)

  <Expandable title="atributos">
    <ParamField type="string">
      Nome do beneficiário final
    </ParamField>

    <ParamField type="string">
      Documento do beneficiário final - CPF ou CNPJ válido
    </ParamField>
  </Expandable>
</ParamField>

## Validações

* `value` deve ser maior que **0.01**
* Se `final_beneficiary` for enviado, ambos `name` e `document` são **obrigatórios**
* `document` deve ser um **CPF ou CNPJ válido** se informado
* `pix_key` deve ter no máximo **255 caracteres**
* `provider_uuid`, se informado, deve referenciar um provedor existente na conta. Se omitido, o provedor padrão de PIX da conta é usado.

## Resposta de Sucesso

A resposta retorna o objeto da transferência criada com a mesma estrutura do endpoint de listagem, mas sem paginação.

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "value": 100.5,
      "fees": 0.5,
      "currency": "BRL",
      "status": "PROCESSING",
      "type": "PIX",
      "external_ref": "REF-001",
      "final_beneficiary": {
        "name": "João Silva",
        "document": "12345678900"
      },
      "transfer": {
        "uuid": "660e8400-e29b-41d4-a716-446655440001",
        "initiation": {
          "sender": {
            "name": "Empresa Exemplo Ltda",
            "document": "00000000000100",
            "account_number": "0000001",
            "account_agency": "0001",
            "bank": {
              "code": "",
              "name": "BANCO EXEMPLO IP LTDA.",
              "ispb": "00000000"
            },
            "account_type": "CHECKING"
          },
          "receiver": {
            "name": "João Silva",
            "document": "123.***.***-00",
            "account_number": "********************",
            "account_agency": "****",
            "bank": {
              "code": "260",
              "name": "BANCO EXEMPLO - IP",
              "ispb": "00000001"
            },
            "account_type": "CHECKING"
          },
          "txid": null,
          "value": 100.5,
          "type": "KEY",
          "pix_key": "12345678900",
          "status": "COMPLETED",
          "expires_at": null,
          "created_at": "2024-01-01T11:59:00Z",
          "updated_at": "2024-01-01T11:59:01Z"
        },
        "value": 100.5,
        "movement_type": "OUT",
        "type": "EXTERNAL_TRANSFER",
        "status": "PROCESSING",
        "end_to_end": "E000000002024010111590000000000",
        "settled_at": null,
        "created_at": "2024-01-01T11:59:00Z",
        "updated_at": "2024-01-01T11:59:01Z"
      },
      "history": [
        {
          "status": "PENDING",
          "created_at": "2024-01-01T11:59:00Z"
        },
        {
          "status": "PROCESSING",
          "created_at": "2024-01-01T11:59:01Z"
        }
      ],
      "created_at": "2024-01-01T11:59:00Z"
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object">
  Dados da transferência criada

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único da transferência
    </ResponseField>

    <ResponseField name="value" type="number">
      Valor da transferência
    </ResponseField>

    <ResponseField name="fees" type="number">
      Taxas aplicadas
    </ResponseField>

    <ResponseField name="currency" type="string">
      Moeda (ex: BRL)
    </ResponseField>

    <ResponseField name="status" type="string">
      Status atual da transferência (PENDING, PROCESSING, PAID, FAILED, REFUNDED, PARTIALLY\_REFUNDED, CANCELLED, EXPIRED)
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo da transferência (ex: PIX)
    </ResponseField>

    <ResponseField name="external_ref" type="string">
      Referência externa (opcional)
    </ResponseField>

    <ResponseField name="error" type="object">
      Presente apenas quando `status = FAILED`. Detalha o motivo retornado pelo provedor.

      <Expandable title="atributos">
        <ResponseField name="code" type="string">
          Código do erro (ex: `INSUFFICIENT_FUNDS`, `INVALID_PIX_KEY`)
        </ResponseField>

        <ResponseField name="message" type="string">
          Descrição legível do erro
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="final_beneficiary" type="object">
      Beneficiário final da cobrança (seller)

      <Expandable title="atributos">
        <ResponseField name="name" type="string">
          Nome do beneficiário final
        </ResponseField>

        <ResponseField name="document" type="string">
          Documento do beneficiário final (CPF ou CNPJ)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponsePixTransaction name="transfer" description="Dados da transferência" />

    <ResponseField name="history" type="object[]">
      Histórico de mudanças de status

      <Expandable title="atributos">
        <ResponseField name="status" type="string">
          Status no histórico
        </ResponseField>

        <ResponseField name="created_at" type="datetime">
          Data e hora do status
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação da transferência
    </ResponseField>
  </Expandable>
</ResponseField>

## Resposta de Falha (transferência rejeitada pelo provedor)

Quando o provedor recusa a transferência, a API responde com **HTTP 400** e o mesmo payload de sucesso, porém com `status = "FAILED"` e o objeto `error` populado. Diferente de um erro 4xx clássico, o transfer é persistido — você pode consultá-lo depois via [`GET /transfers/{uuid}`](/api-reference/transfers/get) ou pelo `external_ref`.

<ResponseExample>
  ```json theme={null}
  {
    "message": "Saldo insuficiente para realizar transferência",
    "data": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "value": 100.5,
      "fees": 0.5,
      "currency": "BRL",
      "status": "FAILED",
      "type": "PIX",
      "pix_key": "12345678900",
      "external_ref": "REF-001",
      "error": {
        "code": "INSUFFICIENT_FUNDS",
        "message": "Saldo insuficiente para realizar transferência"
      },
      "created_at": "2024-01-01T11:59:00Z"
    }
  }
  ```
</ResponseExample>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="400">
  Falha ao processar a transferência. O corpo inclui o transfer no estado `FAILED` e o objeto `error` com o motivo retornado pelo provedor (ex: saldo insuficiente, chave PIX inexistente, indisponibilidade do destinatário).
</ErrorField>

<ErrorField name="422">
  Erro de validação. Possíveis causas:

  * Valor menor que 0.01
  * Chave PIX inválida
  * Documento inválido
  * Beneficiário final incompleto
  * `provider_uuid` não pertence à conta ou está inativo
</ErrorField>


# Detalhar Transferência
Source: https://docs.plowf.com/api-reference/transfers/get

GET /api/v1/transfers/{transferUuid}

Retorna os detalhes completos de uma transferência específica.

<RequestExample>
  ```bash theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/transfers/550e8400-e29b-41d4-a716-446655440000' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Path Parameters

<ParamField type="string">
  UUID da transferência que deseja consultar
</ParamField>

## Resposta de Sucesso

A resposta retorna o objeto completo da transferência com a mesma estrutura do endpoint de listagem.

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "value": 100.5,
      "fees": 0.5,
      "currency": "BRL",
      "status": "PAID",
      "type": "PIX",
      "external_ref": "REF-001",
      "final_beneficiary": {
        "name": "João Silva",
        "document": "12345678900"
      },
      "transfer": {
        "uuid": "660e8400-e29b-41d4-a716-446655440001",
        "initiation": {
          "sender": {
            "name": "Empresa Exemplo Ltda",
            "document": "00000000000100",
            "account_number": "0000001",
            "account_agency": "0001",
            "bank": {
              "code": "",
              "name": "BANCO EXEMPLO IP LTDA.",
              "ispb": "00000000"
            },
            "account_type": "CHECKING"
          },
          "receiver": {
            "name": "João Silva",
            "document": "123.***.***-00",
            "account_number": "********************",
            "account_agency": "****",
            "bank": {
              "code": "260",
              "name": "BANCO EXEMPLO - IP",
              "ispb": "00000001"
            },
            "account_type": "CHECKING"
          },
          "txid": null,
          "value": 100.5,
          "type": "KEY",
          "pix_key": "12345678900",
          "status": "COMPLETED",
          "expires_at": null,
          "created_at": "2024-01-01T11:59:00Z",
          "updated_at": "2024-01-01T11:59:01Z"
        },
        "value": 100.5,
        "movement_type": "OUT",
        "type": "EXTERNAL_TRANSFER",
        "status": "SETTLED",
        "end_to_end": "E000000002024010111590000000000",
        "settled_at": "2024-01-01T11:59:00Z",
        "created_at": "2024-01-01T11:59:00Z",
        "updated_at": "2024-01-01T11:59:01Z"
      },
      "history": [
        {
          "status": "PENDING",
          "created_at": "2024-01-01T11:59:00Z"
        },
        {
          "status": "PROCESSING",
          "created_at": "2024-01-01T11:59:30Z"
        },
        {
          "status": "PAID",
          "created_at": "2024-01-01T12:00:00Z"
        }
      ],
      "created_at": "2024-01-01T11:59:00Z"
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object">
  Dados completos da transferência

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único da transferência
    </ResponseField>

    <ResponseField name="value" type="number">
      Valor da transferência
    </ResponseField>

    <ResponseField name="fees" type="number">
      Taxas aplicadas
    </ResponseField>

    <ResponseField name="currency" type="string">
      Moeda (ex: BRL)
    </ResponseField>

    <ResponseField name="status" type="string">
      Status atual da transferência (PENDING, PROCESSING, PAID, FAILED, REFUNDED, PARTIALLY\_REFUNDED, CANCELLED, EXPIRED)
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo da transferência (ex: PIX)
    </ResponseField>

    <ResponseField name="external_ref" type="string">
      Referência externa (opcional)
    </ResponseField>

    <ResponseField name="final_beneficiary" type="object">
      Beneficiário final da cobrança (seller)

      <Expandable title="atributos">
        <ResponseField name="name" type="string">
          Nome do beneficiário final
        </ResponseField>

        <ResponseField name="document" type="string">
          Documento do beneficiário final (CPF ou CNPJ)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponsePixTransaction name="transfer" description="Dados da transferência" />

    <ResponseField name="history" type="object[]">
      Histórico de mudanças de status

      <Expandable title="atributos">
        <ResponseField name="status" type="string">
          Status no histórico
        </ResponseField>

        <ResponseField name="created_at" type="datetime">
          Data e hora do status
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="404">
  Transferência não encontrada. Verifique se o UUID está correto e se você tem permissão para acessá-la.
</ErrorField>


# Listar Transferências
Source: https://docs.plowf.com/api-reference/transfers/list

GET /api/v1/transfers

Lista todas as transferências da conta autenticada com paginação e filtros avançados.

<RequestExample>
  ```bash theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/transfers?status=PAID&per_page=20' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Parâmetros de Query

Todos os parâmetros são opcionais.

<ParamField type="string">
  Filtrar por UUID específico da transferência
</ParamField>

<ParamField type="string">
  Status da transferência. Valores possíveis: - `UNDEFINED` - `PENDING` - `PAID`

  * `FAILED` - `REFUNDED` - `PARTIALLY_REFUNDED` - `CANCELLED` - `EXPIRED` -
    `PROCESSING`
</ParamField>

<ParamField type="string">
  Tipo da transferência. Valores possíveis: - `UNDEFINED` - `PIX`
</ParamField>

<ParamField type="date">
  Data inicial para filtro (formato: YYYY-MM-DD)
</ParamField>

<ParamField type="date">
  Data final para filtro (formato: YYYY-MM-DD)
</ParamField>

<ParamField type="date">
  Data de transferência inicial (formato: YYYY-MM-DD)
</ParamField>

<ParamField type="date">
  Data de transferência final (formato: YYYY-MM-DD)
</ParamField>

<ParamField type="integer">
  Número de itens por página (mínimo: 1, máximo: 100)
</ParamField>

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "value": 100.5,
        "fees": 0.5,
        "currency": "BRL",
        "status": "PAID",
        "type": "PIX",
        "external_ref": "REF-001",
        "final_beneficiary": {
          "name": "João Silva",
          "document": "12345678900"
        },
        "transfer": {
          "uuid": "660e8400-e29b-41d4-a716-446655440001",
          "initiation": {
            "sender": {
              "name": "Empresa Exemplo Ltda",
              "document": "00000000000100",
              "account_number": "0000001",
              "account_agency": "0001",
              "bank": {
                "code": "",
                "name": "BANCO EXEMPLO IP LTDA.",
                "ispb": "00000000"
              },
              "account_type": "CHECKING"
            },
            "receiver": {
              "name": "João Silva",
              "document": "123.***.***-00",
              "account_number": "********************",
              "account_agency": "****",
              "bank": {
                "code": "260",
                "name": "BANCO EXEMPLO - IP",
                "ispb": "00000001"
              },
              "account_type": "CHECKING"
            },
            "txid": null,
            "value": 100.5,
            "type": "KEY",
            "pix_key": "12345678900",
            "status": "COMPLETED",
            "expires_at": null,
            "created_at": "2024-01-01T11:59:00Z",
            "updated_at": "2024-01-01T11:59:01Z"
          },
          "value": 100.5,
          "movement_type": "OUT",
          "type": "EXTERNAL_TRANSFER",
          "status": "SETTLED",
          "end_to_end": "E000000002024010111590000000000",
          "settled_at": "2024-01-01T11:59:00Z",
          "created_at": "2024-01-01T11:59:00Z",
          "updated_at": "2024-01-01T11:59:01Z"
        },
        "history": [
          {
            "status": "PENDING",
            "created_at": "2024-01-01T11:59:00Z"
          },
          {
            "status": "PROCESSING",
            "created_at": "2024-01-01T11:59:30Z"
          },
          {
            "status": "PAID",
            "created_at": "2024-01-01T12:00:00Z"
          }
        ],
        "created_at": "2024-01-01T11:59:00Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "from": 1,
      "last_page": 10,
      "per_page": 10,
      "to": 10,
      "total": 100
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object[]">
  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único da transferência
    </ResponseField>

    <ResponseField name="value" type="number">
      Valor da transferência
    </ResponseField>

    <ResponseField name="fees" type="number">
      Taxas aplicadas
    </ResponseField>

    <ResponseField name="currency" type="string">
      Moeda (ex: BRL)
    </ResponseField>

    <ResponseField name="status" type="string">
      Status atual da transferência (PENDING, PROCESSING, PAID, FAILED, REFUNDED, PARTIALLY\_REFUNDED, CANCELLED, EXPIRED)
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo da transferência (ex: PIX)
    </ResponseField>

    <ResponseField name="external_ref" type="string">
      Referência externa (opcional)
    </ResponseField>

    <ResponseField name="final_beneficiary" type="object">
      Beneficiário final da cobrança (seller)

      <Expandable title="atributos">
        <ResponseField name="name" type="string">
          Nome do beneficiário final
        </ResponseField>

        <ResponseField name="document" type="string">
          Documento do beneficiário final (CPF ou CNPJ)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponsePixTransaction name="transfer" description="Dados da transferência" />

    <ResponseField name="history" type="object[]">
      Histórico de mudanças de status

      <Expandable title="atributos">
        <ResponseField name="status" type="string">
          Status no histórico
        </ResponseField>

        <ResponseField name="created_at" type="datetime">
          Data e hora do status
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação da transferência
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Metadados de paginação

  <Expandable title="atributos">
    <ResponseField name="current_page" type="number">
      Página atual
    </ResponseField>

    <ResponseField name="from" type="number">
      Índice do primeiro item da página
    </ResponseField>

    <ResponseField name="last_page" type="number">
      Última página disponível
    </ResponseField>

    <ResponseField name="per_page" type="number">
      Itens por página
    </ResponseField>

    <ResponseField name="to" type="number">
      Índice do último item da página
    </ResponseField>

    <ResponseField name="total" type="number">
      Total de itens
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ResponseErrorAuth />


# Criar Webhook
Source: https://docs.plowf.com/api-reference/webhooks/create

POST /api/v1/webhooks

Cria um novo webhook para receber notificações de eventos da plataforma.

<RequestExample>
  ```bash theme={null}
  curl -X POST 'https://app.plowf.com/api/v1/webhooks' \
    -H 'Authorization: Bearer seu_token_aqui' \
    -H 'Content-Type: application/json' \
    -d '{
      "url": "https://webhook.site/04ef5e41-d054-49f9-805c-03a6a345245e",
      "token": "nUeO7RobnrgJxs8mBr1oOvChV4wqOblj"
    }'
  ```
</RequestExample>

## Body Parameters

<ParamField type="string">
  URL do endpoint que receberá os webhooks. Deve ser uma URL válida e acessível via HTTPS.
</ParamField>

<ParamField type="string">
  Token opcional para autenticação dos webhooks. Se não informado, será gerado automaticamente. Este token será usado para validar a assinatura HMAC dos webhooks recebidos.
</ParamField>

<ParamField type="array">
  Eventos que serão enviados para o endpoint. Se não informado, serão enviados todos os eventos.

  <Expandable title="eventos">
    <ResponseField name="PAYMENT" type="string">
      O evento `PAYMENT` é disparado quando o status de um cobrança é atualizado na plataforma
    </ResponseField>

    <ResponseField name="TRANSFER" type="string">
      O evento `TRANSFER` é disparado quando o status de uma transferência é atualizado na plataforma
    </ResponseField>

    <ResponseField name="REFUND" type="string">
      O evento `REFUND` é disparado quando o status de um estorno é atualizado na plataforma
    </ResponseField>

    <ResponseField name="MED" type="string">
      O evento `MED` é disparado quando o status de um MED é atualizado na plataforma
    </ResponseField>

    <ResponseField name="PIX_TRANSACTION" type="string">
      O evento `PIX_TRANSACTION` é disparado quando o status de uma transação PIX recebida via CHAVE PIX ou MANUAL é atualizado na plataforma
    </ResponseField>
  </Expandable>
</ParamField>

## Validações

* `url` deve ser uma **URL válida** e acessível via **HTTPS**
* `url` é **obrigatório**
* `token` é **opcional**. Se não informado, será gerado automaticamente
* `events` é **opcional**. Se não informado, serão enviados todos os eventos

## Resposta de Sucesso

A resposta retorna o objeto do webhook criado com o token gerado (ou o token informado).

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "uuid": "e1afe0f4-9358-4a50-b0fd-55912ca86ee1",
      "url": "https://webhook.site/04ef5e41-d054-49f9-805c-03a6a345245e",
      "token": "nUeO7RobnrgJxs8mBr1oOvChV4wqOblj",
      "status": "ACTIVE",
      "events": [
        "PAYMENT",
        "TRANSFER",
        "REFUND",
        "MED",
        "PIX_TRANSACTION"
      ],
      "created_at": "2026-01-13T00:37:47.000000Z"
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object">
  Dados do webhook criado

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único do webhook
    </ResponseField>

    <ResponseField name="url" type="string">
      URL configurada para receber os webhooks
    </ResponseField>

    <ResponseField name="token" type="string">
      Token usado para validar a assinatura HMAC dos webhooks. Guarde este token com segurança, pois ele será necessário para validar as requisições recebidas.
    </ResponseField>

    <ResponseField name="status" type="string">
      Status do webhook. Valores possíveis: `ACTIVE`, `INACTIVE`
    </ResponseField>

    <ResponseField name="events" type="array">
      Eventos que serão enviados para o endpoint. Valores possíveis: `PAYMENT`, `TRANSFER`, `REFUND`, `MED`, `PIX_TRANSACTION`
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação do webhook
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Guarde o token retornado com segurança. Ele será necessário para validar a assinatura HMAC dos webhooks recebidos. Se você não informou um token, o sistema gerou um automaticamente.
</Note>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="422">
  Erro de validação. Possíveis causas:

  * URL inválida ou não acessível
  * URL não utiliza HTTPS
  * Formato de URL incorreto
</ErrorField>


# Deletar Webhook
Source: https://docs.plowf.com/api-reference/webhooks/delete

DELETE /api/v1/webhooks/{webhookUuid}

Remove um webhook da conta. Após a exclusão, o webhook não receberá mais notificações de eventos.

<RequestExample>
  ```bash theme={null}
  curl -X DELETE 'https://app.plowf.com/api/v1/webhooks/e1afe0f4-9358-4a50-b0fd-55912ca86ee1' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Path Parameters

<ParamField type="string">
  UUID do webhook que deseja deletar
</ParamField>

## Resposta de Sucesso

A resposta retorna uma confirmação de que o webhook foi deletado com sucesso.

<ResponseExample>
  ```json theme={null}
  {
  "message": "Webhook deletado com sucesso"
  }
  ```
</ResponseExample>

<Note>
  Após deletar um webhook, ele não receberá mais notificações de eventos. Esta ação é irreversível.
</Note>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="404">
  Webhook não encontrado. Verifique se o UUID está correto e se você tem permissão para acessá-lo.
</ErrorField>


# Evento MED
Source: https://docs.plowf.com/api-reference/webhooks/events/med

Webhook disparado quando o status de um MED é atualizado

## Visão Geral

O evento `MED` é disparado quando o status de um MED (Mecanismo Especial de Devolução) é atualizado na plataforma. O webhook é enviado quando:

* Um MED é recebido
* Um MED muda de status (ex: `PENDING` → `PROCESSING`, `PROCESSING` → `ACCEPTED`)
* Um MED é resolvido

## Headers do Webhook

```
X-Webhook-Event: MED
X-Webhook-Timestamp: 2024-01-15T12:00:00Z
X-Webhook-Signature: abc123def456...
Content-Type: application/json
```

## Estrutura do Payload

<ResponseExample>
  ```json theme={null}
  {
    "event": "MED",
    "timestamp": "2024-01-15T12:00:00Z",
    "data": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "pix_in_transaction": {
        "uuid": "660e8400-e29b-41d4-a716-446655440001",
        "initiation": {
          "sender": {
            "name": "João Silva",
            "document": "12345678900",
            "account_number": "12345678",
            "account_agency": "0001",
            "bank": {
              "code": "001",
              "name": "Banco Exemplo",
              "ispb": "00000000"
            },
            "account_type": "PAYMENT"
          },
          "receiver": {
            "name": "Empresa Exemplo LTDA",
            "document": "12345678000199",
            "account_number": "87654321",
            "account_agency": "0001",
            "bank": {
              "code": "002",
              "name": "Banco Recebedor",
              "ispb": "00000001"
            },
            "account_type": "CHECKING"
          },
          "txid": "txid123456789abcdef",
          "value": "150.00",
          "type": "QR_DYNAMIC",
          "pix_key": "770e8400-e29b-41d4-a716-446655440002",
          "status": "COMPLETED",
          "expires_at": "2024-01-02T23:59:59.000000Z",
          "created_at": "2024-01-01T10:00:00.000000Z",
          "updated_at": "2024-01-01T10:05:00.000000Z"
        },
        "value": "150.00",
        "movement_type": "IN",
        "type": "EXTERNAL_TRANSFER",
        "status": "SETTLED",
        "end_to_end": "E00000000202401011000abcdef12345",
        "settled_at": "2024-01-01T10:05:00.000000Z",
        "created_at": "2024-01-01T10:05:00.000000Z",
        "updated_at": "2024-01-01T10:05:00.000000Z"
      },
      "attachments": [
        {
          "uuid": "990e8400-e29b-41d4-a716-446655440004",
          "url": "https://app.plowf.com/attachments/meds/550e8400-e29b-41d4-a716-446655440000/990e8400-e29b-41d4-a716-446655440004.jpg"
        }
      ],
      "med_type": "RECEIVED_MED",
      "dispute_type": "SCAM",
      "status": "PROCESSING",
      "details": "01",
      "analysis": null,
      "resolved": false,
      "created_at": "2024-01-15T12:00:00.000000Z",
      "updated_at": "2024-01-15T12:00:00.000000Z"
    }
  }
  ```
</ResponseExample>

## Campos do Payload

<ResponseField name="event" type="string">
  Tipo do evento. Sempre `"MED"` para este webhook.
</ResponseField>

<ResponseField name="timestamp" type="datetime">
  Timestamp ISO 8601 do momento em que o webhook foi enviado.
</ResponseField>

<ResponseField name="data" type="object">
  Dados do MED atualizado.

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único do MED.
    </ResponseField>

    <ResponsePixTransaction name="pix_in_transaction" />

    <ResponseField name="attachments" type="object[]">
      Anexos do MED (comprovantes, documentos).

      <Expandable title="atributos">
        <ResponseField name="uuid" type="string">
          UUID do anexo.
        </ResponseField>

        <ResponseField name="url" type="string">
          URL do anexo.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="med_type" type="string">
      Tipo do MED. Valores possíveis: `RECEIVED_MED`, `REQUESTED_MED`.
    </ResponseField>

    <ResponseField name="dispute_type" type="string">
      Tipo da disputa. Valores possíveis: `UNDEFINED`, `SCAM`, `WRONG_TRANSACTION`, `COERCION_CRIME`, `UNAUTHORIZED_ACCESS`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Status atual do MED.
    </ResponseField>

    <ResponseField name="details" type="string">
      Detalhes adicionais do MED.
    </ResponseField>

    <ResponseField name="analysis" type="string">
      Análise do MED.
    </ResponseField>

    <ResponseField name="resolved" type="boolean">
      Indica se o MED foi resolvido.
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação.
    </ResponseField>

    <ResponseField name="updated_at" type="datetime">
      Data e hora da última atualização.
    </ResponseField>
  </Expandable>
</ResponseField>

## Status Possíveis

Os status possíveis para um MED são:

* `PENDING` - Aguardando processamento
* `PROCESSING` - MED em processamento
* `ACCEPTED` - MED aceito
* `REJECTED` - MED rejeitado
* `CANCELLED` - MED cancelado

## Tipos de Disputa

Os tipos de disputa possíveis são:

* `UNDEFINED` - Tipo não definido
* `SCAM` - Fraude/golpe
* `WRONG_TRANSACTION` - Transação incorreta
* `COERCION_CRIME` - Crime de coação
* `UNAUTHORIZED_ACCESS` - Acesso não autorizado

<Note>
  Use o campo `uuid` para identificar unicamente o MED e implementar idempotência no seu endpoint. O webhook será enviado a cada mudança de status, então é importante tratar eventos duplicados.
</Note>

<Warning>
  MEDs possuem prazo para resposta. Monitore os eventos de MED e responda dentro do prazo estabelecido pelo Banco Central para evitar aprovação automática.
</Warning>


# Evento PAYMENT
Source: https://docs.plowf.com/api-reference/webhooks/events/payment

Webhook disparado quando o status de um cobrança é atualizado

## Visão Geral

O evento `PAYMENT` é disparado quando o status de um cobrança PIX In é atualizado na plataforma. O webhook é enviado quando:

* Um cobrança muda de status (ex: `PENDING` → `PAID`, `PAID` → `REFUNDED`)

## Headers do Webhook

```
X-Webhook-Event: PAYMENT
X-Webhook-Timestamp: 2024-01-15T10:30:00Z
X-Webhook-Signature: abc123def456...
Content-Type: application/json
```

## Estrutura do Payload

<ResponseExample>
  ```json theme={null}
  {
    "event": "PAYMENT",
    "timestamp": "2024-01-15T10:30:00Z",
    "data": {
      "uuid": "770e8400-e29b-41d4-a716-446655440000",
      "value": 250,
      "total_value": 255,
      "fees": 5,
      "currency": "BRL",
      "status": "PAID",
      "type": "PIX",
      "payment": {
        "uuid": "880e8400-e29b-41d4-a716-446655440001",
        "value": "250.00",
        "type": "QR_DYNAMIC",
        "status": "COMPLETED",
        "payload": "00020101021226570014br.gov.bcb.pix2535qr.plowf.com/qr/v2/cob/770e8400-e29b-41d4-a71652040000530398654062500.005802BR5912Empresa_Demo6009Sao_Paulo62290525770e8400e29b41d4a716446663041A2B",
        "pix": {
          "sender": {
            "name": "João Silva",
            "document": "12345678901",
            "account_number": "00123456",
            "account_agency": "0001",
            "bank": {
              "code": "341",
              "name": "ITAÚ UNIBANCO S.A.",
              "ispb": "60701190"
            },
            "account_type": "CHECKING"
          },
          "receiver": {
            "name": "Empresa Demo LTDA",
            "document": "12345678000190",
            "account_number": "9876543",
            "account_agency": "0001",
            "bank": {
              "code": "",
              "name": "PLOWF IP LTDA.",
              "ispb": "00000000"
            },
            "account_type": "CHECKING"
          },
          "txid": "770e8400e29b41d4a716446655440000",
          "value": "250.00",
          "type": "QR_DYNAMIC",
          "pix_key": "1234567890",
          "transaction": {
            "uuid": "990e8400-e29b-41d4-a716-446655440002",
            "value": "250.00",
            "movement_type": "IN",
            "type": "EXTERNAL_TRANSFER",
            "status": "SETTLED",
            "end_to_end": "E6070119020240101100500000000001",
            "settled_at": "2024-01-01T10:05:00.000000Z",
            "created_at": "2024-01-01T10:02:00.000000Z",
            "updated_at": "2024-01-01T10:05:00.000000Z"
          },
          "status": "COMPLETED",
          "expires_at": "2024-03-01T10:00:00.000000Z",
          "created_at": "2024-01-01T10:00:00.000000Z",
          "updated_at": "2024-01-01T10:05:00.000000Z"
        },
        "verify_sender": false,
        "expires_at": "2024-03-01T10:00:00.000000Z",
        "created_at": "2024-01-01T10:00:00.000000Z",
        "updated_at": "2024-01-01T10:05:00.000000Z"
      },
      "external_ref": "PED-001",
      "final_beneficiary": {
        "name": "Maria Santos",
        "document": "98765432100"
      },
      "splits": [
        {
          "uuid": "990e8400-e29b-41d4-a716-446655440002",
          "type": "PERCENTAGE",
          "value": 10,
          "status": "CREDITED",
          "recipient_account": {
            "uuid": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Empresa Parceira LTDA"
          }
        }
      ],
      "history": [
        {
          "status": "PENDING",
          "created_at": "2024-01-01T10:00:00Z"
        },
        {
          "status": "PROCESSING",
          "created_at": "2024-01-01T10:02:00Z"
        },
        {
          "status": "PAID",
          "created_at": "2024-01-01T10:05:00Z"
        }
      ],
      "created_at": "2024-01-01T10:00:00Z",
      "updated_at": "2024-01-01T10:05:00Z"
    }
  }
  ```
</ResponseExample>

## Campos do Payload

<ResponseField name="event" type="string">
  Tipo do evento. Sempre `"PAYMENT"` para este webhook.
</ResponseField>

<ResponseField name="timestamp" type="datetime">
  Timestamp ISO 8601 do momento em que o webhook foi enviado.
</ResponseField>

<ResponseField name="data" type="object">
  Dados da cobrança atualizada.

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único da cobrança.
    </ResponseField>

    <ResponseField name="value" type="number">
      Valor da cobrança.
    </ResponseField>

    <ResponseField name="total_value" type="number">
      Valor total incluindo taxas.
    </ResponseField>

    <ResponseField name="fees" type="number">
      Taxas aplicadas à cobrança.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Moeda da cobrança (ex: "BRL").
    </ResponseField>

    <ResponseField name="status" type="string">
      Status atual da cobrança. Valores possíveis: `PENDING`, `PAID`, `FAILED`, `CANCELLED`.
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo da cobrança (ex: "PIX").
    </ResponseField>

    <ResponsePixCharge />

    <ResponseField name="external_ref" type="string">
      Referência externa fornecida na criação da cobrança.
    </ResponseField>

    <ResponseField name="final_beneficiary" type="object">
      Beneficiário final da cobrança (seller)

      <Expandable title="atributos">
        <ResponseField name="name" type="string">
          Nome do beneficiário final
        </ResponseField>

        <ResponseField name="document" type="string">
          Documento do beneficiário final (CPF ou CNPJ)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="splits" type="object[]">
      Lista de splits aplicados à cobrança

      <Expandable title="atributos">
        <ResponseField name="uuid" type="string">
          UUID único do split
        </ResponseField>

        <ResponseField name="type" type="string">
          Tipo do split: `PERCENTAGE` ou `FIXED`
        </ResponseField>

        <ResponseField name="value" type="number">
          Valor do split. Para `PERCENTAGE`, representa o percentual. Para `FIXED`, o valor em reais
        </ResponseField>

        <ResponseField name="status" type="string">
          Status do split: `PENDING`, `CREDITED` ou `FAILED`
        </ResponseField>

        <ResponseField name="recipient_account" type="object">
          Conta destinatária do split

          <Expandable title="atributos">
            <ResponseField name="uuid" type="string">
              UUID da conta destinatária
            </ResponseField>

            <ResponseField name="name" type="string">
              Nome da conta destinatária
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="history" type="object[]">
      Histórico de mudanças de status

      <Expandable title="atributos">
        <ResponseField name="status" type="string">
          Status no histórico
        </ResponseField>

        <ResponseField name="created_at" type="datetime">
          Data e hora do status
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação da cobrança.
    </ResponseField>

    <ResponseField name="updated_at" type="datetime">
      Data e hora da última atualização.
    </ResponseField>
  </Expandable>
</ResponseField>

## Status Possíveis

Os status possíveis para um cobrança são:

* `PENDING` - Aguardando pagamento
* `PAID` - Cobrança paga
* `FAILED` - Cobrança falhou
* `REFUNDED` - Cobrança estornada
* `PARTIALLY_REFUNDED` - Cobrança estornada parcialmente
* `CANCELLED` - Cobrança cancelada
* `EXPIRED` - Cobrança expirada
* `PROCESSING` - Cobrança em processamento

<Note>
  Use o campo `uuid` para identificar unicamente a cobrança e implementar idempotência no seu endpoint.
</Note>


# Evento PIX_TRANSACTION
Source: https://docs.plowf.com/api-reference/webhooks/events/pix-transaction

Webhook disparado quando o status de uma transação PIX recebida é atualizado

## Visão Geral

O evento `PIX_TRANSACTION` é disparado quando o status de uma transação PIX recebida diretamente (via chave ou manual) é atualizado na plataforma. O webhook é enviado quando:

* Uma transação PIX recebida muda de status (ex: `PENDING` → `SETTLED`, `PENDING` → `FAILED`)

<Note>
  Este evento cobre apenas transações PIX recebidas via **chave PIX** ou **transferência manual**. Para cobranças PIX (QR Code), utilize o evento `PAYMENT`.
</Note>

## Headers do Webhook

```
X-Webhook-Event: PIX_TRANSACTION
X-Webhook-Timestamp: 2024-01-15T10:30:00Z
X-Webhook-Signature: abc123def456...
Content-Type: application/json
```

## Estrutura do Payload

<ResponseExample>
  ```json theme={null}
  {
    "event": "PIX_TRANSACTION",
    "timestamp": "2024-01-15T10:30:00Z",
    "data": {
      "uuid": "990e8400-e29b-41d4-a716-446655440002",
      "initiation": {
        "sender": {
          "name": "João Silva",
          "document": "12345678901",
          "account_number": "00123456",
          "account_agency": "0001",
          "bank": {
            "code": "341",
            "name": "ITAÚ UNIBANCO S.A.",
            "ispb": "60701190"
          },
          "account_type": "CHECKING"
        },
        "receiver": {
          "name": "Empresa Demo LTDA",
          "document": "12345678000190",
          "account_number": "9876543",
          "account_agency": "0001",
          "bank": {
            "code": "",
            "name": "PLOWF IP LTDA.",
            "ispb": "00000000"
          },
          "account_type": "CHECKING"
        },
        "txid": null,
        "value": 150.0,
        "type": "KEY",
        "pix_key": "joao@email.com",
        "description": "Pagamento de serviço",
        "status": "COMPLETED",
        "expires_at": null,
        "created_at": "2024-01-15T10:28:00.000000Z",
        "updated_at": "2024-01-15T10:30:00.000000Z"
      },
      "value": 150.0,
      "movement_type": "IN",
      "type": "EXTERNAL_TRANSFER",
      "status": "SETTLED",
      "end_to_end": "E6070119020240115103000000000001",
      "settled_at": "2024-01-15T10:30:00.000000Z",
      "created_at": "2024-01-15T10:28:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  }
  ```
</ResponseExample>

## Campos do Payload

<ResponseField name="event" type="string">
  Tipo do evento. Sempre `"PIX_TRANSACTION"` para este webhook.
</ResponseField>

<ResponseField name="timestamp" type="datetime">
  Timestamp ISO 8601 do momento em que o webhook foi enviado.
</ResponseField>

<ResponsePixTransaction name="data" description="Transação PIX recebida" />

## Status Possíveis

Os status possíveis para uma transação PIX são:

* `PENDING` - Aguardando liquidação
* `SETTLED` - Transação liquidada com sucesso
* `FAILED` - Transação falhou
* `REFUNDED` - Transação estornada parcialmente ou totalmente

<Note>
  Use o campo `uuid` para identificar unicamente a transação e implementar idempotência no seu endpoint.
</Note>


# Evento REFUND
Source: https://docs.plowf.com/api-reference/webhooks/events/refund

Webhook disparado quando o status de um estorno é atualizado

## Visão Geral

O evento `REFUND` é disparado quando o status de um estorno é atualizado na plataforma. O webhook é enviado quando:

* Um estorno muda de status (ex: `PROCESSING` → `SETTLED`, `PROCESSING` → `FAILED`)

## Headers do Webhook

```
X-Webhook-Event: REFUND
X-Webhook-Timestamp: 2024-01-15T11:00:00Z
X-Webhook-Signature: abc123def456...
Content-Type: application/json
```

## Estrutura do Payload

<ResponseExample>
  ```json theme={null}
  {
    "event": "REFUND",
    "timestamp": "2024-01-15T11:00:00Z",
    "data": {
      "uuid": "770e8400-e29b-41d4-a716-446655440000",
      "status": "PROCESSING",
      "value": 247.99,
      "fees": 0.5,
      "refund": {
        "status": "PROCESSING",
        "value": 247.99,
        "fees": 0.5,
        "pix_original": {
          "uuid": "880e8400-e29b-41d4-a716-446655440001",
          "initiation": {
            "sender": {
              "name": "João Silva",
              "document": "12345678901",
              "account_number": "00123456",
              "account_agency": "0001",
              "bank": {
                "code": "341",
                "name": "ITAÚ UNIBANCO S.A.",
                "ispb": "60701190"
              },
              "account_type": "CHECKING"
            },
            "receiver": {
              "name": "Empresa Demo LTDA",
              "document": "12345678000190",
              "account_number": "9876543",
              "account_agency": "0001",
              "bank": {
                "code": "",
                "name": "PLOWF IP LTDA.",
                "ispb": "00000000"
              },
              "account_type": "CHECKING"
            },
            "txid": "770e8400e29b41d4a716446655440000",
            "value": "247.99",
            "type": "QR_DYNAMIC",
            "pix_key": "550e8400-e29b-41d4-a716-446655440000",
            "additional_info": [
              {
                "name": "ID do pagamento",
                "value": "990e8400-e29b-41d4-a716-446655440002"
              }
            ],
            "status": "COMPLETED",
            "expires_at": "2024-01-02T10:00:00.000000Z",
            "created_at": "2024-01-01T10:00:00.000000Z",
            "updated_at": "2024-01-01T10:05:00.000000Z"
          },
          "value": "247.99",
          "movement_type": "IN",
          "type": "EXTERNAL_TRANSFER",
          "status": "SETTLED",
          "end_to_end": "E6070119020240101100500000000001",
          "settled_at": "2024-01-01T10:05:00.000000Z",
          "created_at": "2024-01-01T10:05:00.000000Z",
          "updated_at": "2024-01-01T10:05:00.000000Z"
        },
        "pix_refund": {
          "uuid": "990e8400-e29b-41d4-a716-446655440002",
          "initiation": {
            "sender": {
              "name": "Empresa Demo LTDA",
              "document": "12345678000190",
              "account_number": "9876543",
              "account_agency": "0001",
              "bank": {
                "code": "",
                "name": "PLOWF IP LTDA.",
                "ispb": "00000000"
              },
              "account_type": "CHECKING"
            },
            "receiver": {
              "name": "João Silva",
              "document": "12345678901",
              "account_number": "00123456",
              "account_agency": "0001",
              "bank": {
                "code": "341",
                "name": "ITAÚ UNIBANCO S.A.",
                "ispb": "60701190"
              },
              "account_type": "CHECKING"
            },
            "txid": null,
            "value": 247.99,
            "type": "REFUND",
            "status": "COMPLETED",
            "expires_at": null,
            "created_at": "2024-01-02T10:00:00.000000Z",
            "updated_at": "2024-01-02T10:00:00.000000Z"
          },
          "value": 247.99,
          "movement_type": "OUT",
          "type": "EXTERNAL_REFUND",
          "status": "PENDING",
          "end_to_end": "D0000000020240102100000000000001",
          "settled_at": null,
          "created_at": "2024-01-02T10:00:00.000000Z",
          "updated_at": "2024-01-02T10:00:00.000000Z"
        },
        "created_at": "2024-01-02T10:00:00.000000Z",
        "updated_at": "2024-01-02T10:00:00.000000Z"
      },
      "history": [
        {
          "status": "PENDING",
          "created_at": "2024-01-01T10:00:00Z"
        },
        {
          "status": "PAID",
          "created_at": "2024-01-01T10:05:00Z"
        }
      ],
      "created_at": "2024-01-15T10:45:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    }
  }
  ```
</ResponseExample>

## Campos do Payload

<ResponseField name="event" type="string">
  Tipo do evento. Sempre `"REFUND"` para este webhook.
</ResponseField>

<ResponseField name="timestamp" type="datetime">
  Timestamp ISO 8601 do momento em que o webhook foi enviado.
</ResponseField>

<ResponseField name="data" type="object">
  Dados do estorno atualizado.

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único da cobrança original.
    </ResponseField>

    <ResponseField name="status" type="string">
      Status atual da cobrança. Valores possíveis: `PENDING`, `PAID`, `REFUNDED`, `PARTIALLY_REFUNDED`, `FAILED`, `CANCELLED`, `EXPIRED`, `PROCESSING`.
    </ResponseField>

    <ResponseField name="value" type="number">
      Valor da cobrança original.
    </ResponseField>

    <ResponseField name="fees" type="number">
      Taxas aplicadas à cobrança.
    </ResponseField>

    <ResponseField name="refund" type="object">
      Dados do estorno PIX realizado.

      <Expandable title="atributos">
        <ResponseField name="value" type="number">
          Valor do estorno.
        </ResponseField>

        <ResponseField name="status" type="string">
          Status do estorno (PENDING, PROCESSING, SETTLED, FAILED, CANCELED).
        </ResponseField>

        <ResponseField name="fees" type="number">
          Taxas aplicadas ao estorno.
        </ResponseField>

        <ResponsePixTransaction name="pix_original" description="Dados do PIX original que foi estornado" />

        <ResponsePixTransaction name="pix_refund" description="Dados do PIX de estorno processado" />

        <ResponseField name="created_at" type="datetime">
          Data e hora de criação do estorno.
        </ResponseField>

        <ResponseField name="updated_at" type="datetime">
          Data e hora da última atualização do estorno.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="history" type="object[]">
      Histórico de mudanças de status

      <Expandable title="atributos">
        <ResponseField name="status" type="string">
          Status no histórico
        </ResponseField>

        <ResponseField name="created_at" type="datetime">
          Data e hora do status
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação da cobrança original.
    </ResponseField>

    <ResponseField name="updated_at" type="datetime">
      Data e hora da última atualização.
    </ResponseField>
  </Expandable>
</ResponseField>

## Status Possíveis

Os status possíveis para um estorno são:

* `PENDING` - Aguardando processamento
* `PROCESSING` - Estorno em processamento
* `SETTLED` - Estorno liquidado
* `FAILED` - Estorno falhou
* `CANCELLED` - Estorno cancelado

<Note>
  Use o campo `uuid` para identificar unicamente o estorno e implementar idempotência no seu endpoint.
</Note>


# Evento TRANSFER
Source: https://docs.plowf.com/api-reference/webhooks/events/transfer

Webhook disparado quando o status de uma transferência é atualizado

## Visão Geral

O evento `TRANSFER` é disparado quando o status de uma transferência PIX Out é atualizado na plataforma. O webhook é enviado quando:

* Uma transferência muda de status (ex: `PROCESSING` → `PAID`, `PROCESSING` → `FAILED`)

## Headers do Webhook

```
X-Webhook-Event: TRANSFER
X-Webhook-Timestamp: 2024-01-15T10:30:00Z
X-Webhook-Signature: abc123def456...
Content-Type: application/json
```

## Estrutura do Payload

<ResponseExample>
  ```json theme={null}
  {
    "event": "TRANSFER",
    "timestamp": "2024-01-15T10:30:00Z",
    "data": {
      "uuid": "770e8400-e29b-41d4-a716-446655440002",
      "value": 100.5,
      "fees": 2.5,
      "currency": "BRL",
      "status": "PAID",
      "type": "PIX",
      "external_ref": "transfer-456",
      "final_beneficiary": {
        "name": "Maria Santos",
        "document": "98765432100"
      },
      "transfer": {
        "uuid": "880e8400-e29b-41d4-a716-446655440003",
        "initiation": {
          "sender": {
            "name": "Empresa Exemplo Ltda",
            "document": "00000000000100",
            "account_number": "0000001",
            "account_agency": "0001",
            "bank": {
              "code": "",
              "name": "BANCO EXEMPLO IP LTDA.",
              "ispb": "00000000"
            },
            "account_type": "CHECKING"
          },
          "receiver": {
            "name": "Maria Santos",
            "document": "987.***.***-00",
            "account_number": "********************",
            "account_agency": "****",
            "bank": {
              "code": "077",
              "name": "BANCO INTER S.A.",
              "ispb": "00416968"
            },
            "account_type": "CHECKING"
          },
          "txid": null,
          "value": 100.5,
          "type": "KEY",
          "pix_key": "teste@pix.com",
          "status": "COMPLETED",
          "expires_at": null,
          "created_at": "2024-01-15T10:25:00Z",
          "updated_at": "2024-01-15T10:30:00Z"
        },
        "value": 100.5,
        "movement_type": "OUT",
        "type": "EXTERNAL_TRANSFER",
        "status": "SETTLED",
        "end_to_end": "E123456782024011510300000123456",
        "settled_at": "2024-01-15T10:30:00Z",
        "created_at": "2024-01-15T10:25:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      "history": [
        {
          "status": "PENDING",
          "created_at": "2024-01-01T10:00:00Z"
        },
        {
          "status": "PROCESSING",
          "created_at": "2024-01-01T10:02:00Z"
        },
        {
          "status": "PAID",
          "created_at": "2024-01-01T10:05:00Z"
        }
      ],
      "created_at": "2024-01-15T10:25:00Z"
    }
  }
  ```
</ResponseExample>

## Campos do Payload

<ResponseField name="event" type="string">
  Tipo do evento. Sempre `"TRANSFER"` para este webhook.
</ResponseField>

<ResponseField name="timestamp" type="datetime">
  Timestamp ISO 8601 do momento em que o webhook foi enviado.
</ResponseField>

<ResponseField name="data" type="object">
  Dados da transferência atualizada.

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único da transferência.
    </ResponseField>

    <ResponseField name="value" type="number">
      Valor da transferência.
    </ResponseField>

    <ResponseField name="fees" type="number">
      Taxas aplicadas à transferência.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Moeda da transferência (ex: "BRL").
    </ResponseField>

    <ResponseField name="status" type="string">
      Status atual da transferência. Valores possíveis: `PENDING`, `PROCESSING`, `PAID`, `FAILED`, `REFUNDED`, `PARTIALLY_REFUNDED`, `CANCELLED`, `EXPIRED`.
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo da transferência (ex: "PIX").
    </ResponseField>

    <ResponseField name="external_ref" type="string">
      Referência externa fornecida na criação da transferência.
    </ResponseField>

    <ResponseField name="final_beneficiary" type="object">
      Beneficiário final da cobrança (seller)

      <Expandable title="atributos">
        <ResponseField name="name" type="string">
          Nome do beneficiário final
        </ResponseField>

        <ResponseField name="document" type="string">
          Documento do beneficiário final (CPF ou CNPJ)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponsePixTransaction name="transfer" description="Dados da transferência PIX processada" />

    <ResponseField name="history" type="object[]">
      Histórico de mudanças de status

      <Expandable title="atributos">
        <ResponseField name="status" type="string">
          Status no histórico
        </ResponseField>

        <ResponseField name="created_at" type="datetime">
          Data e hora do status
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação da transferência.
    </ResponseField>
  </Expandable>
</ResponseField>

## Status Possíveis

Os status possíveis para uma transferência são:

* `PENDING` - Aguardando processamento
* `PROCESSING` - Transferência em processamento
* `PAID` - Transferência confirmada
* `FAILED` - Transferência falhou
* `CANCELLED` - Transferência cancelada
* `REFUNDED` - Transferência estornada
* `PARTIALLY_REFUNDED` - Transferência estornada parcialmente
* `EXPIRED` - Transferência expirada

<Note>
  Use o campo `uuid` para identificar unicamente a transferência e implementar idempotência no seu endpoint.
</Note>


# Detalhar Webhook
Source: https://docs.plowf.com/api-reference/webhooks/get

GET /api/v1/webhooks/{webhookUuid}

Retorna os detalhes completos de um webhook específico.

<RequestExample>
  ```bash theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/webhooks/e1afe0f4-9358-4a50-b0fd-55912ca86ee1' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Path Parameters

<ParamField type="string">
  UUID do webhook que deseja consultar
</ParamField>

## Resposta de Sucesso

A resposta retorna o objeto completo do webhook.

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "uuid": "e1afe0f4-9358-4a50-b0fd-55912ca86ee1",
      "url": "https://webhook.site/04ef5e41-d054-49f9-805c-03a6a345245e",
      "token": "nUeO7RobnrgJxs8mBr1oOvChV4wqOblj",
      "events": [
        "PAYMENT",
        "TRANSFER",
        "REFUND",
        "MED",
        "PIX_TRANSACTION"
      ],
      "status": "ACTIVE",
      "created_at": "2026-01-13T00:37:47.000000Z"
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object">
  Dados completos do webhook

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único do webhook
    </ResponseField>

    <ResponseField name="url" type="string">
      URL configurada para receber os webhooks
    </ResponseField>

    <ResponseField name="token" type="string">
      Token usado para validar a assinatura HMAC dos webhooks. Este token é necessário para validar as requisições recebidas.
    </ResponseField>

    <ResponseField name="status" type="string">
      Status atual do webhook. Valores possíveis: `ACTIVE`, `INACTIVE`
    </ResponseField>

    <ResponseField name="events" type="array">
      Eventos que serão enviados para o endpoint. Valores possíveis: `PAYMENT`, `TRANSFER`, `REFUND`, `MED`, `PIX_TRANSACTION`
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação do webhook
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>

<ErrorField name="404">
  Webhook não encontrado. Verifique se o UUID está correto e se você tem permissão para acessá-lo.
</ErrorField>


# Introdução aos Webhooks
Source: https://docs.plowf.com/api-reference/webhooks/introduction

Visão geral do sistema de webhooks da plataforma

## Visão Geral

A plataforma envia webhooks para URLs configuradas pelos clientes quando eventos importantes acontecem no sistema. Os webhooks permitem que você receba notificações em tempo real sobre mudanças de status em cobranças, transferências e estornos.

## Características Principais

* **Autenticação Segura**: Assinatura HMAC SHA-256 para validação
* **Múltiplos Webhooks**: Suporte a múltiplos endpoints por conta
* **Eventos em Tempo Real**: Notificações imediatas quando eventos ocorrem

## Estrutura Geral

* **Método**: `POST`
* **Content-Type**: `application/json`
* **Autenticação**: Assinatura HMAC SHA-256 no header `X-Webhook-Signature`
* **Timeout**: 5 segundos por requisição

## Estrutura do Payload

Todos os webhooks seguem a mesma estrutura base:

```json theme={null}
{
  "event": "PAYMENT",
  "data": {
    // Dados específicos do evento
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
```

## Headers Enviados

Cada webhook inclui os seguintes headers:

* `Accept: application/json`
* `Content-Type: application/json`
* `User-Agent: {app_name}/1.0.0`
* `X-Webhook-Event`: Nome do evento (ex: "PAYMENT", "TRANSFER", "REFUND")
* `X-Webhook-Timestamp`: Timestamp ISO 8601 do envio
* `X-Webhook-Signature`: Assinatura HMAC SHA-256 do payload completo

## Tipos de Eventos

A plataforma envia três tipos principais de eventos:

1. **PAYMENT** - Eventos relacionados a cobranças PIX In
2. **TRANSFER** - Eventos relacionados a transferências PIX Out
3. **REFUND** - Eventos relacionados a estornos

## Resposta Esperada

O endpoint do cliente deve responder com:

* **Status HTTP 2xx** (200-299): Considerado sucesso
* **Qualquer outro status**: Considerado falha

A resposta não precisa ter um formato específico, apenas um status HTTP válido.

<Note>
  Sempre valide a assinatura HMAC antes de processar o webhook para garantir que a requisição é legítima.
</Note>


# Listar Webhooks
Source: https://docs.plowf.com/api-reference/webhooks/list

GET /api/v1/webhooks

Lista todos os webhooks configurados na conta autenticada com paginação e filtros.

<RequestExample>
  ```bash theme={null}
  curl -X GET 'https://app.plowf.com/api/v1/webhooks?status=ACTIVE&per_page=20' \
    -H 'Authorization: Bearer seu_token_aqui'
  ```
</RequestExample>

## Parâmetros de Query

Todos os parâmetros são opcionais.

<ParamField type="string">
  Filtrar por UUID específico do webhook
</ParamField>

<ParamField type="string">
  Filtrar por URL específica do webhook
</ParamField>

<ParamField type="string">
  Status do webhook. Valores possíveis: - `ACTIVE` - `INACTIVE`
</ParamField>

<ParamField type="array">
  Eventos que serão enviados para o endpoint. Valores possíveis: `PAYMENT`, `TRANSFER`, `REFUND`, `MED`, `PIX_TRANSACTION`
</ParamField>

<ParamField type="integer">
  Número de itens por página (mínimo: 1, máximo: 100)
</ParamField>

## Resposta de Sucesso

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "uuid": "e1afe0f4-9358-4a50-b0fd-55912ca86ee1",
        "url": "https://webhook.site/04ef5e41-d054-49f9-805c-03a6a345245e",
        "token": "nUeO7RobnrgJxs8mBr1oOvChV4wqOblj",
        "status": "ACTIVE",
        "events": [
          "PAYMENT",
          "TRANSFER",
          "REFUND",
          "MED",
          "PIX_TRANSACTION"
        ],
        "created_at": "2026-01-13T00:37:47.000000Z"
      },
      {
        "uuid": "f2b0f1g5-a469-5b61-c1ge-66a23db97ff2",
        "url": "https://api.exemplo.com/webhooks",
        "token": "xYz9AbCdEfGhIjKlMnOpQrStUvWxYz",
        "status": "ACTIVE",
        "events": [
          "PAYMENT",
          "TRANSFER",
          "REFUND",
          "MED",
          "PIX_TRANSACTION"
        ],
        "created_at": "2026-01-12T15:20:30.000000Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "from": 1,
      "last_page": 1,
      "per_page": 10,
      "to": 2,
      "total": 2
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object[]">
  Lista de webhooks

  <Expandable title="atributos">
    <ResponseField name="uuid" type="string">
      UUID único do webhook
    </ResponseField>

    <ResponseField name="url" type="string">
      URL configurada para receber os webhooks
    </ResponseField>

    <ResponseField name="token" type="string">
      Token usado para validar a assinatura HMAC dos webhooks
    </ResponseField>

    <ResponseField name="status" type="string">
      Status atual do webhook. Valores possíveis: `ACTIVE`, `INACTIVE`
    </ResponseField>

    <ResponseField name="events" type="array">
      Eventos que serão enviados para o endpoint. Valores possíveis: `PAYMENT`, `TRANSFER`, `REFUND`, `MED`, `PIX_TRANSACTION`
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Data e hora de criação do webhook
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Metadados de paginação

  <Expandable title="atributos">
    <ResponseField name="current_page" type="number">
      Página atual
    </ResponseField>

    <ResponseField name="from" type="number">
      Índice do primeiro item da página
    </ResponseField>

    <ResponseField name="last_page" type="number">
      Última página disponível
    </ResponseField>

    <ResponseField name="per_page" type="number">
      Itens por página
    </ResponseField>

    <ResponseField name="to" type="number">
      Índice do último item da página
    </ResponseField>

    <ResponseField name="total" type="number">
      Total de itens
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros Comuns

<ErrorField name="401">
  Token de autenticação inválido ou ausente
</ErrorField>


# Validação de Assinatura
Source: https://docs.plowf.com/api-reference/webhooks/validation-link





# Autenticação e segurança
Source: https://docs.plowf.com/guides/intro/auth-and-security

Bearer Token, IPs permitidos na API e segurança dos webhooks

## Autenticação na API

Todos os endpoints exigem um **Bearer Token** no header `Authorization`:

```bash theme={null}
Authorization: Bearer seu_token_aqui
```

Sem um token válido, a API responde com **401**. Permissões insuficientes para o recurso podem resultar em **403**.

### Onde obter o token

O token pode ser obtido no menu **Integrações → Chaves API** em:

**[Integrações → Chaves API](https://app.plowf.com/integrations?tab=apiTokens)**

<img alt="Integrações → Chaves API → Nova Chave" />

Na criação você também pode **vincular o token a um provedor específico** — operações de leitura ficam filtradas para aquele provedor e webhooks/defaults globais ficam bloqueados. Veja [Tokens vinculados a um provedor](/guides/intro/provider-scoped-tokens) para o comportamento completo.

## Lista de IPs permitidos

A API pode exigir que as requisições partam apenas de endereços IP que você autorizou. Cadastrar esses IPs ajuda a:

* **Reduzir o risco de uso indevido** da sua conta, mesmo que credenciais vazem
* **Limitar a superfície de ataque** ao restringir chamadas a servidores ou redes que você controla
* **Atender boas práticas** em ambientes corporativos e de produção

Se o IP de origem não estiver na lista, as chamadas podem ser **bloqueadas** até você incluir o endereço correto.

### Onde configurar

Cadastre e atualize os IPs em:

**[Integrações → IPs Permitidos](https://app.plowf.com/integrations?tab=apiIps)**

<img alt="Integrações → IPs Permitidos → Adicionar IP" />

Use os endereços **públicos de saída** dos servidores, balanceadores ou gateways que chamam a API. Se sua infraestrutura usar IPs dinâmicos, ajuste a lista sempre que eles mudarem.

<Note>
  Revise a lista ao implantar em novo ambiente, ao trocar de provedor ou ao escalar com novos pontos de saída.
</Note>

## Segurança dos webhooks

Os webhooks são **chamadas HTTP da Plowf para a sua URL**. Além de usar HTTPS no seu endpoint, você deve **validar a origem** do payload: cada envio inclui assinatura **HMAC SHA-256** no header `X-Webhook-Signature`, gerada com o token secreto do webhook. Assim você garante integridade do corpo e que a notificação veio da plataforma.

Leia mais em:

* **[Introdução aos Webhooks](/api-reference/webhooks/introduction)** — visão geral, headers e fluxo
* **[Validação de assinatura](/guides/webhooks/validation)** — como implementar a verificação HMAC em código


# Contexto para assistentes de IA
Source: https://docs.plowf.com/guides/intro/context-for-ai-assistants

Arquivos llms-full.txt e llms.txt para Cursor, ChatGPT e outras ferramentas

## Por que existem esses arquivos

Assistentes e IDEs com IA precisam de **contexto em texto** sobre a API para sugerir código, revisar integrações e responder dúvidas sem alucinar endpoints inexistentes. Publicamos dois arquivos estáticos para isso:

| Arquivo                             | Uso recomendado                                                                                                                                |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **[llms-full.txt](/llms-full.txt)** | Documentação **completa** em texto plano — ideal quando você quer o máximo de detalhe no contexto (referência de endpoints, exemplos, regras). |
| **[llms.txt](/llms.txt)**           | Versão **resumida** — útil quando o limite de contexto é menor ou você só precisa de um panorama antes de mergulhar na referência web.         |

## Como usar o `llms-full.txt`

1. **Baixe ou copie** o conteúdo de [llms-full.txt](/llms-full.txt) (é um único arquivo de texto).
2. **Inclua no contexto** da ferramenta:
   * Em editores como o **Cursor**: anexe o arquivo na conversa, coloque na pasta do projeto como referência ou use em regras/instruções do agente, conforme o fluxo da ferramenta.
   * Em chats (**ChatGPT**, **Claude**, etc.): cole trechos relevantes ou o arquivo inteiro se couber no limite do modelo.
3. **Atualize quando a doc mudar** — o site é a fonte viva; regenere ou baixe de novo o `llms-full.txt` após releases importantes da API.

## Quando preferir o `llms.txt`

Use [llms.txt](/llms.txt) para uma **visão compacta** (visão geral, links conceituais) e combine com a **documentação online** para detalhes de cada endpoint. É uma boa porta de entrada antes de carregar o arquivo completo.

<Note>
  Os arquivos complementam, não substituem, os exemplos deste site e os testes na sua conta. Sempre confira parâmetros obrigatórios e códigos de erro na referência publicada.
</Note>


# Tokens vinculados a um provedor
Source: https://docs.plowf.com/guides/intro/provider-scoped-tokens

Como criar e usar tokens API com escopo restrito a um provedor específico

A Plowf permite que sua conta opere com **múltiplos provedores financeiros** simultaneamente. Cada integração ativa aparece em [`GET /providers`](/api-reference/providers/list) como um **provedor** — com saldo, limites e chaves PIX próprios.

Por padrão, um token de API tem acesso a **todos** os provedores da conta. Você também pode emitir um token **vinculado a um provedor específico** — útil para isolar responsabilidades, separar contabilidade ou limitar a superfície de risco de uma integração externa.

## Como criar

Crie a chave em **[Integrações → Chaves API](https://app.plowf.com/integrations?tab=apiTokens)** e selecione o provedor ao qual ela deve ficar restrita. Tokens sem provedor selecionado continuam funcionando como antes.

## Comportamento do token vinculado

Quando um token está vinculado a um provedor, a API aplica automaticamente o escopo em todas as chamadas:

* **Leituras filtradas**: `GET /payments`, `GET /transfers`, `GET /pix-keys`, `GET /meds` e `GET /providers` retornam apenas registros do provedor vinculado.
* **`provider_uuid` no body é ignorado**: ao chamar [`POST /transfers`](/api-reference/transfers/create), [`POST /pix-keys`](/api-reference/pix-keys/create) ou [`POST /pix-keys/auth-code`](/api-reference/pix-keys/auth-code), o provedor do token sempre prevalece — mesmo que você envie um `provider_uuid` diferente.
* **Detalhes de outros provedores**: `GET /providers/{uuid}` retorna **404** se o UUID informado não for o provedor do token.
* **Defaults**: [`GET /providers/defaults`](/api-reference/providers/defaults-get) só mostra o provedor vinculado nas listas de `payment_type` em que ele estiver configurado como padrão.

## Operações bloqueadas

As chamadas a seguir respondem com **HTTP 403** e a mensagem *"Operação não permitida para tokens vinculados a um provedor."*:

* `GET`, `POST` e `DELETE` em `/api/v1/webhooks/*` — webhooks são configurados no nível da conta, não do provedor
* `PUT /api/v1/providers/defaults` — alterar a lista global de defaults exige um token sem escopo de provedor

```json theme={null}
{
  "message": "Operação não permitida para tokens vinculados a um provedor."
}
```

## Quando preferir cada formato

| Use um token **global**                                              | Use um token **vinculado a provedor**                                    |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Backoffice ou painel interno que precisa enxergar toda a conta       | Microserviço dedicado a uma linha de negócio com provedor próprio        |
| Ferramenta que precisa gerenciar webhooks ou defaults                | Integração externa em que você quer limitar o blast radius               |
| Códigos que ainda escolhem o provedor por operação (`provider_uuid`) | Ambientes em que faz sentido separar credenciais por contabilidade/risco |

<Tip>
  Você pode criar quantos tokens vinculados quiser — um por provedor — e mantê-los lado a lado com um token global usado pelo seu backoffice.
</Tip>


# Boas-vindas
Source: https://docs.plowf.com/guides/intro/welcome

O que é a Plowf, o painel e o panorama da API REST

## O que é a Plowf

A Plowf é uma plataforma para operar **PIX** e fluxos financeiros associados: você pode **receber** (cobranças PIX In), **enviar** (transferências PIX Out), gerenciar **chaves PIX**, acompanhar **MEDs** (Mecanismo Especial de Devolução) e ser notificado por **webhooks** quando o status dos eventos mudar.

Tudo isso pode ser usado pelo **painel web** e automatizado pela **API REST** documentada nas seções seguintes deste site.

## Painel

O ambiente principal fica em **[app.plowf.com](https://app.plowf.com)**. Por lá você acessa o dashboard, configurações da conta e a área de **integrações** (incluindo restrição por IP para a API).

## Módulos e API

| Área                         | O que faz                                               | Na API                                                               |
| ---------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------- |
| **Cobranças (PIX In)**       | Gerar e acompanhar cobranças para recebimento via PIX   | Endpoints em `/payments`                                             |
| **Transferências (PIX Out)** | Enviar valores por PIX para terceiros                   | Endpoints em `/transfers`                                            |
| **Chaves PIX**               | Cadastrar, consultar e remover chaves PIX da conta      | Endpoints em `/pix-keys`                                             |
| **MEDs**                     | Listar, consultar e responder em processos de devolução | Endpoints em `/meds`                                                 |
| **Webhooks**                 | Receber notificações em tempo real na sua URL           | CRUD em `/webhooks` e eventos documentados em **Eventos do Webhook** |

## Panorama da API

Esta API permite gerenciar transferências PIX Out, cobranças PIX In e demais recursos de forma programática.

* **Base URL**: `https://app.plowf.com/api/v1`
* **Formato**: JSON
* **Respostas de sucesso** trazem o conteúdo dentro de um objeto `data`

### Formato de resposta

```json theme={null}
{
  "data": {
    // dados da resposta
  }
}
```

Em **listagens paginadas**, a resposta inclui também `links` e `meta`:

```json theme={null}
{
  "data": [...],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "per_page": 10,
    "to": 10,
    "total": 100
  }
}
```

### Códigos de status HTTP

<ParamField type="number">
  * `200` — Sucesso
  * `401` — Não autenticado
  * `403` — Não autorizado
  * `404` — Recurso não encontrado
  * `422` — Erro de validação
  * `500` — Erro interno do servidor
</ParamField>

### Observações

1. Campos de data/datetime seguem **ISO 8601** (ex.: `2024-01-01T12:00:00Z`)
2. Campos marcados como `| null` podem retornar `null` ou serem omitidos
3. Status e tipos são **strings** com nomes dos enums (ex.: `"PAID"`, `"PIX"`)

## Próximos passos

1. **[Autenticação e segurança](/guides/intro/auth-and-security)** — token, IPs permitidos e visão geral dos webhooks
2. **[Contexto para assistentes de IA](/guides/intro/context-for-ai-assistants)** — arquivos `llms.txt` e `llms-full.txt`
3. Endpoints detalhados nos grupos **Cobranças**, **Transferências**, **Chaves PIX**, **MEDs** e **Webhooks** no menu

<CardGroup>
  <Card title="Autenticação e segurança" icon="key" href="/guides/intro/auth-and-security">
    Bearer Token, lista de IPs e segurança dos webhooks.
  </Card>

  <Card title="Contexto para IA" icon="sparkles" href="/guides/intro/context-for-ai-assistants">
    Como usar a documentação em texto para modelos e ferramentas.
  </Card>
</CardGroup>


# Referência API
Source: https://docs.plowf.com/guides/meds/api-link





# Introdução
Source: https://docs.plowf.com/guides/meds/intro

Receba, analise e responda contestações de PIX via Mecanismo Especial de Devolução

MEDs são contestações formais de PIX reguladas pelo Banco Central. Quando um pagador aciona o MED junto ao seu banco, você é notificado e precisa responder dentro do prazo — aceitando ou rejeitando a solicitação de devolução.

## O que você pode fazer

* **Monitorar** MEDs recebidos via webhook `MED`
* **Consultar** detalhes e histórico de contestações
* **Responder** com aceite ou rejeição, incluindo análise textual e anexos como comprovantes

## Ciclo de vida

```
PENDING → PROCESSING → ACCEPTED
PENDING → PROCESSING → REJECTED
PENDING → PROCESSING → CANCELLED
```

Quando um MED muda de status, um webhook [`MED`](/guides/webhooks/intro) é disparado automaticamente.

## Referência da API

<CardGroup>
  <Card title="Listar MEDs" icon="list" href="/api-reference/meds/list">
    `GET /api/v1/meds`
  </Card>

  <Card title="Detalhar MED" icon="magnifying-glass" href="/api-reference/meds/get">
    `GET /api/v1/meds/{uuid}`
  </Card>

  <Card title="Responder MED" icon="reply" href="/api-reference/meds/reply">
    `POST /api/v1/meds/{uuid}/reply`
  </Card>
</CardGroup>

## Receitas

<CardGroup>
  <Card title="Responder a um MED" href="/guides/meds/recipes/reply-med">
    Receba, analise e responda a uma contestação de PIX passo a passo
  </Card>
</CardGroup>


# Recebendo um MED
Source: https://docs.plowf.com/guides/meds/recipes/receiving-med

Como MEDs chegam via webhook, o que cada campo significa e como decidir como responder

Quando um pagador abre uma contestação, a Plowf notifica você imediatamente via webhook com o evento `MED`. É por ali que você fica sabendo que precisa agir — e o objeto do evento contém tudo que você precisa para analisar e responder.

<Note>
  Para mais detalhes sobre o evento MED e a descrição completa de todos os campos do payload, consulte a [referência do evento MED](/api-reference/webhooks/events/med).
</Note>

## Estrutura do webhook

O evento `MED` é enviado a cada mudança de status. Implemente idempotência no seu endpoint usando o `uuid` do MED para evitar processar o mesmo evento mais de uma vez.

```json theme={null}
{
  "event": "MED",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "med_type": "RECEIVED_MED",
    "dispute_type": "SCAM",
    "status": "PENDING",
    "resolved": false,
    "pix_in_transaction": {
      "value": "150.00",
      "end_to_end": "E00000000202401011000abcdef12345",
      "settled_at": "2024-01-01T10:05:00Z"
    }
  }
}
```

## Campos do objeto MED

```json theme={null}
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "med_type": "RECEIVED_MED",
  "dispute_type": "SCAM",
  "status": "PENDING",
  "resolved": false,
  "pix_in_transaction": {
    "value": "150.00",
    "end_to_end": "E00000000202401011000abcdef12345",
    "settled_at": "2024-01-01T10:05:00Z"
  }
}
```

| Campo                           | Tipo    | Descrição                                                                          |
| ------------------------------- | ------- | ---------------------------------------------------------------------------------- |
| `uuid`                          | string  | Identificador único do MED — use para idempotência e para enviar a resposta        |
| `med_type`                      | enum    | Direção da contestação em relação à sua conta                                      |
| `dispute_type`                  | enum    | Motivo alegado pelo contestante                                                    |
| `status`                        | enum    | Fase atual do MED no ciclo de vida                                                 |
| `resolved`                      | boolean | `true` quando o MED chegou ao status final (`ACCEPTED`, `REJECTED` ou `CANCELLED`) |
| `pix_in_transaction`            | object  | Dados do PIX contestado                                                            |
| `pix_in_transaction.value`      | string  | Valor em reais do PIX contestado                                                   |
| `pix_in_transaction.end_to_end` | string  | ID fim a fim do PIX — use para localizar a transação no seu sistema                |
| `pix_in_transaction.settled_at` | string  | Data e hora em que o PIX foi liquidado                                             |

***

## `med_type` — direção da contestação

| Valor           | Significado                                                              |
| --------------- | ------------------------------------------------------------------------ |
| `RECEIVED_MED`  | Você recebeu uma contestação — alguém quer de volta um PIX que te enviou |
| `REQUESTED_MED` | Você abriu uma contestação de um PIX que enviou                          |

Na maioria dos casos você vai lidar com `RECEIVED_MED`: um cliente contestou um pagamento e você precisa aceitar ou rejeitar a devolução.

***

## `dispute_type` — motivo da contestação

| Valor                 | Descrição                    | O que costuma indicar                                                   |
| --------------------- | ---------------------------- | ----------------------------------------------------------------------- |
| `SCAM`                | Fraude ou golpe              | O pagador alega ter sido enganado para realizar o pagamento             |
| `WRONG_TRANSACTION`   | Transação enviada por engano | O pagador enviou para a chave errada ou pelo valor errado               |
| `COERCION_CRIME`      | Crime de coação              | O pagamento foi feito sob ameaça (ex: sequestro relâmpago)              |
| `UNAUTHORIZED_ACCESS` | Acesso não autorizado        | A conta do pagador foi invadida e o PIX foi feito sem seu consentimento |
| `UNDEFINED`           | Motivo não definido          | Contestação sem motivo especificado                                     |

Use o `dispute_type` para calibrar sua análise. `WRONG_TRANSACTION` costuma ser mais fácil de refutar com evidências de entrega. `COERCION_CRIME` e `UNAUTHORIZED_ACCESS` tendem a ter maior peso regulatório.

***

## `status` — ciclo de vida

```
PENDING → PROCESSING → ACCEPTED
                     → REJECTED
                     → CANCELLED
```

| Status       | `resolved` | O que fazer                                           |
| ------------ | ---------- | ----------------------------------------------------- |
| `PENDING`    | `false`    | **Aja agora**: você precisa responder dentro do prazo |
| `PROCESSING` | `false`    | Aguarde — o MED está em processo de resposta          |
| `ACCEPTED`   | `true`     | MED aceito — valor devolvido ao pagador               |
| `REJECTED`   | `true`     | MED rejeitado — valor permanece na sua conta          |
| `CANCELLED`  | `true`     | MED cancelado — nenhuma ação necessária               |

<Warning>
  MEDs com `status: "PENDING"` têm prazo de resposta regulado pelo Banco Central. Se não responder a tempo, o MED pode ser aceito automaticamente e o valor devolvido.
</Warning>

***

## Como decidir o que fazer

Ao receber um `RECEIVED_MED` com `status: "PENDING"`, avalie:

**Rejeite o MED** se você tem evidências de que a transação foi legítima:

* Nota fiscal ou recibo do produto/serviço
* Comprovante de entrega
* Registro de uso do serviço (log de acesso, ativação de licença, etc.)
* Histórico de comunicação com o cliente

**Aceite o MED** se:

* A contestação faz sentido e você reconhece o erro
* Você não tem evidências suficientes para contestar
* O valor ou o esforço não justificam a disputa

Para o passo a passo de como enviar a resposta via API, consulte a receita [Responder a um MED](/guides/meds/recipes/reply-med).


# Responder a um MED
Source: https://docs.plowf.com/guides/meds/recipes/reply-med

Como receber, analisar e responder a uma contestação de PIX via Mecanismo Especial de Devolução

<Note>
  Para mais detalhes sobre o endpoint e a descrição completa de todos os campos do body, consulte a [referência do endpoint](/api-reference/meds/reply).
</Note>

## Visão Geral

Esta receita mostra como lidar com um MED recebido: desde a notificação via webhook até o envio da resposta com aceite ou rejeição dentro do prazo.

**O fluxo completo:**

1. Receber a notificação de MED via webhook
2. Identificar a transação original
3. Reunir evidências (se for rejeitar)
4. Enviar a resposta

## Pré-requisitos

* Token de autenticação da API ([ver autenticação](/api-reference/auth-and-security))
* Webhook configurado para receber eventos `MED` ([ver Webhooks](/guides/webhooks/intro))

***

## 1. Receber a notificação de MED

Quando um MED é aberto contra sua conta, a Plowf envia um evento `MED` com `status: "PENDING"`:

```json theme={null}
{
  "event": "MED",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "med_type": "RECEIVED_MED",
    "dispute_type": "SCAM",
    "status": "PENDING",
    "resolved": false,
    "pix_in_transaction": {
      "value": "150.00",
      "end_to_end": "E00000000202401011000abcdef12345",
      "settled_at": "2024-01-01T10:05:00Z"
    }
  }
}
```

No seu endpoint, filtre por `med_type === "RECEIVED_MED"` e `status === "PENDING"` para identificar MEDs que precisam de resposta:

```javascript theme={null}
app.post('/webhooks/plowf', (req, res) => {
  // ... validação de assinatura HMAC ...

  const { event, data } = req.body;

  if (event === 'MED' && data.med_type === 'RECEIVED_MED' && data.status === 'PENDING') {
    // Registre o MED e inicie o processo de análise
    console.log('MED recebido:', data.uuid);
    console.log('Motivo:', data.dispute_type);
    console.log('Transação:', data.pix_in_transaction.end_to_end);

    // Notifique sua equipe ou enfileire para análise
    notificarEquipe(data);
  }

  res.status(200).json({ received: true });
});
```

<Warning>
  Responda `200` ao webhook imediatamente e processe o MED de forma assíncrona. MEDs têm prazo para resposta — não atrase o processamento.
</Warning>

***

## 2. Identificar a transação original

Use o `end_to_end` ou o `value` da `pix_in_transaction` para localizar a cobrança no seu sistema:

```bash theme={null}
curl 'https://app.plowf.com/api/v1/meds/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer seu_token_aqui'
```

O retorno inclui todos os dados da transação contestada, incluindo remetente e valor.

***

## 3a. Rejeitar o MED (contestar a devolução)

Use quando a transação é legítima e você tem documentos que comprovam isso (nota fiscal, comprovante de entrega, registro de uso do serviço).

```bash theme={null}
curl -X POST 'https://app.plowf.com/api/v1/meds/550e8400-e29b-41d4-a716-446655440000/reply' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: multipart/form-data' \
  -F 'accept=0' \
  -F 'analysis=Pagamento referente ao pedido #12345, realizado em 2024-01-01. O produto foi entregue em 2024-01-03, conforme nota fiscal em anexo.' \
  -F 'attachments[0][file]=@nota-fiscal.pdf'
```

<Note>
  Inclua o máximo de evidências possível: notas fiscais, comprovantes de entrega, capturas de tela de comunicações com o cliente. Isso aumenta a chance de rejeição do MED ser aceita.
</Note>

***

## 3b. Aceitar o MED (concordar com a devolução)

Use quando a contestação é procedente ou quando você opta por devolver o valor sem disputa:

```bash theme={null}
curl -X POST 'https://app.plowf.com/api/v1/meds/550e8400-e29b-41d4-a716-446655440000/reply' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: multipart/form-data' \
  -F 'accept=1' \
  -F 'analysis=Reconhecemos a transação indevida e concordamos com a devolução integral do valor.'
```

***

## 4. Monitorar o resultado

Após enviar a resposta, continue recebendo webhooks `MED` para saber o resultado final:

| Status      | O que significa                              |
| ----------- | -------------------------------------------- |
| `ACCEPTED`  | MED aceito — valor devolvido ao pagador      |
| `REJECTED`  | MED rejeitado — valor permanece na sua conta |
| `CANCELLED` | MED cancelado pelo solicitante ou pelo banco |

```javascript theme={null}
if (event === 'MED' && data.resolved === true) {
  if (data.status === 'REJECTED') {
    console.log('MED rejeitado — valor mantido:', data.uuid);
  } else if (data.status === 'ACCEPTED') {
    console.log('MED aceito — valor devolvido:', data.uuid);
  }
}
```

## Boas práticas

* **Responda dentro do prazo**: MEDs não respondidos podem ser aprovados automaticamente pelo Banco Central.
* **Documente tudo**: Mantenha registros de pedidos, entregas e comunicações para facilitar contestações futuras.
* **Idempotência**: Use o `uuid` do MED para evitar processar ou responder o mesmo MED mais de uma vez.
* **Monitore por `dispute_type`**: Ajuste sua análise conforme o motivo — `SCAM` exige mais evidências do que `WRONG_TRANSACTION`.

## Referências

* [Recebendo um MED](/guides/meds/recipes/receiving-med)
* [Listar MEDs](/api-reference/meds/list)
* [Detalhar MED](/api-reference/meds/get)
* [Responder MED](/api-reference/meds/reply)
* [Evento MED](/api-reference/webhooks/events/med)


# Referência API
Source: https://docs.plowf.com/guides/payments/api-link





# Introdução
Source: https://docs.plowf.com/guides/payments/intro

Gere cobranças PIX In com QR Code, splits de pagamento e estornos

Cobranças são **PIX In** — requisições de pagamento que você cria para receber dinheiro. Ao criar uma cobrança, a plataforma gera um QR Code e um Copia e Cola que o pagador usa para concluir o pagamento.

## O que você pode fazer

* **Criar cobranças** com valor fixo e referência externa (`external_ref`) para rastreamento no seu sistema
* **Split de pagamento**: distribuir automaticamente o valor recebido entre múltiplas contas (percentual ou fixo)
* **Beneficiário final** (`final_beneficiary`): identificar quem é o recebedor final da cobrança para fins de compliance
* **Estornar** uma cobrança liquidada quando necessário

## Ciclo de vida

```
PENDING → PAID → REFUNDED
PENDING → PAID → PARTIALLY_REFUNDED → REFUNDED
PENDING → PROCESSING → PAID
PENDING → PROCESSING → FAILED
PENDING → CANCELLED
PENDING → EXPIRED    
```

Quando uma cobrança muda de status, um webhook [`PAYMENT`](/guides/payments/recipes/payment-webhook) é disparado automaticamente.

## Referência da API

<CardGroup>
  <Card title="Criar Cobrança" icon="plus" href="/api-reference/payments/create">
    `POST /api/v1/payments`
  </Card>

  <Card title="Listar Cobranças" icon="list" href="/api-reference/payments/list">
    `GET /api/v1/payments`
  </Card>

  <Card title="Detalhar Cobrança" icon="magnifying-glass" href="/api-reference/payments/get">
    `GET /api/v1/payments/{uuid}`
  </Card>

  <Card title="Estornar Cobrança" icon="arrow-uturn-left" href="/api-reference/payments/refund">
    `POST /api/v1/payments/{uuid}/refund`
  </Card>
</CardGroup>

## Receitas

<CardGroup>
  <Card title="Criar cobrança PIX" href="/guides/payments/recipes/payment">
    Gere uma cobrança e exiba o QR Code para o pagador
  </Card>

  <Card title="Processar confirmação via webhook" href="/guides/payments/recipes/payment-webhook">
    Configure o endpoint e reaja ao evento PAYMENT em tempo real
  </Card>

  <Card title="Cobrança com split" href="/guides/payments/recipes/payment-with-split">
    Distribua automaticamente o valor entre múltiplas contas
  </Card>
</CardGroup>


# Criar cobrança PIX
Source: https://docs.plowf.com/guides/payments/recipes/payment

Como gerar uma cobrança PIX e exibir o QR Code para o pagador

<Note>
  Para mais detalhes sobre o endpoint e a descrição completa de todos os campos do body, consulte a [referência do endpoint](/api-reference/payments/create).
</Note>

## Visão Geral

Esta receita mostra como criar uma cobrança PIX e exibir o QR Code para o pagador.

**O fluxo completo:**

1. Criar a cobrança PIX
2. Exibir o QR Code para o pagador
3. Receber a confirmação via webhook ([ver página dedicada](/guides/payments/recipes/payment-webhook))

## Pré-requisitos

* Token de autenticação da API ([ver autenticação](/api-reference/autenticacao-e-seguranca))

***

## 1. Criar a cobrança PIX

Crie a cobrança enviando o valor e, opcionalmente, uma referência externa para identificar o pedido no seu sistema:

```bash theme={null}
curl -X POST 'https://app.plowf.com/api/v1/payments' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": 150.00,
    "type": "pix",
    "external_ref": "PEDIDO-12345"
  }'
```

A resposta inclui o campo `payment.payload` com o código Copia e Cola do PIX:

```json theme={null}
{
  "data": {
    "uuid": "770e8400-e29b-41d4-a716-446655440000",
    "status": "PENDING",
    "payment": {
      "payload": "00020126580014br.gov.bcb.pix...",
      "expires_at": "2024-01-01T23:59:59Z"
    },
    "external_ref": "PEDIDO-12345"
  }
}
```

***

## 2. Exibir o QR Code para o pagador

Use o `payload` para gerar o QR Code na sua interface. Exemplo com Node.js:

```javascript theme={null}
const QRCode = require('qrcode');

async function gerarQRCode(payload) {
  const dataUrl = await QRCode.toDataURL(payload);
  return dataUrl; // Base64 PNG para exibir em <img src="...">
}
```

Exiba também o código Copia e Cola como texto para quem preferir copiar e colar no app do banco.

<Note>
  O QR Code expira na data indicada em `payment.expires_at`. Informe o usuário sobre o prazo.
</Note>

***

## Próximos passos

Com a cobrança criada, configure seu endpoint para processar a confirmação de pagamento:

* [Processar confirmação via webhook](/guides/payments/recipes/payment-webhook) — configure o endpoint, registre o webhook e reaja ao evento `PAYMENT`

## Referências

* [Criar Cobrança](/api-reference/payments/create)
* [Evento PAYMENT](/api-reference/webhooks/events/payment)


# Recebendo webhook "PAYMENT"
Source: https://docs.plowf.com/guides/payments/recipes/payment-webhook

Como configurar seu endpoint, registrar o webhook e processar o evento PAYMENT em tempo real

<Note>
  Para mais detalhes sobre o evento PAYMENT e a descrição completa de todos os campos do payload, consulte a [referência do evento PAYMENT](/api-reference/webhooks/events/payment).
</Note>

## Visão Geral

Quando um pagamento PIX é confirmado, a Plowf envia um evento `PAYMENT` para seu endpoint. Esta página mostra como configurar o endpoint, registrar o webhook e reagir aos eventos.

## Pré-requisitos

* Token de autenticação da API ([ver autenticação](/api-reference/auth-and-security))
* Um servidor com endpoint HTTPS acessível publicamente

***

## 1. Configurar seu endpoint de webhook

Prepare um endpoint no seu servidor para receber os eventos. Ele deve:

* Aceitar requisições `POST`
* Validar a assinatura HMAC antes de processar
* Responder com status `2xx` em até 5 segundos

```javascript theme={null}
const crypto = require('crypto');
const express = require('express');

const app = express();
app.use(express.json());

const WEBHOOK_TOKEN = process.env.WEBHOOK_TOKEN;

app.post('/webhooks/plowf', (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  if (!signature) {
    return res.status(401).json({ error: 'Assinatura ausente' });
  }

  const expected = crypto
    .createHmac('sha256', WEBHOOK_TOKEN)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }

  const { event, data } = req.body;

  if (event === 'PAYMENT' && data.status === 'PAID') {
    // Seu pedido foi pago — atualize o banco de dados aqui
    console.log('Cobrança paga:', data.uuid, 'Ref:', data.external_ref);
  }

  res.status(200).json({ received: true });
});
```

<Note>
  Consulte a [página de validação de assinatura](/guides/webhooks/validation) para exemplos em Python e PHP.
</Note>

***

## 2. Registrar o webhook na Plowf

Com seu endpoint pronto, registre-o para receber eventos `PAYMENT`:

```bash theme={null}
curl -X POST 'https://app.plowf.com/api/v1/webhooks' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://seusite.com/webhooks/plowf",
    "token": "token-secreto-que-voce-escolheu"
  }'
```

Guarde o `uuid` do webhook retornado. Guarde também o `token` — você vai usá-lo para validar a assinatura.

***

## 3. Receber e processar o evento PAYMENT

Quando o pagamento for confirmado, a Plowf envia um `POST` para seu endpoint com este payload:

```json theme={null}
{
  "event": "PAYMENT",
  "timestamp": "2024-01-01T10:05:00Z",
  "data": {
    "uuid": "770e8400-e29b-41d4-a716-446655440000",
    "status": "PAID",
    "value": 150,
    "external_ref": "PEDIDO-12345",
    "payment": {
      "pix": {
        "sender": {
          "name": "João Silva",
          "document": "12345678901"
        },
        "transaction": {
          "end_to_end": "E6070119020240101100500000000001",
          "settled_at": "2024-01-01T10:05:00Z"
        }
      }
    }
  }
}
```

Use o campo `external_ref` para identificar a qual pedido o pagamento pertence no seu sistema.

## Status possíveis no evento PAYMENT

| Status               | Significado                    |
| -------------------- | ------------------------------ |
| `PENDING`            | Aguardando pagamento           |
| `PROCESSING`         | Pagamento em processamento     |
| `PAID`               | Pago com sucesso               |
| `EXPIRED`            | QR Code expirado sem pagamento |
| `FAILED`             | Pagamento falhou               |
| `CANCELLED`          | Cobrança cancelada             |
| `REFUNDED`           | Valor estornado                |
| `PARTIALLY_REFUNDED` | Valor estornado parcialmente   |

## Boas práticas

* **Idempotência**: Use o `uuid` da cobrança para evitar processar o mesmo evento mais de uma vez.
* **Resposta rápida**: Responda `200` imediatamente e processe o evento de forma assíncrona se necessário. O timeout é de 5 segundos.
* **Nunca confie sem validar**: Sempre verifique a assinatura HMAC antes de atualizar pedidos.

***

## Cobranças com split

Se a cobrança tiver splits, o evento `PAYMENT` inclui o status de cada split no campo `splits`:

```json theme={null}
{
  "event": "PAYMENT",
  "data": {
    "uuid": "770e8400-e29b-41d4-a716-446655440000",
    "status": "PAID",
    "splits": [
      {
        "uuid": "990e8400-e29b-41d4-a716-446655440002",
        "type": "PERCENTAGE",
        "value": 10,
        "status": "CREDITED",
        "recipient_account": {
          "uuid": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Empresa Parceira LTDA"
        }
      }
    ]
  }
}
```

O status `CREDITED` confirma que o split foi transferido para a conta destinatária.

| Status do split | Significado                           |
| --------------- | ------------------------------------- |
| `PENDING`       | Aguardando processamento              |
| `CREDITED`      | Transferido para a conta destinatária |
| `FAILED`        | Falhou ao transferir                  |

***

## Referências

* [Criar Cobrança](/api-reference/payments/create)
* [Criar Webhook](/api-reference/webhooks/create)
* [Validação de Assinatura](/guides/webhooks/validation)
* [Evento PAYMENT](/api-reference/webhooks/events/payment)


# Criar cobrança PIX com split de pagamento
Source: https://docs.plowf.com/guides/payments/recipes/payment-with-split

Como distribuir automaticamente o valor recebido entre múltiplas contas usando splits percentuais e fixos

<Note>
  Para mais detalhes sobre o endpoint e a descrição completa de todos os campos do body, consulte a [referência do endpoint](/api-reference/payments/create).
</Note>

## Visão Geral

O split de pagamento permite que, ao receber um PIX, o valor seja distribuído automaticamente entre outras contas — por exemplo, para repassar comissões a parceiros ou cobrar taxas de plataforma.

**Dois tipos de split:**

* **`PERCENTAGE`** — repassa uma porcentagem do valor recebido
* **`FIXED`** — repassa um valor fixo em reais independente do total

***

## Pré-requisito

Você precisa do `recipient_account_uuid` de cada conta que vai receber parte do valor. Esse UUID identifica a conta destinatária na plataforma Plowf.

***

## Exemplo 1: Split percentual (comissão de parceiro)

Cenário: cobrança de R\$ 200,00, repassando 15% para um parceiro.

```bash theme={null}
curl -X POST 'https://app.plowf.com/api/v1/payments' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": 200.00,
    "type": "pix",
    "external_ref": "PEDIDO-789",
    "splits": [
      {
        "type": "PERCENTAGE",
        "value": 15,
        "recipient_account_uuid": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'
```

Resultado: o parceiro recebe R\$ 30,00 (15% de R\$ 200,00) automaticamente ao confirmar o pagamento.

***

## Exemplo 2: Split fixo (taxa de plataforma)

Cenário: cobrança de R\$ 100,00, deduzindo R\$ 5,00 fixos como taxa de plataforma.

```bash theme={null}
curl -X POST 'https://app.plowf.com/api/v1/payments' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": 100.00,
    "type": "pix",
    "external_ref": "PEDIDO-790",
    "splits": [
      {
        "type": "FIXED",
        "value": 5.00,
        "recipient_account_uuid": "660e8400-e29b-41d4-a716-446655440001"
      }
    ]
  }'
```

***

## Exemplo 3: Splits combinados (percentual + fixo)

Cenário: cobrança de R\$ 500,00 com dois splits simultâneos.

```bash theme={null}
curl -X POST 'https://app.plowf.com/api/v1/payments' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": 500.00,
    "type": "pix",
    "external_ref": "PEDIDO-791",
    "splits": [
      {
        "type": "PERCENTAGE",
        "value": 10,
        "recipient_account_uuid": "550e8400-e29b-41d4-a716-446655440000"
      },
      {
        "type": "FIXED",
        "value": 8.00,
        "recipient_account_uuid": "660e8400-e29b-41d4-a716-446655440001"
      }
    ]
  }'
```

Resultado: parceiro recebe R\$ 50,00 (10%) + plataforma recebe R\$ 8,00 (fixo). Total distribuído: R\$ 58,00.

***

## Validações importantes

* A soma de todos os splits `PERCENTAGE` não pode ultrapassar **100%**
* A soma total de todos os splits (percentual + fixo) não pode ser maior que o **valor da cobrança**
* Para a **mesma conta**, você não pode ter dois splits do mesmo tipo (ex: dois `PERCENTAGE` para o mesmo `recipient_account_uuid`)
* Para splits `FIXED`, o `value` representa reais (ex: `5.00` = R\$ 5,00)
* Para splits `PERCENTAGE`, o `value` representa porcentagem (ex: `10` = 10%)

***

## Referências

* [Criar Cobrança](/api-reference/payments/create)
* [Processar confirmação via webhook](/guides/payments/recipes/payment-webhook)
* [Evento PAYMENT](/api-reference/webhooks/events/payment)


# Estornar uma cobrança PIX
Source: https://docs.plowf.com/guides/payments/recipes/refund

Como solicitar um estorno total ou parcial de uma cobrança paga e confirmar a liquidação via webhook

<Note>
  Para mais detalhes sobre o endpoint e a descrição completa de todos os campos do body, consulte a [referência do endpoint](/api-reference/payments/refund).
</Note>

## Visão Geral

Esta receita mostra como estornar uma cobrança PIX já paga e acompanhar a confirmação do estorno via webhook.

**O fluxo completo:**

1. Solicitar o estorno (total ou parcial)
2. Receber a confirmação via webhook `REFUND`

## Pré-requisitos

* Token de autenticação da API ([ver autenticação](/api-reference/auth-and-security))
* UUID da cobrança com status `PAID`

***

## 1. Solicitar o estorno

### Estorno total

Omita o campo `value` para estornar o valor integral da cobrança:

```bash theme={null}
curl -X POST 'https://app.plowf.com/api/v1/payments/770e8400-e29b-41d4-a716-446655440000/refund' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json'
```

### Estorno parcial

Informe `value` para estornar apenas parte do valor:

```bash theme={null}
curl -X POST 'https://app.plowf.com/api/v1/payments/770e8400-e29b-41d4-a716-446655440000/refund' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": 100.00
  }'
```

A resposta confirma que o estorno foi iniciado com status `PROCESSING`:

```json theme={null}
{
  "message": "Reembolso iniciado",
  "data": {
    "uuid": "770e8400-e29b-41d4-a716-446655440000",
    "status": "PROCESSING",
    "value": 247.99,
    "fees": 0.5,
    "origin": {
        "uuid": "880e8400-e29b-41d4-a716-446655440001",
        "value": 247.99,
        "fees": 0.5,
    },
    "origin_type": "PAYMENT",
    "refund": {
      "status": "PROCESSING",
      "value": 100.00,
      "pix_original": {
        "end_to_end": "E6070119020240101100500000000001"
      }
    }
  }
}
```

<Note>
  Após um estorno parcial, o status da cobrança será `PARTIALLY_REFUNDED`. Após um estorno total, o status será `REFUNDED`. Você pode realizar múltiplos estornos parciais enquanto houver saldo disponível.
</Note>

***

## 2. Receber a confirmação via webhook

Quando o estorno for processado, a Plowf envia um evento `REFUND` para seu endpoint. Configure-o para escutar esse evento:

```javascript theme={null}
app.post('/webhooks/plowf', (req, res) => {
  // Valide a assinatura HMAC antes de processar
  const { event, data } = req.body;

  if (event === 'REFUND') {
    const refundStatus = data.refund.status;

    if (refundStatus === 'SETTLED') {
      // Estorno liquidado — atualize seu sistema
      console.log('Estorno confirmado para cobrança:', data.uuid);
    } else if (refundStatus === 'FAILED') {
      // Estorno falhou — notifique sua equipe ou tente novamente
      console.log('Estorno falhou para cobrança:', data.uuid);
    }
  }

  res.status(200).json({ received: true });
});
```

<Note>
  Consulte a [página de validação de assinatura](/guides/webhooks/validation) para ver como validar a assinatura HMAC.
</Note>

## Status possíveis do estorno

| Status       | Significado                   |
| ------------ | ----------------------------- |
| `PROCESSING` | Estorno em processamento      |
| `SETTLED`    | Estorno liquidado com sucesso |
| `FAILED`     | Estorno falhou                |
| `CANCELLED`  | Estorno cancelado             |

## Boas práticas

* **Idempotência**: Use o `uuid` da cobrança para evitar processar o mesmo evento `REFUND` mais de uma vez.
* **Resposta rápida**: Responda `200` imediatamente e processe o evento de forma assíncrona se necessário.
* **Nunca confie sem validar**: Sempre verifique a assinatura HMAC antes de atualizar seu sistema.

***

## Referências

* [Estornar Cobrança](/api-reference/payments/refund)
* [Evento REFUND](/api-reference/webhooks/events/refund)
* [Validação de Assinatura](/guides/webhooks/validation)


# Referência API
Source: https://docs.plowf.com/guides/pix-keys/api-link





# Introdução
Source: https://docs.plowf.com/guides/pix-keys/intro

Gerencie as chaves PIX vinculadas à sua conta de forma programática

Chaves PIX são os identificadores que permitem receber transferências PIX na sua conta. Você pode cadastrar, consultar e remover chaves diretamente pela API.

## O que você pode fazer

* **Cadastrar chaves** dos tipos `DOCUMENT`, `EMAIL`, `PHONE` e `RANDOM`
* **Listar e consultar** as chaves ativas da conta
* **Remover chaves** quando não forem mais necessárias

## Tipos de chave

| Tipo       | Descrição                                                                                    |
| ---------- | -------------------------------------------------------------------------------------------- |
| `DOCUMENT` | CPF (11 dígitos, ex: `52998224725`) ou CNPJ (14 dígitos, ex: `12345678000100`)               |
| `EMAIL`    | Endereço de e-mail (ex: `user@email.com`) — requer código de autenticação                    |
| `PHONE`    | Número de telefone com código do país (ex: `+5511999999999`) — requer código de autenticação |
| `RANDOM`   | Chave aleatória (UUID, ex: `550e8400-e29b-41d4-a716-446655440000`)                           |

## Limites

* Máximo de **3 chaves por tipo** por conta
* Chaves do tipo `EMAIL` e `PHONE` exigem verificação prévia via [código de autenticação](/api-reference/pix-keys/auth-code)
* Alguns providers não suportam chaves `EMAIL` e `PHONE`

## Referência da API

<CardGroup>
  <Card title="Listar Chaves PIX" icon="list" href="/api-reference/pix-keys/list">
    `GET /api/v1/pix-keys`
  </Card>

  <Card title="Buscar Chave PIX" icon="magnifying-glass" href="/api-reference/pix-keys/get">
    `GET /api/v1/pix-keys/{key}`
  </Card>

  <Card title="Criar Chave PIX" icon="plus" href="/api-reference/pix-keys/create">
    `POST /api/v1/pix-keys`
  </Card>

  <Card title="Remover Chave PIX" icon="trash" href="/api-reference/pix-keys/delete">
    `DELETE /api/v1/pix-keys/{key}`
  </Card>
</CardGroup>

## Receitas

<CardGroup>
  <Card title="Criar chave PIX" href="/guides/pix-keys/recipes/create-pix-key">
    Cadastre uma chave simples ou siga o fluxo de verificação para EMAIL e PHONE
  </Card>
</CardGroup>


# Criar chave PIX
Source: https://docs.plowf.com/guides/pix-keys/recipes/create-pix-key

Como cadastrar uma chave PIX na sua conta, incluindo o fluxo de verificação para EMAIL e PHONE

<Note>
  Para a descrição completa de todos os campos, consulte a [referência do endpoint](/api-reference/pix-keys/create).
</Note>

## Visão Geral

Existem dois fluxos dependendo do tipo de chave:

* **`DOCUMENT` e `RANDOM`** — uma única chamada à API cria a chave imediatamente.
* **`EMAIL` e `PHONE`** — é necessário solicitar um código de verificação primeiro e informá-lo na criação.

***

## Fluxo 1 — Chaves simples (DOCUMENT e RANDOM)

### 1. Criar a chave

Envie apenas o `type`. A chave é criada a partir dos dados já vinculados à conta:

```bash DOCUMENT theme={null}
curl -X POST 'https://app.plowf.com/api/v1/pix-keys' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "DOCUMENT" }'
```

```bash RANDOM theme={null}
curl -X POST 'https://app.plowf.com/api/v1/pix-keys' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "RANDOM" }'
```

A resposta retorna a chave criada:

```json theme={null}
{
  "message": "Chave PIX criada com sucesso.",
  "data": {
    "key": "52998224725",
    "type": "DOCUMENT",
    "is_active": true,
    "created_at": "2026-01-19T19:32:14.000000Z"
  }
}
```

Para chaves `RANDOM`, o campo `key` conterá um UUID gerado automaticamente.

***

## Fluxo 2 — Chaves com verificação (EMAIL e PHONE)

### 1. Solicitar o código de autenticação

Antes de criar a chave, solicite o envio de um código de verificação para o valor da chave desejada:

```bash EMAIL theme={null}
curl -X POST 'https://app.plowf.com/api/v1/pix-keys/auth-code' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{ "key": "user@email.com" }'
```

```bash PHONE theme={null}
curl -X POST 'https://app.plowf.com/api/v1/pix-keys/auth-code' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{ "key": "+5511999999999" }'
```

A resposta retorna o identificador do código enviado:

```json theme={null}
{
  "message": "Código de autenticação enviado com sucesso.",
  "data": {
    "auth_code_id": "abc123xyz"
  }
}
```

Armazene o `auth_code_id` — ele será necessário na próxima etapa.

<Note>
  O código tem rate limit de **3 tentativas por 60 segundos** por conta. Se o usuário não receber, aguarde antes de reenviar.
</Note>

### 2. Criar a chave com o código recebido

Informe o `auth_code_id` retornado e o código que o usuário recebeu por SMS ou e-mail:

```bash EMAIL theme={null}
curl -X POST 'https://app.plowf.com/api/v1/pix-keys' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "EMAIL",
    "auth_code_id": "abc123xyz",
    "auth_code": "123456"
  }'
```

```bash PHONE theme={null}
curl -X POST 'https://app.plowf.com/api/v1/pix-keys' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "PHONE",
    "auth_code_id": "abc123xyz",
    "auth_code": "123456"
  }'
```

Resposta de sucesso:

```json theme={null}
{
  "message": "Chave PIX criada com sucesso.",
  "data": {
    "key": "user@email.com",
    "type": "EMAIL",
    "is_active": true,
    "created_at": "2026-01-19T19:32:14.000000Z"
  }
}
```

***

## Tratamento de erros

| Código | Causa                                       | Ação recomendada                                         |
| ------ | ------------------------------------------- | -------------------------------------------------------- |
| `403`  | Conta virtual inativa                       | Verifique o status da conta antes de tentar criar chaves |
| `422`  | Chave já cadastrada em outra conta          | Informe o usuário que a chave não está disponível        |
| `422`  | Código de autenticação inválido ou expirado | Solicite um novo código e repita o fluxo                 |
| `422`  | Provider não suporta este tipo de chave     | Use um tipo alternativo (`DOCUMENT` ou `RANDOM`)         |
| `429`  | Rate limit excedido                         | Aguarde 60 segundos antes de tentar novamente            |

***

## Referências

* [Solicitar Código de Autenticação](/api-reference/pix-keys/auth-code)
* [Criar Chave PIX](/api-reference/pix-keys/create)
* [Listar Chaves PIX](/api-reference/pix-keys/list)
* [Remover Chave PIX](/api-reference/pix-keys/delete)


# Referência API
Source: https://docs.plowf.com/guides/transfers/api-link





# Introdução
Source: https://docs.plowf.com/guides/transfers/intro

Envie PIX Out para qualquer chave PIX de forma programática

Transferências são **PIX Out** — pagamentos que você inicia para enviar dinheiro a uma chave PIX. O destinatário pode ser qualquer conta no sistema PIX, dentro ou fora da plataforma Plowf.

## O que você pode fazer

* **Enviar PIX** para qualquer chave (CPF, CNPJ, e-mail, telefone ou chave aleatória)
* **Referenciar** a transferência com `external_ref` para rastreamento no seu sistema
* **Identificar o beneficiário final** (`final_beneficiary`) para fins de compliance
* **Consultar** o status e o histórico de uma transferência específica

## Ciclo de vida

```
PENDING → PROCESSING → PAID → REFUNDED
PENDING → PROCESSING → PAID → PARTIALLY_REFUNDED → REFUNDED
PENDING → PROCESSING → FAILED
PENDING → CANCELLED       
```

Quando uma transferência muda de status, um webhook [`TRANSFER`](/guides/transfers/recipes/transfer-webhook) é disparado automaticamente.

## Referência da API

<CardGroup>
  <Card title="Criar Transferência" icon="plus" href="/api-reference/transfers/create">
    `POST /api/v1/transfers`
  </Card>

  <Card title="Listar Transferências" icon="list" href="/api-reference/transfers/list">
    `GET /api/v1/transfers`
  </Card>

  <Card title="Detalhar Transferência" icon="magnifying-glass" href="/api-reference/transfers/get">
    `GET /api/v1/transfers/{uuid}`
  </Card>
</CardGroup>

## Receitas

<CardGroup>
  <Card title="Criar transferência PIX" href="/guides/transfers/recipes/transfer">
    Envie um PIX Out e acompanhe o status pelo uuid
  </Card>

  <Card title="Processar confirmação via webhook" href="/guides/transfers/recipes/transfer-webhook">
    Receba o evento TRANSFER, valide a assinatura e trate falhas
  </Card>
</CardGroup>


# Criar transferência PIX
Source: https://docs.plowf.com/guides/transfers/recipes/transfer

Passo a passo para enviar um PIX Out

<Note>
  Para mais detalhes sobre o endpoint e a descrição completa de todos os campos do body, consulte a [referência do endpoint](/api-reference/transfers/create).
</Note>

## Visão Geral

Esta receita mostra como criar uma transferência PIX e receber a confirmação de liquidação automaticamente via webhook, sem precisar consultar a API repetidamente.

**O fluxo completo:**

1. Criar a transferência PIX
2. Receber e processar o evento `TRANSFER` ([ver página dedicada](/guides/transfers/recipes/transfer-webhook))

## Pré-requisitos

* Token de autenticação da API ([ver autenticação](/api-reference/auth-and-security))
* Chave PIX do destinatário: CPF (`52998224725`), CNPJ (`12345678000100`), e-mail (`user@email.com`), telefone (`+5511999999999`) ou chave aleatória (UUID)
* Webhook configurado para receber eventos `TRANSFER` ([ver Webhooks](/guides/webhooks/intro))

***

## 1. Criar a transferência PIX

Envie o valor e a chave PIX do destinatário. Use `external_ref` para rastrear a transferência no seu sistema:

```bash theme={null}
curl -X POST 'https://app.plowf.com/api/v1/transfers' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": 250.00,
    "pix_key": "destinatario@email.com",
    "external_ref": "SAQUE-98765"
  }'
```

A resposta retorna a transferência com status `PROCESSING`:

```json theme={null}
{
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "value": 250.00,
    "fees": 0.50,
    "status": "PROCESSING",
    "type": "PIX",
    "external_ref": "SAQUE-98765",
    "transfer": {
      "initiation": {
        "receiver": {
          "name": "Maria Santos",
          "bank": { "name": "BANCO INTER S.A." }
        },
        "pix_key": "destinatario@email.com"
      }
    }
  }
}
```

Armazene o `uuid` retornado para correlacionar com os eventos de webhook.

<Note>
  A transferência vai para `PROCESSING` imediatamente, mas só é liquidada quando o sistema PIX confirmar o crédito na conta destino. Aguarde o webhook para garantir a liquidação.
</Note>

***

## Próximos passos

Com a transferência criada, configure seu endpoint para processar a confirmação:

* [Processar confirmação via webhook](/guides/transfers/recipes/transfer-webhook) — receba o evento `TRANSFER`, valide a assinatura e trate falhas

## Referências

* [Criar Transferência](/api-reference/transfers/create)
* [Detalhar Transferência](/api-reference/transfers/get)
* [Evento TRANSFER](/api-reference/webhooks/events/transfer)


# Recebendo webhook "TRANSFER"
Source: https://docs.plowf.com/guides/transfers/recipes/transfer-webhook

Como receber e tratar o evento TRANSFER para confirmar a liquidação ou falha de um PIX Out

<Note>
  Para mais detalhes sobre o evento TRANSFER e a descrição completa de todos os campos do payload, consulte a [referência do evento TRANSFER](/api-reference/webhooks/events/transfer).
</Note>

## Visão Geral

Quando uma transferência PIX é liquidada ou falha, a Plowf envia um evento `TRANSFER` para seu endpoint de webhook. Use esse evento para confirmar a liquidação sem precisar consultar a API repetidamente.

## Pré-requisitos

* Webhook configurado para receber eventos `TRANSFER` ([ver Webhooks](/guides/webhooks/intro))
* Transferência criada ([ver Criar transferência PIX](/guides/transfers/recipes/transfer))

***

## 1. Receber e processar o evento TRANSFER

Quando a transferência for liquidada (ou falhar), a Plowf envia um `POST` para seu endpoint:

```json theme={null}
{
  "event": "TRANSFER",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "PAID",
    "value": 250.00,
    "external_ref": "SAQUE-98765",
    "transfer": {
      "end_to_end": "E000000002024010112000000000001",
      "settled_at": "2024-01-01T12:00:00Z"
    }
  }
}
```

No seu endpoint, valide a assinatura e reaja ao status:

```javascript theme={null}
const crypto = require('crypto');
const express = require('express');

const app = express();
app.use(express.json());

const WEBHOOK_TOKEN = process.env.WEBHOOK_TOKEN;

app.post('/webhooks/plowf', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const expected = crypto
    .createHmac('sha256', WEBHOOK_TOKEN)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }

  const { event, data } = req.body;

  if (event === 'TRANSFER') {
    if (data.status === 'PAID') {
      // Transferência liquidada — libere o fluxo no seu sistema
      console.log('Transferência confirmada:', data.uuid, 'Ref:', data.external_ref);
      console.log('End-to-end:', data.transfer.end_to_end);
    } else if (data.status === 'FAILED') {
      // Transferência falhou — notifique e trate o reenvio
      console.error('Transferência falhou:', data.uuid);
    }
  }

  res.status(200).json({ received: true });
});
```

<Note>
  Consulte a [página de validação de assinatura](/guides/webhooks/validation) para exemplos em Python e PHP.
</Note>

***

## 2. Tratar falhas

Se a transferência falhar (`FAILED`), o valor não é debitado. Você pode criar uma nova transferência para reenviar:

```javascript theme={null}
async function reenviarTransferencia(transferenciaOriginal) {
  const response = await fetch('https://app.plowf.com/api/v1/transfers', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.PLOWF_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      value: transferenciaOriginal.value,
      pix_key: transferenciaOriginal.pix_key,
      external_ref: `${transferenciaOriginal.external_ref}-RETRY`,
    }),
  });

  return response.json();
}
```

## Status possíveis no evento TRANSFER

| Status               | Significado                      |
| -------------------- | -------------------------------- |
| `PENDING`            | Aguardando processamento         |
| `PROCESSING`         | Em processamento no sistema PIX  |
| `PAID`               | Liquidada com sucesso            |
| `FAILED`             | Falhou — valor não debitado      |
| `CANCELLED`          | Cancelada antes do processamento |
| `REFUNDED`           | Valor estornado                  |
| `PARTIALLY_REFUNDED` | Valor estornado parcialmente     |

## Boas práticas

* **Idempotência**: Use o `uuid` da transferência para evitar processar o mesmo evento mais de uma vez.
* **Nunca confirme por polling**: Aguarde o webhook `PAID` antes de considerar a transferência concluída.
* **Trate `FAILED` imediatamente**: Notifique o usuário e registre a causa para diagnóstico.

## Referências

* [Criar Transferência](/api-reference/transfers/create)
* [Evento TRANSFER](/api-reference/webhooks/events/transfer)
* [Validação de Assinatura](/guides/webhooks/validation)


# Referência API
Source: https://docs.plowf.com/guides/webhooks/api-link





# Firewall e IPs
Source: https://docs.plowf.com/guides/webhooks/firewall

Configure seu firewall para aceitar requisições da plataforma Plowf

Os webhooks da plataforma são enviados a partir de endereços IP fixos. Se o seu servidor possui um firewall ou uma lista de permissões (allowlist), você precisa liberar o tráfego originário desses IPs para que os webhooks cheguem corretamente.

## IPs oficiais

| IP                | Região           |
| ----------------- | ---------------- |
| `44.196.41.87/32` | US - N. Virginia |

Você também pode baixar a lista em formato JSON para uso em scripts e automações: [webhook-ips.json](/webhook-ips.json)

<Warning>
  Esta lista pode ser atualizada conforme a infraestrutura evolui. Verifique esta página antes de configurar seu firewall.
</Warning>

## Configuração

### iptables (Linux)

```bash theme={null}
# Liberar porta 443 (HTTPS) para os IPs da Plowf
iptables -A INPUT -s 44.196.41.87 -p tcp --dport 443 -j ACCEPT
```

### AWS Security Group

No console da AWS (EC2 → Security Groups → Inbound rules), adicione:

| Type  | Protocol | Port | Source            |
| ----- | -------- | ---- | ----------------- |
| HTTPS | TCP      | 443  | `44.196.41.87/32` |

Via AWS CLI:

```bash theme={null}
aws ec2 authorize-security-group-ingress \
  --group-id sg-xxxxxxxx \
  --protocol tcp \
  --port 443 \
  --cidr 44.196.41.87/32
```

### Nginx

Se você usa Nginx como proxy reverso, restrinja o acesso ao endpoint de webhook por IP:

```nginx theme={null}
location /webhooks/plowf {
    allow 44.196.41.87;
    deny all;
    proxy_pass http://localhost:3000;
}
```

### Cloudflare

Se o seu domínio está por trás do Cloudflare, o tráfego dos webhooks passa pelos servidores da Cloudflare antes de chegar ao seu servidor. Isso pode fazer com que o IP de origem visível seja da Cloudflare, e não da Plowf — o que exige configuração adicional.

**Opção 1 — Regra WAF (recomendado)**

Crie uma regra no **Security → WAF → Custom rules** que permite o acesso ao seu endpoint de webhook diretamente pelos IPs da Plowf, antes de qualquer outra verificação:

| Campo      | Valor                                                                             |
| ---------- | --------------------------------------------------------------------------------- |
| Expression | `(ip.src eq 44.196.41.87) and (http.request.uri.path contains "/webhooks/plowf")` |
| Action     | `Allow`                                                                           |

Isso garante que requisições vindas dos IPs da Plowf não sejam bloqueadas por regras de rate limiting, Bot Fight Mode ou outros desafios.

**Opção 2 — IP Access Rules**

Em **Security → WAF → Tools → IP Access Rules**, adicione o IP `44.196.41.87` com a ação **Allow** e escopo **Website**. Essa opção é mais simples, mas se aplica a todas as rotas do domínio.

**Opção 3 — Desativar o proxy para o endpoint (modo DNS-only)**

Se você não precisa que o Cloudflare faça proxy do seu endpoint de webhook, pode configurar o registro DNS correspondente como **DNS only** (ícone de nuvem cinza no painel). Assim, o IP real do seu servidor é exposto e a filtragem por IP no servidor funciona normalmente.

<Warning>
  O modo **DNS only** expõe o IP real do seu servidor. Avalie os tradeoffs de segurança antes de adotar essa abordagem.
</Warning>

## Diagnóstico

Se os webhooks não chegam ao seu servidor, verifique:

1. O endpoint responde a requisições HTTPS externas?
2. O firewall permite tráfego de entrada na porta 443?
3. Os IPs acima estão na allowlist?
4. O certificado SSL é válido (não autoassinado)?

<Tip>
  Use o [webhook.site](https://webhook.site) para criar um endpoint temporário e verificar se os webhooks chegam corretamente antes de depurar seu próprio servidor.
</Tip>


# Idempotência
Source: https://docs.plowf.com/guides/webhooks/idempotency

Como garantir que o mesmo webhook não seja processado mais de uma vez

A plataforma pode reenviar um webhook em caso de falha — por exemplo, se o seu servidor não respondeu a tempo ou retornou um status não-2xx. Por isso, seu endpoint deve ser **idempotente**: processar o mesmo evento duas vezes deve produzir o mesmo resultado que processar uma vez.

## Estratégia

A abordagem recomendada é **salvar um hash do payload recebido** e, antes de processar qualquer evento, verificar se aquele hash já foi registrado.

```
Receber evento
    ↓
Calcular hash do payload (SHA-256)
    ↓
Hash já existe no banco? → Sim → Retornar 200 (ignorar)
    ↓ Não
Processar evento
    ↓
Salvar hash no banco
```

### Schema sugerido

```sql theme={null}
CREATE TABLE webhook_events (
  hash        CHAR(64) PRIMARY KEY,  -- SHA-256 em hex
  event       VARCHAR(50) NOT NULL,
  received_at TIMESTAMP   NOT NULL DEFAULT NOW()
);
```

## Implementação

### Node.js

```javascript theme={null}
const crypto = require('crypto');
const express = require('express');

const app = express();

// Usar o corpo bruto como texto para garantir consistência do hash
app.use(express.text({ type: 'application/json' }));

app.post('/webhooks/plowf', async (req, res) => {
  const rawBody = req.body; // string bruta, antes de qualquer parse
  const signature = req.headers['x-webhook-signature'];

  // ... validar assinatura HMAC (ver guia de validação)

  const hash = crypto.createHash('sha256').update(rawBody).digest('hex');

  // Verificar se o evento já foi processado
  const { rowCount } = await db.query(
    'SELECT 1 FROM webhook_events WHERE hash = $1',
    [hash]
  );
  if (rowCount > 0) {
    return res.status(200).json({ received: true }); // duplicado, ignorar
  }

  // Registrar o hash e processar
  const payload = JSON.parse(rawBody);
  await db.query(
    'INSERT INTO webhook_events (hash, event) VALUES ($1, $2)',
    [hash, payload.event]
  );

  // ... lógica de negócio

  res.status(200).json({ received: true });
});
```

### Python

```python theme={null}
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/plowf', methods=['POST'])
def webhook():
    raw_body = request.get_data()  # bytes brutos
    signature = request.headers.get('X-Webhook-Signature')

    # ... validar assinatura HMAC (ver guia de validação)

    hash_val = hashlib.sha256(raw_body).hexdigest()

    # Verificar se o evento já foi processado
    cursor.execute('SELECT 1 FROM webhook_events WHERE hash = %s', (hash_val,))
    if cursor.fetchone():
        return jsonify({'received': True}), 200  # duplicado, ignorar

    # Registrar o hash e processar
    payload = request.get_json()
    cursor.execute(
        'INSERT INTO webhook_events (hash, event) VALUES (%s, %s)',
        (hash_val, payload['event'])
    )

    # ... lógica de negócio

    return jsonify({'received': True}), 200
```

### PHP

```php theme={null}
<?php

$rawBody = file_get_contents('php://input');  // bytes brutos
$hash = hash('sha256', $rawBody);
$payload = json_decode($rawBody, true);

// ... validar assinatura HMAC (ver guia de validação)

// Verificar se o evento já foi processado
$stmt = $pdo->prepare('SELECT 1 FROM webhook_events WHERE hash = ?');
$stmt->execute([$hash]);
if ($stmt->fetch()) {
    http_response_code(200);
    echo json_encode(['received' => true]);  // duplicado, ignorar
    exit;
}

// Registrar o hash e processar
$stmt = $pdo->prepare('INSERT INTO webhook_events (hash, event) VALUES (?, ?)');
$stmt->execute([$hash, $payload['event']]);

// ... lógica de negócio

http_response_code(200);
echo json_encode(['received' => true]);
```

## Pontos importantes

* **Hash do corpo bruto**: calcule o hash antes de qualquer parse JSON para garantir consistência entre reenvios.
* **Retorne 200 mesmo se duplicado**: não retornar 2xx faz a plataforma continuar tentando reenviar.
* **Limpeza periódica**: considere remover registros com mais de 30 dias para evitar crescimento indefinido da tabela.

<Warning>
  Não use apenas `data.uuid` como chave de idempotência. O mesmo objeto pode gerar eventos distintos conforme o status muda (ex: `PENDING` → `PAID` → `REFUNDED`). O hash do payload completo garante que cada combinação de evento e estado seja única.
</Warning>


# Introdução
Source: https://docs.plowf.com/guides/webhooks/intro

Receba notificações em tempo real sobre eventos da sua conta

Webhooks são requisições `POST` que a plataforma envia para a URL do seu servidor quando eventos importantes acontecem — como um PIX recebido, uma transferência liquidada ou um MED aberto. Em vez de consultar a API repetidamente, você reage a eventos conforme eles ocorrem.

## Eventos disponíveis

| Evento     | Quando é disparado                          |
| ---------- | ------------------------------------------- |
| `PAYMENT`  | Cobrança criada ou com status alterado      |
| `TRANSFER` | Transferência criada ou com status alterado |
| `REFUND`   | Estorno processado                          |
| `MED`      | MED recebido ou com status alterado         |

## Como funciona

1. Você registra uma URL na plataforma via API
2. A plataforma envia um `POST` para essa URL a cada evento
3. Seu servidor valida a assinatura HMAC no header `X-Webhook-Signature`
4. Seu servidor responde com HTTP `2xx` para confirmar o recebimento

<Warning>
  Sempre valide a assinatura HMAC antes de processar o payload. Implemente idempotência usando o `uuid` do objeto no evento — o mesmo webhook pode ser reenviado em caso de falha.
</Warning>

## Referência da API

<CardGroup>
  <Card title="Criar Webhook" icon="plus" href="/api-reference/webhooks/create">
    `POST /api/v1/webhooks`
  </Card>

  <Card title="Listar Webhooks" icon="list" href="/api-reference/webhooks/list">
    `GET /api/v1/webhooks`
  </Card>

  <Card title="Detalhar Webhook" icon="magnifying-glass" href="/api-reference/webhooks/get">
    `GET /api/v1/webhooks/{uuid}`
  </Card>

  <Card title="Excluir Webhook" icon="trash" href="/api-reference/webhooks/delete">
    `DELETE /api/v1/webhooks/{uuid}`
  </Card>
</CardGroup>

## Eventos detalhados

<CardGroup>
  <Card title="Estrutura geral" href="/api-reference/webhooks/introduction">
    Estrutura geral e headers
  </Card>

  <Card title="Validação de assinatura" href="/guides/webhooks/validation">
    Validação de assinatura HMAC
  </Card>

  <Card title="Evento PAYMENT" href="/api-reference/webhooks/events/payment">
    Payload do evento de cobrança
  </Card>

  <Card title="Evento TRANSFER" href="/api-reference/webhooks/events/transfer">
    Payload do evento de transferência
  </Card>

  <Card title="Evento MED" href="/api-reference/webhooks/events/med">
    Payload do evento de MED
  </Card>

  <Card title="Evento PIX_TRANSACTION" href="/api-reference/webhooks/events/pix-transaction">
    Payload do evento de transação PIX
  </Card>
</CardGroup>


# Polling vs Webhooks
Source: https://docs.plowf.com/guides/webhooks/polling-vs-webhooks

Quando usar consulta periódica à API versus notificações por webhook

Existem duas formas de acompanhar eventos na plataforma: **polling** (consultando a API periodicamente) e **webhooks** (recebendo notificações quando os eventos ocorrem). Cada abordagem tem seus casos de uso.

## Comparação

|                    | Polling                                         | Webhooks                                          |
| ------------------ | ----------------------------------------------- | ------------------------------------------------- |
| **Como funciona**  | Você consulta a API em intervalos regulares     | A plataforma envia uma requisição ao seu servidor |
| **Latência**       | Alta — depende do intervalo de consulta         | Baixa — notificação imediata                      |
| **Carga na API**   | Alta — requisições constantes mesmo sem eventos | Baixa — requisição apenas quando há evento        |
| **Complexidade**   | Menor — sem endpoint exposto                    | Maior — requer endpoint HTTPS público             |
| **Confiabilidade** | Você controla a frequência                      | Depende de rede e disponibilidade do seu servidor |

## Quando usar webhooks

Webhooks são a abordagem recomendada para a maioria dos casos:

* Atualizar o status de um pedido assim que o PIX é recebido
* Disparar notificações ou e-mails ao cliente
* Acionar lógica de negócio em tempo real

## Quando usar polling

Polling pode ser útil em cenários específicos:

* **Reconciliação**: verificar periodicamente se todos os eventos foram processados corretamente
* **Recuperação de falhas**: identificar eventos perdidos por indisponibilidade do seu servidor
* **Ambientes sem endpoint público**: servidores internos sem exposição à internet

## Recomendação

Use webhooks como mecanismo principal e polling como fallback de reconciliação. Por exemplo, um job noturno que consulta a API e compara com os eventos já processados garante que nenhum evento seja perdido.

<Tip>
  Ao usar polling para reconciliação, filtre por `updated_at` para buscar apenas os registros alterados desde a última consulta e reduzir o volume de dados retornados.
</Tip>


# Criar e registrar um webhook
Source: https://docs.plowf.com/guides/webhooks/recipes/create

Como preparar seu endpoint, registrar o webhook na Plowf e verificar a configuração

## Pré-requisitos

* Token de autenticação da API ([ver autenticação](/api-reference/auth-and-security))
* Um servidor com endpoint HTTPS acessível publicamente

***

## 1. Preparar seu endpoint

Crie um endpoint `POST` no seu servidor para receber os eventos. Ele deve validar a assinatura HMAC e responder com `2xx` em até 5 segundos.

```javascript theme={null}
const crypto = require('crypto');
const express = require('express');

const app = express();
app.use(express.json());

const WEBHOOK_TOKEN = process.env.WEBHOOK_TOKEN;

app.post('/webhooks/plowf', (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  if (!signature) {
    return res.status(401).json({ error: 'Assinatura ausente' });
  }

  const expected = crypto
    .createHmac('sha256', WEBHOOK_TOKEN)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }

  const { event, data } = req.body;
  console.log('Evento recebido:', event, data.uuid);

  res.status(200).json({ received: true });
});

app.listen(3000);
```

<Note>
  Consulte a [página de validação de assinatura](/guides/webhooks/validation) para exemplos em Python e PHP.
</Note>

***

## 2. Registrar o webhook na Plowf

Com o endpoint pronto, registre-o via API. Você pode escolher os eventos que quer receber ou omitir `events` para receber todos.

```bash theme={null}
curl -X POST 'https://app.plowf.com/api/v1/webhooks' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://seusite.com/webhooks/plowf",
    "token": "token-secreto-que-voce-escolheu",
    "events": ["PAYMENT", "TRANSFER"]
  }'
```

A resposta retorna o webhook criado:

```json theme={null}
{
  "data": {
    "uuid": "e1afe0f4-9358-4a50-b0fd-55912ca86ee1",
    "url": "https://seusite.com/webhooks/plowf",
    "token": "token-secreto-que-voce-escolheu",
    "status": "ACTIVE",
    "events": ["PAYMENT", "TRANSFER"],
    "created_at": "2026-01-13T00:37:47.000000Z"
  }
}
```

<Warning>
  Guarde o `token` com segurança — você vai usá-lo para validar a assinatura de todos os eventos recebidos. Se você não informar um token, a plataforma gera um automaticamente.
</Warning>

***

## 3. Verificar o webhook criado

Use o `uuid` retornado para confirmar a configuração:

```bash theme={null}
curl 'https://app.plowf.com/api/v1/webhooks/e1afe0f4-9358-4a50-b0fd-55912ca86ee1' \
  -H 'Authorization: Bearer seu_token_aqui'
```

## Boas práticas

* **HTTPS obrigatório**: A plataforma só aceita URLs com HTTPS.
* **Filtre os eventos**: Especifique apenas os eventos relevantes para reduzir o volume de requisições no seu servidor.
* **Idempotência**: Use o `uuid` do objeto recebido no evento para evitar processar o mesmo evento mais de uma vez.
* **Resposta rápida**: Responda `200` imediatamente e processe o evento de forma assíncrona se necessário. O timeout é de 5 segundos.

## Eventos disponíveis

| Evento            | Quando é disparado                         |
| ----------------- | ------------------------------------------ |
| `PAYMENT`         | Status de uma cobrança atualizado          |
| `TRANSFER`        | Status de uma transferência atualizado     |
| `REFUND`          | Estorno processado                         |
| `MED`             | Status de um MED atualizado                |
| `PIX_TRANSACTION` | Transação PIX recebida via chave ou manual |

## Referências

* [Criar Webhook](/api-reference/webhooks/create)
* [Listar Webhooks](/api-reference/webhooks/list)
* [Excluir Webhook](/api-reference/webhooks/delete)
* [Validação de Assinatura](/guides/webhooks/validation)


# Validação de Assinatura
Source: https://docs.plowf.com/guides/webhooks/validation

Como validar a assinatura HMAC dos webhooks

## Visão Geral

Todos os webhooks enviados pela plataforma incluem uma assinatura HMAC SHA-256 no header `X-Webhook-Signature`. Esta assinatura permite que você valide que o webhook é legítimo e foi enviado pela plataforma.

## Por que Validar?

A validação da assinatura é essencial para:

* **Segurança**: Garantir que o webhook foi enviado pela plataforma e não por um atacante
* **Integridade**: Verificar que o payload não foi alterado durante a transmissão
* **Autenticação**: Confirmar a identidade do remetente

## Como Funciona

A assinatura é gerada usando:

1. **Algoritmo**: HMAC SHA-256
2. **Chave**: O token secreto configurado no webhook
3. **Mensagem**: O payload JSON completo (stringificado)

## Implementação

### Node.js

```javascript theme={null}
const crypto = require('crypto');
const express = require('express');

const app = express();
app.use(express.json());

const WEBHOOK_TOKEN = 'seu-token-aqui'; // Token configurado no webhook

function validateWebhookSignature(payload, signature, token) {
  const expectedSignature = crypto
    .createHmac('sha256', token)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return signature === expectedSignature;
}

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  
  if (!signature) {
    return res.status(401).json({ error: 'Missing signature' });
  }
  
  // Validar assinatura
  const isValid = validateWebhookSignature(req.body, signature, WEBHOOK_TOKEN);
  
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Processar webhook
  // ...
  
  res.status(200).json({ received: true });
});
```

### Python

```python theme={null}
import hmac
import hashlib
import json
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_TOKEN = 'seu-token-aqui'  # Token configurado no webhook

def validate_webhook_signature(payload, signature, token):
    expected_signature = hmac.new(
        token.encode('utf-8'),
        json.dumps(payload, separators=(',', ':')).encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature')
    
    if not signature:
        return jsonify({'error': 'Missing signature'}), 401
    
    # Validar assinatura
    if not validate_webhook_signature(request.json, signature, WEBHOOK_TOKEN):
        return jsonify({'error': 'Invalid signature'}), 401
    
    # Processar webhook
    # ...
    
    return jsonify({'received': True}), 200
```

### PHP

```php theme={null}
<?php

function validateWebhookSignature($payload, $signature, $token) {
    $expectedSignature = hash_hmac(
        'sha256',
        json_encode($payload, JSON_UNESCAPED_SLASHES),
        $token
    );
    
    return hash_equals($signature, $expectedSignature);
}

$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? null;

if (!$signature) {
    http_response_code(401);
    echo json_encode(['error' => 'Missing signature']);
    exit;
}

$payload = json_decode(file_get_contents('php://input'), true);
$token = 'seu-token-aqui'; // Token configurado no webhook

if (!validateWebhookSignature($payload, $signature, $token)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// Processar webhook
// ...

http_response_code(200);
echo json_encode(['received' => true]);
```

## Pontos Importantes

### 1. Stringificação do Payload

O payload deve ser stringificado **exatamente como recebido**, preservando:

* Ordem dos campos
* Espaçamento (sem espaços extras)
* Formato de números (sem alterações)
* Encoding UTF-8

### 2. Comparação Segura

Use funções de comparação segura para evitar timing attacks:

* Node.js: `===` (comparação direta é segura para strings hex)
* Python: `hmac.compare_digest()`
* PHP: `hash_equals()`

### 3. Encoding

Certifique-se de usar UTF-8 para:

* Token (chave secreta)
* Payload JSON

### 4. Headers Case-Insensitive

O header `X-Webhook-Signature` pode vir em diferentes casos. Normalize para minúsculas ao ler:

```javascript theme={null}
const signature = req.headers['x-webhook-signature'] || 
                  req.headers['X-Webhook-Signature'];
```

## Tratamento de Erros

Sempre retorne um status HTTP apropriado:

* **401 Unauthorized**: Assinatura ausente ou inválida
* **400 Bad Request**: Payload malformado
* **200 OK**: Assinatura válida e webhook processado

<Warning>
  Nunca processe um webhook sem validar a assinatura. Isso pode expor seu sistema a ataques.
</Warning>

<Note>
  O token usado para validar deve ser o mesmo configurado no webhook. Mantenha-o seguro e não o exponha em logs ou código cliente.
</Note>