Skip to main content
POST
/
api
/
v1
/
transactions
{
  "paymentMethod": "pix",
  "ip": "172.18.0.1",
  "pix": {
    "expiresInDays": 1
  },
  "items": [
    {
      "title": "Produto teste",
      "quantity": 1,
      "tangible": false,
      "unitPrice": 1100,
      "product_image": "https://seusite.com.br/imagens/produto.png"
    }
  ],
  "amount": 1100,
  "customer": {
    "name": "João Silva",
    "email": "[email protected]",
    "phone": "11987654321",
    "document": {
      "type": "cpf",
      "number": "12345678909"
    }
  },
  "metadata": "{\"provider\":\"Hydra Checkout\",\"user_email\":\"[email protected]\"}",
  "traceable": false,
  "externalRef": "pedido_123456",
  "postbackUrl": "https://seusite.com.br/webhook"
}

{
  "success": true,
  "message": "Transaction created",
  "status": 201,
  "data": {
    "id": 12345,
    "status": "pending",
    "amount": 1100,
    "companyId": 1,
    "installments": 1,
    "refusedAmount": 0,
    "paidAmount": 0,
    "refundedAmount": 0,
    "paymentMethod": "pix",
    "acquirerType": "horizon",
    "secureId": "c30a4718-a548-4e07-aa1a-9db459015f48",
    "secureUrl": "https://pay.hydrapayments.com/checkout/c30a4718-a548-4e07-aa1a-9db459015f48",
    "externalId": "pedido_123456",
    "customer": {
      "name": "João Silva",
      "email": "[email protected]",
      "phone": "11987654321",
      "document": {
        "number": "12345678909",
        "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": "2025-05-03T15:57:33.751Z"
    },
    "traceable": false,
    "fees": 164,
    "createdAt": "2025-05-02T15:57:33.751Z"
  }
}

​
Transações PIX

Este endpoint permite criar transações utilizando o método de pagamento PIX, gerando um QR Code que pode ser escaneado pelo cliente para realizar o pagamento.

​
Autenticação

Este endpoint utiliza autenticação via Basic Auth: 
Authorization: Basic {base64(sk_userKey:pk_userKey)}

​
Parâmetros da Requisição

​
paymentMethod
string
required
Método de pagamento (deve ser “pix”)
​
amount
integer
required
Valor total em centavos
​
pix.expiresInDays
integer
required
Dias para expiração do PIX
​
customer
object
required
Dados do cliente
​
customer.name
string
required
Nome completo do cliente
​
customer.email
string
required
Email do cliente
​
customer.phone
string
required
Telefone do cliente
​
customer.document.type
string
required
Tipo do documento (cpf ou cnpj)
​
customer.document.number
string
required
Número do documento
​
externalRef
string
required
Referência externa para identificação da transação
​
postbackUrl
string
required
URL para receber notificações de alteração de status
​
traceable
boolean
required
Se a transação é rastreável
​
items
array
required
Lista de itens do pedido
​
ip
string
required
Endereço IP do cliente
​
metadata
string
required
Dados adicionais em formato JSON string
{
  "paymentMethod": "pix",
  "ip": "172.18.0.1",
  "pix": {
    "expiresInDays": 1
  },
  "items": [
    {
      "title": "Produto teste",
      "quantity": 1,
      "tangible": false,
      "unitPrice": 1100,
      "product_image": "https://seusite.com.br/imagens/produto.png"
    }
  ],
  "amount": 1100,
  "customer": {
    "name": "João Silva",
    "email": "[email protected]",
    "phone": "11987654321",
    "document": {
      "type": "cpf",
      "number": "12345678909"
    }
  },
  "metadata": "{\"provider\":\"Hydra Checkout\",\"user_email\":\"[email protected]\"}",
  "traceable": false,
  "externalRef": "pedido_123456",
  "postbackUrl": "https://seusite.com.br/webhook"
}

​
Resposta

{
  "success": true,
  "message": "Transaction created",
  "status": 201,
  "data": {
    "id": 12345,
    "status": "pending",
    "amount": 1100,
    "companyId": 1,
    "installments": 1,
    "refusedAmount": 0,
    "paidAmount": 0,
    "refundedAmount": 0,
    "paymentMethod": "pix",
    "acquirerType": "horizon",
    "secureId": "c30a4718-a548-4e07-aa1a-9db459015f48",
    "secureUrl": "https://pay.hydrapayments.com/checkout/c30a4718-a548-4e07-aa1a-9db459015f48",
    "externalId": "pedido_123456",
    "customer": {
      "name": "João Silva",
      "email": "[email protected]",
      "phone": "11987654321",
      "document": {
        "number": "12345678909",
        "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": "2025-05-03T15:57:33.751Z"
    },
    "traceable": false,
    "fees": 164,
    "createdAt": "2025-05-02T15:57:33.751Z"
  }
}

​
Exemplo com cURL

curl --location 'https://api.hydrahub.com.br/api/v1/transactions' \
--header 'Authorization: Basic {base64(sk_userKey:pk_userKey)}' \
--header 'Content-Type: application/json' \
--data '{
  "paymentMethod": "pix",
  "ip": "172.18.0.1",
  "pix": {
    "expiresInDays": 1
  },
  "items": [
    {
      "title": "Produto teste",
      "quantity": 1,
      "tangible": false,
      "unitPrice": 1100,
      "product_image": "https://seusite.com.br/imagens/produto.png"
    }
  ],
  "amount": 1100,
  "customer": {
    "name": "João Silva",
    "email": "[email protected]",
    "phone": "11987654321",
    "document": {
      "type": "cpf",
      "number": "12345678909"
    }
  },
  "metadata": "{\"provider\":\"Hydra Checkout\",\"user_email\":\"[email protected]\"}",
  "traceable": false,
  "externalRef": "pedido_123456",
  "postbackUrl": "https://seusite.com.br/webhook"
}'

​
Status de Transação

StatusDescrição
pendingAguardando pagamento
approvedPagamento recebido e confirmado
cancelledTransação cancelada
expiredTransação expirada (QR Code não foi pago no prazo)
refundedTransação estornada

​
Códigos de Resposta

  • 201 - Transação criada e QR Code gerado
  • 401 - Erro de autenticação
  • 400 - Dados inválidos

​
Observações

  • O QR Code PIX é enviado no formato base64 e pode ser exibido diretamente em uma tag de imagem HTML.
  • O campo qrcodeText contém o código PIX “copia e cola” que pode ser utilizado pelos clientes.
  • Utilize o webhook (postbackUrl) para receber notificações automáticas quando o pagamento for confirmado.
  • O PIX expira conforme o número de dias especificado no parâmetro expiresInDays.