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

> Endpoint unificado para processar transações de pagamento

## Transações de Pagamento

Este endpoint unificado permite criar transações utilizando diferentes métodos de pagamento. A mesma rota é usada tanto para cartão de crédito quanto para PIX, diferenciando-se apenas pelo valor do campo `paymentMethod` e seus parâmetros específicos.

### Autenticação

Este endpoint utiliza autenticação via Basic Auth:

```
Authorization: Basic {base64(sk_userKey:pk_userKey)}
```

### Parâmetros Comuns da Requisição

<ParamField body="paymentMethod" type="string" required>
  Método de pagamento ("credit\_card" ou "pix")
</ParamField>

<ParamField body="amount" type="integer" required>
  Valor total em centavos
</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>

### Parâmetros para Cartão de Crédito

<ParamField body="paymentMethod" type="string" required>
  Deve ser "credit\_card"
</ParamField>

<ParamField body="installments" type="string" required>
  Número de parcelas
</ParamField>

<ParamField body="card.hash" type="string" required>
  Token do cartão gerado previamente
</ParamField>

### Parâmetros para PIX

<ParamField body="paymentMethod" type="string" required>
  Deve ser "pix"
</ParamField>

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

### Exemplos de Requisição

<CodeGroup>
  ```json Cartão de Crédito
  {
    "paymentMethod": "credit_card",
    "ip": "172.18.0.1",
    "items": [
      {
        "title": "Produto teste",
        "unitPrice": 1100,
        "quantity": 1,
        "tangible": false
      }
    ],
    "amount": 1100,
    "externalRef": "05b8caaf6ba6f4bdb68675ab8b893bda",
    "customer": {
      "name": "Fabio Teste",
      "email": "fabio@teste.com",
      "phone": "22948618616",
      "document": {
        "type": "cpf",
        "number": "69686902414"
      }
    },
    "postbackUrl": "https://devbackendvenus.cloud/checkout/payment/skallapay/webhook?wl=app.devakta.site",
    "traceable": false,
    "card": {
      "hash": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZWxsZXIiOjEsImNhcmQiOnsibnVtYmVyIjoiNDAwMDAwMDAwMDAwMDAxMCIsImhvbGRlck5hbWUiOiJHQUJSSUVMIEwgQyBET1MgUkVJUyIsImV4cGlyYXRpb25Nb250aCI6IjA2IiwiZXhwaXJhdGlvblllYXIiOiIyMDMzIiwiY3Z2IjoiMTIzIn0sImlhdCI6MTc0NjE4NzAwOCwiZXhwIjoxNzQ2MTg3MzA4fQ.FN6m4VDutP8A5uTOh0YfDvn5PY-H6Gojs2n9Rtco10g"
    },
    "installments": "1"
  }
  ```

  ```json PIX
  {
    "paymentMethod": "pix",
    "ip": "45.190.70.56",
    "pix": {
      "expiresInDays": 1
    },
    "items": [
      {
        "title": "Hydra HUB TESTE",
        "quantity": 1,
        "tangible": false,
        "unitPrice": 600,
        "product_image": ""
      }
    ],
    "amount": 600,
    "customer": {
      "name": "Jeferson",
      "email": "bruno@gmail.com",
      "phone": "21321313212",
      "document": {
        "type": "cpf",
        "number": "13138222722"
      }
    },
    "metadata": "{\"provider\":\"Vega Checkout\",\"user_identitication_number\":\"072.761.241-77\",\"user_email\":\"evmgroup.contabilidade@gmail.com\",\"sell_url\":\"https:\\/\\/hydradev.online\",\"order_url\":\"https:\\/\\/pay.hydradev.online\\/order\\/30edrvLZ\",\"referrer_link\":null}",
    "traceable": false,
    "externalRef": "30edrvLZ",
    "postbackUrl": "https://devbackendvenus.cloud/checkout/payment/skallapay/webhook?wl=app.devakta.site"
  }
  ```
</CodeGroup>

### Exemplos de Resposta

<CodeGroup>
  ```json Cartão de Crédito
  {
    "success": true,
    "message": "Transaction created",
    "status": 201,
    "data": {
      "id": 12345,
      "status": "refused",
      "refusedReason": "Token inválido (RL-3).",
      "amount": 1100,
      "companyId": 1,
      "installments": 1,
      "refusedAmount": 1100,
      "paidAmount": 0,
      "refundedAmount": 0,
      "paymentMethod": "credit_card",
      "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"
        }
      },
      "traceable": false,
      "fees": 164,
      "createdAt": "2025-05-02T15:57:33.751Z"
    }
  }
  ```

  ```json PIX
  {
    "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"
    }
  }
  ```
</CodeGroup>

### Exemplo com cURL

<CodeGroup>
  ```bash Cartão de Crédito
  curl --location 'https://api.hydrahub.com.br/api/v1/transactions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic c2tfQnoyU2UxQURnMUFzT3NqVnF0dVRER3NwV1lPR3QtOEl4Y0RuLWt5UzRXbDlCVHdwOnBrX29LSmthWU1RZUR3SUh3VjM3TENqUkhQMXlaSEFNRTVVMTMxUWtkY2lNRVh6dVQ1cw==' \
  --data-raw '{
      "paymentMethod": "credit_card",
      "ip": "172.18.0.1",
      "items": [
          {
              "title": "Produto teste",
              "unitPrice": 1100,
              "quantity": 1,
              "tangible": false
          }
      ],
      "amount": 1100,
      "externalRef": "05b8caaf6ba6f4bdb68675ab8b893bda",
      "customer": {
          "name": "Fabio Teste",
          "email": "fabio@teste.com",
          "phone": "22948618616",
          "document": {
              "type": "cpf",
              "number": "69686902414"
          }
      },
      "postbackUrl": "https://devbackendvenus.cloud/checkout/payment/skallapay/webhook?wl=app.devakta.site",
      "traceable": false,
      "card": {
          "hash": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZWxsZXIiOjEsImNhcmQiOnsibnVtYmVyIjoiNDAwMDAwMDAwMDAwMDAxMCIsImhvbGRlck5hbWUiOiJHQUJSSUVMIEwgQyBET1MgUkVJUyIsImV4cGlyYXRpb25Nb250aCI6IjA2IiwiZXhwaXJhdGlvblllYXIiOiIyMDMzIiwiY3Z2IjoiMTIzIn0sImlhdCI6MTc0NjE4NzAwOCwiZXhwIjoxNzQ2MTg3MzA4fQ.FN6m4VDutP8A5uTOh0YfDvn5PY-H6Gojs2n9Rtco10g"
      },
      "installments": "1"
  }'
  ```

  ```bash PIX
  curl --location 'https://api.hydrahub.com.br/api/v1/transactions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic c2tfMWhZXzlOWEN4bmVGbElhTHlibWhTUTJNY3FqX2VZWnVnNGNQUlllY2dybWhXT0hnOnBrX1VZalczbEhfWlNqZzJmSU1jYUp4UXBEbU9xVlpPcFQ4alUyaTZoaHEtNEx2SS1yMg==' \
  --data-raw '{
      "paymentMethod": "pix",
      "ip": "45.190.70.56",
      "pix": {
          "expiresInDays": 1
      },
      "items": [
          {
              "title": "Hydra HUB TESTE",
              "quantity": 1,
              "tangible": false,
              "unitPrice": 600,
              "product_image": ""
          }
      ],
      "amount": 600,
      "customer": {
          "name": "Jeferson",
          "email": "bruno@gmail.com",
          "phone": "21321313212",
          "document": {
              "type": "cpf",
              "number": "13138222722"
          }
      },
      "metadata": "{\"provider\":\"Vega Checkout\",\"user_identitication_number\":\"072.761.241-77\",\"user_email\":\"evmgroup.contabilidade@gmail.com\",\"sell_url\":\"https:\\/\\/hydradev.online\",\"order_url\":\"https:\\/\\/pay.hydradev.online\\/order\\/30edrvLZ\",\"referrer_link\":null}",
      "traceable": false,
      "externalRef": "30edrvLZ",
      "postbackUrl": "https://devbackendvenus.cloud/checkout/payment/skallapay/webhook?wl=app.devakta.site"
  }'
  ```
</CodeGroup>

### Status de Transação

| Status    | Descrição                               |
| --------- | --------------------------------------- |
| pending   | Aguardando pagamento                    |
| approved  | Pagamento recebido e confirmado         |
| refused   | Transação recusada (apenas para cartão) |
| cancelled | Transação cancelada                     |
| expired   | Transação expirada                      |
| refunded  | Transação estornada                     |

### Códigos de Resposta

* `201` - Transação criada com sucesso
* `401` - Erro de autenticação
* `400` - Dados inválidos

### Observações

* Para cartão de crédito, é necessário tokenizar o cartão previamente usando o endpoint `/card-token`.
* Para PIX, o QR Code é enviado no formato base64 e pode ser exibido diretamente em uma tag de imagem HTML.
* Utilize o webhook (postbackUrl) para receber notificações automáticas quando o status da transação mudar.