iHubGamesiHubGamesdocs
Dashboard

Referência da API

Criar transação (MXN)

Cria uma transação de entrada em MXN (pesos mexicanos). Dois métodos, escolhidos pelo paymentMethod: SPEI (padrão) devolve uma clabe de 18 dígitos para o pagador transferir pelo app do banco, e confirma em segundos; OXXO devolve uma reference com código de barras para pagar em dinheiro na loja, e pode levar horas ou dias. É o mesmo endpoint do PIX — POST /transactions/v2/purchase — mudando currency para "MXN". Nos dois, a instrução vem na própria resposta, e o webhook cashin.paid confirma o pagamento. Conceitos em México (MXN).

POST/transactions/v2/purchase
Moeda fixa por conta
currency A moeda é definida na criação da conta e travada após a primeira transação — o currency do request precisa casar com a moeda da conta. Uma conta MXN opera sempre em pesos (saldo, taxas, faturas e transações todos em MXN); uma conta BRL não recebe SPEI e vice-versa.

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 da transação em centavos de peso. MX$ 10,00 = 1000. Mesma unidade do BRL — não é mil pesos.

Exemplo: 1000

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'MXN'obrigatório

Código da moeda. Para SPEI/México use "MXN". O amount continua em CENTAVOS (de pesos — 1000 = MX$ 10,00). Omitir currency cai no padrão BRL (PIX) — veja Criar transação (PIX).

Exemplo: MXN

paymentMethod'SPEI' | 'OXXO'opcional

Opcional para currency: MXN — default SPEI. SPEI: o comprador transfere pelo app do banco para a clabe que volta na resposta; confirma em segundos. OXXO: o comprador leva a reference (com código de barras) a uma loja e paga em dinheiro; pode levar horas ou dias, e o email do pagador passa a ser obrigatório.

Exemplo: SPEI

cpfstringopcional

Não obrigatório em MXN — é um documento brasileiro (CPF/CNPJ) e o SPEI não usa documento do pagador. Envie só name/email (+ phone opcional). No BRL o cpf continua obrigatório.

phonestringopcional

Telefone do pagador, 8 a 12 dígitos numéricos. Opcional para currency: MXN.

externalIdstringopcional

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

Exemplo: pedido-5678

postbackUrlstringopcional

URL de webhook para eventos dessa transação. Se omitido, usa a URL de webhook global configurada no 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": 1000,
  "currency": "MXN",
  "description": "Suscripción Pro",
  "responsibleDocument": "12345678901",
  "responsibleExternalId": "user-1234",
  "externalId": "pedido-5678",
  "postbackUrl": "https://seu-dominio.com/webhook",
  "paymentMethod": "SPEI"
}

Respostas

201

Transação MXN criada. A resposta traz method: "SPEI" e uma clabe (CLABE de depósito, 18 dígitos) no lugar do pixCode — o pagador transfere via SPEI para essa CLABE. status fica PENDING até o SPEI cair (confirmado pelo webhook cashin.paid). amount em centavos de pesos (1000 = MX$ 10,00).

JSON
{
  "id": "17864385245624641191295936",
  "currency": "MXN",
  "method": "SPEI",
  "installments": null,
  "externalId": "pedido-5678",
  "status": "PENDING",
  "amount": 1000,
  "postbackUrl": "https://seu-dominio.com/webhook",
  "referrerUrl": null,
  "clabe": "684180330080887521",
  "expiresAt": null,
  "createdAt": "2026-08-11T08:55:24.748Z",
  "costFee": 100
}
400

Erro de validação. O campo message descreve qual(is) campo(s) falharam.

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

bash
# OXXO — dinheiro no balcão. Muda só o paymentMethod.
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": "Luis Legs",
    "email": "luis@ejemplo.com",
    "amount": 10000,
    "currency": "MXN",
    "paymentMethod": "OXXO",
    "description": "Suscripción Pro",
    "responsibleDocument": "12345678901",
    "responsibleExternalId": "user-1234"
  }'

# Volta "reference" e, em paymentInstruction, o "barcode" (PNG).
# Mostre os DOIS — muita loja lê o código de barras em vez de digitar.
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": 1000,
    "currency": "MXN",
    "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 res = await fetch("https://api.ihubplay.com/transactions/v2/purchase", {
  method: "POST",
  headers: {
    Authorization: `Basic ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Juan Pérez",
    email: "juan@ejemplo.com",
    amount: 1000,
    currency: "MXN",
    description: "Suscripción Pro",
    responsibleDocument: "12345678901",
    responsibleExternalId: "user-1234",
    externalId: "pedido-5678",
    postbackUrl: "https://seu-dominio.com/webhook",
  }),
});

const traceId = res.headers.get("x-trace-id");
console.log("trace:", traceId);

if (!res.ok) {
  const err = await res.json();
  throw new Error(`${err.message} (trace: ${traceId})`);
}

const tx = await res.json();
console.log("CLABE SPEI:", tx.clabe);
Python
import base64, json, os, requests

token = base64.b64encode(
    f"secret:{os.environ['IHUBGAMES_SECRET_KEY']}".encode()
).decode()

res = requests.post(
    "https://api.ihubplay.com/transactions/v2/purchase",
    headers={
        "Authorization": f"Basic {token}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Juan Pérez",
        "email": "juan@ejemplo.com",
        "amount": 1000,
        "currency": "MXN",
        "description": "Suscripción Pro",
        "responsibleDocument": "12345678901",
        "responsibleExternalId": "user-1234",
        "externalId": "pedido-5678",
        "postbackUrl": "https://seu-dominio.com/webhook",
    },
)

print("trace:", res.headers.get("x-trace-id"))
res.raise_for_status()
tx = res.json()
print("CLABE SPEI:", tx["clabe"])