Documentação

Cartão (visão geral)

Cartão de crédito usa o mesmo endpoint das transações (POST /transactions/v2/purchase com paymentMethod: "CREDIT_CARD"), mudando só como o número do cartão chega até nós. Por segurança (PCI) e por causa do 3D Secure, cartão nunca é 100% servidor-a-servidor: o número precisa ser tokenizado e, quando o emissor exige 3DS, o desafio acontece num navegador.

📦 Biblioteca iHubGames.js: inclua no seu HTML com <script src="https://portal.ihubplay.com/sdk/hubplay.js"></script>, ou abra/baixe direto aqui → https://portal.ihubplay.com/sdk/hubplay.js. É ela que tokeniza o cartão e resolve o 3DS no navegador (usada nos Modelos A e no 3DS do B).

Existem dois modelos — escolha pelo seu fluxo:

	Modelo A — Token	Modelo B — PAN cru
Pra quem	tem checkout no navegador	sub-adquirente PCI, server-to-server
Você envia	`creditCard.token`	`creditCard.number` + validade + cvv
PCI	não precisa	obrigatório
Como	a iHubGames.js tokeniza no navegador	manda o número direto; o backend tokeniza

A resposta é a mesma nos dois modelos. last4 / brand são opcionais — no Modelo A a iHubGames.js devolve; no Modelo B o backend deriva do número.

Modelo A — Token (iHubGames.js, sem PCI)

1. Pegue a chave de tokenização no seu backend — GET /transactions/card-config:

bash

curl "https://api.ihubplay.com/transactions/card-config" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"
# → { "available": true, "tokenizationKey": "pgk_live_...", "allowsInstallments": true }

2. Tokenize no navegador com a iHubGames.js (o número nunca toca o seu servidor):

HTML

<script src="https://portal.ihubplay.com/sdk/hubplay.js"></script>
<div id="card-element"></div>
<script>
  const card = iHubGames.card({ tokenizationKey }); // do passo 1
  await card.mount("#card-element");
  const { token } = await card.tokenize({ name: "João Silva" });
  // mande 'token' pro seu servidor
</script>

3. Cobre com o token — Criar transação (Cartão — token):

JSON

{ "paymentMethod": "CREDIT_CARD",
  "creditCard": { "token": "<token>", "holder": "JOAO SILVA", "installments": 1 },
  "amount": 1000, "name": "João Silva", "email": "joao@exemplo.com", "cpf": "12345678901" }

Modelo B — PAN cru (sub-adquirente PCI)

Se você já tem o número do cartão no servidor, mande direto — sem iHubGames.js — em Criar transação (Cartão — PAN):

JSON

{ "paymentMethod": "CREDIT_CARD",
  "creditCard": { "number": "5155901222280001", "holder": "JOAO SILVA",
    "expMonth": "12", "expYear": "2030", "cvv": "123", "installments": 1 },
  "amount": 1000, "name": "João Silva", "email": "joao@exemplo.com", "cpf": "12345678901" }

O backend tokeniza e cobra; last4 / bin / brand são derivados do número.

⚠️ PCI: o número trafega pelo seu servidor — a origem precisa ser PCI DSS compliant. Havendo navegador no fluxo, prefira o Modelo A.

3D Secure — pode exigir ou não

Quem decide o 3DS é o emissor do cartão, não você — vale pros dois modelos:

Sem 3DS → { "status": "APPROVED", ... } na hora.
Com 3DS → { "status": "PENDING", "requiresAction": true, "clientSecret": "..." }. Apresente o desafio num navegador com a iHubGames.js:

JavaScript

const card = iHubGames.card({ tokenizationKey });
await card.confirmAction(clientSecret); // abre o desafio 3DS
// concluído → o webhook cashin.paid marca APPROVED

Não dá pra concluir 3DS 100% server-side (é regra do 3DS/SCA). Em fluxo sem navegador (ex.: MOTO), só passam sem requiresAction as transações que se qualificam pra isenção.