(
'https://api.public.firebanking.com.br/api/pix/cash-in',
payload,
{
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
}
}
);
console.log('Cobrança PIX gerada com sucesso!');
console.log(`ID da Transação: ${response.data.transactionId}`);
console.log(`Código PIX: ${response.data.pixCode}`);
console.log(`Expira em: ${new Date(response.data.expirationDate).toLocaleString('pt-BR')}`);
if (response.data.qrCodeImage) {
console.log('QR Code Image disponível para exibição');
}
return response.data;
} catch (error) {
if (axios.isAxiosError(error)) {
console.error('Erro ao gerar cobrança:', error.response?.data);
throw new Error(error.response?.data?.message || 'Erro ao gerar cobrança PIX');
}
throw error;
}
}
// Uso
const token = 'seu_token_aqui';
createPixCharge(token, '12345', 150.00, 'Carlos Oliveira', '12345678901');
```
### Python
```python theme={null}
import requests
from datetime import datetime, timedelta
from typing import Dict, Optional
def create_pix_charge(
token: str,
order_id: str,
amount: float,
customer_name: str,
customer_document: str,
expiration_hours: int = 1,
additional_info: Optional[Dict[str, str]] = None
) -> Dict:
"""
Gera uma cobrança PIX
Args:
token: Token Bearer válido
order_id: ID do pedido
amount: Valor em reais
customer_name: Nome do cliente
customer_document: CPF ou CNPJ (apenas números)
expiration_hours: Horas até expiração (padrão: 1)
additional_info: Informações adicionais
Returns:
Dados da cobrança gerada
"""
url = 'https://api.public.firebanking.com.br/api/pix/cash-in'
payload = {
'transaction': {
'value': round(amount, 2),
'description': f'Pagamento do pedido {order_id}',
'expirationTime': expiration_hours * 3600,
'externalId': f'ORDER-{order_id}-{int(datetime.now().timestamp())}',
'generateQrCode': True
},
'payer': {
'fullName': customer_name,
'document': customer_document
},
'additionalInfo': additional_info or {}
}
headers = {
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json'
}
try:
response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()
data = response.json()
print('Cobrança PIX gerada com sucesso!')
print(f"ID da Transação: {data['transactionId']}")
print(f"Código PIX: {data['pixCode']}")
print(f"Status: {data['status']}")
expiration = datetime.fromisoformat(data['expirationDate'].replace('Z', '+00:00'))
print(f"Expira em: {expiration.strftime('%d/%m/%Y %H:%M:%S')}")
if 'qrCodeImage' in data:
print('QR Code Image disponível para exibição')
return data
except requests.exceptions.RequestException as e:
print(f'Erro ao gerar cobrança: {e}')
if hasattr(e.response, 'json'):
print(f'Detalhes: {e.response.json()}')
raise
# Uso
token = 'seu_token_aqui'
charge = create_pix_charge(
token=token,
order_id='12345',
amount=150.00,
customer_name='Carlos Oliveira',
customer_document='12345678901',
expiration_hours=24,
additional_info={
'storeName': 'Tech Solutions',
'productCategory': 'Eletrônicos'
}
)
```
### PHP
```php theme={null}
[
'value' => round($amount, 2),
'description' => "Pagamento do pedido $orderId",
'expirationTime' => $expirationHours * 3600,
'externalId' => "ORDER-$orderId-" . time(),
'generateQrCode' => true
],
'payer' => [
'fullName' => $customerName,
'document' => $customerDocument
],
'additionalInfo' => [
'orderId' => $orderId
]
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
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) {
throw new Exception("Erro ao gerar cobrança: HTTP $httpCode - $response");
}
$data = json_decode($response, true);
echo "Cobrança PIX gerada com sucesso!" . PHP_EOL;
echo "ID da Transação: {$data['transactionId']}" . PHP_EOL;
echo "Código PIX: {$data['pixCode']}" . PHP_EOL;
echo "Status: {$data['status']}" . PHP_EOL;
if (isset($data['qrCodeImage'])) {
echo "QR Code Image disponível para exibição" . PHP_EOL;
}
return $data;
}
// Uso
$token = 'seu_token_aqui';
$charge = createPixCharge(
$token,
'12345',
150.00,
'Carlos Oliveira',
'12345678901',
24
);
```
## Casos de Uso
### 1. E-commerce - Checkout com PIX
```javascript theme={null}
// Integração em checkout de e-commerce
class PixCheckout {
constructor(token) {
this.token = token;
}
async generatePayment(order) {
const charge = await createPixCharge(
this.token,
order.id,
order.total,
order.customer.name,
order.customer.document
);
// Exibir QR Code na página (usando imagem da API ou gerando localmente)
this.displayQrCode(charge);
// Iniciar polling para verificar pagamento
this.startPaymentPolling(charge.transactionId);
return charge;
}
displayQrCode(charge) {
const qrCanvas = document.getElementById('qr-canvas');
const qrImage = document.getElementById('qr-image');
// Usar imagem Base64 da API (preferível - evita processamento no cliente)
if (charge.qrCodeImage) {
qrImage.src = charge.qrCodeImage;
qrImage.style.display = 'block';
qrCanvas.style.display = 'none';
} else {
// Fallback: gerar QR Code localmente usando biblioteca (ex: qrcode.js)
QRCode.toCanvas(qrCanvas, charge.pixCode, {
width: 300,
margin: 2
});
qrCanvas.style.display = 'block';
qrImage.style.display = 'none';
}
// Mostrar também o código Pix Copia e Cola
document.getElementById('pix-code').textContent = charge.pixCode;
}
startPaymentPolling(transactionId) {
// Verificar status a cada 3 segundos
const interval = setInterval(async () => {
const status = await this.checkPaymentStatus(transactionId);
if (status === 'CONFIRMED') {
clearInterval(interval);
this.onPaymentConfirmed();
}
}, 3000);
// Parar após 10 minutos
setTimeout(() => clearInterval(interval), 10 * 60 * 1000);
}
onPaymentConfirmed() {
// Redirecionar para página de sucesso
window.location.href = '/payment/success';
}
}
```
### 2. PDV (Ponto de Venda)
```python theme={null}
class PixPDV:
"""Sistema de PDV com cobrança PIX"""
def __init__(self, token: str):
self.token = token
def process_sale(self, items: list, customer: dict) -> dict:
"""Processar venda e gerar cobrança PIX"""
# Calcular total
total = sum(item['price'] * item['quantity'] for item in items)
# Gerar descrição
description = self.generate_sale_description(items)
# Criar cobrança PIX (expira em 15 minutos)
charge = create_pix_charge(
token=self.token,
order_id=self.generate_sale_id(),
amount=total,
customer_name=customer['name'],
customer_document=customer['document'],
expiration_hours=0.25, # 15 minutos
additional_info={
'items_count': str(len(items)),
'cashier_id': self.get_cashier_id()
}
)
# Imprimir comprovante com QR Code
self.print_receipt(charge, items, total)
return charge
def generate_sale_description(self, items: list) -> str:
"""Gerar descrição resumida da venda"""
if len(items) == 1:
return f"{items[0]['name']}"
else:
return f"{len(items)} itens - {items[0]['name']} e mais"
def print_receipt(self, charge: dict, items: list, total: float):
"""Imprimir comprovante com QR Code"""
# Implementar impressão térmica ou gerar PDF
print("\n" + "="*50)
print("COMPROVANTE DE COBRANÇA PIX")
print("="*50)
for item in items:
print(f"{item['name']}: R$ {item['price']:.2f}")
print("-"*50)
print(f"TOTAL: R$ {total:.2f}")
print(f"\nID da Transação: {charge['transactionId']}")
print(f"Código PIX:\n{charge['pixCode']}")
print("="*50 + "\n")
```
### 3. SaaS - Cobrança de Assinatura
```typescript theme={null}
class SubscriptionBilling {
constructor(private token: string) {}
async chargeMonthlySubscription(
subscriptionId: string,
userId: string,
planValue: number
) {
// Buscar dados do usuário
const user = await this.getUserData(userId);
// Gerar cobrança com expiração de 3 dias
const charge = await createPixCharge(
this.token,
`SUB-${subscriptionId}-${new Date().getMonth() + 1}`,
planValue,
user.name,
user.document
);
// Enviar email com link de pagamento
await this.sendPaymentEmail(user.email, charge);
// Agendar lembrete 1 dia antes de expirar
await this.scheduleReminder(user, charge, 24);
return charge;
}
async sendPaymentEmail(email: string, charge: CashInResponse) {
// Implementar envio de email
const paymentLink = `https://app.exemplo.com/payment/${charge.transactionId}`;
await sendEmail({
to: email,
subject: 'Fatura disponível - Pague com PIX',
html: `
Sua fatura está disponível
Valor: R$ ${charge.value}
Vencimento: ${new Date(charge.expirationDate).toLocaleDateString('pt-BR')}
Clique aqui para pagar com PIX
`
});
}
}
```
## Monitoramento de Pagamentos
Para ser notificado quando um pagamento for confirmado, você pode:
Configure webhooks para receber notificações automáticas quando o status mudar.
```javascript theme={null}
// Endpoint webhook em seu servidor
app.post('/webhooks/pix', (req, res) => {
const { transactionId, status, externalId } = req.body;
if (status === 'CONFIRMED') {
// Processar pagamento confirmado
processPaymentConfirmation(externalId);
}
res.sendStatus(200);
});
```
Consulte periodicamente o status da transação.
```javascript theme={null}
async function monitorPayment(transactionId, maxAttempts = 200) {
for (let i = 0; i < maxAttempts; i++) {
const status = await checkTransactionStatus(transactionId);
if (status === 'CONFIRMED') {
return true;
}
// Aguardar 3 segundos antes de tentar novamente
await new Promise(resolve => setTimeout(resolve, 3000));
}
return false; // Timeout
}
```
## Códigos de Resposta
| Código | Descrição | Significado |
| ------ | --------------- | ------------------------------------------- |
| `201` | Cobrança Criada | Cobrança PIX gerada com sucesso |
| `400` | Dados Inválidos | Verifique os campos obrigatórios e formatos |
| `401` | Token Inválido | Token não fornecido, expirado ou inválido |
Consulte a [Referência da API](/api-reference/endpoints/pix-cash-in) para detalhes completos dos campos de resposta.
## Boas Práticas
Inclua informações que facilitem a identificação: `ORDER-{orderId}-{timestamp}` ou `INV-{invoiceId}-{date}`
* **E-commerce:** 15-30 minutos
* **Boletos/Faturas:** 3-7 dias
* **PDV:** 5-15 minutos
Implemente validação local para evitar erros 400.
```javascript theme={null}
function isValidCPF(cpf: string): boolean {
cpf = cpf.replace(/\D/g, '');
if (cpf.length !== 11) return false;
// Adicionar lógica de validação de CPF
return true;
}
```
Use bibliotecas de precisão decimal para evitar erros de arredondamento.
```javascript theme={null}
import Decimal from 'decimal.js';
const total = new Decimal(price).times(quantity).toNumber();
```
## Observações Importantes
Cobranças expiradas não podem ser reativadas. Gere uma nova cobrança se necessário.
* **Valor mínimo:** R\$ 0,01
* **Expiração mínima:** 5 minutos (300 segundos)
* **Expiração máxima:** 7 dias (604800 segundos)
## Próximos Passos
Aprenda a estornar pagamentos recebidos
Envie pagamentos PIX
Realize pagamentos via QR Code PIX