Visão Geral
O HYDRA HUB oferece uma solução completa para processamento de pagamentos via PIX, o sistema de pagamentos instantâneos do Banco Central do Brasil. Com o PIX, seus clientes podem efetuar pagamentos 24/7, incluindo finais de semana e feriados, com confirmação em segundos.
Endpoint
POST /api/v1/transactions
Autenticação
Todas as operações de transação exigem autenticação usando Basic Auth. Concatene sua chave secreta e pública no formato sk_userKey:pk_userKey e codifique em Base64.
Authorization: Basic {base64(sk_userKey:pk_userKey)}
Request Body
{
"paymentMethod": "pix",
"ip": "187.122.63.11",
"pix": {
"expiresInDays": 1
},
"items": [
{
"title": "Assinatura Premium",
"quantity": 1,
"tangible": false,
"unitPrice": 9990,
"product_image": "https://seusite.com.br/imagens/assinatura.png"
}
],
"amount": 9990,
"customer": {
"name": "Carolina Lima",
"email": "[email protected]",
"phone": "11954321987",
"document": {
"type": "cpf",
"number": "98765432101"
}
},
"metadata": "{\"provider\":\"Hydra Checkout\",\"user_email\":\"[email protected]\"}",
"traceable": false,
"externalRef": "pedido456",
"postbackUrl": "https://seusite.com.br/webhook"
}
Campos Obrigatórios
| Campo | Tipo | Descrição |
|---|
| paymentMethod | string | Método de pagamento (deve ser “pix”) |
| amount | integer | Valor total em centavos (exemplo: 9990 = R$ 99,90) |
| customer | object | Dados do cliente |
| customer.name | string | Nome completo do cliente |
| customer.email | string | Email do cliente |
| customer.document.type | string | Tipo de documento (cpf ou cnpj) |
| customer.document.number | string | Número do documento (somente números) |
Campos Opcionais
| Campo | Tipo | Descrição |
|---|
| pix.expiresInDays | integer | Dias até expiração do QR Code (padrão: 1 dia) |
| ip | string | Endereço IP do cliente |
| items | array | Lista de itens do pedido |
| externalRef | string | Referência externa para identificação da transação |
| customer.phone | string | Telefone do cliente |
| postbackUrl | string | URL para receber notificações de alteração de status |
| traceable | boolean | Se a transação é rastreável |
| metadata | string | Dados adicionais em formato JSON |
Tempo de Expiração do PIX
Por padrão, os QR Codes gerados expiram em 1 dia. Você pode personalizar esse período utilizando o campo pix.expiresInDays:
"pix": {
"expiresInDays": 3 // QR Code válido por 3 dias
}
O tempo máximo de expiração é de 30 dias. Valores maiores serão limitados automaticamente.
Response
{
"success": true,
"message": "Transação criada com sucesso",
"status": 1,
"data": {
"id": 12345,
"status": "pending",
"amount": 9990,
"companyId": 123,
"installments": 1,
"refusedAmount": 0,
"paidAmount": 0,
"refundedAmount": 0,
"paymentMethod": "pix",
"metadata": "{\"provider\":\"Hydra Checkout\"}",
"acquirerType": "direct",
"secureId": "tx_abcdef123456",
"secureUrl": "https://api.hydrahub.com.br/secure/tx_abcdef123456",
"externalId": "pedido456",
"customer": {
"name": "Carolina Lima",
"email": "[email protected]",
"phone": "11954321987",
"externalRef": "cliente_789",
"document": {
"number": "98765432101",
"type": "cpf"
}
},
"pix": {
"qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
"qrcodeText": "00020101021226880014br.gov.bcb.pix2566qrcodepix.hydrahub.com.br/v1/pix/31be673d9866c5ee3c1891a988a5864852040000530398654041.005802BR5925HYDRA HUB INTERMEDIACAO6009SAO PAULO62360532e673d9866c5ee3c1891a988a586486304A6C2",
"expirationDate": "2023-05-15T23:59:59Z"
},
"traceable": false,
"fees": 299,
"postBackUrl": "https://seusite.com.br/webhook",
"createdAt": "2023-05-14T14:30:45Z"
}
}
Campos Importantes da Resposta
| Campo | Descrição |
|---|
| data.id | ID da transação no sistema HYDRA HUB |
| data.status | Status atual da transação (“pending” inicialmente) |
| data.externalId | Sua referência externa, se fornecida |
| data.pix.qrcode | Imagem do QR Code em formato Base64, pronta para exibição |
| data.pix.qrcodeText | Texto do PIX Copia e Cola |
| data.pix.expirationDate | Data e hora de expiração do PIX |
Exibindo o QR Code para o Cliente
A resposta inclui o QR Code em formato Base64, pronto para ser exibido diretamente em uma tag img:
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." alt="QR Code PIX" />
<button onclick="navigator.clipboard.writeText('00020101021226880014br.gov.bcb.pix2566qrcodepix...')">
Copiar PIX Copia e Cola
</button>
Status da Transação PIX
Uma transação PIX pode ter os seguintes status:
| Status | Descrição |
|---|
| pending | Aguardando pagamento |
| approved | Pagamento recebido e confirmado |
| canceled | Transação cancelada |
| expired | Transação expirada (QR Code não foi pago no prazo) |
| refunded | Transação estornada |
Notificações de Pagamento
O HYDRA HUB notificará automaticamente seu sistema sobre a confirmação do pagamento via webhook. Configure a URL de callback no campo postbackUrl para receber essas notificações.
A confirmação do PIX geralmente ocorre em segundos, mas é importante implementar um fluxo assíncrono usando webhooks em vez de polling.
Webhook
Quando o status da transação mudar (por exemplo, quando o PIX for pago), o HYDRA HUB enviará uma notificação POST para a URL configurada em postbackUrl:
{
"id": 12345,
"status": "approved",
"externalRef": "pedido456",
"amount": 9990,
"transactionDate": "2023-05-14T14:35:22Z"
}
Testes no Ambiente Sandbox
Para testar o pagamento via PIX no ambiente de Sandbox:
- Crie uma transação conforme documentado acima
- Acesse o Dashboard do Sandbox
- Na seção “Transações”, localize a transação criada
- Clique no botão “Simular Pagamento” para aprovar a transação
Possíveis Erros
Erro de Autenticação
{
"success": false,
"message": "Unauthorized"
}
Erro de Validação
{
"success": false,
"message": "Validation Error",
"errors": [
{
"field": "customer.document.number",
"message": "CPF inválido"
}
]
}
Boas Práticas
- Implemente webhooks para receber atualizações de status em tempo real
- Armazene o ID da transação na sua base de dados para referência futura
- Verifique o status da transação antes de liberar o produto/serviço
- Ofereça opções de PIX Copia e Cola além do QR Code
- Configure um tempo de expiração adequado para seu modelo de negócio
Próximos Passos
