Introdução

Quickstart

A API da NGPAYX recebe Pix, transfere entre contas, envia Pix para qualquer chave e saca em USDT, tudo numa integração só. Este guia leva você do zero ao primeiro Pix em 3 passos.

1
Crie a conta e gere a chave#
No painel, vá em Chaves de Acesso e gere uma chave. Você recebe o Client ID e o Client Secret. O secret aparece uma vez só, então guarde em lugar seguro.

Segurança
O Client Secret nunca deve aparecer no front-end (navegador ou app). Use só no seu servidor e, se puder, restrinja a chave por IP.
2
Crie a primeira cobrança#
Gere um Pix de R$ 10,00 com POST /charges. A resposta traz o QR Code, o copia e cola e o clientTransactionId.
3
Configure o webhook#
No painel, cadastre a URL do seu sistema em Webhooks. A NGPAYX avisa assim que o Pix cai, com a entrega assinada por HMAC e reenvio automático se falhar.
Ver a referência de webhooks

POST /charges

curl -X POST https://ngpayx.com.br/api/v1/charges \
  -H "ci: SEU_CLIENT_ID" \
  -H "cs: SEU_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10, "description": "Meu primeiro Pix"}'

const res = await fetch("https://ngpayx.com.br/api/v1/charges", {
  method: "POST",
  headers: {
    ci: process.env.NGPAYX_CLIENT_ID,
    cs: process.env.NGPAYX_CLIENT_SECRET,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "amount": 10,
    "description": "Meu primeiro Pix"
  })
});
const data = await res.json();

import os, requests

headers = {
    "ci": os.environ["NGPAYX_CLIENT_ID"],
    "cs": os.environ["NGPAYX_CLIENT_SECRET"],
}
res = requests.post("https://ngpayx.com.br/api/v1/charges", headers=headers, json={
    "amount": 10,
    "description": "Meu primeiro Pix"
})
data = res.json()

<?php
$ch = curl_init("https://ngpayx.com.br/api/v1/charges");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "ci: " . getenv("NGPAYX_CLIENT_ID"),
    "cs: " . getenv("NGPAYX_CLIENT_SECRET"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode(["amount" => 10, "description" => "Meu primeiro Pix"]),
]);
$data = json_decode(curl_exec($ch), true);

Conceitos

URL base#

Todas as chamadas vão para um único host. Requisições e respostas usam application/json.

AmbienteURL

API (REST)https://ngpayx.com.br/api/v1

Painelhttps://SEU-DOMINIO/painel.html

Documentaçãohttps://SEU-DOMINIO/docs.html

Sandbox#

Teste a integração inteira com uma chave de sandbox própria, sem tocar a produção e sem gastar nada. O volume do sandbox não entra nas premiações nem no volume processado.

Mesma URL, chave diferente

O endereço da API é o mesmo; o que muda é a chave usada. Quando estiver tudo certo, troque para a chave de produção.

Valores e status#

Os valores são enviados em reais: "amount": 50 é uma cobrança de R$ 50,00. Todas as rotas são escopadas à sua conta, então você só acessa os seus próprios dados.

Depois de gerar o QR Code, a cobrança muda para COMPLETO quando o Pix é confirmado. Para saber disso na hora, use o webhook em vez de consultar em loop.

Autenticação

Chave de acesso#

Use uma chave de acesso (Client ID + Client Secret) gerada em Chaves de Acesso. Dá para ter várias, cada uma com os seus escopos. Há duas formas de enviar:

Recomendado

Headers ci / cs

Envie o Client ID e o Client Secret em dois headers.

Bearer

Envie só o Client Secret no header Authorization.

Escopos#

Cada chave carrega escopos (cobrança, consulta, saque, MEDs…). Uma chamada fora do escopo da chave responde 403, por exemplo um saque com uma chave sem withdrawals:pix.

Escopos não mudam depois

Para ampliar, crie outra chave com os escopos certos e revogue a antiga. O recomendado é uma chave com o mínimo necessário para cada integração.

Allowlist de IP#

Opcional, mas recomendado para a chave de produção: em Chaves de Acesso, restrinja de quais IPs a chave pode chamar a API. Chamadas de IPs fora da lista respondem 401.

Referência da API

Cobranças#

Gere e consulte cobranças Pix (QR Code + copia e cola).

POST/chargesCriar cobrança Pix GET/chargesListar cobranças GET/charges/:clientTransactionIdConsultar cobrança

POST/charges

Criar cobrança Pix#

Gera uma cobrança Pix com QR Code e copia e cola. Só o valor é obrigatório.

A resposta traz o clientTransactionId, que você usa para consultar a cobrança depois. Para saber quando o Pix cai, configure um webhook.

AuthChave de acesso (ci / cs ou Bearer)

Body

amountnumberobrigatório

Valor da cobrança em reais.

Ex.: 50

descriptionstringopcional

Descrição da cobrança.

Ex.: "Pedido #123"

Respostas

2xxCobrança criada, com QR Code, copia e cola e clientTransactionId.
400Dados inválidos, por exemplo amount faltando.
401Chave ausente ou inválida, ou IP fora da allowlist.
403A chave não tem o escopo dessa rota.

POST /charges

curl -X POST https://ngpayx.com.br/api/v1/charges \
  -H "ci: SEU_CLIENT_ID" \
  -H "cs: SEU_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50, "description": "Pedido #123"}'

const res = await fetch("https://ngpayx.com.br/api/v1/charges", {
  method: "POST",
  headers: {
    ci: process.env.NGPAYX_CLIENT_ID,
    cs: process.env.NGPAYX_CLIENT_SECRET,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "amount": 50,
    "description": "Pedido #123"
  })
});
const data = await res.json();

import os, requests

headers = {
    "ci": os.environ["NGPAYX_CLIENT_ID"],
    "cs": os.environ["NGPAYX_CLIENT_SECRET"],
}
res = requests.post("https://ngpayx.com.br/api/v1/charges", headers=headers, json={
    "amount": 50,
    "description": "Pedido #123"
})
data = res.json()

<?php
$ch = curl_init("https://ngpayx.com.br/api/v1/charges");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "ci: " . getenv("NGPAYX_CLIENT_ID"),
    "cs: " . getenv("NGPAYX_CLIENT_SECRET"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode(["amount" => 50, "description" => "Pedido #123"]),
]);
$data = json_decode(curl_exec($ch), true);

GET/charges

Listar cobranças#

Lista as suas cobranças, das mais recentes para as mais antigas.

AuthChave de acesso (ci / cs ou Bearer)

Respostas

2xxLista de cobranças da sua conta.
401Chave ausente ou inválida, ou IP fora da allowlist.
403A chave não tem o escopo dessa rota.

GET /charges

curl https://ngpayx.com.br/api/v1/charges \
  -H "ci: SEU_CLIENT_ID" \
  -H "cs: SEU_CLIENT_SECRET"

const res = await fetch("https://ngpayx.com.br/api/v1/charges", {
  headers: {
    ci: process.env.NGPAYX_CLIENT_ID,
    cs: process.env.NGPAYX_CLIENT_SECRET
  }
});
const data = await res.json();

import os, requests

headers = {
    "ci": os.environ["NGPAYX_CLIENT_ID"],
    "cs": os.environ["NGPAYX_CLIENT_SECRET"],
}
res = requests.get("https://ngpayx.com.br/api/v1/charges", headers=headers)
data = res.json()

<?php
$ch = curl_init("https://ngpayx.com.br/api/v1/charges");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "ci: " . getenv("NGPAYX_CLIENT_ID"),
    "cs: " . getenv("NGPAYX_CLIENT_SECRET"),
  ],
]);
$data = json_decode(curl_exec($ch), true);

GET/charges/:clientTransactionId

Consultar cobrança#

Consulta uma cobrança pelo clientTransactionId devolvido em POST /charges.

Use para checar se o status virou COMPLETO depois de gerar o QR Code. Para acompanhar em tempo real, prefira o webhook em vez de consultar em loop.

AuthChave de acesso (ci / cs ou Bearer)

Parâmetros de caminho

clientTransactionIdstringobrigatório

ID devolvido na criação da cobrança.

Ex.: "chg_abc123"

Respostas

2xxDados da cobrança.
404O ID não existe ou não é da sua conta.
401Chave ausente ou inválida, ou IP fora da allowlist.

GET /charges/:clientTransactionId

curl https://ngpayx.com.br/api/v1/charges/chg_abc123 \
  -H "ci: SEU_CLIENT_ID" \
  -H "cs: SEU_CLIENT_SECRET"

const res = await fetch("https://ngpayx.com.br/api/v1/charges/chg_abc123", {
  headers: {
    ci: process.env.NGPAYX_CLIENT_ID,
    cs: process.env.NGPAYX_CLIENT_SECRET
  }
});
const data = await res.json();

import os, requests

headers = {
    "ci": os.environ["NGPAYX_CLIENT_ID"],
    "cs": os.environ["NGPAYX_CLIENT_SECRET"],
}
res = requests.get("https://ngpayx.com.br/api/v1/charges/chg_abc123", headers=headers)
data = res.json()

<?php
$ch = curl_init("https://ngpayx.com.br/api/v1/charges/chg_abc123");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "ci: " . getenv("NGPAYX_CLIENT_ID"),
    "cs: " . getenv("NGPAYX_CLIENT_SECRET"),
  ],
]);
$data = json_decode(curl_exec($ch), true);

Referência da API

Transferências e saques#

Saldo, transferência entre contas, Pix para qualquer chave e saque em USDT.

GET/transfers/balanceConsultar saldo POST/transfers/internalTransferência interna POST/transfers/externalPix para qualquer chave POST/transfers/cryptoSaque em USDT GET/transfersExtrato de transferências

GET/transfers/balance

Consultar saldo#

Saldo disponível na sua conta NGPAYX.

AuthChave de acesso (ci / cs ou Bearer)

Respostas

2xxSaldo disponível.
401Chave ausente ou inválida, ou IP fora da allowlist.

GET /transfers/balance

curl https://ngpayx.com.br/api/v1/transfers/balance \
  -H "ci: SEU_CLIENT_ID" \
  -H "cs: SEU_CLIENT_SECRET"

const res = await fetch("https://ngpayx.com.br/api/v1/transfers/balance", {
  headers: {
    ci: process.env.NGPAYX_CLIENT_ID,
    cs: process.env.NGPAYX_CLIENT_SECRET
  }
});
const data = await res.json();

import os, requests

headers = {
    "ci": os.environ["NGPAYX_CLIENT_ID"],
    "cs": os.environ["NGPAYX_CLIENT_SECRET"],
}
res = requests.get("https://ngpayx.com.br/api/v1/transfers/balance", headers=headers)
data = res.json()

<?php
$ch = curl_init("https://ngpayx.com.br/api/v1/transfers/balance");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "ci: " . getenv("NGPAYX_CLIENT_ID"),
    "cs: " . getenv("NGPAYX_CLIENT_SECRET"),
  ],
]);
$data = json_decode(curl_exec($ch), true);

POST/transfers/internal

Transferência interna#

Transferência instantânea e sem tarifa para outra conta NGPAYX, pelo e-mail.

AuthChave de acesso (ci / cs ou Bearer)

Body

emailstringobrigatório

E-mail da conta NGPAYX de destino.

Ex.: "outra@conta.com"

amountnumberobrigatório

Valor em reais.

Ex.: 30

descriptionstringopcional

Descrição da transferência.

Respostas

2xxTransferência concluída.
400Regra de negócio, por exemplo saldo insuficiente.
401Chave ausente ou inválida, ou IP fora da allowlist.
403A chave não tem o escopo dessa rota.

POST /transfers/internal

curl -X POST https://ngpayx.com.br/api/v1/transfers/internal \
  -H "ci: SEU_CLIENT_ID" \
  -H "cs: SEU_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email": "outra@conta.com", "amount": 30}'

const res = await fetch("https://ngpayx.com.br/api/v1/transfers/internal", {
  method: "POST",
  headers: {
    ci: process.env.NGPAYX_CLIENT_ID,
    cs: process.env.NGPAYX_CLIENT_SECRET,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "email": "outra@conta.com",
    "amount": 30
  })
});
const data = await res.json();

import os, requests

headers = {
    "ci": os.environ["NGPAYX_CLIENT_ID"],
    "cs": os.environ["NGPAYX_CLIENT_SECRET"],
}
res = requests.post("https://ngpayx.com.br/api/v1/transfers/internal", headers=headers, json={
    "email": "outra@conta.com",
    "amount": 30
})
data = res.json()

<?php
$ch = curl_init("https://ngpayx.com.br/api/v1/transfers/internal");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "ci: " . getenv("NGPAYX_CLIENT_ID"),
    "cs: " . getenv("NGPAYX_CLIENT_SECRET"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode(["email" => "outra@conta.com", "amount" => 30]),
]);
$data = json_decode(curl_exec($ch), true);

POST/transfers/external

Pix para qualquer chave#

Transferência via Pix para qualquer chave. Cobra a tarifa fixa de saque.

AuthChave de acesso (ci / cs ou Bearer)

Escopowithdrawals:pix

Body

amountnumberobrigatório

Valor em reais.

Ex.: 30

pixKeystringobrigatório

Chave Pix de destino.

Ex.: "email@exemplo.com"

pixKeyTypestringobrigatório

Tipo da chave: CPF, CNPJ, EMAIL, TELEFONE ou CHAVE_ALEATORIA.

Ex.: "EMAIL"

descriptionstringopcional

Descrição da transferência.

Respostas

2xxTransferência enviada.
400Saldo insuficiente, valor fora da faixa ou chave Pix inválida.
401Chave ausente ou inválida, ou IP fora da allowlist.
403A chave não tem o escopo withdrawals:pix.
503Provedor Pix em manutenção (code = PROVIDER_MAINTENANCE).

POST /transfers/external

curl -X POST https://ngpayx.com.br/api/v1/transfers/external \
  -H "ci: SEU_CLIENT_ID" \
  -H "cs: SEU_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"amount": 30, "pixKey": "email@exemplo.com", "pixKeyType": "EMAIL"}'

const res = await fetch("https://ngpayx.com.br/api/v1/transfers/external", {
  method: "POST",
  headers: {
    ci: process.env.NGPAYX_CLIENT_ID,
    cs: process.env.NGPAYX_CLIENT_SECRET,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "amount": 30,
    "pixKey": "email@exemplo.com",
    "pixKeyType": "EMAIL"
  })
});
const data = await res.json();

import os, requests

headers = {
    "ci": os.environ["NGPAYX_CLIENT_ID"],
    "cs": os.environ["NGPAYX_CLIENT_SECRET"],
}
res = requests.post("https://ngpayx.com.br/api/v1/transfers/external", headers=headers, json={
    "amount": 30,
    "pixKey": "email@exemplo.com",
    "pixKeyType": "EMAIL"
})
data = res.json()

<?php
$ch = curl_init("https://ngpayx.com.br/api/v1/transfers/external");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "ci: " . getenv("NGPAYX_CLIENT_ID"),
    "cs: " . getenv("NGPAYX_CLIENT_SECRET"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode(["amount" => 30, "pixKey" => "email@exemplo.com", "pixKeyType" => "EMAIL"]),
]);
$data = json_decode(curl_exec($ch), true);

POST/transfers/crypto

Saque em USDT#

Saque em USDT na rede BEP20. Valor entre R$ 20 e R$ 3.000.

AuthChave de acesso (ci / cs ou Bearer)

Body

amountnumberobrigatório

Valor em reais, entre 20 e 3000.

Ex.: 50

walletstringobrigatório

Endereço da carteira BEP20 de destino.

Ex.: "0x..."

descriptionstringopcional

Descrição do saque.

Respostas

2xxSaque enviado.
400Valor fora da faixa ou saldo insuficiente.
401Chave ausente ou inválida, ou IP fora da allowlist.
403A chave não tem o escopo dessa rota.

POST /transfers/crypto

curl -X POST https://ngpayx.com.br/api/v1/transfers/crypto \
  -H "ci: SEU_CLIENT_ID" \
  -H "cs: SEU_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50, "wallet": "0x..."}'

const res = await fetch("https://ngpayx.com.br/api/v1/transfers/crypto", {
  method: "POST",
  headers: {
    ci: process.env.NGPAYX_CLIENT_ID,
    cs: process.env.NGPAYX_CLIENT_SECRET,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "amount": 50,
    "wallet": "0x..."
  })
});
const data = await res.json();

import os, requests

headers = {
    "ci": os.environ["NGPAYX_CLIENT_ID"],
    "cs": os.environ["NGPAYX_CLIENT_SECRET"],
}
res = requests.post("https://ngpayx.com.br/api/v1/transfers/crypto", headers=headers, json={
    "amount": 50,
    "wallet": "0x..."
})
data = res.json()

<?php
$ch = curl_init("https://ngpayx.com.br/api/v1/transfers/crypto");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "ci: " . getenv("NGPAYX_CLIENT_ID"),
    "cs: " . getenv("NGPAYX_CLIENT_SECRET"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode(["amount" => 50, "wallet" => "0x..."]),
]);
$data = json_decode(curl_exec($ch), true);

GET/transfers

Extrato de transferências#

Extrato unificado: transferências internas, Pix externo e cripto.

AuthChave de acesso (ci / cs ou Bearer)

Respostas

2xxLista de movimentações.
401Chave ausente ou inválida, ou IP fora da allowlist.

GET /transfers

curl https://ngpayx.com.br/api/v1/transfers \
  -H "ci: SEU_CLIENT_ID" \
  -H "cs: SEU_CLIENT_SECRET"

const res = await fetch("https://ngpayx.com.br/api/v1/transfers", {
  headers: {
    ci: process.env.NGPAYX_CLIENT_ID,
    cs: process.env.NGPAYX_CLIENT_SECRET
  }
});
const data = await res.json();

import os, requests

headers = {
    "ci": os.environ["NGPAYX_CLIENT_ID"],
    "cs": os.environ["NGPAYX_CLIENT_SECRET"],
}
res = requests.get("https://ngpayx.com.br/api/v1/transfers", headers=headers)
data = res.json()

<?php
$ch = curl_init("https://ngpayx.com.br/api/v1/transfers");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "ci: " . getenv("NGPAYX_CLIENT_ID"),
    "cs: " . getenv("NGPAYX_CLIENT_SECRET"),
  ],
]);
$data = json_decode(curl_exec($ch), true);

Referência da API

Conta#

Taxas atuais e infrações (MED) da sua conta.

GET/feesTabela de taxas GET/infractionsInfrações (MED)

GET/fees

Tabela de taxas#

Tabela de taxas atual da gateway.

AuthChave de acesso (ci / cs ou Bearer)

Respostas

2xxTaxas vigentes.
401Chave ausente ou inválida, ou IP fora da allowlist.

GET /fees

curl https://ngpayx.com.br/api/v1/fees \
  -H "ci: SEU_CLIENT_ID" \
  -H "cs: SEU_CLIENT_SECRET"

const res = await fetch("https://ngpayx.com.br/api/v1/fees", {
  headers: {
    ci: process.env.NGPAYX_CLIENT_ID,
    cs: process.env.NGPAYX_CLIENT_SECRET
  }
});
const data = await res.json();

import os, requests

headers = {
    "ci": os.environ["NGPAYX_CLIENT_ID"],
    "cs": os.environ["NGPAYX_CLIENT_SECRET"],
}
res = requests.get("https://ngpayx.com.br/api/v1/fees", headers=headers)
data = res.json()

<?php
$ch = curl_init("https://ngpayx.com.br/api/v1/fees");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "ci: " . getenv("NGPAYX_CLIENT_ID"),
    "cs: " . getenv("NGPAYX_CLIENT_SECRET"),
  ],
]);
$data = json_decode(curl_exec($ch), true);

GET/infractions

Infrações (MED)#

Infrações (MED) registradas nas suas transações.

AuthChave de acesso (ci / cs ou Bearer)

Respostas

2xxLista de infrações.
401Chave ausente ou inválida, ou IP fora da allowlist.
403A chave não tem o escopo dessa rota.

GET /infractions

curl https://ngpayx.com.br/api/v1/infractions \
  -H "ci: SEU_CLIENT_ID" \
  -H "cs: SEU_CLIENT_SECRET"

const res = await fetch("https://ngpayx.com.br/api/v1/infractions", {
  headers: {
    ci: process.env.NGPAYX_CLIENT_ID,
    cs: process.env.NGPAYX_CLIENT_SECRET
  }
});
const data = await res.json();

import os, requests

headers = {
    "ci": os.environ["NGPAYX_CLIENT_ID"],
    "cs": os.environ["NGPAYX_CLIENT_SECRET"],
}
res = requests.get("https://ngpayx.com.br/api/v1/infractions", headers=headers)
data = res.json()

<?php
$ch = curl_init("https://ngpayx.com.br/api/v1/infractions");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "ci: " . getenv("NGPAYX_CLIENT_ID"),
    "cs: " . getenv("NGPAYX_CLIENT_SECRET"),
  ],
]);
$data = json_decode(curl_exec($ch), true);

Webhooks

Configurar#

A NGPAYX chama a sua URL com POST sempre que um depósito ou uma retirada confirma, falha ou é cancelado. É a forma recomendada de acompanhar as cobranças, sem atraso de polling.

No painel, abra Webhooks.
Cadastre a URL HTTPS do seu sistema.
Salve. Para desativar, deixe a URL em branco.

Reenvio automático

Se a entrega falhar, a NGPAYX tenta de novo sozinha, com intervalos crescentes, até 5 vezes. O histórico de entregas fica no painel. Por isso o seu sistema deve aceitar a mesma notificação mais de uma vez sem duplicar nada.

Payload#

Exemplo de uma notificação de depósito Pix confirmado, no mesmo formato mostrado no painel.

CampoO que é

eventTipo do evento, por exemplo deposito.completo.

transactionIdID da transação na NGPAYX.

clientTransactionIdO mesmo ID devolvido em POST /charges. Use para achar o pedido no seu sistema.

amountValor em reais.

statusSituação da transação, por exemplo COMPLETO.

typeDEPOSITO ou RETIRADA.

methodMeio de pagamento, por exemplo PIX.

createdAtData e hora da transação (ISO 8601).

json

POST · SUA URL DE WEBHOOK

{
  "event": "deposito.completo",
  "transactionId": "cktxid...",
  "clientTransactionId": "dep_...",
  "amount": 50,
  "status": "COMPLETO",
  "type": "DEPOSITO",
  "method": "PIX",
  "createdAt": "2026-07-23T12:00:00.000Z"
}

Boas práticas#

Confirme antes de liberar: consulte a cobrança com GET /charges/:clientTransactionId e só entregue o produto se o status for COMPLETO. Assim ninguém consegue forjar uma notificação.
Responda 2xx rápido e processe o pedido depois, numa fila ou tarefa em segundo plano.
Trate repetições: use o clientTransactionId para não entregar o mesmo pedido duas vezes.
Use HTTPS público no endereço do webhook.

Referência

Erros#

Toda resposta de erro vem no formato { "error": "mensagem" }. O status HTTP diz a categoria.

400

Dados inválidos

O body não bate com o esperado: campo faltando, tipo errado etc. details traz o campo.

400

Regra de negócio

Formato certo, mas a operação não pode acontecer agora: saldo insuficiente, valor fora da faixa, chave Pix inválida. Chamadas com chave de acesso não exigem o 2FA do painel.

401

Não autenticado

Chave de acesso ausente ou inválida, ou IP não liberado na allowlist.

403

Sem permissão

Chave autenticada, mas sem o escopo da rota (ex.: saque sem withdrawals:pix).

404

Não encontrado

O recurso não existe ou não pertence à sua conta.

409

Conflito

Registro duplicado, como e-mail já cadastrado em outra conta.

429

Muitas requisições

Rate limit: espere alguns minutos antes de tentar de novo.

500

Erro interno

Erro inesperado do nosso lado. Guarde o horário e fale com o suporte.

502

Falha no provedor Pix

O provedor recusou ou falhou na chamada. Normalmente passageiro.

503

Manutenção no provedor

Saques e transferências em manutenção temporária. O campo code = PROVIDER_MAINTENANCE identifica o caso.

json

EXEMPLOS DE ERRO

{
  "error": "Dados inválidos",
  "details": { "fieldErrors": { "amount": ["Required"] } }
}

{ "error": "Saldo insuficiente (disponível: R$ 10.00, necessário: R$ 50.00 incluindo taxa de R$ 1.00)" }

{ "error": "Esta chave de acesso não tem permissão: withdrawals:pix" }

{ "error": "Saques em manutenção temporária no provedor. Tente novamente em alguns minutos.", "code": "PROVIDER_MAINTENANCE" }

Precisa de ajuda com a integração?

Crie sua conta e abra um ticket pelo painel. A conversa fica registrada do início ao fim.

Criar conta

Quickstart

Crie a conta e gere a chave#

Crie a primeira cobrança#

Configure o webhook#

URL base#

Sandbox#

Valores e status#

Chave de acesso#

Headers ci / cs

Bearer

Escopos#

Allowlist de IP#

Cobranças#

Criar cobrança Pix#

Body

Respostas

Listar cobranças#

Respostas

Consultar cobrança#

Parâmetros de caminho

Respostas

Transferências e saques#

Consultar saldo#

Respostas

Transferência interna#

Body

Respostas

Pix para qualquer chave#

Body

Respostas

Saque em USDT#

Body

Respostas

Extrato de transferências#

Respostas

Conta#

Tabela de taxas#

Respostas

Infrações (MED)#

Respostas

Configurar#

Payload#

Boas práticas#

Erros#

Dados inválidos

Regra de negócio

Não autenticado

Sem permissão

Não encontrado

Conflito

Muitas requisições

Erro interno

Falha no provedor Pix

Manutenção no provedor

Precisa de ajuda com a integração?