Três passos até criar uma venda e receber a confirmação no seu servidor.
Cada passo abaixo tem um exemplo pronto para colar no terminal.
No painel, em Integrações, você encontra a chave pública e a chave secreta da sua conta.
A autenticação segue o padrão Basic: a chave pública entra como usuário e a secreta como senha, em base64.
Um POST em /v1/transactions cria a venda. O mesmo endpoint atende Pix, boleto e cartão — muda só o paymentMethod.
A API usa Basic Access Authentication. Use a sua chave de teste enquanto valida a integração, para não movimentar dinheiro de verdade.
// A chave pública é o usuário e a secreta é a senha.
const auth =
'Basic ' + Buffer.from(publicKey + ':' + secretKey).toString('base64');
const response = await fetch('https://api.hylexpay.com/v1/transactions', {
method: 'POST',
headers: {
Authorization: auth,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});curl --request POST \
--url https://api.hylexpay.com/v1/transactions \
--header 'authorization: Basic <base64(publicKey:secretKey)>' \
--header 'content-type: application/json'Repare no amount: o valor vai sempre em centavos. 750 é R$ 7,50.
{
"amount": 750,
"paymentMethod": "pix",
"postbackUrl": "https://sua-api.com/postback",
"externalRef": "pedido-abc123",
"items": [
{
"title": "Assinatura Pro",
"quantity": 1,
"unitPrice": 750,
"tangible": false
}
],
"customer": {
"name": "Carlos Exemplar",
"email": "[email protected]",
"phone": "11987654321",
"document": { "type": "cpf", "number": "00011122233" }
}
}Não há webhook para cadastrar: você informa a postbackUrl no corpo de cada transação e recebe ali toda mudança de status dela.
{
"type": "transaction",
"objectId": "123456",
"url": "https://sua-api.com/postback",
"data": {
"id": 123456,
"amount": 750,
"paymentMethod": "pix",
"status": "waiting_payment",
"externalRef": "pedido-abc123",
"pix": {
"qrcode": "00020101021226870014br.gov.bcb.pix...",
"expirationDate": "2026-04-30"
}
}
}waiting_paymentpendingapprovedpaidrefusedin_protestrefundedcancelledchargebackTrês detalhes que evitam a maior parte dos problemas de integração.
amount e unitPrice são inteiros em centavos. Enviar 7.5 em vez de 750 é o erro mais comum de quem está começando.
Uma transação não vai direto de criada para paga. Cubra também refused, cancelled e chargeback no seu fluxo.
O rateio entre recebedores e a autenticação 3DS são configurados na própria criação da venda.
Ver na documentação