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
Método de pagamento (“credit_card” ou “pix”)
Valor total em centavos
Dados do cliente
Nome completo do cliente
Email do cliente
Telefone do cliente
Tipo do documento (cpf ou cnpj)
Número do documento
Referência externa para identificação da transação
URL para receber notificações de alteração de status
Se a transação é rastreável
Lista de itens do pedido
Endereço IP do cliente
Dados adicionais em formato JSON string
Parâmetros para Cartão de Crédito
Deve ser “credit_card”
Número de parcelas
Token do cartão gerado previamente
Parâmetros para PIX
Deve ser “pix”
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.
⌘I
