> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.hydrahub.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Transações PIX

> Endpoint para gerar QR Codes e transações PIX

## 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

<ParamField body="paymentMethod" type="string" required>
  Método de pagamento (deve ser "pix")
</ParamField>

<ParamField body="amount" type="integer" required>
  Valor total em centavos
</ParamField>

<ParamField body="pix.expiresInDays" type="integer" required>
  Dias para expiração do PIX
</ParamField>

<ParamField body="customer" type="object" required>
  Dados do cliente
</ParamField>

<ParamField body="customer.name" type="string" required>
  Nome completo do cliente
</ParamField>

<ParamField body="customer.email" type="string" required>
  Email do cliente
</ParamField>

<ParamField body="customer.phone" type="string" required>
  Telefone do cliente
</ParamField>

<ParamField body="customer.document.type" type="string" required>
  Tipo do documento (cpf ou cnpj)
</ParamField>

<ParamField body="customer.document.number" type="string" required>
  Número do documento
</ParamField>

<ParamField body="externalRef" type="string" required>
  Referência externa para identificação da transação
</ParamField>

<ParamField body="postbackUrl" type="string" required>
  URL para receber notificações de alteração de status
</ParamField>

<ParamField body="traceable" type="boolean" required>
  Se a transação é rastreável
</ParamField>

<ParamField body="items" type="array" required>
  Lista de itens do pedido
</ParamField>

<ParamField body="ip" type="string" required>
  Endereço IP do cliente
</ParamField>

<ParamField body="metadata" type="string" required>
  Dados adicionais em formato JSON string
</ParamField>

<RequestExample>
  ```json
  {
    "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": "joao@email.com",
      "phone": "11987654321",
      "document": {
        "type": "cpf",
        "number": "12345678909"
      }
    },
    "metadata": "{\"provider\":\"Hydra Checkout\",\"user_email\":\"joao@email.com\"}",
    "traceable": false,
    "externalRef": "pedido_123456",
    "postbackUrl": "https://seusite.com.br/webhook"
  }
  ```
</RequestExample>

### Resposta

<ResponseExample>
  ```json
  {
    "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": "joao@email.com",
        "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"
    }
  }
  ```
</ResponseExample>

### Exemplo com cURL

```bash
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": "joao@email.com",
    "phone": "11987654321",
    "document": {
      "type": "cpf",
      "number": "12345678909"
    }
  },
  "metadata": "{\"provider\":\"Hydra Checkout\",\"user_email\":\"joao@email.com\"}",
  "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`.