Guia de Início Rápido

Visão Geral

Este guia vai te ajudar a processar seu primeiro pagamento usando a API EconPay. Vamos criar um pagamento via PIX, mas o processo é similar para outros métodos.

Ambiente de Testes: Use o ambiente sandbox para testar sem processar transações reais. Veja mais em Ambientes.

Pré-requisitos

Antes de começar, você precisa:

Uma conta EconPay (crie em app.econpay.com.br)
Seu access_token (disponível no dashboard)
Um cliente HTTP (cURL, Postman, ou sua linguagem preferida)

Passo 1: Autenticação

Primeiro, faça login para obter seu token JWT:

cURL

curl --request POST \
  --url https://api.econpay.com.br/auth \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]",
    "password": "sua-senha"
  }'

JavaScript

const response = await fetch('https://api.econpay.com.br/auth', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'sua-senha'
  })
});

const data = await response.json();
const token = data.response.token;

Python

import requests

response = requests.post(
    'https://api.econpay.com.br/auth',
    json={
        'email': '[email protected]',
        'password': 'sua-senha'
    }
)

token = response.json()['response']['token']

Resposta de Sucesso

{
  "response": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "name": "Seu Nome",
      "email": "[email protected]"
    }
  }
}

Passo 2: Criar um Pagamento PIX

Agora vamos criar um pagamento via PIX de R$ 100,00:

cURL

curl --request POST \
  --url https://api.econpay.com.br/payments/order \
  --header 'Authorization: Bearer SEU_TOKEN_JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "access_token": "SEU_ACCESS_TOKEN",
    "customer": {
      "name": "João da Silva",
      "email": "[email protected]",
      "document": "12345678900",
      "phone": {
        "country_code": "55",
        "area_code": "11",
        "number": "999999999"
      }
    },
    "items": [
      {
        "name": "Produto Teste",
        "quantity": 1,
        "price": 10000
      }
    ],
    "payment": {
      "type": "pix",
      "installments": 1
    },
    "shipping": {
      "name": "Digital",
      "price": 0
    },
    "subtotal": 10000,
    "total": 10000
  }'

JavaScript

const response = await fetch('https://api.econpay.com.br/payments/order', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    access_token: 'SEU_ACCESS_TOKEN',
    customer: {
      name: 'João da Silva',
      email: '[email protected]',
      document: '12345678900',
      phone: {
        country_code: '55',
        area_code: '11',
        number: '999999999'
      }
    },
    items: [{
      name: 'Produto Teste',
      quantity: 1,
      price: 10000 // R$ 100,00 em centavos
    }],
    payment: {
      type: 'pix',
      installments: 1
    },
    shipping: {
      name: 'Digital',
      price: 0
    },
    subtotal: 10000,
    total: 10000
  })
});

const payment = await response.json();
console.log('QR Code PIX:', payment.transaction.pix_qr_code);

Python

response = requests.post(
    'https://api.econpay.com.br/payments/order',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'access_token': 'SEU_ACCESS_TOKEN',
        'customer': {
            'name': 'João da Silva',
            'email': '[email protected]',
            'document': '12345678900',
            'phone': {
                'country_code': '55',
                'area_code': '11',
                'number': '999999999'
            }
        },
        'items': [{
            'name': 'Produto Teste',
            'quantity': 1,
            'price': 10000  # R$ 100,00 em centavos
        }],
        'payment': {
            'type': 'pix',
            'installments': 1
        },
        'shipping': {
            'name': 'Digital',
            'price': 0
        },
        'subtotal': 10000,
        'total': 10000
    }
)

payment = response.json()
print('QR Code PIX:', payment['transaction']['pix_qr_code'])

Resposta de Sucesso

{
  "success": true,
  "transaction": {
    "id": 123,
    "order_number": "ORD-20240122-123456",
    "status": "PENDING",
    "amount": 10000,
    "payment_type": "pix",
    "pix_qr_code": "00020126580014br.gov.bcb.pix...",
    "pix_qr_code_url": "https://api.econpay.com.br/qrcode/123.png",
    "created_at": "2024-01-22T10:30:00Z"
  }
}

Valores em Centavos: Todos os valores monetários devem ser enviados em centavos. R$ 100,00 = 10000 centavos.

Passo 3: Exibir o QR Code

Para pagamentos PIX, você receberá:

pix_qr_code: String do QR Code (formato EMV)
pix_qr_code_url: URL da imagem do QR Code

Exiba o QR Code para o cliente escanear com o app do banco:

HTML

<img src="https://api.econpay.com.br/qrcode/123.png" alt="QR Code PIX" />
<p>Ou copie o código PIX:</p>
<code>00020126580014br.gov.bcb.pix...</code>

Passo 4: Receber Notificações

Configure um webhook para receber notificações quando o pagamento for aprovado:

Exemplo de Webhook

{
  "event": "payment.approved",
  "transaction_id": 123,
  "order_number": "ORD-20240122-123456",
  "status": "APPROVED",
  "amount": 10000,
  "payment_type": "pix",
  "paid_at": "2024-01-22T10:35:00Z"
}

Configurar Webhooks

Aprenda a configurar e testar webhooks

Próximos Passos

Agora que você processou seu primeiro pagamento, explore:

Boleto Bancário

Gere boletos registrados

Reembolsos

Processe estornos e cancelamentos

Listar Transações

Consulte histórico de pagamentos

Ambientes

Configure ambiente de testes

​Visão Geral

​Pré-requisitos

​Passo 1: Autenticação

​Passo 2: Criar um Pagamento PIX

​Passo 3: Exibir o QR Code

​Passo 4: Receber Notificações

Configurar Webhooks

​Próximos Passos

Boleto Bancário

Reembolsos

Listar Transações

Ambientes

Visão Geral

Pré-requisitos

Passo 1: Autenticação

Passo 2: Criar um Pagamento PIX

Passo 3: Exibir o QR Code

Passo 4: Receber Notificações

Próximos Passos