iHubGamesiHubGamesdocs

Referência da API

Criar transação (ARS)

Cria uma transação de entrada em ARS (pesos argentinos) por transferência bancária. Mesmo endpoint do PIX — POST /transactions/v2/purchase — mudando currency para "ARS". A instrução de pagamento NÃO vem nesta resposta: o cvu chega alguns segundos depois, buscado por GET /transactions/:id. Conceitos e o fluxo completo em Argentina (ARS).

POST/transactions/v2/purchase
O CVU chega depois — faça polling
cvu Diferente de BRL e MXN, a resposta da criação vem com cvu VAZIO. O identificador é negociado com a rede argentina e fica pronto em alguns segundos. Busque em GET /transactions/:id até cvu vir preenchido — a mesma resposta traz paymentInstruction com o beneficiário. Não trate o cvu vazio como erro.

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

namestringobrigatório

Nome completo do pagador (máximo 255 caracteres).

Exemplo: Juan Pérez

emailstringobrigatório

E-mail válido do pagador. Usado para comprovantes e notificações ao cliente.

Exemplo: juan@ejemplo.com

amountnumberobrigatório

Valor em centavos de peso argentino. AR$ 2.000,00 = 200000. A rede aceita de AR$ 2.000 a AR$ 1.000.000 por transação — fora dessa faixa a cobrança é recusada na criação.

Exemplo: 200000

descriptionstringobrigatório

Descrição curta da transação que aparece no comprovante do pagador.

Exemplo: Suscripción Pro

responsibleDocumentstringobrigatório

CPF ou CNPJ da parte legal do seu negócio responsável por essa cobrança.

Exemplo: 12345678901

responsibleExternalIdstringobrigatório

ID interno do responsável no seu sistema (ex: ID do vendedor, ID da conta).

Exemplo: user-1234

currency'ARS'obrigatório

Código da moeda. Para Argentina use "ARS". O amount continua em CENTAVOS (200000 = AR$ 2.000,00). Omitir currency cai no padrão BRL (PIX).

Exemplo: ARS

paymentMethod'BANK_TRANSFER'opcional

Opcional para currency: ARS — default BANK_TRANSFER. (No BRL, PIX é obrigatório.)

Exemplo: BANK_TRANSFER

cpfstringopcional

Não obrigatório em ARS — é um documento brasileiro. Envie só name/email.

phonestringopcional

Telefone do pagador. Opcional para currency: ARS.

externalIdstringopcional

Sua referência para essa transação. Retornada em GET /transactions/:id?searchBy=externalId e em todo webhook vinculado a essa transação.

Exemplo: pedido-5678

postbackUrlstringopcional

URL de webhook para eventos dessa transação. Se omitido, usa a URL global do dashboard.

Exemplo: https://seu-dominio.com/webhook

Body da requisição

Content-Type: application/json

JSON
{
  "name": "Juan Pérez",
  "email": "juan@ejemplo.com",
  "amount": 200000,
  "currency": "ARS",
  "description": "Suscripción Pro",
  "responsibleDocument": "12345678901",
  "responsibleExternalId": "user-1234",
  "externalId": "pedido-5678",
  "postbackUrl": "https://seu-dominio.com/webhook"
}

Respostas

201

Cobrança criada. cvu vem vazio — é o esperado: a instrução é negociada com a rede argentina e chega em alguns segundos. Busque em GET /transactions/:id até vir preenchida. expiresAt é nulo (transferência não tem prazo). status fica PENDING até o dinheiro cair (webhook cashin.paid).

JSON
{
  "id": "17864385245624641191295936",
  "currency": "ARS",
  "method": "BANK_TRANSFER",
  "installments": null,
  "externalId": "pedido-5678",
  "status": "PENDING",
  "amount": 200000,
  "postbackUrl": "https://seu-dominio.com/webhook",
  "referrerUrl": null,
  "cvu": null,
  "expiresAt": null,
  "createdAt": "2026-08-27T08:55:24.748Z",
  "costFee": 6000
}
400

Erro de validação — inclui valor fora da faixa aceita pela rede (AR$ 2.000 a AR$ 1.000.000).

JSON
{
  "statusCode": 400,
  "message": "The 'email' field must be a valid email address.",
  "error": "Bad Request"
}
401

API key inválida ou ausente.

JSON
{ "statusCode": 401, "message": "Unauthorized" }
403

API key sem a permissão createTransaction.

JSON
{
  "statusCode": 403,
  "message": "You do not have permission to access this resource"
}

Exemplos

cURL
curl -X POST "https://api.ihubplay.com/transactions/v2/purchase" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Pérez",
    "email": "juan@ejemplo.com",
    "amount": 200000,
    "currency": "ARS",
    "description": "Suscripción Pro",
    "responsibleDocument": "12345678901",
    "responsibleExternalId": "user-1234",
    "externalId": "pedido-5678",
    "postbackUrl": "https://seu-dominio.com/webhook"
  }'
JavaScript
const token = Buffer.from("secret:" + process.env.IHUBGAMES_SECRET_KEY).toString("base64");

const headers = {
  Authorization: `Basic ${token}`,
  "Content-Type": "application/json",
};

const res = await fetch("https://api.ihubplay.com/transactions/v2/purchase", {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Juan Pérez",
    email: "juan@ejemplo.com",
    amount: 200000,
    currency: "ARS",
    description: "Suscripción Pro",
    responsibleDocument: "12345678901",
    responsibleExternalId: "user-1234",
    externalId: "pedido-5678",
    postbackUrl: "https://seu-dominio.com/webhook",
  }),
});

if (!res.ok) throw new Error(await res.text());
const tx = await res.json();

// O CVU nao vem na criacao: a rede argentina leva alguns segundos pra
// devolver. Busque ate aparecer, e so entao mostre a tela de pagamento.
async function esperarInstrucao(id, tentativas = 15) {
  for (let i = 0; i < tentativas; i++) {
    const r = await fetch(`https://api.ihubplay.com/transactions/${id}`, { headers });
    const t = await r.json();
    if (t.cvu) return t;
    await new Promise((ok) => setTimeout(ok, 2000));
  }
  throw new Error("Instrucao de pagamento nao chegou a tempo");
}

const pronto = await esperarInstrucao(tx.id);
console.log("CVU:", pronto.cvu);
console.log("Beneficiario:", pronto.paymentInstruction?.beneficiary);
Python
import base64, os, time, requests

token = base64.b64encode(
    f"secret:{os.environ['IHUBGAMES_SECRET_KEY']}".encode()
).decode()
headers = {"Authorization": f"Basic {token}", "Content-Type": "application/json"}

res = requests.post(
    "https://api.ihubplay.com/transactions/v2/purchase",
    headers=headers,
    json={
        "name": "Juan Pérez",
        "email": "juan@ejemplo.com",
        "amount": 200000,
        "currency": "ARS",
        "description": "Suscripción Pro",
        "responsibleDocument": "12345678901",
        "responsibleExternalId": "user-1234",
        "externalId": "pedido-5678",
        "postbackUrl": "https://seu-dominio.com/webhook",
    },
)
res.raise_for_status()
tx = res.json()

# O CVU nao vem na criacao — a rede argentina leva alguns segundos.
def esperar_instrucao(tx_id, tentativas=15):
    for _ in range(tentativas):
        t = requests.get(
            f"https://api.ihubplay.com/transactions/{tx_id}", headers=headers
        ).json()
        if t.get("cvu"):
            return t
        time.sleep(2)
    raise RuntimeError("Instrucao de pagamento nao chegou a tempo")

pronto = esperar_instrucao(tx["id"])
print("CVU:", pronto["cvu"])
print("Beneficiario:", (pronto.get("paymentInstruction") or {}).get("beneficiary"))