curl --request POST "$ALLIANCEPAY_BASE_URL/oauth/token" \
  --user "$ALLIANCEPAY_CLIENT_ID:$ALLIANCEPAY_CLIENT_SECRET" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials'

// Executar somente no backend. Node.js 22+; sem dependências externas.
const ENVIRONMENTS = new Set([
  "https://api-hml.alliancepay.app",
  "https://api.alliancepay.app",
]);

export class GatewayError extends Error {
  constructor(status, body, requestId) {
    super(`AlliancePay respondeu HTTP ${status}`);
    this.name = "GatewayError";
    this.status = status;
    this.body = body;
    this.requestId = requestId;
  }
}

export function checkoutPath(publicToken) {
  if (typeof publicToken !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(publicToken)) {
    throw new Error("public_token inválido");
  }
  return `/acquiring/payment-links/public/${publicToken}`;
}

export function createGatewayClient({
  baseUrl,
  clientId,
  clientSecret,
  fetchImpl = globalThis.fetch,
  timeoutMs = 25000,
  now = Date.now,
}) {
  const origin = new URL(baseUrl).origin;
  if (!ENVIRONMENTS.has(origin) || !clientId || !clientSecret) {
    throw new Error("Configure ambiente, client_id e client_secret no backend");
  }
  let cachedToken;
  let usableUntil = 0;
  let tokenInFlight;

  async function exchangeToken() {
    const response = await fetchImpl(`${origin}/oauth/token`, {
      method: "POST",
      redirect: "error",
      signal: AbortSignal.timeout(timeoutMs),
      headers: {
        Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`,
        "Content-Type": "application/x-www-form-urlencoded",
        Accept: "application/json",
      },
      body: new URLSearchParams({ grant_type: "client_credentials" }),
    });
    const body = await response.json().catch(() => null);
    if (!response.ok) {
      throw new GatewayError(response.status, body, response.headers.get("x-request-id"));
    }
    const ttl = Number(body?.expires_in);
    if (typeof body?.access_token !== "string" || !Number.isFinite(ttl) || ttl <= 0) {
      throw new Error("Resposta de autenticação inválida");
    }
    cachedToken = body.access_token;
    usableUntil = now() + Math.max(0, Math.min(ttl, 3600) - 60) * 1000;
    return cachedToken;
  }

  async function accessToken() {
    if (cachedToken && now() < usableUntil) return cachedToken;
    tokenInFlight ??= exchangeToken().finally(() => { tokenInFlight = undefined; });
    return tokenInFlight;
  }

  async function request(path, { method = "GET", body, idempotencyKey } = {}) {
    const url = new URL(path, origin);
    if (url.origin !== origin || !url.pathname.startsWith("/acquiring/") || !["GET", "POST"].includes(method)) {
      throw new Error("Destino não permitido neste exemplo");
    }
    const headers = {
      Accept: "application/json",
      Authorization: `Bearer ${await accessToken()}`,
      "X-Request-Id": crypto.randomUUID(),
    };
    if (body !== undefined) headers["Content-Type"] = "application/json";
    if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
    // Não repetir escritas automaticamente: o resultado de um timeout pode ser incerto.
    const response = await fetchImpl(url, {
      method, headers, redirect: "error", signal: AbortSignal.timeout(timeoutMs),
      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
    });
    const data = await response.json().catch(() => null);
    if (!response.ok) {
      if (response.status === 401) { cachedToken = undefined; usableUntil = 0; }
      throw new GatewayError(response.status, data, response.headers.get("x-request-id"));
    }
    return { status: response.status, data, requestId: response.headers.get("x-request-id") };
  }

  return { request };
}

import { createGatewayClient, checkoutPath } from "./gateway-client.mjs";

const alliancepay = createGatewayClient({
  baseUrl: process.env.ALLIANCEPAY_BASE_URL,
  clientId: process.env.ALLIANCEPAY_CLIENT_ID,
  clientSecret: process.env.ALLIANCEPAY_CLIENT_SECRET,
});

GET /acquiring/payment-links/creation-options/?acquirer_registration_id={ec_id}
Authorization: Bearer {access_token}

POST /acquiring/payment-links/
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "acquirer_registration_id": "11111111-1111-4111-8111-111111111111",
  "billing_type": "ONE_TIME",
  "amount": "149.90",
  "description": "Pedido de exemplo",
  "external_reference": "pedido-exemplo-001",
  "payment_methods": ["CREDIT", "PIX"],
  "max_installments": 3
}

const url = new URL(link.checkout_url);
const publicToken = url.pathname.split("/").filter(Boolean).at(-1);
const base = checkoutPath(publicToken); // somente no backend
const { data: checkout } = await alliancepay.request(base);

GET /acquiring/payment-links/public/{public_token}
Authorization: Bearer {access_token}

// Adaptador do browser para rotas DO PARCEIRO. Essas URLs NÃO pertencem à AlliancePay.
// Implemente o mapeamento descrito no guia, validando sessão de checkout, pedido e IDs.
export function createCheckoutApi(orderId, { csrfToken, fetchImpl = globalThis.fetch } = {}) {
  const base = `/api/checkout/${encodeURIComponent(orderId)}`;
  return async function call(suffix, { method = "GET", body, idempotencyKey } = {}) {
    const headers = { Accept: "application/json" };
    if (body !== undefined) headers["Content-Type"] = "application/json";
    if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
    if (csrfToken) headers["X-CSRF-Token"] = csrfToken;
    const response = await fetchImpl(`${base}${suffix}`, {
      method, headers, credentials: "same-origin", cache: "no-store", redirect: "error",
      signal: AbortSignal.timeout(30000),
      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
    });
    const data = await response.json().catch(() => null);
    if (!response.ok) {
      const error = new Error("Não foi possível concluir esta etapa; consulte a tentativa existente.");
      error.status = response.status;
      error.body = data;
      throw error;
    }
    return data;
  };
}

POST /acquiring/payment-links/public/{public_token}/card-tokenizations
Authorization: Bearer {access_token}
Idempotency-Key: {chave_da_tokenizacao}
Content-Type: application/json

{}

POST /acquiring/payment-links/public/{public_token}/card-tokenizations/{tokenization_id}/confirm
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "payment_method": "CREDIT",
  "card": {
    "brand": "VISA",
    "number": "BASE64_DO_NUMERO_CIFRADO",
    "expiration_month": "BASE64_DO_MES_CIFRADO",
    "expiration_year": "BASE64_DO_ANO_CIFRADO"
  }
}

GET /acquiring/payment-links/public/{public_token}/card-tokenizations/{tokenization_id}

POST /acquiring/payment-links/public/{public_token}/payments
Authorization: Bearer {access_token}
Idempotency-Key: {chave_do_pagamento}
Content-Type: application/json

{
  "payment_method_id": "22222222-2222-4222-8222-222222222222",
  "payment_method": "CREDIT",
  "installments": 1,
  "card": { "security_code": "BASE64_DO_CVV_CIFRADO" },
  "payer": {
    "name": "Pagador de Exemplo",
    "email": "[email protected]",
    "document": "11144477735"
  },
  "phone": { "country_code": "55", "area_code": "65", "number": "999990000" },
  "billing_address": {
    "country": "BR",
    "zip_code": "78000000",
    "state": "MT",
    "city": "Cuiaba",
    "street": "Rua de Exemplo",
    "district": "Centro",
    "street_number": "100"
  },
  "browser": {
    "http_accept_browser_value": "text/html,application/xhtml+xml",
    "http_browser_java_script_enabled": true,
    "http_browser_java_enabled": false,
    "http_browser_language": "pt-BR",
    "http_browser_color_depth": 24,
    "http_browser_screen_height": 1080,
    "http_browser_screen_width": 1920,
    "http_browser_time_difference": 240,
    "user_agent_browser_value": "Mozilla/5.0",
    "ip_address": "192.0.2.10"
  }
}

import { createCheckoutApi } from "./checkout-api.mjs";
import { browserPayload, importCheckoutKey, encryptCheckoutField } from "./browser-3ds.mjs";

const call = createCheckoutApi(orderId, { csrfToken });
// Chaves geradas/persistidas uma vez por tentativa; reutilizadas nas retomadas.
const tokenization = await call("/card-tokenizations", {
  method: "POST", body: {}, idempotencyKey: checkoutState.tokenizationKey,
});
if (!tokenization.public_key) throw new Error("Tokenização sem chave disponível");
const key = await importCheckoutKey(tokenization.public_key);
const encrypted = {
  number: await encryptCheckoutField(key, form.cardNumber.replace(/\D/g, "")),
  expiration_month: await encryptCheckoutField(key, form.month.padStart(2, "0")),
  expiration_year: await encryptCheckoutField(key, form.fullYear),
};
const tokenized = await call(`/card-tokenizations/${tokenization.id}/confirm`, {
  method: "POST", body: { payment_method: "CREDIT", card: { brand: form.brand, ...encrypted } },
});
// Se PROCESSING, consultar a tokenização; não reiniciar o fluxo por timeout.
if (tokenized.status !== "READY" || !tokenized.payment_method_id) {
  throw new Error("Acompanhe a tokenização existente antes de prosseguir");
}
const payment = await call("/payments", {
  method: "POST", idempotencyKey: checkoutState.paymentKey,
  body: {
    payment_method_id: tokenized.payment_method_id,
    payment_method: "CREDIT", installments: 1,
    card: { security_code: await encryptCheckoutField(key, form.cvv) },
    payer, phone, billing_address: billingAddress, browser: browserPayload(),
  },
});
// O backend acrescenta browser.ip_address e persiste payment.id antes de responder.
// Seguir para trackCardOperation(payment); não mostrar sucesso apenas pelo HTTP 201.

{
  "id": "33333333-3333-4333-8333-333333333333",
  "status": "AUTHENTICATING",
  "amount": "149.90",
  "currency": "BRL",
  "installments": 1,
  "payment_method": {
    "id": "22222222-2222-4222-8222-222222222222",
    "type": "CREDIT",
    "brand": "VISA",
    "last_four": "1111"
  },
  "next_action": {
    "type": "THREE_DS_CHALLENGE",
    "url": "https://acs.example.com/challenge",
    "creq": "VALOR_OPACO_RETORNADO_PELA_API"
  }
}

// Helpers para o navegador. Nenhuma credencial OAuth é recebida por este módulo.
export function publicTokenFromCheckoutUrl(checkoutUrl) {
  const url = new URL(checkoutUrl);
  const segments = url.pathname.split("/").filter(Boolean);
  const token = segments.at(-1);
  if (url.protocol !== "https:" || segments.at(-2) !== "payment-links" || !/^[A-Za-z0-9_-]{1,128}$/.test(token ?? "")) {
    throw new Error("checkout_url inválida");
  }
  return token;
}

export function browserPayload() {
  return {
    http_accept_browser_value: "text/html,application/xhtml+xml",
    http_browser_java_script_enabled: true,
    http_browser_java_enabled: navigator.javaEnabled?.() ?? false,
    http_browser_language: navigator.language,
    http_browser_color_depth: screen.colorDepth,
    http_browser_screen_height: screen.height,
    http_browser_screen_width: screen.width,
    http_browser_time_difference: new Date().getTimezoneOffset(),
    user_agent_browser_value: navigator.userAgent,
  };
}

export async function importCheckoutKey(publicKeyPem) {
  const pem = publicKeyPem.replace(/-----BEGIN PUBLIC KEY-----|-----END PUBLIC KEY-----|\s/g, "");
  const bytes = Uint8Array.from(atob(pem), character => character.charCodeAt(0));
  return crypto.subtle.importKey("spki", bytes, { name: "RSA-OAEP", hash: "SHA-1" }, false, ["encrypt"]);
}

export async function encryptCheckoutField(key, value) {
  const ciphertext = await crypto.subtle.encrypt({ name: "RSA-OAEP" }, key, new TextEncoder().encode(value));
  return btoa(String.fromCharCode(...new Uint8Array(ciphertext)));
}

export function wait(ms, signal) {
  return new Promise((resolve, reject) => {
    signal?.throwIfAborted();
    const abort = () => {
      clearTimeout(timer);
      reject(signal.reason ?? new DOMException("Interrompido", "AbortError"));
    };
    const timer = setTimeout(() => { signal?.removeEventListener("abort", abort); resolve(); }, ms);
    signal?.addEventListener("abort", abort, { once: true });
  });
}

export function mountThreeDsForm({ url, field, value, visible, container }) {
  const target = new URL(url);
  if (target.protocol !== "https:" || target.username || target.password) throw new Error("URL 3DS inválida");
  if (visible && !container) throw new Error("Informe o container visível para o desafio");
  const frame = document.createElement("iframe");
  frame.name = `three-ds-${crypto.randomUUID()}`;
  frame.title = visible ? "Autenticação do cartão pelo banco emissor" : "Verificação do navegador";
  frame.hidden = !visible;
  if (visible) { frame.style.width = "100%"; frame.style.minHeight = "600px"; frame.style.border = "0"; }
  (visible ? container : document.body).append(frame);
  const form = document.createElement("form");
  form.hidden = true;
  form.method = "POST";
  form.action = target.href;
  form.target = frame.name;
  form.enctype = "application/x-www-form-urlencoded";
  const input = document.createElement("input");
  input.type = "hidden";
  input.name = field;
  input.value = value;
  form.append(input);
  document.body.append(form);
  try { form.submit(); } catch (error) { frame.remove(); throw error; } finally { form.remove(); }
  return () => frame.remove();
}

export function createThreeDsController({ container, mountForm = mountThreeDsForm, sleep = wait }) {
  let active;
  const completedMethods = new Set();
  const dispose = () => { active?.remove(); active = undefined; };

  async function handle(resource, { continueThreeDs, signal }) {
    const action = resource.next_action;
    if (!action) {
      // Uma resposta incompleta enquanto AUTHENTICATING não deve desmontar o desafio.
      if (resource.status !== "AUTHENTICATING") dispose();
      return null;
    }
    if (action.type === "THREE_DS_DECOUPLED") { dispose(); return null; }
    if (!["THREE_DS_METHOD", "THREE_DS_CHALLENGE"].includes(action.type)) {
      throw new Error("Ação 3DS desconhecida; consulte novamente ou acione o suporte");
    }
    const challenge = action.type === "THREE_DS_CHALLENGE";
    const value = challenge ? action.creq : action.three_ds_method_data;
    if (!action.url || !value) throw new Error("Ação 3DS incompleta; preserve a tentativa e consulte novamente");
    const key = JSON.stringify([resource.id, action.type, action.url, value]);
    if (active?.key !== key) {
      dispose();
      active = {
        key,
        remove: mountForm({ url: action.url, field: challenge ? "creq" : "threeDSMethodData", value, visible: challenge, container }),
        methodWaited: false,
      };
    }
    if (challenge || completedMethods.has(key)) return null;
    if (!active.methodWaited) {
      const current = active;
      await sleep(10000, signal);
      signal?.throwIfAborted();
      if (active !== current) return null;
      current.methodWaited = true;
    }
    // O Core determina a conclusão do Method pelos callbacks. O corpo é {}.
    const result = await continueThreeDs(resource.id, {});
    completedMethods.add(key);
    return result;
  }
  return { handle, dispose };
}

export function isTerminal(resource, kind = "payment") {
  const statuses = kind === "card_setup"
    ? ["COMPLETED", "FAILED", "EXPIRED", "CANCELED"]
    : ["APPROVED", "DECLINED", "FAILED", "EXPIRED"];
  return statuses.includes(resource.status);
}

// get e continueThreeDs chamam exclusivamente o backend do parceiro.
export async function trackCardOperation({
  initial, get, continueThreeDs, controller, kind = "payment", onUpdate = () => {},
  onTransientError = () => {}, signal, sleep = wait, now = Date.now, maxMs = 300000,
}) {
  const started = now();
  let resource = initial;
  while (now() - started < maxMs) {
    signal?.throwIfAborted();
    onUpdate(resource);
    if (isTerminal(resource, kind)) { controller.dispose(); return { outcome: "terminal", resource }; }
    try {
      const continued = await controller.handle(resource, { continueThreeDs, signal });
      if (continued) { resource = continued; continue; }
    } catch (error) {
      signal?.throwIfAborted();
      if (error.status >= 400 && error.status < 500 && error.status !== 429) throw error;
      onTransientError(error); // Falha de rede ou de renderização não comprova falha financeira.
    }
    const suggested = resource.next_action?.type === "THREE_DS_DECOUPLED"
      ? Number(resource.next_action.poll_after_seconds) : 20;
    const seconds = Number.isFinite(suggested) && suggested > 0 ? Math.max(1, suggested) : 20;
    await sleep(seconds * 1000, signal);
    try { resource = await get(resource.id); } catch (error) {
      signal?.throwIfAborted();
      if (error.status >= 400 && error.status < 500 && error.status !== 429) throw error;
      onTransientError(error);
    }
  }
  // Preservar a tentativa e a interface; oferecer "Atualizar status".
  return { outcome: "paused", resource };
}

<p id="payment-status" role="status" aria-live="polite"></p>
<div id="three-ds-challenge-slot"></div>

import { createThreeDsController, trackCardOperation } from "./browser-3ds.mjs";

const abort = new AbortController();
const controller = createThreeDsController({
  container: document.getElementById("three-ds-challenge-slot"),
});
const result = await trackCardOperation({
  initial: payment,
  get: id => call(`/payments/${id}`),
  continueThreeDs: (id, body) => call(`/payments/${id}/three-ds/continue`, { method: "POST", body }),
  controller,
  signal: abort.signal,
  onUpdate: resource => {
    document.getElementById("payment-status").textContent =
      resource.status === "APPROVED" ? "Pagamento aprovado" : `Status: ${resource.status}`;
  },
  onTransientError: () => {
    document.getElementById("payment-status").textContent = "Aguardando confirmação. Preserve esta tentativa.";
  },
});
if (result.outcome === "paused") {
  // Habilitar botão "Atualizar status" que consulta result.resource.id.
}
// Ao desmontar a tela: abort.abort(); controller.dispose();
// Tratar rejeições do acompanhamento na camada de UI, preservando o ID da tentativa.

POST /acquiring/payment-links/public/{public_token}/payments/{payment_id}/three-ds/continue
Authorization: Bearer {access_token}
Content-Type: application/json

{}

POST /acquiring/payment-links/public/{public_token}/pix-payments
Authorization: Bearer {access_token}
Idempotency-Key: {chave_do_pix}
Content-Type: application/json

{}

{
  "id": "44444444-4444-4444-8444-444444444444",
  "payment_method": "PIX",
  "status": "PENDING_CONFIRMATION",
  "amount": "149.90",
  "currency": "BRL",
  "txid": "IDENTIFICADOR_RETORNADO_PELA_API",
  "copy_paste": "PAYLOAD_PIX_REAL_RETORNADO_PELA_API",
  "expires_at": "2030-01-15T18:30:00Z",
  "approved_at": null,
  "poll_after_seconds": 5,
  "pix": { "phase": "WAITING_PAYMENT", "processing_reason": null, "can_pay": true },
  "recurring_acceptance": null
}

GET /acquiring/payment-links/public/{public_token}/pix-payments/{payment_id}
Authorization: Bearer {access_token}

import { wait } from "./browser-3ds.mjs";

// get consulta a MESMA tentativa pelo backend do parceiro; nunca cria outra cobrança.
export async function trackPixPayment({
  initial, get, onUpdate = () => {}, onTransientError = () => {}, signal,
  sleep = wait, now = Date.now, maxMs = 300000,
}) {
  let payment = initial;
  const started = now();
  while (now() - started < maxMs) {
    signal?.throwIfAborted();
    onUpdate(payment);
    if (payment.status === "APPROVED" && payment.pix?.phase === "PAID") {
      return { outcome: "paid", payment };
    }
    if (["DECLINED", "FAILED", "EXPIRED"].includes(payment.status)) {
      return { outcome: "terminal", payment };
    }
    const suggested = Number(payment.poll_after_seconds);
    const seconds = Number.isFinite(suggested) && suggested > 0 ? Math.max(1, suggested) : 5;
    await sleep(seconds * 1000, signal);
    try { payment = await get(payment.id); } catch (error) {
      signal?.throwIfAborted();
      if (error.status >= 400 && error.status < 500 && error.status !== 429) throw error;
      onTransientError(error);
    }
  }
  return { outcome: "paused", payment };
}

<textarea id="pix-code" readonly aria-label="Pix copia e cola"></textarea>
<button id="copy-pix" type="button">Copiar Pix</button>
<p id="pix-status" role="status" aria-live="polite"></p>

import { trackPixPayment } from "./browser-pix.mjs";

const pix = await call("/pix-payments", {
  method: "POST", body: {}, idempotencyKey: checkoutState.pixKey,
});
const field = document.getElementById("pix-code");
const copy = document.getElementById("copy-pix");
copy.onclick = () => navigator.clipboard.writeText(field.value);
const result = await trackPixPayment({
  initial: pix,
  get: id => call(`/pix-payments/${id}`),
  onUpdate: payment => {
    const canPay = payment.pix.can_pay && Boolean(payment.copy_paste);
    field.value = canPay ? payment.copy_paste : "";
    field.hidden = !canPay;
    copy.disabled = !canPay;
    document.getElementById("pix-status").textContent =
      payment.status === "APPROVED" && payment.pix.phase === "PAID"
        ? "Pix confirmado" : `Status: ${payment.pix.phase}`;
  },
});
// Se paused, preservar pix.id e oferecer atualização manual do status.

POST /acquiring/payment-links/public/{public_token}/card-setups
Authorization: Bearer {access_token}
Idempotency-Key: {chave_da_adesao}
Content-Type: application/json

const result = await trackCardOperation({
  initial: setup,
  kind: "card_setup",
  get: id => call(`/card-setups/${id}`),
  continueThreeDs: (id, body) => call(`/card-setups/${id}/three-ds/continue`, { method: "POST", body }),
  controller,
  onUpdate: resource => { /* Atualizar a interface da adesão. */ },
});

GET /acquiring/payment-links/public/{public_token}/payments/by-idempotency-key
Authorization: Bearer {access_token}
Idempotency-Key: {chave_original_do_pagamento}

GET /acquiring/payment-links/public/{public_token}/pix-payments/by-idempotency-key
Authorization: Bearer {access_token}
Idempotency-Key: {chave_original_do_pix}