> ## Documentation Index
> Fetch the complete documentation index at: https://docs.econpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia de Início Rápido

> Processe seu primeiro pagamento em minutos

## 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.

<Note>
  **Ambiente de Testes:** Use o ambiente sandbox para testar sem processar transações reais. Veja mais em [Ambientes](/guides/environments).
</Note>

## Pré-requisitos

Antes de começar, você precisa:

1. Uma conta EconPay (crie em [app.econpay.com.br](https://app.econpay.com.br))
2. Seu `access_token` (disponível no dashboard)
3. Um cliente HTTP (cURL, Postman, ou sua linguagem preferida)

## Passo 1: Autenticação

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

```bash cURL theme={null}
curl --request POST \
  --url https://api.econpay.com.br/auth \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "seu-email@exemplo.com",
    "password": "sua-senha"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch('https://api.econpay.com.br/auth', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'seu-email@exemplo.com',
    password: 'sua-senha'
  })
});

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

```python Python theme={null}
import requests

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

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

<Accordion title="Resposta de Sucesso">
  ```json theme={null}
  {
    "response": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "user": {
        "id": 1,
        "name": "Seu Nome",
        "email": "seu-email@exemplo.com"
      }
    }
  }
  ```
</Accordion>

## Passo 2: Criar um Pagamento PIX

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

```bash cURL theme={null}
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": "joao@exemplo.com",
      "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 JavaScript theme={null}
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: 'joao@exemplo.com',
      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 Python theme={null}
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': 'joao@exemplo.com',
            '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'])
```

<Accordion title="Resposta de Sucesso">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

<Warning>
  **Valores em Centavos:** Todos os valores monetários devem ser enviados em centavos. R\$ 100,00 = 10000 centavos.
</Warning>

## 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 HTML theme={null}
<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:

```json Exemplo de Webhook theme={null}
{
  "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"
}
```

<Card title="Configurar Webhooks" icon="webhook" href="/guides/webhooks">
  Aprenda a configurar e testar webhooks
</Card>

## Próximos Passos

Agora que você processou seu primeiro pagamento, explore:

<CardGroup cols={2}>
  <Card title="Boleto Bancário" icon="file-invoice" href="/api-reference/payments/create-payment">
    Gere boletos registrados
  </Card>

  <Card title="Reembolsos" icon="rotate-left" href="/api-reference/payments/refund">
    Processe estornos e cancelamentos
  </Card>

  <Card title="Listar Transações" icon="list" href="/api-reference/transactions/list">
    Consulte histórico de pagamentos
  </Card>

  <Card title="Ambientes" icon="flask" href="/guides/environments">
    Configure ambiente de testes
  </Card>
</CardGroup>