Nextjs White Label

1. Usar App Router (app/) com separação clara entre:
   • Server Components para dados e composição de página;
   • Client Components apenas para interações necessárias (SDK, estado de UI, formulários).
2. Criar uma camada de domínio para pagamento:
   • src/features/checkout/ para casos de uso, tipos e integrações;
   • src/lib/lina-pay/ para wrapper do SDK e helpers.
3. Evitar acoplamento direto do SDK em múltiplos componentes:
   • encapsular o SDK em serviço/facade;
   • expor API interna estável para o restante da aplicação.
4. Manter segredos no servidor:
   • nunca expor chaves sensíveis no client;
   • usar process.env e validação de variáveis.
5. Tratar estados de pagamento explicitamente:
   • idle, loading, success, error, retry.

Estrutura Recomendada de Pastas

src/
  app/
    (store)/
      products/
      cart/
      checkout/
  components/
    ui/                  # shadcn-ui
    checkout/
  features/
    checkout/
      application/
      domain/
      infrastructure/
  lib/
    lina-pay/
      client.ts
      mapper.ts
      types.ts

Boas Práticas de Integração do SDK

1. Instalar dependências:
   • npm i @lina-openx/web-lina-pay-sdk
2. Criar um adapter do SDK em src/lib/lina-pay/client.ts.
3. Inicializar o SDK apenas em ambiente client quando necessário.
4. Centralizar tratamento de erros do SDK e mapear para mensagens de UI.
5. Criar testes para fluxos críticos:
   • criação da intenção de pagamento;
   • callback com getPaymentRequest (SUCESSO quando PAGO, FALHA caso contrário);
   • confirmação e retorno de erro;
   • retry e feedback visual.

Configuração Inicial do SDK

Antes de usar o SDK, você pode configurar as URLs base para diferentes ambientes (homologação ou produção):

import { configure } from "@lina-openx/web-lina-pay-sdk";

// Configurar para produção
configure({
  iamBaseUrl: "https://iam.linaob.com.br",
  apiBaseUrl: "https://embedded-payment-manager.linaob.com.br",
});

// Configurar para homologação (padrão)
configure({
  iamBaseUrl: "https://iam.linaob.com.br",
  apiBaseUrl: "https://embedded-payment-manager.linaob.com.br",
});

Métodos do SDK para integração no momento do redirecionamento após selecionar o meio de pagamento e o produto

1. configure(config: Partial<LinaPayConfig>)

Configura as URLs base do SDK para diferentes ambientes.

Parâmetros:

• config: Objeto parcial com as configurações:
  • iamBaseUrl (string, opcional): URL base do serviço de IAM
  • apiBaseUrl (string, opcional): URL base da API de pagamentos

Exemplo:

configure({
  iamBaseUrl: "https://iam.prod.linaob.com.br",
  apiBaseUrl: "https://embedded-payment-manager.prod.linaob.com.br",
});

2. createPaymentRequest(credentials, payload)

Cria uma solicitação de pagamento e redireciona para o portal de inicialização do pagamento.

Parâmetros:

• credentials: Objeto com credenciais do subtenant:
  • subtenantId (string): ID do subtenant
  • subtenantSecret (string): Secret do subtenant
• payload: Objeto CreatePaymentRequest com:
  • details (string): Detalhes do pagamento
  • txId (string): ID da transação (opcional)
  • redirectUri (string): URI de redirecionamento
  • cpfCnpj (string): CPF ou CNPJ do cliente
  • value (number): Valor do pagamento
  • creditor (objeto): Detalhes do crédito
    • personType (string): Tipo de pessoa ('PESSOA_JURIDICA' | 'PESSOA_NATURAL')
    • cpfCnpj (string): CPF ou CNPJ do cliente
    • name (string): Nome do cliente
    • accountNumber (string): Número da conta
    • accountIssuer (string): Emissor da conta
    • accountIspb (string): ISPB da conta
    • accountType (string): Tipo de conta ('CACC' | 'SVGS')

Retorna: Promise<CreatePaymentResponse> com id e redirectUrl

Exemplo:

const consent = await createPaymentRequest(
  {
    subtenantId: 'seu-subtenant-id',
    subtenantSecret: 'seu-subtenant-secret'
  },
  {
    "details": "Detalhes do pagamento",
    "redirectUri": "https://redirect-demo-opal.vercel.app",
    "cpfCnpj": "08116143018",
    "value": 0.01,
    "creditor": {
      "personType": "PESSOA_JURIDICA",
      "cpfCnpj": "50685362006773",
      "name": "Ralph Bragg"
      "accountNumber": "11188222",
      "accountIssuer": "0001",
      "accountIspb": "99999004",
      "accountType": "SVGS",
    }
  }
)

• Usar o retorno redirectUrl para redirecionar o usuário para o portal de inicialização do pagamento.

3. Fluxo de callback — getPaymentRequest(credentials, id)

Após o usuário concluir (ou sair) do fluxo no portal Lina, a aplicação white-label recebe o retorno na URL configurada em redirectUri do createPaymentRequest. Nessa rota, use getPaymentRequest do @lina-openx/web-lina-pay-sdk para obter o estado atual da solicitação e montar a tela de resultado.

Função (conforme skill web-lina-pay-sdk):

• Assinatura: (credentials: LinaPayCredentials, id: string) => Promise<PaymentRequestData>
• id: o mesmo identificador retornado por createPaymentRequest (persistir na sessão ou receber por query string no retorno, conforme contrato do redirect do produto).
• O SDK chama GET …/requests/:id, obtém o token internamente e devolve PaymentRequestData. Na consulta, a API costuma preencher mais campos do que na criação (status, value, creditor, debitor, payments, datas, etc.) — ver distinção createPaymentRequest vs getPaymentRequest em web-lina-pay-sdk/SKILL.md e tipos em web-lina-pay-sdk/reference.md.

Regra de interface (obrigatória nesta skill):

• Exibir SUCESSO quando o status do pagamento for PAGO (tipo PaymentItemStatus nos itens de payments).
• Exibir FALHA quando o status for qualquer valor diferente de PAGO (incluindo pendências, erros, expirado, ou ausência de itens/payments vazio até haver conclusão com PAGO).

Onde checar PAGO: nos itens retornados em payments (cada item tem status). Exemplo de critério para uma solicitação com um ou mais itens:

import { getPaymentRequest } from "@lina-openx/web-lina-pay-sdk";

/** Resposta do GET costuma incluir `payments` com `status` por item — ver `reference.md` do skill web-lina-pay-sdk */
type EnrichedPaymentRequest = {
  payments?: Array<{ status: string }>;
};

function isPaidSuccess(data: EnrichedPaymentRequest): boolean {
  const items = data.payments ?? [];
  return items.some((p) => p.status === "PAGO");
}

Arquitetura no Next.js:

• Chamar getPaymentRequest no servidor (Server Component, Route Handler ou Server Action) com subtenantId / subtenantSecret vindos de process.env, para não expor credenciais no client.
• A página de callback pode ser Client Component que consome GET /api/payment-requests/[id] (handler interno que chama o SDK), ou um Server Component assíncrono que chama o SDK diretamente e repassa apenas dados necessários para componentes de UI (ShadCN: Alert, Card, tipografia de sucesso/erro).
• Tratar LinaPayError (try/catch, instanceof LinaPayError, statusCode) e mapear para mensagem amigável na variante FALHA.
• Apresentar em tela os dados úteis do retorno (valor, identificadores, status exibido para suporte), sem vazar segredos.

Exemplo mínimo (Route Handler + decisão SUCESSO/FALHA):

// app/api/payment-requests/[id]/route.ts
import { getPaymentRequest, LinaPayError } from "@lina-openx/web-lina-pay-sdk";
import { NextResponse } from "next/server";

export async function GET(
  _request: Request,
  context: { params: Promise<{ id: string }> }
) {
  const { id } = await context.params;
  if (!id) {
    return NextResponse.json({ error: "missing id" }, { status: 400 });
  }
  try {
    const data = await getPaymentRequest(
      {
        subtenantId: process.env.LINA_SUBTENANT_ID!,
        subtenantSecret: process.env.LINA_SUBTENANT_SECRET!,
      },
      id
    );
    const items = "payments" in data && Array.isArray((data as { payments?: unknown }).payments)
      ? (data as { payments: Array<{ status: string }> }).payments
      : [];
    const outcome = items.some((p) => p.status === "PAGO") ? "SUCESSO" : "FALHA";
    return NextResponse.json({ outcome, data });
  } catch (e) {
    if (e instanceof LinaPayError) {
      return NextResponse.json(
        { outcome: "FALHA", statusCode: e.statusCode, message: e.message },
        { status: e.statusCode ?? 500 }
      );
    }
    throw e;
  }
}

A página de retorno consome esse JSON (ou equivalente via Server Component) e renderiza UI distinta para outcome === "SUCESSO" vs outcome === "FALHA", exibindo os campos de data relevantes para o usuário.

Boas Práticas de UI/UX (ShadCN-UI)

• Usar componentes acessíveis (Button, Input, Form, Dialog, Alert).
• Garantir feedback visual de carregamento no checkout (skeleton/spinner).
• Exibir erros de pagamento de forma clara e acionável.
• Preservar consistência visual com tokens e tema centralizado.
• Evitar bloqueio da jornada: sempre oferecer opção de tentar novamente.

Segurança e Confiabilidade

• Validar payloads com schema (ex.: Zod) antes de enviar ao SDK.
• Sanitizar e validar entradas de usuário.
• Implementar logs de erro sem expor dados sensíveis.
• Preferir idempotência em chamadas de backend relacionadas ao pagamento.

Performance

• Minimizar bundle de checkout com importação sob demanda.
• Evitar renderização desnecessária de componentes client.
• Usar cache e revalidação no lado servidor para dados de catálogo.

Prompt Base para Uso da Skill

Quando esta Skill for acionada, seguir este fluxo:

1. Confirmar requisitos do checkout (campos, meios de pagamento, regras).
2. Propor arquitetura em Next.js App Router com separação server/client.
3. Implementar integração via adapter do @lina-openx/web-lina-pay-sdk.
4. Construir interface com ShadCN-UI.
5. Garantir tratamento de estado, erro, loading e sucesso.
6. Implementar rota de callback com getPaymentRequest, regra SUCESSO/PAGO vs FALHA e UI ShadCN-UI.
7. Sugerir testes e checklist de validação final.

Referência

• Documentação do pacote: https://www.npmjs.com/package/@lina-openx/web-lina-pay-sdk
• Recomendação de skill: https://github.com/Lina-Infratech/lina-pay-skills/blob/main/web-lina-pay-sdk/SKILL.md