# EvoPay API — Documentação Completa

Gateway de pagamentos Pix para criação de cobranças (cash-in), saques (cash-out) e gerenciamento de transações.

- Base URL: https://pix.evopay.cash/v1
- Autenticação: Header `API-Key: SEU_TOKEN` (UUID v4)
- Dashboard / tokens: https://app.evopay.cash/settings/tokens
- Documentação: https://docs.evopay.cash

---

# Introdução

A **EvoPay API** permite criar cobranças Pix (cash-in) e saques (cash-out) diretamente no seu sistema, além de consultar transações e configurar sua conta.

## Base URL

```
https://pix.evopay.cash/v1
```

## Autenticação

Todas as requisições (exceto rotas públicas) exigem o header:

```
API-Key: SEU_TOKEN
```

## Formato de valores

Valores monetários são sempre em **reais decimais**. `R$ 10,50 = 10.50` — nunca em centavos.

## IDs de transações

Transações são identificadas por **CUIDs**: strings alfanuméricas de 25 caracteres em minúsculas.

```
cmq47c6un0c05ufvvo58ohpqk
```

## Taxas

Cada conta tem regras de taxa (TaxRule) configuradas separadamente para DEPOSIT e WITHDRAW. Cada regra define: taxValue (valor da taxa), taxType (FIXED em reais ou PERCENTAGE do valor), minAmount (valor mínimo aceito por transação — abaixo é rejeitada) e maxAmount (valor máximo aceito — acima é rejeitada; null = sem limite). A regra com o range correspondente ao valor da transação é aplicada. O campo taxAmount na transação é a taxa cobrada. amountWithTax = amount − taxAmount em DEPOSIT (valor creditado); amount + taxAmount em WITHDRAW (total debitado). Regras configuradas pelo gerente de contas.

## Formato de erro

```json
{
  "success": false,
  "message": "Descrição do erro"
}
```

Alguns endpoints retornam o formato alternativo:

```json
{
  "error": "Descrição do erro"
}
```

---

# Autenticação

## Header obrigatório

Todas as requisições autenticadas devem incluir o token no header:

```
API-Key: SEU_TOKEN
```

Requisições sem esse header ou com token inválido retornam `401 Unauthorized`.

## Como obter um token

Acesse **Settings → Tokens** no painel:

```
https://app.evopay.cash/settings/tokens
```

## Formato do token

O token é um **UUID v4** gerado automaticamente. Exemplo:

```
550e8400-e29b-41d4-a716-446655440000
```

## Boas práticas

- Nunca exponha o token no frontend — guarde-o exclusivamente no backend
- Não use em variáveis de ambiente prefixadas com `NEXT_PUBLIC_` ou equivalentes de outros frameworks
- O token é fixo e único por conta — para substituí-lo, solicite ao seu gerente de contas

## Exemplos de uso

### cURL

```bash
curl -X POST https://pix.evopay.cash/v1/pix \
  -H "API-Key: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100.00}'
```

### Node.js (Axios)

```js
import axios from 'axios';

const client = axios.create({
  baseURL: 'https://pix.evopay.cash/v1',
  headers: {
    'API-Key': process.env.EVOPAY_TOKEN,
    'Content-Type': 'application/json',
  },
});

const { data } = await client.post('/pix', { amount: 100.00 });
console.log(data.id); // cmq47c6un0c05ufvvo58ohpqk
```

### Python (requests)

```python
import requests, os

BASE = 'https://pix.evopay.cash/v1'
HEADERS = {
    'API-Key': os.environ['EVOPAY_TOKEN'],
    'Content-Type': 'application/json',
}

r = requests.post(f'{BASE}/pix', json={'amount': 100.00}, headers=HEADERS)
print(r.json()['id'])  # cmq47c6un0c05ufvvo58ohpqk
```

---

# Webhooks

Quando o status de uma transação muda, a EvoPay faz um `POST` para a `callbackUrl` fornecida na criação.

## Headers enviados

```
Content-Type: application/json
```

## Payload — Depósito (DEPOSIT)

```json
{
  "id": "cmq47c6un0c05ufvvo58ohpqk",
  "type": "DEPOSIT",
  "status": "COMPLETED",
  "amount": 100.00,
  "endToEndId": "E60746948202406101500abcdef123456",
  "payerDocument": "12345678901",
  "payerName": "João Silva"
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | `string` | ID da transação |
| `type` | `"DEPOSIT"` | Tipo fixo |
| `status` | `TransactionStatus` | Status atual |
| `amount` | `number` | Valor em reais |
| `endToEndId` | `string \| null` | ID fim a fim Pix — presente após liquidação |
| `payerDocument` | `string \| null` | CPF/CNPJ do pagador — presente após pagamento |
| `payerName` | `string \| null` | Nome do pagador — presente após pagamento |

## Payload — Saque (WITHDRAW)

```json
{
  "id": "cmq47c6un0c05ufvvo58ohpqk",
  "type": "WITHDRAW",
  "status": "COMPLETED",
  "amount": 100.00,
  "endToEndId": "E60746948202406101500abcdef123456"
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | `string` | ID da transação |
| `type` | `"WITHDRAW"` | Tipo fixo |
| `status` | `TransactionStatus` | Status atual |
| `amount` | `number` | Valor em reais |
| `endToEndId` | `string \| null` | ID fim a fim Pix — presente após liquidação |

## Política de entrega

O callback é uma **única tentativa** — não há reenvio automático em caso de falha. Sua aplicação deve ser resiliente: retorne `2xx` rapidamente e processe o evento de forma assíncrona.

## Idempotência

O mesmo evento pode ser entregue mais de uma vez (ex: reprocessamento interno). Trate idempotência usando a combinação `id + status`.

## Consultando o status

Se o callback não for recebido, consulte o status diretamente:

```bash
curl "https://pix.evopay.cash/v1/pix?id=cmq47c6un0c05ufvvo58ohpqk" \
  -H "API-Key: SEU_TOKEN"
```

---

# Schemas

## Enums

### TransactionStatus

| Valor | Descrição |
|---|---|
| `PENDING` | Aguardando pagamento ou processamento |
| `COMPLETED` | Concluída com sucesso |
| `CANCELED` | Cancelada |
| `WAITING_FOR_REFUND` | Aguardando estorno |
| `REFUNDED` | Estorno concluído |
| `EXPIRED` | Expirou antes do pagamento |

Fluxo típico — Depósito: `PENDING → COMPLETED | CANCELED | EXPIRED`, `COMPLETED → WAITING_FOR_REFUND → REFUNDED`
Fluxo típico — Saque: `PENDING → COMPLETED | CANCELED`

### TransactionType

| Valor | Descrição |
|---|---|
| `DEPOSIT` | Cobrança Pix (cash-in) |
| `WITHDRAW` | Saque Pix (cash-out) |
| `TEF` | Transferência eletrônica (uso interno) |

### TaxType

| Valor | Descrição |
|---|---|
| `FIXED` | Valor fixo em reais |
| `PERCENTAGE` | Percentual sobre o valor da transação |

### PixType

| Valor | Formato esperado |
|---|---|
| `cpf` | 11 dígitos numéricos |
| `cnpj` | 14 dígitos numéricos |
| `email` | Endereço de e-mail válido |
| `phone` | Número com DDD e código do país (ex: `+5511999999999`) |
| `evp` | Chave aleatória — 36 caracteres com hífens |

## Objetos

### Transaction

Objeto retornado em `GET /v1/pix`, `GET /v1/account/transactions` e nos webhooks.

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | `string` | ID CUID da transação |
| `status` | `TransactionStatus` | Status atual |
| `type` | `TransactionType` | Tipo da transação |
| `amount` | `number` | Valor em reais |
| `taxValue` | `number` | Valor da taxa cobrada |
| `taxType` | `TaxType` | Tipo da taxa aplicada |
| `callbackUrl` | `string \| null` | URL de callback registrada na criação |
| `qrCodeText` | `string \| null` | Payload Pix Copia e Cola (depósitos) |
| `qrCodeUrl` | `string \| null` | URL da imagem PNG do QR Code |
| `qrCodeBase64` | `string \| null` | QR Code em Base64 PNG (depósitos) |
| `payerName` | `string \| null` | Nome do pagador — preenchido após pagamento |
| `payerDocument` | `string \| null` | CPF/CNPJ do pagador — preenchido após pagamento |
| `receiverName` | `string \| null` | Nome do recebedor (saques) |
| `receiverDocument` | `string \| null` | Documento do recebedor (saques) |
| `withdrawPixKey` | `string \| null` | Chave Pix de destino do saque |
| `withdrawPixType` | `PixType \| null` | Tipo da chave Pix de destino |
| `endToEndId` | `string \| null` | ID fim a fim Pix — presente após liquidação |
| `createdAt` | `string` | Data de criação (ISO 8601 UTC) |
| `updatedAt` | `string` | Data da última atualização (ISO 8601 UTC) |

### WebhookDeposit

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | `string` | ID da transação |
| `type` | `"DEPOSIT"` | Fixo |
| `status` | `TransactionStatus` | Status atual |
| `amount` | `number` | Valor em reais |
| `endToEndId` | `string \| null` | Presente após liquidação |
| `payerDocument` | `string \| null` | CPF/CNPJ do pagador |
| `payerName` | `string \| null` | Nome do pagador |

### WebhookWithdraw

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | `string` | ID da transação |
| `type` | `"WITHDRAW"` | Fixo |
| `status` | `TransactionStatus` | Status atual |
| `amount` | `number` | Valor em reais |
| `endToEndId` | `string \| null` | Presente após liquidação |

### QrCodeInfo

Retornado por `POST /v1/pix/qr-code/read`.

| Campo | Tipo | Descrição |
|---|---|---|
| `qrCodeType` | `"DYNAMIC" \| "STATIC"` | Tipo do QR Code |
| `amount` | `number \| null` | Valor. `null` em QR estático sem valor fixo |
| `name` | `string \| null` | Nome do recebedor |
| `document` | `string \| null` | Documento do recebedor |
| `additionalInfo` | `string \| null` | Informação adicional |
| `expiresIn` | `integer` | Segundos até expiração (apenas DYNAMIC) |
| `txid` | `string` | ID da transação no sistema do recebedor (apenas DYNAMIC) |
| `createdAt` | `string` | Data de criação (apenas DYNAMIC) |

---

# OpenAPI Specification (YAML)

```yaml
openapi: 3.1.0
info:
  title: EvoPay API
  description: Gateway de pagamentos Pix para criação de cobranças (cash-in), saques
    (cash-out) e gerenciamento de transações.
  version: '1.0'
servers:
- url: https://pix.evopay.cash
  description: Produção
security:
- ApiKey: []
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: API-Key
      description: Token da conta. Obtido em https://app.evopay.cash/settings/tokens
  schemas:
    TransactionStatus:
      type: string
      enum:
      - PENDING
      - COMPLETED
      - CANCELED
      - WAITING_FOR_REFUND
      - REFUNDED
      - EXPIRED
    TransactionType:
      type: string
      enum:
      - DEPOSIT
      - WITHDRAW
      - TEF
    TaxType:
      type: string
      enum:
      - FIXED
      - PERCENTAGE
    PixType:
      type: string
      enum:
      - cpf
      - cnpj
      - email
      - phone
      - evp
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
    ErrorObject:
      type: object
      properties:
        error:
          type: string
    WebhookDeposit:
      type: object
      description: Payload enviado à callbackUrl quando uma cobrança Pix muda de status
      properties:
        id:
          type: string
          example: cmq47c6un0c05ufvvo58ohpqk
        type:
          type: string
          enum:
          - DEPOSIT
        status:
          $ref: '#/components/schemas/TransactionStatus'
        amount:
          type: number
        endToEndId:
          type:
          - string
          - 'null'
          description: Presente após liquidação
        payerDocument:
          type:
          - string
          - 'null'
          description: CPF/CNPJ do pagador — presente após pagamento
        payerName:
          type:
          - string
          - 'null'
          description: Nome do pagador — presente após pagamento
    WebhookWithdraw:
      type: object
      description: Payload enviado à callbackUrl quando um saque muda de status
      properties:
        id:
          type: string
          example: cmq47c6un0c05ufvvo58ohpqk
        type:
          type: string
          enum:
          - WITHDRAW
        status:
          $ref: '#/components/schemas/TransactionStatus'
        amount:
          type: number
        endToEndId:
          type:
          - string
          - 'null'
          description: Presente após liquidação
paths:
  /v1/account:
    get:
      summary: Dados da conta
      description: Retorna os dados completos da conta autenticada.
      tags:
      - Account
      responses:
        '200':
          description: Dados da conta
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      balance:
                        type: number
                      taxRules:
                        type: array
                        items:
                          type: object
                          properties:
                            minAmount:
                              type: number
                            maxAmount:
                              type:
                              - number
                              - 'null'
                            taxValue:
                              type: number
                            taxType:
                              $ref: '#/components/schemas/TaxType'
                            typeTransaction:
                              $ref: '#/components/schemas/TransactionType'
                      pix:
                        type: object
                        properties:
                          type:
                            oneOf:
                            - $ref: '#/components/schemas/PixType'
                            - type: 'null'
                          key:
                            type:
                            - string
                            - 'null'
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
        '401':
          description: Token ausente, inválido ou conta bloqueada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/account/balance:
    get:
      summary: Saldo da conta
      description: Retorna o saldo atual e o saldo elegível para saque.
      tags:
      - Account
      responses:
        '200':
          description: Saldo da conta
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance:
                    type: number
                    description: Saldo total disponível em reais
                  eligibleWithdraw:
                    type: number
                    description: Saldo elegível para saque (após dedução de taxas fixas)
        '401':
          description: Token ausente, inválido ou conta bloqueada
  /v1/account/transactions:
    get:
      summary: Listar transações
      description: Lista as transações da conta com paginação e filtros.
      tags:
      - Account
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 10
      - name: dateFrom
        in: query
        schema:
          type: string
          format: date-time
      - name: dateTo
        in: query
        schema:
          type: string
          format: date-time
      - name: id
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          $ref: '#/components/schemas/TransactionStatus'
      - name: type
        in: query
        schema:
          type: string
          enum:
          - DEPOSIT
          - WITHDRAW
      - name: amount
        in: query
        schema:
          type: number
      - name: payerDocument
        in: query
        schema:
          type: string
      - name: payerName
        in: query
        schema:
          type: string
      - name: endToEndId
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Lista paginada de transações
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  pages:
                    type: integer
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
        '401':
          description: Token ausente, inválido ou conta bloqueada
  /v1/pix:
    post:
      summary: Criar cobrança Pix
      description: Cria uma cobrança Pix (depósito). Retorna QR Code para pagamento.
      tags:
      - Pix
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amount
              properties:
                amount:
                  type: number
                  minimum: 1
                callbackUrl:
                  type: string
                  format: uri
                payerName:
                  type: string
                  description: "Apenas letras e espaços. Padrão: ^[a-zA-Z ]+$"
                payerDocument:
                  type: string
                payerEmail:
                  type: string
                externalReference:
                  type: string
      responses:
        '200':
          description: Cobrança criada com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: cmq47c6un0c05ufvvo58ohpqk
                  status:
                    type: string
                    example: PENDING
                  amount:
                    type: number
                  taxAmount:
                    type: number
                  amountWithTax:
                    type: number
                  qrCodeText:
                    type: string
                  qrCodeBase64:
                    type: string
                  qrCodeUrl:
                    type: string
        '400':
          description: Depósito bloqueado ou configuração de taxa ausente
        '401':
          description: Token ausente, inválido ou conta bloqueada
        '500':
          description: Erro crítico no processamento do gateway
    get:
      summary: Consultar cobrança Pix
      description: Consulta o status e os detalhes de uma transação Pix pelo ID.
      tags:
      - Pix
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Dados da transação
        '401':
          description: Token ausente, inválido ou conta bloqueada
        '404':
          description: Transação não encontrada
  /v1/pix/qr-code/read:
    post:
      summary: Ler QR Code Pix
      description: Decodifica um QR Code Pix externo e retorna os dados estruturados
        da cobrança. Útil para exibir ao usuário o valor e destinatário antes de confirmar
        um saque via QR Code.
      tags:
      - Pix
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - qrCode
              properties:
                qrCode:
                  type: string
                  minLength: 20
                  description: Payload Pix Copia e Cola
      responses:
        '200':
          description: Dados do QR Code decodificado
          content:
            application/json:
              schema:
                type: object
                properties:
                  qrCodeType:
                    type: string
                    enum:
                    - DYNAMIC
                    - STATIC
                  amount:
                    type:
                    - number
                    - 'null'
                  name:
                    type:
                    - string
                    - 'null'
                  document:
                    type:
                    - string
                    - 'null'
                  additionalInfo:
                    type:
                    - string
                    - 'null'
                  expiresIn:
                    type: integer
                  txid:
                    type: string
                  createdAt:
                    type: string
        '400':
          description: QR Code inválido
        '401':
          description: Token ausente, inválido ou conta bloqueada
  /v1/pix/qr-code/{transactionId}:
    get:
      summary: Imagem PNG do QR Code
      description: Retorna a imagem PNG do QR Code de uma cobrança. Rota pública — não requer autenticação.
      tags:
      - Pix
      security: []
      parameters:
      - name: transactionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Imagem PNG do QR Code
          content:
            image/png:
              schema:
                type: string
                format: binary
        '404':
          description: Transação não encontrada ou sem QR Code
  /v1/withdraw:
    post:
      summary: Criar saque
      description: Realiza um saque para uma chave Pix.
      tags:
      - Withdraw
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amount
              - pixKey
              - pixType
              properties:
                amount:
                  type: number
                pixKey:
                  type: string
                pixType:
                  $ref: '#/components/schemas/PixType'
                callbackUrl:
                  type: string
                  format: uri
      responses:
        '200':
          description: Saque criado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    $ref: '#/components/schemas/TransactionStatus'
                  amount:
                    type: number
                  amountWithTax:
                    type: number
                    description: Valor total debitado do saldo (inclui taxa)
                  pixKey:
                    type: string
                  pixType:
                    $ref: '#/components/schemas/PixType'
                  transactionId:
                    type: string
        '400':
          description: Saque bloqueado ou saldo insuficiente
        '401':
          description: Token ausente, inválido ou conta bloqueada
        '500':
          description: Falha ao reservar o saldo
        '502':
          description: Falha no provedor — saldo não foi debitado
  /v1/withdraw/qrcode:
    post:
      summary: Saque via QR Code
      description: Realiza um saque usando um QR Code Pix dinâmico ou estático como
        destino. Se o QR Code já contém um valor fixo, o campo amount é ignorado.
        Se o QR Code for estático (sem valor), amount se torna obrigatório.
      tags:
      - Withdraw
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - qrCode
              properties:
                qrCode:
                  type: string
                  description: Payload Pix Copia e Cola do QR Code de destino
                amount:
                  type: number
                  description: Obrigatório quando o QR Code não contém valor fixo
                callbackUrl:
                  type: string
                  format: uri
      responses:
        '200':
          description: Saque criado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    $ref: '#/components/schemas/TransactionStatus'
                  amount:
                    type: number
                  transactionId:
                    type: string
        '400':
          description: Validação, saldo insuficiente ou QR Code inválido
        '401':
          description: Token ausente, inválido ou conta bloqueada
        '500':
          description: Falha ao reservar o saldo
        '502':
          description: Falha no provedor — saldo não foi debitado
tags:
- name: Account
  description: Gerenciamento de conta, saldo e transações
- name: Pix
  description: Cobranças Pix (depósito) e utilitários de QR Code
- name: Withdraw
  description: Saques via chave Pix ou QR Code
```