Referência da API

Transferência interna

Move saldo para qualquer outra conta iHubGames, sem passar por PSP. A liquidação é imediata: os dois lançamentos acontecem na mesma transação de banco, então ou os dois entram ou nenhum entra. Quem recebe não precisa de nada; quem ENVIA precisa do módulo de transferência interna habilitado na conta. Sem ele a rota responde 403. A taxa é cobrada por cima: a origem é debitada em amount + fee e o destino recebe o amount cheio. A taxa vem da configuração da sua conta (transferFee). Origem e destino precisam estar na mesma moeda. Esta rota não converte nada — transferir entre moedas diferentes é recusado com 400. Conversão entre moedas é operação de liquidação, feita pelo nosso time. Escopo: createInternalTransfer, desligado por padrão. Como toda rota que move dinheiro, use junto da allowlist de IPs.

POST/internal-transfers

Repetição da mesma transferência

amount Duas requisições idênticas (mesma origem, destino, valor e taxa) dentro de 10 segundos são tratadas como a MESMA transferência: a segunda devolve o registro da primeira e não move saldo de novo. Isso protege contra retry de rede e duplo POST. Passados os 10 segundos, uma repetição idêntica é uma transferência nova — é uma operação legítima e não deve ser bloqueada.

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

toAccountNumbernumberobrigatório

Número da conta de destino. Qualquer conta ativa da plataforma.

Exemplo: 10062

amountnumberobrigatório

Valor a transferir, em centavos. A taxa é somada por cima.

Exemplo: 150000

descriptionstringopcional

Nota livre, gravada nos dois lançamentos do extrato. Máximo de 140 caracteres.

Exemplo: repasse mensal

Respostas

201

Transferência concluída. O saldo já está disponível no destino.

JSON

{
  "id": "3d9a...",
  "status": "COMPLETED",
  "amount": 150000,
  "fee": 250,
  "total": 150250,
  "currency": "BRL",
  "description": "repasse mensal",
  "completedAt": "2026-09-07T14:22:10.482Z",
  "to": {
    "accountNumber": 10062,
    "name": "MINHA EMPRESA FILIAL",
    "document": "489***30"
  }
}

400

Valor inválido, saldo insuficiente (incluindo a taxa), moedas diferentes ou destino inativo.

JSON

{
  "status": 400,
  "message": "Origem (BRL) e destino (MXN) estão em moedas diferentes."
}

403

Transferência interna não habilitada na conta, ou conta bloqueada para saída de saldo.

JSON

{
  "status": 403,
  "message": "Transferência interna não está habilitada para esta conta."
}

Exemplos

bash

curl -X POST "https://api.ihubplay.com/internal-transfers" \
  -H "Authorization: Basic $(echo -n "secret:$SECRET_KEY" | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "toAccountNumber": 10062,
    "amount": 150000,
    "description": "repasse mensal"
  }'

TypeScript

const secret = process.env.IHUBGAMES_SECRET_KEY!;
const token = Buffer.from(`secret:${secret}`).toString("base64");

const res = await fetch("https://api.ihubplay.com/internal-transfers", {
  method: "POST",
  headers: {
    Authorization: `Basic ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    toAccountNumber: 10062,
    amount: 150_000, // R$ 1.500,00 em centavos
    description: "repasse mensal",
  }),
});

const transfer = await res.json();
// transfer.total = amount + fee, o que saiu da conta de origem