Autenticação

A API do AvanPay suporta dois métodos de autenticação: JWT Token (Bearer Token) para aplicações web e frontend, e API Keys para integrações server-to-server.

JWT Token (Bearer Token)

O método de autenticação via JWT Token é recomendado para aplicações web e frontend. O token deve ser incluído no header Authorization de todas as requisições autenticadas.

Authorization: Bearer {seu_token_jwt}

Obtenção do Token

Para obter um token JWT, realize uma requisição de autenticação no endpoint /api/auth/login com suas credenciais. O processo consiste em:

1. Realizar requisição POST para /api/auth/login com email e senha
2. Receber accessToken e refreshToken na resposta
3. Utilizar o accessToken no header Authorization de requisições subsequentes
4. Utilizar o refreshToken para renovar o token quando necessário

{
  "email": "empresa@exemplo.com",
  "password": "senhaSegura123"
}

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "name": "Nome da Empresa",
      "email": "empresa@exemplo.com"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

API Keys

O método de autenticação via API Keys é recomendado para integrações server-to-server. As chaves devem ser incluídas nos headers de todas as requisições.

X-API-Public-Key: {sua_public_key}
X-API-Secret-Key: {sua_secret_key}

Pagamento PIX

O endpoint de pagamento PIX permite criar transações de pagamento instantâneo via PIX. Os pagamentos PIX são processados em tempo real e oferecem confirmação imediata após a realização do pagamento.

POST /api/payments/pix
Authorization: Bearer {token}
Content-Type: application/json

{
  "amount": 10000,
  "sellerExternalRef": "PEDIDO-123",
  "customer": {
    "name": "João Silva",
    "email": "joao@example.com",
    "phone": "11999999999",
    "documentType": "CPF",
    "document": "12345678900"
  },
  "items": [
    {
      "title": "Produto Exemplo",
      "quantity": 1,
      "amount": 10000,
      "tangible": true
    }
  ],
  "postbackUrl": "https://seu-site.com/webhook",
  "metadata": {
    "orderId": "12345",
    "customField": "valor"
  }
}

{
  "success": true,
  "data": {
    "id": "tx_abc123",
    "status": "WAITING_PAYMENT",
    "amount": 10000,
    "pix": {
      "qrcode": "data:image/png;base64,iVBORw0KGgo...",
      "copyPaste": "00020126360014BR.GOV.BCB.PIX...",
      "expirationDate": "2024-12-03T10:00:00Z"
    },
    "createdAt": "2024-12-02T10:00:00Z"
  }
}

Pagamento Boleto

O endpoint de pagamento Boleto permite criar transações de pagamento via Boleto Bancário. Os boletos são gerados com código de barras e linha digitável para pagamento em bancos, lotéricas e aplicativos bancários.

POST /api/payments/boleto
Authorization: Bearer {token}
Content-Type: application/json

{
  "amount": 10000,
  "sellerExternalRef": "PEDIDO-123",
  "customer": {
    "name": "João Silva",
    "email": "joao@example.com",
    "phone": "11999999999",
    "documentType": "CPF",
    "document": "12345678900"
  },
  "items": [
    {
      "title": "Produto Exemplo",
      "quantity": 1,
      "amount": 10000,
      "tangible": true
    }
  ]
}

{
  "success": true,
  "data": {
    "id": "tx_abc123",
    "status": "WAITING_PAYMENT",
    "amount": 10000,
    "boleto": {
      "barcode": "34191.09008 01234.567890 12345.678901 2 12340000010000",
      "url": "https://seu-boleto.com/12345",
      "expirationDate": "2024-12-05T10:00:00Z"
    }
  }
}

Pagamento Cartão

O endpoint de pagamento Cartão permite processar transações de pagamento via Cartão de Crédito. Suporta pagamentos à vista e parcelados, com validação de segurança e processamento em tempo real.

POST /api/payments/card
Authorization: Bearer {token}
Content-Type: application/json

{
  "amount": 10000,
  "installments": 1,
  "sellerExternalRef": "PEDIDO-123",
  "customer": {
    "name": "João Silva",
    "email": "joao@example.com",
    "phone": "11999999999",
    "documentType": "CPF",
    "document": "12345678900"
  },
  "card": {
    "number": "4111111111111111",
    "holderName": "JOAO SILVA",
    "expirationMonth": "12",
    "expirationYear": "2025",
    "cvv": "123"
  },
  "items": [
    {
      "title": "Produto Exemplo",
      "quantity": 1,
      "amount": 10000,
      "tangible": true
    }
  ]
}

{
  "success": true,
  "data": {
    "id": "tx_abc123",
    "status": "PAID",
    "amount": 10000,
    "card": {
      "last4": "1111",
      "brand": "VISA"
    },
    "paidAt": "2024-12-02T10:00:05Z"
  }
}

Transações

Os endpoints de transações permitem consultar e gerenciar todas as transações realizadas através da API. É possível listar transações com filtros e paginação, além de consultar detalhes de transações específicas.

Consultar Transação

{
  "success": true,
  "data": {
    "id": "tx_abc123",
    "status": "PAID",
    "amount": 10000,
    "paymentMethod": "PIX",
    "customer": { ... },
    "items": [ ... ],
    "pix": { ... },
    "createdAt": "2024-12-02T10:00:00Z",
    "paidAt": "2024-12-02T10:05:00Z"
  }
}

Listar Transações

Saldo

O endpoint de saldo permite consultar o saldo disponível, pendente e bloqueado da conta.

{
  "success": true,
  "data": {
    "available": 5000.00,
    "pending": 1000.00,
    "blocked": 500.00,
    "currency": "BRL"
  }
}

Saques

O endpoint de saques permite criar solicitações de saque para contas bancárias cadastradas. Os saques são processados conforme a política de liquidação configurada.

Criar Saque

POST /api/payments/cash-out
Authorization: Bearer {token}
Content-Type: application/json

{
  "amount": 5000,
  "pixKey": "11999999999",
  "pixKeyType": "PHONE",
  "method": "PIX",
  "sellerExternalRef": "SAQUE-001"
}

{
  "success": true,
  "data": {
    "id": "cashout_abc123",
    "status": "PENDING",
    "amount": 5000,
    "pixKey": "11999999999",
    "pixKeyType": "PHONE",
    "createdAt": "2024-12-02T10:00:00Z"
  }
}

Consultar Saque

Listar Saques

Payment Links

Os Payment Links são links de pagamento que podem ser compartilhados com clientes. Permitem que clientes realizem pagamentos sem necessidade de integração direta, suportando múltiplos métodos de pagamento.

{
  "name": "Link de Pagamento #1",
  "description": "Pagamento de produtos",
  "amount": 10000,
  "currency": "BRL",
  "paymentMethods": ["pix", "boleto", "card"],
  "expiresAt": "2024-12-31T23:59:59Z",
  "maxUses": 10
}

Webhooks

Os webhooks permitem receber notificações em tempo real sobre eventos de pagamento e transações.

Configurar Webhook

Configure a URL do webhook ao criar o pagamento usando o campo postbackUrl:

{
  "amount": 10000,
  "postbackUrl": "https://seu-site.com/webhook",
  ...
}

Formato do Webhook

{
  "event": "pix.confirmed",
  "eventId": "evt_1234567890",
  "timestamp": "2024-12-02T10:05:00Z",
  "data": {
    "id": "tx_abc123",
    "status": "PAID",
    "amount": 10000,
    "paymentMethod": "PIX",
    "customer": { ... },
    "metadata": { ... }
  },
  "signature": "v1=abc123...",
  "timestamp": "1234567890"
}

Validação de Assinatura

O webhook inclui uma assinatura HMAC-SHA256 para validação:

const crypto = require('crypto');

function validateWebhook(payload, signature, secret, timestamp) {
  const message = `${timestamp}.${JSON.stringify(payload)}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  
  return `v1=${expectedSignature}` === signature;
}

Eventos de Webhook

Lista completa de eventos disponíveis para configuração de webhooks.

Eventos Enviados

Conta Virtual PIX

O endpoint de Conta Virtual PIX permite criar e gerenciar contas virtuais para recebimento de pagamentos PIX. As contas virtuais são úteis para recebimentos recorrentes e integrações específicas.

Wallet

O endpoint de Wallet permite gerenciar carteiras digitais e cartões salvos dos clientes. Útil para implementar funcionalidades de pagamento recorrente e armazenamento seguro de dados de cartão.

Segurança

A API do AvanPay implementa diversas camadas de segurança para proteger dados e transações. Esta seção descreve as políticas de segurança, rate limiting e boas práticas recomendadas.

Rate Limiting

A API implementa rate limiting para proteger contra abuso e garantir disponibilidade. Os limites variam conforme o tipo de operação:

Valores Mínimos

Os valores mínimos aceitos para cada método de pagamento são:

• PIX: R$ 5,00 (500 centavos)
• Boleto: R$ 5,00 (500 centavos)
• Cartão: R$ 5,00 (500 centavos)

Boas Práticas de Segurança

• Nunca exponha credenciais de API em código cliente ou repositórios públicos
• Utilize HTTPS para todas as comunicações com a API
• Valide sempre a assinatura de webhooks recebidos
• Implemente idempotência utilizando chaves únicas para operações críticas
• Mantenha logs de auditoria de todas as operações financeiras
• Rotacione credenciais de API periodicamente

Códigos de Status

Status de Transação

Status de Saque

Tratamento de Erros

Códigos HTTP

Formato de Erro

{
  "success": false,
  "message": "Descrição do erro",
  "error": {
    "code": "ERROR_CODE",
    "details": "Detalhes adicionais"
  }
}

Erros Comuns

Exemplos de Integração

Esta seção contém exemplos práticos de integração em diferentes linguagens de programação. Utilize estes exemplos como base para implementar sua integração.

const axios = require('axios');

const api = axios.create({
  baseURL: 'https://api.avanpay.com.br/api',
  headers: {
    'Authorization': `Bearer ${process.env.API_TOKEN}`,
    'Content-Type': 'application/json'
  }
});

// Criar pagamento PIX
async function createPixPayment() {
  try {
    const response = await api.post('/payments/pix', {
      amount: 10000,
      sellerExternalRef: 'PEDIDO-123',
      customer: {
        name: 'João Silva',
        email: 'joao@example.com',
        phone: '11999999999',
        documentType: 'CPF',
        document: '12345678900'
      },
      items: [{
        title: 'Produto',
        quantity: 1,
        amount: 10000,
        tangible: true
      }],
      postbackUrl: 'https://seu-site.com/webhook'
    });
    
    console.log('Pagamento criado:', response.data);
    return response.data;
  } catch (error) {
    console.error('Erro:', error.response?.data || error.message);
    throw error;
  }
}

import requests

url = 'https://api.avanpay.com.br/api/payments/pix'
headers = {
    'Authorization': f'Bearer {API_TOKEN}',
    'Content-Type': 'application/json'
}

data = {
    'amount': 10000,
    'sellerExternalRef': 'PEDIDO-123',
    'customer': {
        'name': 'João Silva',
        'email': 'joao@example.com',
        'phone': '11999999999',
        'documentType': 'CPF',
        'document': '12345678900'
    },
    'items': [{
        'title': 'Produto',
        'quantity': 1,
        'amount': 10000,
        'tangible': True
    }]
}

response = requests.post(url, json=data, headers=headers)
if response.status_code == 201:
    print('Pagamento criado:', response.json())
else:
    print('Erro:', response.json())

<?php

$token = 'seu_token_jwt';
$url = 'https://api.avanpay.com.br/api/payments/pix';

$data = [
    'amount' => 10000,
    'sellerExternalRef' => 'PEDIDO-123',
    'customer' => [
        'name' => 'João Silva',
        'email' => 'joao@example.com',
        'phone' => '11999999999',
        'documentType' => 'CPF',
        'document' => '12345678900'
    ],
    'items' => [[
        'title' => 'Produto',
        'quantity' => 1,
        'amount' => 10000,
        'tangible' => true
    ]]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 201) {
    $result = json_decode($response, true);
    echo "Pagamento criado: " . $result['data']['id'];
} else {
    echo "Erro: " . $response;
}
?>

curl -X POST https://api.avanpay.com.br/api/payments/pix \
  -H "Authorization: Bearer sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "sellerExternalRef": "PEDIDO-123",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "phone": "11999999999",
      "documentType": "CPF",
      "document": "12345678900"
    },
    "items": [
      {
        "title": "Produto",
        "quantity": 1,
        "amount": 10000,
        "tangible": true
      }
    ],
    "postbackUrl": "https://seu-site.com/webhook"
  }'

Suporte

Última atualização: Dezembro 2024