Referência da API

Criar transação (BRL)

Cria uma transação de entrada via PIX. Retorna um BR Code copia-e-cola (pixCode) que seu cliente paga por qualquer app de banco; o webhook cashin.paid confirma. Para cartão, use os endpoints Cartão (token) e Cartão (PAN) — mesmo endpoint, paymentMethod: CREDIT_CARD. Multi-moeda: o campo opcional currency (padrão BRL) aceita MXN, ARS, COP e BOB. Fora do Brasil o paymentMethod é opcional — cada moeda tem um padrão — e o cpf não é exigido. A lista completa de trilhos, dados obrigatórios e limites está em Métodos de pagamento por moeda.

POST/transactions/v2/purchase

Restrinja quem pode pagar

restrictPayerDocument Defina como true para travar a transação ao CPF/CNPJ informado em cpf. Se outra pessoa tentar pagar, o banco rejeita o PIX. Essa é a defesa mais forte contra fraude de roteamento de pagamento, onde um atacante paga por um terceiro e depois contesta a cobrança.

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: João Silva

emailstringobrigatório

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

Exemplo: joaosilva@exemplo.com

cpfstringobrigatório

CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador, apenas números. Sem máscara. Obrigatório para BRL; opcional para currency: MXN (documento brasileiro — no México o pagador não tem CPF, e o SPEI não usa documento do pagador).

Exemplo: 12345678901

phonestringobrigatório

Telefone do pagador, 8 a 12 dígitos numéricos. Obrigatório para BRL; opcional para currency: MXN.

Exemplo: 9876543210

amountnumberobrigatório

Valor da transação em centavos. R$ 10,00 = 1000. R$ 0,01 = 1. Não há mínimo, mas valores muito baixos podem ser rejeitados pela instituição recebedora.

Exemplo: 1000

descriptionstringobrigatório

Descrição curta da transação que aparece no comprovante e no extrato bancário do pagador.

Exemplo: Assinatura 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

Para currency: BRL é obrigatório — use PIX (retorna um BR Code copia-e-cola). Nas demais moedas é OPCIONAL: cada uma tem um método padrão, e você só envia o campo para escolher outro. MXN: SPEI (padrão) ou OXXO. ARS: BANK_TRANSFER. COP: BANK_TRANSFER (padrão), PSE, NEQUI ou BREB. BOB: QR. Para cartão, use os endpoints Cartão (token) ou Cartão (PAN).

Exemplo: PIX

currency'BRL' | 'MXN' | 'ARS'opcional

Código da moeda. Padrão BRL (PIX/cartão). Também aceita MXN (SPEI ou OXXO), ARS (transferência), COP (transferência, PSE, Nequi ou Bre-B) e BOB (QR). Em BRL e MXN a instrução de pagamento vem na própria resposta; em ARS, COP e BOB ela chega alguns segundos depois, por polling em GET /transactions/:id. Em todas, amount continua em CENTAVOS da moeda.

Exemplo: BRL

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

referrerUrlstringopcional

URL da página de origem dessa transação.

Exemplo: https://exemplo.com/checkout

checkoutUrlstringopcional

URL da sua página de checkout hospedada, se aplicável.

Exemplo: https://exemplo.com/pagar/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

restrictPayerDocumentbooleanopcional

Quando true, apenas o titular do cpf informado pode pagar essa transação. Pagamentos de qualquer outro CPF/CNPJ são rejeitados pela instituição recebedora.

Exemplo: true

Body da requisição

Content-Type: application/json

JSON

{
  "name": "João Silva",
  "email": "joaosilva@exemplo.com",
  "cpf": "12345678901",
  "phone": "9876543210",
  "amount": 1000,
  "description": "Assinatura Pro",
  "responsibleDocument": "12345678901",
  "responsibleExternalId": "user-1234",
  "externalId": "pedido-5678",
  "postbackUrl": "https://seu-dominio.com/webhook",
  "paymentMethod": "PIX",
  "currency": "BRL"
}

Respostas

201

Transação criada. pixCode é o BR Code copia-e-cola para exibir ao seu cliente; status fica PENDING até o pagamento (confirmado pelo webhook cashin.paid).

JSON

{
  "id": "17913320791467683016950003",
  "currency": "BRL",
  "method": "PIX",
  "installments": null,
  "externalId": "pedido-5678",
  "status": "PENDING",
  "amount": 1000,
  "postbackUrl": "https://seu-dominio.com/webhook",
  "referrerUrl": null,
  "pixCode": "00020126580014br.gov.bcb.pix...6304B0D2",
  "expiresAt": "2026-10-07T15:32:01.923Z",
  "createdAt": "2026-10-07T00:14:40.893Z",
  "costFee": 2
}

201

Transação MXN (SPEI). A resposta traz method: "SPEI" e uma clabe (CLABE de depósito) no lugar do pixCode — o pagador transfere via SPEI para essa CLABE. amount em centavos de pesos (1000 = MX$ 10,00).

JSON

{
  "id": "17864385245624641191295936",
  "currency": "MXN",
  "method": "SPEI",
  "installments": null,
  "externalId": null,
  "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

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": "João Silva",
    "email": "joaosilva@exemplo.com",
    "cpf": "12345678901",
    "phone": "9876543210",
    "amount": 1000,
    "description": "Assinatura Pro",
    "responsibleDocument": "12345678901",
    "responsibleExternalId": "user-1234",
    "externalId": "pedido-5678",
    "postbackUrl": "https://seu-dominio.com/webhook",
    "paymentMethod": "PIX",
    "currency": "BRL"
  }'

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: "João Silva",
    email: "joaosilva@exemplo.com",
    cpf: "12345678901",
    phone: "9876543210",
    amount: 1000,
    description: "Assinatura Pro",
    responsibleDocument: "12345678901",
    responsibleExternalId: "user-1234",
    externalId: "pedido-5678",
    postbackUrl: "https://seu-dominio.com/webhook",
    paymentMethod: "PIX",
    currency: "BRL",
  }),
});

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("Código PIX:", tx.pixCode);

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": "João Silva",
        "email": "joaosilva@exemplo.com",
        "cpf": "12345678901",
        "phone": "9876543210",
        "amount": 1000,
        "description": "Assinatura Pro",
        "responsibleDocument": "12345678901",
        "responsibleExternalId": "user-1234",
        "externalId": "pedido-5678",
        "postbackUrl": "https://seu-dominio.com/webhook",
        "paymentMethod": "PIX",
        "currency": "BRL",
    },
)

print("trace:", res.headers.get("x-trace-id"))
res.raise_for_status()
tx = res.json()
print("Código PIX:", tx["pixCode"])