# Veno Payments - API PIX Gateway

> Gateway de pagamentos PIX para integracao via API REST.

## Autenticacao

Todas as requisicoes autenticadas devem incluir o header:
Authorization: Bearer {sua_api_key}

As API Keys possuem prefixo veno_live_ e sao geradas no painel:
Dashboard > Integracoes > API Keys > "Nova Chave".

## Base URL

https://beta.venopayments.com

## Endpoints

### Criar PIX (Deposito)

POST /api/v1/pix

Headers:
- Authorization: Bearer {api_key}
- Content-Type: application/json

Body:
{
  "amount": 1000,              // Valor em centavos (R$ 10,00). Obrigatorio.
  "description": "Pedido #123", // Descricao (opcional)
  "external_id": "order-123",  // Seu ID interno, usado para idempotencia (opcional)
  "callback_url": "https://seu-servidor.com/webhook", // URL de callback (opcional)
  "payer": {                   // Dados do pagador (opcional)
    "name": "Joao Silva",
    "email": "joao@email.com",
    "document": "12345678900", // CPF ou CNPJ
    "phone": "11999999999",
    "address": "Rua Exemplo, 123",
    "city": "Sao Paulo",
    "state": "SP",             // UF, 2 caracteres
    "zip_code": "01001000"     // CEP, 8 digitos
  },
  "splits": [                  // Split de pagamento (opcional)
    {
      "account_id": "uuid-da-conta",
      "amount": 500            // Valor em centavos
    }
  ],
  "utm_source": "facebook",    // UTM tracking (opcional)
  "utm_campaign": "black-friday",
  "utm_medium": "cpc",
  "utm_content": "banner-topo",
  "utm_term": "pix desconto",
  "src": "utmify-src",         // Utmify src (opcional)
  "sck": "utmify-sck"          // Utmify sck (opcional)
}

Response 201:
{
  "id": "uuid-do-deposito",
  "txid": "identificador-pix",
  "status": "pending",
  "amount": 1000,
  "qr_code": "",
  "qr_code_image": "payload-pix-copia-cola",
  "pix_copy_paste": "payload-pix-copia-cola",
  "expires_at": "2026-03-23T15:00:00Z",
  "splits": [
    {"account_id": "uuid-da-conta", "amount": 500}
  ]
}

### Consultar Status

GET /api/v1/pix/{id}/status

Response 200:
{
  "id": "uuid",
  "txid": "identificador",
  "status": "paid",
  "amount": 1000,
  "paid_at": "2026-03-23T14:30:00Z",
  "end_to_end_id": "E12345678202603...",
  "external_id": "pedido-123",
  "payer_name": "Joao Silva",
  "payer_document": "12345678900"
}

## Status do PIX

- pending: Aguardando pagamento
- paid: Pagamento confirmado
- expired: Expirou sem pagamento
- cancelled: Cancelado
- refunded: Valor devolvido

## Webhooks

Quando um PIX e pago, enviamos um POST para:
1. A callback_url informada ao criar o PIX
2. A URL configurada nas configuracoes da conta (legado)
3. URLs configuradas em Dashboard > Integracoes > Webhooks

Eventos disponiveis:
- pix.paid: Pagamento confirmado
- pix.expired: PIX expirou
- pix.refunded: Estorno realizado

Headers enviados:
- Content-Type: application/json
- User-Agent: VenoPayments/2.0

Formato do payload:
{
  "event": "pix.paid",
  "data": {
    "id": "uuid-do-deposito",
    "txid": "identificador-pix",
    "external_id": "order-123",
    "status": "paid",
    "amount": 1000,
    "paid_at": "2026-03-23T14:30:00Z",
    "end_to_end_id": "E12345678202603...",
    "payer": {
      "name": "Joao Silva",
      "document": "12345678900",
      "email": "joao@email.com",
      "phone": "11999999999",
      "city": "Sao Paulo",
      "state": "SP"
    }
  }
}

Retentativas em caso de falha (resposta != 2xx):
- 1a: 30 segundos
- 2a: 2 minutos
- 3a: 15 minutos

## Split de Pagamento

- Adicione o campo splits ao criar o PIX
- A taxa e cobrada somente na conta dona da API Key
- As contas receptoras recebem o valor sem desconto de taxa
- Soma dos splits nao pode exceder o valor total
- Nao e possivel fazer split para a propria conta
- Maximo de 10 splits por pagamento

## Idempotencia

Se voce enviar o mesmo external_id duas vezes, o segundo request retorna o PIX original sem criar duplicata.

## Rastreamento

Os parametros UTM (utm_source, utm_campaign, utm_medium, utm_content, utm_term) e Utmify (src, sck) sao armazenados no deposito.
O dominio de origem e capturado automaticamente do header Origin ou Referer.

## Erros

- 400 Bad Request: Parametros invalidos
- 401 Unauthorized: API Key invalida ou ausente
- 404 Not Found: Recurso nao encontrado
- 429 Too Many Requests: Rate limit excedido
- 500 Internal Server Error: Erro interno

## Rate Limits

- 100 requisicoes por minuto por token
- 1000 requisicoes por hora por token

## Valores

Todos os valores monetarios sao em centavos (int64).
R$ 10,00 = 1000 centavos.