Transações PIX

{
  "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"
  }
}

POST

api

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"
  }
}

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

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

Status	Descrição
pending	Aguardando pagamento
approved	Pagamento recebido e confirmado
cancelled	Transação cancelada
expired	Transação expirada (QR Code não foi pago no prazo)
refunded	Transaçã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.

Transações com Cartão Gerenciamento de Entregas

Introdução

Status e Informações

Transações

Sellers

Transações PIX