Velani Pagamentos API v1.0

Cria uma cobrança PIX. Retorna o QR Code para o cliente pagar.

Headers

Body (JSON)

Exemplo

curl -X POST https://api.velanipagamentos.com.br/api/v1/api-gateway/v1/transactions \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_sua_chave_secreta" \
  -d '{
  "paymentMethod": "pix",
  "amount": 10000,
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "phone": "11999999999",
    "document": { "type": "cpf", "number": "12345678900" }
  },
  "items": [
    { "title": "Assinatura Premium", "unitPrice": 10000, "quantity": 1 }
  ],
  "postbackUrl": "https://meusite.com/webhook/velani",
  "externalId": "pedido-123",
  "tracking": {
    "utm_source": "facebook",
    "utm_campaign": "campanha-verao",
    "utm_medium": "cpc",
    "utm_content": "criativo-a"
  }
}'

Resposta (200)

{
  "success": true,
  "data": {
    "id": "uuid-da-transacao",
    "status": "pending",
    "amount": 10000,
    "paymentMethod": "pix",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com"
    },
    "pixQrCode": "00020126580014br.gov.bcb.pix...",
    "pixQrCodeImage": "https://api.velanipagamentos.com.br/qrcode/xxx.png",
    "expiresAt": "2026-01-15T11:00:00.000Z",
    "createdAt": "2026-01-15T10:30:00.000Z"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1"
  }
}

Consulta status e dados de uma transação. Aceita Secret Key ou Public Key.

curl https://api.velanipagamentos.com.br/api/v1/api-gateway/v1/transactions/uuid \
  -H "x-api-key: sk_live_sua_chave_secreta"

Resposta

{
  "success": true,
  "data": {
    "id": "uuid-da-transacao",
    "externalId": "pedido-123",
    "status": "paid",
    "amount": 10000,
    "paymentMethod": "pix",
    "customerName": "João Silva",
    "customerEmail": "joao@email.com",
    "paidAt": "2026-01-15T10:35:00.000Z",
    "expiresAt": "2026-01-15T11:00:00.000Z",
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}

Lista suas transações com paginação. Aceita Secret Key ou Public Key.

Solicita um saque. O valor solicitado + taxa é debitado imediatamente do saldo disponível. O saque fica como PENDING até aprovação manual pelo admin.

Headers

Body (JSON)

Validação de pixKey por tipo

Exemplo 1 — Saque para conta bancária cadastrada

curl -X POST https://api.velanipagamentos.com.br/api/v1/api-gateway/v1/withdrawals \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_sua_chave_secreta" \
  -d '{ "amount": 5000 }'

Exemplo 2 — Saque para chave PIX externa

curl -X POST https://api.velanipagamentos.com.br/api/v1/api-gateway/v1/withdrawals \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_sua_chave_secreta" \
  -d '{
    "amount": 5000,
    "pixKey": "joao@email.com",
    "pixKeyType": "EMAIL",
    "holderName": "João da Silva",
    "holderDocument": "12345678909"
  }'

Resposta (200) — Modo padrão (conta bancária)

{
  "success": true,
  "data": {
    "id": "uuid-do-saque",
    "amount": 50.00,
    "fee": 2.00,
    "netAmount": 48.00,
    "status": "PENDING",
    "destination": "BANK_ACCOUNT",
    "pixKey": null,
    "pixKeyType": null,
    "holderName": null,
    "holderDocument": null,
    "createdAt": "2026-05-04T12:00:00.000Z",
    "updatedAt": "2026-05-04T12:00:00.000Z",
    "paidAt": null,
    "rejectionReason": null,
    "autoApproved": false
  }
}
/* amount      = total debitado do saldo (bruto solicitado)
   fee         = taxa da plataforma cobrada
   netAmount   = valor líquido que será creditado no PIX (amount − fee)
   autoApproved = true quando a auto-aprovação processou o saque na hora (status vem "PAID"/"PROCESSING") */

Resposta (200) — Modo PIX externo

{
  "success": true,
  "data": {
    "id": "uuid-do-saque",
    "amount": 50.00,
    "fee": 2.00,
    "netAmount": 48.00,
    "status": "PENDING",
    "destination": "EXTERNAL_PIX",
    "pixKey": "joao@email.com",
    "pixKeyType": "EMAIL",
    "holderName": "João da Silva",
    "holderDocument": "12345678909",
    "createdAt": "2026-05-04T12:00:00.000Z",
    "updatedAt": "2026-05-04T12:00:00.000Z",
    "paidAt": null,
    "rejectionReason": null,
    "autoApproved": false
  }
}

Erros comuns

Lista todos os saques da conta com paginação. Aceita Secret Key ou Public Key.

curl "https://api.velanipagamentos.com.br/api/v1/api-gateway/v1/withdrawals?page=1&limit=20" \
  -H "x-api-key: sk_live_sua_chave_secreta"

Resposta (200)

{
  "success": true,
  "data": [
    {
      "id": "uuid-do-saque",
      "amount": 52.00,
      "fee": 2.00,
      "netAmount": 50.00,
      "status": "PENDING",
      "createdAt": "2026-04-13T12:00:00.000Z",
      "paidAt": null,
      "rejectionReason": null
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "limit": 20
  }
}

Consulta detalhes de um saque específico. Aceita Secret Key ou Public Key.

curl "https://api.velanipagamentos.com.br/api/v1/api-gateway/v1/withdrawals/uuid-do-saque" \
  -H "x-api-key: sk_live_sua_chave_secreta"

Resposta (200)

{
  "success": true,
  "data": {
    "id": "uuid-do-saque",
    "amount": 52.00,
    "fee": 2.00,
    "netAmount": 50.00,
    "status": "PAID",
    "createdAt": "2026-04-13T12:00:00.000Z",
    "updatedAt": "2026-04-13T14:30:00.000Z",
    "paidAt": "2026-04-13T14:30:00.000Z",
    "rejectionReason": null
  }
}

Exemplo com Split Inline

curl -X POST https://api.velanipagamentos.com.br/api/v1/api-gateway/v1/transactions \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_sua_chave_secreta" \
  -d '{
  "paymentMethod": "pix",
  "amount": 10000,
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "split": [
    { "email": "parceiro@email.com", "percentage": "10" },
    { "email": "afiliado@email.com", "percentage": "5" }
  ],
  "postbackUrl": "https://meusite.com/webhook",
  "externalId": "pedido-456"
}'

Campos do Split

Exemplo de divisão:

Venda: R$ 100,00
Taxa plataforma (6%): - R$ 6,00
Valor líquido: R$ 94,00

Split parceiro (10%): R$ 9,40 → creditado para parceiro@email.com
Split afiliado (5%):  R$ 4,70 → creditado para afiliado@email.com
Você recebe (85%):    R$ 79,90