Transações com Cartão

{
  "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": "[email protected]",
    "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"
}

{
  "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": "[email protected]",
      "phone": "11987654321",
      "document": {
        "number": "12345678909",
        "type": "cpf"
      }
    },
    "traceable": false,
    "fees": 164,
    "createdAt": "2025-05-02T15:57:33.751Z"
  }
}

POST

api

transactions

{
  "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": "[email protected]",
    "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"
}

{
  "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": "[email protected]",
      "phone": "11987654321",
      "document": {
        "number": "12345678909",
        "type": "cpf"
      }
    },
    "traceable": false,
    "fees": 164,
    "createdAt": "2025-05-02T15:57:33.751Z"
  }
}

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.

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

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 “credit_card”)

amount

integer

required

Valor total em centavos

installments

string

required

Número de parcelas

card.hash

string

required

Token do cartão gerado previamente

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": "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": "[email protected]",
    "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"
}

Resposta

{
  "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": "[email protected]",
      "phone": "11987654321",
      "document": {
        "number": "12345678909",
        "type": "cpf"
      }
    },
    "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' \
--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": "[email protected]",
        "phone": "22948618616",
        "document": {
            "type": "cpf",
            "number": "69686902414"
        }
    },
  "metadata": "{\"provider\":\"Hydra Checkout\",\"user_email\":\"[email protected]\"}",
  "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.

Tokenização de Cartão Transações PIX

Introdução

Status e Informações

Transações

Sellers

Transações com Cartão

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

Autenticação

Parâmetros da Requisição

Resposta

Exemplo com cURL

Status de Transação

Códigos de Resposta

Importante

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

​Autenticação

​Parâmetros da Requisição

​Resposta

​Exemplo com cURL

​Status de Transação

​Códigos de Resposta

​Importante

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

Autenticação

Parâmetros da Requisição

Resposta

Exemplo com cURL

Status de Transação

Códigos de Resposta

Importante