```
## Parâmetros detalhados
### Campos Obrigatórios
| Campo | Tipo | Descrição |
| ----------------------- | -------- | ------------------------------------------ |
| `amountInCents` | `number` | Valor em centavos (ex: 10000 = R\$ 100,00) |
| `customer` | `object` | Dados do cliente pagador |
| `customer.name` | `string` | Nome completo do cliente |
| `customer.email` | `string` | Email do cliente |
| `customer.documentType` | `string` | Tipo do documento (`cpf` ou `cnpj`) |
| `customer.document` | `string` | Número do documento (apenas números) |
### Campos Opcionais
| Campo | Tipo | Descrição |
| ------------------------- | -------- | -------------------------------------------- |
| `description` | `string` | Descrição da transação (máx. 140 caracteres) |
| `postbackUrl` | `string` | URL específica para webhooks desta transação |
| `items` | `array` | Lista de itens da compra |
| `customer.phone` | `string` | Telefone do cliente |
| `customer.billingAddress` | `object` | Endereço de cobrança |
### Exemplo Completo
```json theme={null}
{
"amountInCents": 10000,
"description": "Assinatura - Plano Exemplo",
"postbackUrl": "https://exemplo.com.br/webhooks/pix-payments",
"customer": {
"name": "Cliente Exemplo Silva",
"email": "cliente@exemplo.com",
"documentType": "cpf",
"document": "11122233344",
"phone": "11912345678",
"billingAddress": {
"street": "Rua Exemplo",
"number": "100",
"neighborhood": "Centro",
"city": "São Paulo",
"state": "SP",
"zipCode": "00000000"
}
},
"items": [
{
"title": "Produto Exemplo",
"tangible": false,
"quantity": 1,
"amountInCents": 10000
}
]
}
```
## Recebendo confirmações
### Via Webhook
Configure um webhook para receber confirmações automáticas:
```json theme={null}
{
"id": "trx_1a2b3c4d5e6f7g8h9i0j",
"type": "transaction",
"event": "transaction_paid",
"scope": "postback",
"transaction": {
"id": "trx_1a2b3c4d5e6f7g8h9i0j",
"amount": 5000,
"status": "paid",
"pix": {
"endToEndId": "E00000000202401011200000000000000",
"payerInfo": {
"bank": "000",
"name": "Cliente Pagador",
"branch": "0001",
"document": "11122233344",
"account_type": "CHECKING",
"account_number": "000000"
}
}
}
}
```
### Processamento do Webhook
```javascript theme={null}
app.post('/webhooks/pix-payments', (req, res) => {
const event = req.body
if (event.event === 'transaction_paid') {
const transaction = event.transaction
// Liberar produto/serviço
await liberarProduto(transaction.id)
// Enviar email de confirmação
await enviarEmailConfirmacao(transaction.customer.email)
// Atualizar banco de dados
await atualizarStatusPagamento(transaction.id, 'paid')
}
res.status(200).send('OK')
})
```
## Taxas e valores
### Estrutura de Taxas
* **Taxa**: Consulte sua conta para verificar as taxas aplicáveis
* **Sem taxa mínima**: Cobranças a partir de R\$ 0,01
* **Sem mensalidade**: Pague apenas pelo que usar
### Cálculo de Valores
```javascript theme={null}
// Exemplo de cálculo
const valorProduto = 5000 // R$ 50,00 em centavos
const taxa = 0 // Taxa aplicável
// Na resposta da API
{
"data": {
"amount": 5000, // Valor total
"fees": 0 // Taxa cobrada
}
}
```
## Status das transações
| Status | Descrição | Próximo Passo |
| ---------- | -------------------- | -------------------------------- |
| `pending` | Aguardando pagamento | Mostrar QR Code para cliente |
| `paid` | Pago com sucesso | Liberar produto/serviço |
| `canceled` | Cancelado | Gerar novo QR Code se necessário |
| `refunded` | Estornado | Valor devolvido ao pagador |
## Fluxo completo de implementação
### 1. Gerar QR Code
```javascript theme={null}
async function criarPagamentoPIX(dadosPagamento) {
const response = await fetch('/api/v1/pix/in/qrcode', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(dadosPagamento)
})
const data = await response.json()
return data.data
}
```
### 2. Exibir para Cliente
```javascript theme={null}
function exibirQRCode(transacao) {
// Mostrar QR Code
document.getElementById('qr-code').src = transacao.pix.qrCode
// Mostrar código para copiar
document.getElementById('pix-code').value = transacao.pix.emv
// Iniciar verificação de status
verificarStatus(transacao.id)
}
```
### 3. Verificar Status (Polling)
```javascript theme={null}
async function verificarStatus(transactionId) {
const interval = setInterval(async () => {
const response = await fetch(`/api/v1/transactions/${transactionId}`, {
headers: { 'Authorization': `Bearer ${token}` }
})
const data = await response.json()
if (data.status === 'paid') {
clearInterval(interval)
mostrarSucesso()
}
}, 3000) // Verifica a cada 3 segundos
}
```
### 4. Processar Confirmação
```javascript theme={null}
function mostrarSucesso() {
document.getElementById('qr-code-container').style.display = 'none'
document.getElementById('sucesso-container').style.display = 'block'
// Redirecionar após 3 segundos
setTimeout(() => {
window.location.href = '/obrigado'
}, 3000)
}
```
## Boas práticas
### Segurança