> ## 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 com Cartão

> Endpoint para criar transações com cartão de crédito

## Transações com Cartão de Crédito

Este endpoint permite processar pagamentos com cartão de crédito utilizando um token previamente gerado. É possível configurar diversos parâmetros como parcelamento, dados do cliente e informações sobre os produtos.

<Note>
  Atualmente, o HYDRA HUB suporta apenas transações com cartão de crédito. Não oferecemos suporte a Cartão de Débito.
</Note>

### 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 "credit\_card")
</ParamField>

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

<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": "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"
  }
  ```
</RequestExample>

### Resposta

<ResponseExample>
  ```json
  {
    "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"
    }
  }
  ```
</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' \
--header 'Authorization: Basic c2tfQnoyU2UxQURnMUFzT3NqVnF0dVRER3NwV1lPR3QtOEl4Y0RuLWt5UzRXbDlCVHdwOnBrX29LSmthWU1RZUR3SUh3VjM3TENqUk==' \
--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"
        }
    },
  "metadata": "{\"provider\":\"Hydra Checkout\",\"user_email\":\"joao@email.com\"}",
  "postbackUrl": "https://seusite.com.br/webhook",
    "traceable": false,
    "card": {
    "hash": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZWxsZXIiOjEsImNhcmQiOnsib...kZCI6dHJ1ZX0sImlhdCI6MTY4NTM4MjAwMSwiZXhwIjoxNjg1MzgyMzAxfQ.aBcDeFgHiJkLmNoPqRsTuVwXyZ"
    },
    "installments": "1"
}'
```

### Status de Transação

| Status      | Descrição                  |
| ----------- | -------------------------- |
| approved    | Transação aprovada         |
| refused     | Transação recusada         |
| pending     | Transação pendente         |
| processing  | Transação em processamento |
| cancelled   | Transação cancelada        |
| refunded    | Transação estornada        |
| chargedback | Transação com chargeback   |

### Códigos de Resposta

* `201` - Transação criada (verifique o status no retorno)
* `401` - Erro de autenticação
* `400` - Dados inválidos

### Importante

A aprovação da transação depende de diversos fatores, incluindo limite disponível, dados corretos e regras antifraude. Sempre verifique o campo `status` na resposta para confirmar o estado da transação.