Transações de Pagamento
curl --request POST \
--url https://api.example.com/api/v1/transactions \
--header 'Content-Type: application/json' \
--data '
{
"paymentMethod": "<string>",
"amount": 123,
"customer": {},
"customer.name": "<string>",
"customer.email": "<string>",
"customer.phone": "<string>",
"customer.document.type": "<string>",
"customer.document.number": "<string>",
"externalRef": "<string>",
"postbackUrl": "<string>",
"traceable": true,
"items": [
{}
],
"ip": "<string>",
"metadata": "<string>",
"installments": "<string>",
"card.hash": "<string>",
"pix.expiresInDays": 123
}
'import requests
url = "https://api.example.com/api/v1/transactions"
payload = {
"paymentMethod": "<string>",
"amount": 123,
"customer": {},
"customer.name": "<string>",
"customer.email": "<string>",
"customer.phone": "<string>",
"customer.document.type": "<string>",
"customer.document.number": "<string>",
"externalRef": "<string>",
"postbackUrl": "<string>",
"traceable": True,
"items": [{}],
"ip": "<string>",
"metadata": "<string>",
"installments": "<string>",
"card.hash": "<string>",
"pix.expiresInDays": 123
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
paymentMethod: '<string>',
amount: 123,
customer: {},
'customer.name': '<string>',
'customer.email': '<string>',
'customer.phone': '<string>',
'customer.document.type': '<string>',
'customer.document.number': '<string>',
externalRef: '<string>',
postbackUrl: '<string>',
traceable: true,
items: [{}],
ip: '<string>',
metadata: '<string>',
installments: '<string>',
'card.hash': '<string>',
'pix.expiresInDays': 123
})
};
fetch('https://api.example.com/api/v1/transactions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/transactions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'paymentMethod' => '<string>',
'amount' => 123,
'customer' => [
],
'customer.name' => '<string>',
'customer.email' => '<string>',
'customer.phone' => '<string>',
'customer.document.type' => '<string>',
'customer.document.number' => '<string>',
'externalRef' => '<string>',
'postbackUrl' => '<string>',
'traceable' => true,
'items' => [
[
]
],
'ip' => '<string>',
'metadata' => '<string>',
'installments' => '<string>',
'card.hash' => '<string>',
'pix.expiresInDays' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/transactions"
payload := strings.NewReader("{\n \"paymentMethod\": \"<string>\",\n \"amount\": 123,\n \"customer\": {},\n \"customer.name\": \"<string>\",\n \"customer.email\": \"<string>\",\n \"customer.phone\": \"<string>\",\n \"customer.document.type\": \"<string>\",\n \"customer.document.number\": \"<string>\",\n \"externalRef\": \"<string>\",\n \"postbackUrl\": \"<string>\",\n \"traceable\": true,\n \"items\": [\n {}\n ],\n \"ip\": \"<string>\",\n \"metadata\": \"<string>\",\n \"installments\": \"<string>\",\n \"card.hash\": \"<string>\",\n \"pix.expiresInDays\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/transactions")
.header("Content-Type", "application/json")
.body("{\n \"paymentMethod\": \"<string>\",\n \"amount\": 123,\n \"customer\": {},\n \"customer.name\": \"<string>\",\n \"customer.email\": \"<string>\",\n \"customer.phone\": \"<string>\",\n \"customer.document.type\": \"<string>\",\n \"customer.document.number\": \"<string>\",\n \"externalRef\": \"<string>\",\n \"postbackUrl\": \"<string>\",\n \"traceable\": true,\n \"items\": [\n {}\n ],\n \"ip\": \"<string>\",\n \"metadata\": \"<string>\",\n \"installments\": \"<string>\",\n \"card.hash\": \"<string>\",\n \"pix.expiresInDays\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/transactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"paymentMethod\": \"<string>\",\n \"amount\": 123,\n \"customer\": {},\n \"customer.name\": \"<string>\",\n \"customer.email\": \"<string>\",\n \"customer.phone\": \"<string>\",\n \"customer.document.type\": \"<string>\",\n \"customer.document.number\": \"<string>\",\n \"externalRef\": \"<string>\",\n \"postbackUrl\": \"<string>\",\n \"traceable\": true,\n \"items\": [\n {}\n ],\n \"ip\": \"<string>\",\n \"metadata\": \"<string>\",\n \"installments\": \"<string>\",\n \"card.hash\": \"<string>\",\n \"pix.expiresInDays\": 123\n}"
response = http.request(request)
puts response.read_bodyTransações
Transações de Pagamento
Endpoint unificado para processar transações de pagamento
POST
/
api
/
v1
/
transactions
Transações de Pagamento
curl --request POST \
--url https://api.example.com/api/v1/transactions \
--header 'Content-Type: application/json' \
--data '
{
"paymentMethod": "<string>",
"amount": 123,
"customer": {},
"customer.name": "<string>",
"customer.email": "<string>",
"customer.phone": "<string>",
"customer.document.type": "<string>",
"customer.document.number": "<string>",
"externalRef": "<string>",
"postbackUrl": "<string>",
"traceable": true,
"items": [
{}
],
"ip": "<string>",
"metadata": "<string>",
"installments": "<string>",
"card.hash": "<string>",
"pix.expiresInDays": 123
}
'import requests
url = "https://api.example.com/api/v1/transactions"
payload = {
"paymentMethod": "<string>",
"amount": 123,
"customer": {},
"customer.name": "<string>",
"customer.email": "<string>",
"customer.phone": "<string>",
"customer.document.type": "<string>",
"customer.document.number": "<string>",
"externalRef": "<string>",
"postbackUrl": "<string>",
"traceable": True,
"items": [{}],
"ip": "<string>",
"metadata": "<string>",
"installments": "<string>",
"card.hash": "<string>",
"pix.expiresInDays": 123
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
paymentMethod: '<string>',
amount: 123,
customer: {},
'customer.name': '<string>',
'customer.email': '<string>',
'customer.phone': '<string>',
'customer.document.type': '<string>',
'customer.document.number': '<string>',
externalRef: '<string>',
postbackUrl: '<string>',
traceable: true,
items: [{}],
ip: '<string>',
metadata: '<string>',
installments: '<string>',
'card.hash': '<string>',
'pix.expiresInDays': 123
})
};
fetch('https://api.example.com/api/v1/transactions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/transactions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'paymentMethod' => '<string>',
'amount' => 123,
'customer' => [
],
'customer.name' => '<string>',
'customer.email' => '<string>',
'customer.phone' => '<string>',
'customer.document.type' => '<string>',
'customer.document.number' => '<string>',
'externalRef' => '<string>',
'postbackUrl' => '<string>',
'traceable' => true,
'items' => [
[
]
],
'ip' => '<string>',
'metadata' => '<string>',
'installments' => '<string>',
'card.hash' => '<string>',
'pix.expiresInDays' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/transactions"
payload := strings.NewReader("{\n \"paymentMethod\": \"<string>\",\n \"amount\": 123,\n \"customer\": {},\n \"customer.name\": \"<string>\",\n \"customer.email\": \"<string>\",\n \"customer.phone\": \"<string>\",\n \"customer.document.type\": \"<string>\",\n \"customer.document.number\": \"<string>\",\n \"externalRef\": \"<string>\",\n \"postbackUrl\": \"<string>\",\n \"traceable\": true,\n \"items\": [\n {}\n ],\n \"ip\": \"<string>\",\n \"metadata\": \"<string>\",\n \"installments\": \"<string>\",\n \"card.hash\": \"<string>\",\n \"pix.expiresInDays\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/transactions")
.header("Content-Type", "application/json")
.body("{\n \"paymentMethod\": \"<string>\",\n \"amount\": 123,\n \"customer\": {},\n \"customer.name\": \"<string>\",\n \"customer.email\": \"<string>\",\n \"customer.phone\": \"<string>\",\n \"customer.document.type\": \"<string>\",\n \"customer.document.number\": \"<string>\",\n \"externalRef\": \"<string>\",\n \"postbackUrl\": \"<string>\",\n \"traceable\": true,\n \"items\": [\n {}\n ],\n \"ip\": \"<string>\",\n \"metadata\": \"<string>\",\n \"installments\": \"<string>\",\n \"card.hash\": \"<string>\",\n \"pix.expiresInDays\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/transactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"paymentMethod\": \"<string>\",\n \"amount\": 123,\n \"customer\": {},\n \"customer.name\": \"<string>\",\n \"customer.email\": \"<string>\",\n \"customer.phone\": \"<string>\",\n \"customer.document.type\": \"<string>\",\n \"customer.document.number\": \"<string>\",\n \"externalRef\": \"<string>\",\n \"postbackUrl\": \"<string>\",\n \"traceable\": true,\n \"items\": [\n {}\n ],\n \"ip\": \"<string>\",\n \"metadata\": \"<string>\",\n \"installments\": \"<string>\",\n \"card.hash\": \"<string>\",\n \"pix.expiresInDays\": 123\n}"
response = http.request(request)
puts response.read_bodyTransaçõ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 campopaymentMethod 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
string
required
Método de pagamento (“credit_card” ou “pix”)
integer
required
Valor total em centavos
object
required
Dados do cliente
string
required
Nome completo do cliente
string
required
Email do cliente
string
required
Telefone do cliente
string
required
Tipo do documento (cpf ou cnpj)
string
required
Número do documento
string
required
Referência externa para identificação da transação
string
required
URL para receber notificações de alteração de status
boolean
required
Se a transação é rastreável
array
required
Lista de itens do pedido
string
required
Endereço IP do cliente
string
required
Dados adicionais em formato JSON string
Parâmetros para Cartão de Crédito
string
required
Deve ser “credit_card”
string
required
Número de parcelas
string
required
Token do cartão gerado previamente
Parâmetros para PIX
string
required
Deve ser “pix”
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"
}
{
"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": "[email protected]",
"phone": "21321313212",
"document": {
"type": "cpf",
"number": "13138222722"
}
},
"metadata": "{\"provider\":\"Vega Checkout\",\"user_identitication_number\":\"072.761.241-77\",\"user_email\":\"[email protected]\",\"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"
}
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"
}
}
{
"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": "[email protected]",
"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"
}
}
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"
}'
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": "[email protected]",
"phone": "21321313212",
"document": {
"type": "cpf",
"number": "13138222722"
}
},
"metadata": "{\"provider\":\"Vega Checkout\",\"user_identitication_number\":\"072.761.241-77\",\"user_email\":\"[email protected]\",\"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"
}'
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 sucesso401- Erro de autenticação400- 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.