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

paymentMethod

string

required

Método de pagamento (“credit_card” ou “pix”)

amount

integer

required

Valor total em centavos

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

Parâmetros para Cartão de Crédito

paymentMethod

string

required

Deve ser “credit_card”

installments

string

required

Número de parcelas

card.hash

string

required

Token do cartão gerado previamente

Parâmetros para PIX

paymentMethod

string

required

Deve ser “pix”

pix.expiresInDays

integer

required

Dias para expiração do PIX

Exemplos de Requisiçã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"
}

Exemplos de 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 '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": "[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"
}'

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.

Introdução

Status e Informações

Transações

Sellers

Transações de Pagamento