@lina-openx/web-lina-pay-sdk

SDK para criação de pagamentos Open Finance de forma simples e integrada.

📋 Descrição

O @lina-openx/web-lina-pay-sdk é um SDK TypeScript desenvolvido para facilitar a integração com a plataforma Lina OpenX para criação e gerenciamento de pagamentos Open Finance. O SDK oferece uma interface simples e type-safe para realizar operações como:

• Criação de consentimentos de pagamento
• Criação e consulta de solicitações de pagamento automático / recorrente (createAutomaticPaymentRequest, getAutomaticPaymentRequest), com autenticação por subtenant ou token Bearer (TokenCredentials)
• Criação de solicitações de pagamento (payment request)
• Consulta dos detalhes de uma solicitação de pagamento pelo identificador
• Criação de pagamentos
• Gerenciamento de enrollments (cadastros de dispositivos)
• Consulta de participantes
• Gestão de contas de recebimento do subtenant (createReceivingAccount, listReceivingAccounts, getReceivingAccount, updateReceivingAccount, deleteReceivingAccount) e consulta de identificadores bancários (getBankIdentifiers, getBankIdentifier)
• Jornada otimizada (Linked Journey): criação de vínculo único de consentimento Data Link + enrollment (createOptimizedBinding), consulta de consentimento (getConsentById) e listagem de contas vinculadas por usuário (getAccountsByUserId), expostos via linkedJourney
• Integração com FIDO2/WebAuthn para autenticação segura

📦 Instalação

npm install @lina-openx/web-lina-pay-sdk

ou

yarn add @lina-openx/web-lina-pay-sdk

ou

pnpm add @lina-openx/web-lina-pay-sdk

🚀 Como Usar

Importação

import {
  configure,
  createConsent,
  createPaymentRequest,
  getPaymentRequest,
  createPayment,
  createEnrollment,
  getEnrollmentList,
  revokeEnrollment,
  registerDevice,
  createPaymentWithEnrollment,
  getParticipants,
  createAutomaticPaymentRequest,
  getAutomaticPaymentRequest,
  createReceivingAccount,
  listReceivingAccounts,
  getReceivingAccount,
  updateReceivingAccount,
  deleteReceivingAccount,
  getBankIdentifiers,
  getBankIdentifier,
  linkedJourney,
  LinaPayError
} from '@lina-openx/web-lina-pay-sdk'

// Funções de jornada otimizada (Linked Journey) são expostas via namespace:
// linkedJourney.createOptimizedBinding(...)
// linkedJourney.getConsentById(...)
// linkedJourney.getAccountsByUserId(...)

Configuração Inicial

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.hml.linaob.com.br',
  apiBaseUrl: 'https://embedded-payment-manager.hml.linaob.com.br'
})

📚 Métodos Disponíveis

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.linaob.com.br',
  apiBaseUrl: 'https://embedded-payment-manager.linaob.com.br'
})

2. createConsent(credentials, payload)

Cria um consentimento de pagamento Open Finance.

Parâmetros:

• credentials: Objeto com credenciais do subtenant:
  • subtenantId (string): ID do subtenant
  • subtenantSecret (string): Secret do subtenant
• payload: Objeto CreateConsentRequest com:
  • organisationId (string): ID da organização
  • authorisationServerId (string): ID do servidor de autorização
  • payment (objeto): Detalhes do pagamento
  • redirectUri (string, opcional): URI de redirecionamento
  • platform (string, opcional): Plataforma ('APP' | 'WEB')

Retorna: Promise<CreateConsentResponse> com consentId e redirectUrl

Exemplo:

const consent = await createConsent(
  {
    subtenantId: 'seu-subtenant-id',
    subtenantSecret: 'seu-subtenant-secret'
  },
  {
    organisationId: 'c8f0bf49-4744-4933-8960-7add6e590841',
    authorisationServerId: 'c8f0bf49-4744-4933-8960-7add6e590841',
    payment: {
      redirectUri: 'https://exemplo.com/redirect',
      value: 1500.50,
      creditor: {
        name: 'João Silva',
        personType: 'PESSOA_NATURAL',
        cpfCnpj: '12345678901',
        accountNumber: '12345-6',
        accountIssuer: '0001',
        accountPixKey: '[email protected]',
        accountIspb: '12345678',
        accountType: 'CACC'
      }
    },
    platform: 'WEB'
  }
)

console.log('Consent ID:', consent.consentId)
console.log('Redirect URL:', consent.redirectUrl)

Exemplo com agendamento:

const consent = await createConsent(
  credentials,
  {
    organisationId: 'org-id',
    authorisationServerId: 'auth-id',
    payment: {
      redirectUri: 'https://exemplo.com/redirect',
      value: 100.00,
      creditor: { /* ... */ },
      schedule: {
        monthly: {
          dayOfMonth: 15,
          startDate: '2024-01-15',
          quantity: 12
        }
      }
    }
  }
)

3. createPayment(credentials, payload)

Cria um pagamento após o consentimento ser autorizado.

Parâmetros:

• credentials: Objeto com credenciais do subtenant
• payload: Objeto CreatePaymentRequest com:
  • state (string): Estado do fluxo OAuth
  • code (string): Código de autorização
  • idToken (string): Token de identificação
  • tenantId (string): ID do tenant

Retorna: Promise<CreatePaymentResponse> com detalhes do pagamento

Exemplo:

const payment = await createPayment(
  {
    subtenantId: 'seu-subtenant-id',
    subtenantSecret: 'seu-subtenant-secret'
  },
  {
    state: 'rumUP',
    code: '1RDYVFQnPn721',
    idToken: 'eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9...',
    tenantId: 'tenant-id-123'
  }
)

console.log('Payment ID:', payment.id)
console.log('Status:', payment.status)
console.log('Value:', payment.value)

4. createPaymentRequest(credentials, payload)

Cria uma solicitação de pagamento na API (POST no endpoint de payment request). O fluxo é distinto de createPayment: aqui você envia os dados do pagamento (valor, credor, URI de retorno etc.) e recebe um identificador e uma redirectUri para continuar o fluxo no ambiente da detentora. O token de acesso é obtido automaticamente a partir das credenciais do subtenant.

Parâmetros:

• credentials: objeto LinaPayCredentials (subtenantId, subtenantSecret)
• payload: objeto CreatePaymentRequestDTO validado antes do envio:
  • details (string): descrição ou detalhes do pagamento
  • redirectUri (string): URL de redirecionamento após o fluxo
  • cpfCnpj (string): CPF ou CNPJ do pagador (formato livre; a API pode normalizar)
  • value (number): valor do pagamento
  • creditor (objeto): dados do favorecido, alinhados ao tipo Creditor do consentimento:
    • name, personType (PESSOA_NATURAL | PESSOA_JURIDICA), cpfCnpj, accountNumber, accountIssuer, accountIspb, accountType (CACC | SLRY | SVGS | TRAN)
    • accountPixKey (string, opcional)
  • txId (string ou array de strings, opcional): identificador(es) de transação Pix, se aplicável
  • externalId (string, opcional): identificador externo
  • schedule (objeto): na validação atual do SDK, a chave schedule deve estar presente; pode ser um objeto vazio {} ou conter apenas um dos tipos de agenda abaixo (campos internos conforme validação):
    • single: { date } (data YYYY-MM-DD)
    • daily: { startDate, quantity } (quantity numérico)
    • weekly: { startDate, quantity, dayOfWeek } (dayOfWeek: SEGUNDA_FEIRA … DOMINGO)
    • monthly: { startDate, quantity, dayOfMonth }
    • custom: { dates: string[], additionalInformation? }

Retorna: Promise<PaymentRequestCreated> com:

• id (string): identificador da solicitação (use em getPaymentRequest ou no fluxo subsequente)
• redirectUri (string): URI para seguir o fluxo de autorização/pagamento

Erros: falhas de validação do payload resultam em LinaPayError com a mensagem Invalid payload. Erros HTTP e de rede seguem o mesmo padrão dos demais métodos do SDK.

Exemplo:

import {
  createPaymentRequest,
  type CreatePaymentRequestDTO,
  type PaymentRequestCreated,
} from '@lina-openx/web-lina-pay-sdk'

const result: PaymentRequestCreated = await createPaymentRequest(
  {
    subtenantId: 'seu-subtenant-id',
    subtenantSecret: 'seu-subtenant-secret',
  },
  {
    details: 'Pagamento de serviço',
    redirectUri: 'https://exemplo.com/retorno',
    cpfCnpj: '12345678901',
    value: 150.5,
    creditor: {
      name: 'Maria Souza',
      personType: 'PESSOA_NATURAL',
      cpfCnpj: '98765432100',
      accountNumber: '12345-6',
      accountIssuer: '0001',
      accountPixKey: '[email protected]',
      accountIspb: '12345678',
      accountType: 'CACC',
    },
    schedule: {},
  } satisfies CreatePaymentRequestDTO,
)

console.log('ID da solicitação:', result.id)
console.log('Redirect:', result.redirectUri)

Exemplo com txId e agendamento único:

await createPaymentRequest(credentials, {
  details: 'Pagamento agendado',
  txId: 'E123456782024...',
  redirectUri: 'https://exemplo.com/callback',
  cpfCnpj: '12345678901',
  value: 200,
  creditor: {
    /* ... */
  },
  schedule: {
    single: { date: '2026-02-15' },
  },
})

5. getPaymentRequest(credentials, id)

Consulta os detalhes de uma solicitação de pagamento já criada. O SDK chama GET no endpoint de payment requests (…/requests/:id) com o token obtido automaticamente a partir das credenciais do subtenant.

Parâmetros:

• credentials: objeto LinaPayCredentials (subtenantId, subtenantSecret)
• id (string): identificador da solicitação — em geral o mesmo id retornado por createPaymentRequest

Retorna: Promise<PaymentRequestData> — o SDK devolve apenas o objeto data da resposta (sem o envelope message / type). Campos tipados pelo pacote:

| Campo | Tipo | Descrição | |--------|------|-----------| | id | string | Identificador da solicitação | | createDateTime | string | ISO 8601 | | lastChangedDateTime | string | ISO 8601 | | externalComment | string \| null | | | externalId | string \| null | | | cpfCnpj | string \| null | | | redirectUri | string | | | tenantId | string | | | consentId | string \| null | | | value | number | | | status | string | | | creditor | objeto | name, personType, cpfCnpj, contas, accountPixKey, etc. | | debitor | objeto | accountNumber, accountIssuer, accountIspb, accountType | | type | string \| null | | | payments | PaymentRequestPaymentItem[] | Itens/parcelas (id, dueDate, status, txId, etc.) | | requestExpiresAt | string \| null | Opcional | | businessCnpj | string \| null | Opcional |

Datas vêm como string (JSON da API), não como Date em runtime.

Erros: respostas HTTP de erro e falhas de rede propagam LinaPayError, como nos demais métodos.

Exemplo:

import {
  createPaymentRequest,
  getPaymentRequest,
  type PaymentRequestData,
} from '@lina-openx/web-lina-pay-sdk'

const created = await createPaymentRequest(credentials, payload)

const details: PaymentRequestData = await getPaymentRequest(credentials, created.id)

console.log('Status:', details.status)
console.log('Valor:', details.value)
console.log('Redirect:', details.redirectUri)

6. createEnrollment(credentials, payload)

Cria um enrollment (cadastro de dispositivo) para pagamentos recorrentes com autenticação FIDO2.

Parâmetros:

• credentials: Objeto com credenciais do subtenant
• payload: Objeto CreateEnrollmentRequest com:
  • organisationId (string): ID da organização
  • authorisationServerId (string): ID do servidor de autorização
  • enrollment (objeto): Detalhes do enrollment
  • redirectUri (string): URI de redirecionamento
  • paymentId (string, opcional): ID do pagamento relacionado

Retorna: Promise<CreateEnrollmentResponse> com consentId e redirectUrl

Exemplo:

const enrollment = await createEnrollment(
  {
    subtenantId: 'seu-subtenant-id',
    subtenantSecret: 'seu-subtenant-secret'
  },
  {
    organisationId: 'c8f0bf49-4744-4933-8960-7add6e590841',
    authorisationServerId: 'c8f0bf49-4744-4933-8960-7add6e590841',
    enrollment: {
      deviceName: 'Meu Dispositivo',
      document: '12345678901', // CPF sem formatação
      debtor: {
        accountIspb: '00000000',
        accountIssuer: '2558',
        accountNumber: '5271110',
        accountType: 'CACC'
      }
    },
    redirectUri: 'https://exemplo.com/redirect'
  }
)

console.log('Enrollment Consent ID:', enrollment.consentId)

7. registerDevice(credentials, payload)

Registra um dispositivo após o callback do enrollment, validando e processando o registro FIDO2.

Parâmetros:

• credentials: Objeto com credenciais do subtenant
• payload: Objeto RegisterDeviceRequest com:
  • state (string): Estado do fluxo OAuth
  • code (string): Código de autorização
  • idToken (string): Token de identificação
  • tenantId (string): ID do tenant
  • platform (string): Plataforma ('ANDROID' | 'IOS' | 'WEB' | 'BROWSER' | 'CROSS_PLATFORM')
  • rp (string, opcional): Relying Party identifier

Retorna: Promise<Enrollment> com detalhes do enrollment registrado

Exemplo:

const enrollment = await registerDevice(
  {
    subtenantId: 'seu-subtenant-id',
    subtenantSecret: 'seu-subtenant-secret'
  },
  {
    state: 'rumUP',
    code: '1RDYVFQnPn721',
    idToken: 'eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9...',
    tenantId: 'tenant-id-123',
    platform: 'WEB'
  }
)

console.log('Enrollment ID:', enrollment.id)
console.log('Device Name:', enrollment.deviceName)

8. getEnrollmentList(credentials, cpf)

Obtém a lista de enrollments registrados para um CPF.

Parâmetros:

• credentials: Objeto com credenciais do subtenant
• cpf (string): CPF do usuário (com ou sem formatação)

Retorna: Promise<EnrollmentList> com array de enrollments

Exemplo:

const enrollments = await getEnrollmentList(
  {
    subtenantId: 'seu-subtenant-id',
    subtenantSecret: 'seu-subtenant-secret'
  },
  '12345678901'
)

console.log('Total de enrollments:', enrollments.length)
enrollments.forEach(enrollment => {
  console.log(`- ${enrollment.deviceName} (ID: ${enrollment.id})`)
})

9. revokeEnrollment(credentials, enrollmentId)

Revoga (remove) um enrollment específico.

Parâmetros:

• credentials: Objeto com credenciais do subtenant
• enrollmentId (string): ID do enrollment a ser revogado

Retorna: Promise<RevokeEnrollmentResponse> com status da revogação

Exemplo:

const result = await revokeEnrollment(
  {
    subtenantId: 'seu-subtenant-id',
    subtenantSecret: 'seu-subtenant-secret'
  },
  '1728979312391739'
)

console.log('Enrollment revogado com sucesso')

10. createPaymentWithEnrollment(credentials, payload)

Cria um pagamento usando um enrollment existente (pagamento recorrente com autenticação FIDO2).

Parâmetros:

• credentials: Objeto com credenciais do subtenant
• payload: Objeto PaymentWithEnrollmentRequest com:
  • enrollmentId (string): ID do enrollment
  • organisationId (string): ID da organização
  • authorisationServerId (string): ID do servidor de autorização
  • payment (objeto): Detalhes do pagamento
  • fidoSignOptions (objeto): Opções de assinatura FIDO2
  • paymentId (string, opcional): ID do pagamento relacionado

Retorna: Promise<RetornoJsrPaymentDto> com detalhes do pagamento criado

Exemplo:

const payment = await createPaymentWithEnrollment(
  {
    subtenantId: 'seu-subtenant-id',
    subtenantSecret: 'seu-subtenant-secret'
  },
  {
    enrollmentId: 'enrollment-id-123',
    organisationId: 'c8f0bf49-4744-4933-8960-7add6e590841',
    authorisationServerId: 'c8f0bf49-4744-4933-8960-7add6e590841',
    payment: {
      redirectUri: 'https://exemplo.com/redirect',
      value: 1500.50,
      creditor: {
        name: 'João Silva',
        personType: 'PESSOA_NATURAL',
        cpfCnpj: '12345678901',
        accountNumber: '12345-6',
        accountIssuer: '0001',
        accountPixKey: '[email protected]',
        accountIspb: '12345678',
        accountType: 'CACC'
      }
    },
    fidoSignOptions: {
      rp: 'relying-party-id',
      platform: 'WEB'
    }
  }
)

console.log('Payment ID:', payment.id)
console.log('Status:', payment.status)

11. getParticipants(credentials)

Obtém a lista de participantes (bancos) registrados na plataforma Lina Open Finance.

Parâmetros:

• credentials: Objeto com credenciais do subtenant

Retorna: Promise<Participant[]> com array de participantes

Exemplo:

const participants = await getParticipants({
  subtenantId: 'seu-subtenant-id',
  subtenantSecret: 'seu-subtenant-secret'
})

console.log('Participantes disponíveis:')
participants.forEach(participant => {
  console.log(`- ${participant.name} (ISPB: ${participant.ispb})`)
})

12. Pagamento automático / recorrente

Fluxos de criação e consulta de solicitação de pagamento automático (consentimento recorrente). Ambos aceitam o mesmo parâmetro credentials, com duas formas de autenticação:

1. LinaPayCredentials — subtenantId e subtenantSecret: o SDK chama o IAM (client_credentials), usa cache de token quando aplicável e envia Authorization: Bearer ….
2. TokenCredentials — apenas { access_token: string }: o SDK não chama o IAM; usa o valor como Bearer nas requisições (útil quando o access token já foi obtido por outro fluxo ou serviço).

Os tipos são mutuamente exclusivos (TokenCredentials em auth.types.ts impede subtenantId/subtenantSecret no mesmo objeto tipado).

12.1 createAutomaticPaymentRequest(credentials, payload)

Cria uma solicitação de pagamento automático / recorrente (consentimento recorrente com configuração automática ou de varredura). O SDK valida o payload com Zod e envia POST para o mesmo endpoint base de pagamentos usado por outras operações de payment request (apiBaseUrl configurada + rota de pagamentos). A resposta exposta pelo SDK é apenas o objeto data retornado pela API.

Parâmetros:

• credentials: LinaPayCredentials ou TokenCredentials (ver introdução do §12)
• payload: objeto CreateAutomaticPaymentRequest (inferido do schema Zod em automatic-payment.utils), em resumo:
  • redirectUri (string): URI de retorno do fluxo (campo no topo do payload; alinhado à API / Open Finance)
  • recurringConsent (objeto):
    • loggedUser.document: rel (CPF | CNPJ) e identification (string)
    • businessEntity (opcional): document com rel: 'CNPJ' e identification
    • creditors: array de { name, personType ('PESSOA_NATURAL' | 'PESSOA_JURIDICA'), cpfCnpj }
    • additionalInformation (string, opcional)
    • debtorAccount (opcional): ispb, issuer, number, accountType (CACC | SLRY | SVGS | TRAN)
    • recurringConfiguration: exatamente um dos ramos:
      • automatic: contractId, interval (SEMANAL | MENSAL | ANUAL | SEMESTRAL), referenceStartDate, contractDebtor (name, document), opcionais fixedAmount, minimumVariableAmount, maximumVariableAmount, isRetryAccepted, e obrigatório pelo menos um entre firstPayment (Pix: type, date, currency, amount, remittanceInformation, creditorAccount) ou paymentConfig (amount, remittanceInformation, creditorAccount) — validação customizada no schema
      • sweeping: totalAllowedAmount, transactionLimit, periodicLimits (objeto com apenas um de day | week | month | year, cada um com quantityLimit e transactionLimit), startDateTime
  • canBeAutomaticallyRevoked (boolean, opcional)

Retorna: Promise<AutomaticPaymentRequestCreated> com:

• redirectUrl (string)
• paymentRequestId (string)

Erros: payload inválido → LinaPayError com mensagem Invalid payload. Demais erros HTTP/rede seguem o padrão do SDK.

Exemplo (configuração automática simplificada):

import {
  createAutomaticPaymentRequest,
  type CreateAutomaticPaymentRequest,
  type AutomaticPaymentRequestCreated,
} from '@lina-openx/web-lina-pay-sdk'

const result: AutomaticPaymentRequestCreated = await createAutomaticPaymentRequest(
  {
    subtenantId: 'seu-subtenant-id',
    subtenantSecret: 'seu-subtenant-secret',
  },
  {
    redirectUri: 'https://exemplo.com/retorno',
    recurringConsent: {
      loggedUser: {
        document: { rel: 'CPF', identification: '12345678901' },
      },
      creditors: [
        {
          name: 'Acme Ltda',
          personType: 'PESSOA_JURIDICA',
          cpfCnpj: '12345678000199',
        },
      ],
      recurringConfiguration: {
        automatic: {
          contractId: 'CTR-001',
          interval: 'MENSAL',
          referenceStartDate: '2026-01-01',
          contractDebtor: {
            name: 'Maria',
            document: { identification: '12345678901', rel: 'CPF' },
          },
          paymentConfig: {
            amount: '150.00',
            remittanceInformation: 'Mensalidade',
            creditorAccount: {
              ispb: '00000000',
              issuer: '0001',
              number: '123456',
              accountType: 'CACC',
            },
          },
        },
      },
    },
  } satisfies CreateAutomaticPaymentRequest,
)

console.log('ID:', result.paymentRequestId)
console.log('Redirect:', result.redirectUrl)

Exemplo com token direto:

import {
  createAutomaticPaymentRequest,
  type CreateAutomaticPaymentRequest,
  type TokenCredentials,
} from '@lina-openx/web-lina-pay-sdk'

const tokenAuth: TokenCredentials = {
  access_token: await myApp.getEmbeddedPaymentAccessToken(),
}

await createAutomaticPaymentRequest(
  tokenAuth,
  {
    redirectUri: 'https://exemplo.com/retorno',
    recurringConsent: {
      /* ... mesmo formato do exemplo principal §12.1 (incl. firstPayment ou paymentConfig no ramo automatic) */
    },
  } satisfies CreateAutomaticPaymentRequest,
)

12.2 getAutomaticPaymentRequest(credentials, payload)

Consulta os detalhes de uma solicitação de pagamento automático já criada.

Parâmetros:

• credentials: LinaPayCredentials ou TokenCredentials (igual ao §12.1)
• payload: objeto GetAutomaticPaymentRequest com paymentRequestId (string não vazia; em geral o valor de AutomaticPaymentRequestCreated.paymentRequestId após a criação)

HTTP: GET em …/payments/request/:paymentRequestId (sobre a base PAYMENTS_REQUEST configurada).

Retorna: Promise<AutomaticPaymentRequest> — conteúdo de data da API (estrutura ampla: status, consentimento, credores, configurações recorrentes, automaticPayments, subTenant, etc.; ver src/types/automatic-payment.types.ts).

Erros: paymentRequestId inválido ou vazio → LinaPayError Invalid payload. Demais erros HTTP/rede como nos outros métodos.

Exemplo:

import {
  createAutomaticPaymentRequest,
  getAutomaticPaymentRequest,
  type AutomaticPaymentRequestCreated,
  type AutomaticPaymentRequest,
} from '@lina-openx/web-lina-pay-sdk'

const created: AutomaticPaymentRequestCreated = await createAutomaticPaymentRequest(credentials, payload)
const details: AutomaticPaymentRequest = await getAutomaticPaymentRequest(credentials, {
  paymentRequestId: created.paymentRequestId,
})
console.log(details.status, details.redirectUri)

13. Contas de recebimento (sub-tenants-accounts)

O SDK expõe cinco métodos para contas de recebimento e dois para identificadores bancários na API apiBaseUrl + /api/v1/sub-tenants-accounts. O token pode ser obtido com LinaPayCredentials (subtenantId / subtenantSecret no IAM) ou passado diretamente como TokenCredentials (access_token), como nos demais controllers. Nos payloads de contas, subTenantId é o identificador usado na URL da API de contas (segmento :subTenantId); pode coincidir ou não com o subtenantId das credenciais, conforme o modelo da sua integração.

Validação de entrada: Zod nos utilitários receiving-accounts.utils; falha → LinaPayError Invalid payload. Em caso de sucesso, o SDK devolve o conteúdo de data da resposta JSON da API (tipado como ReceivingAccount, ReceivingAccount[], BankIdentifier ou BankIdentifier[], conforme o método).

13.1 createReceivingAccount(credentials, payload)

Parâmetros:

• credentials: LinaPayCredentials | TokenCredentials
• payload: CreateReceivingAccountRequest
  • subTenantId (string): id na rota da API de contas
  • account: bankIspb, agency, accountNumber, accountType (CACC | SLRY | SVGS | TRAN), holderName, holderDocument

HTTP: POST …/:subTenantId/receiving-accounts — corpo enviado = apenas account (objeto).

Retorna: Promise<ReceivingAccount>

Exemplo:

import { createReceivingAccount, type CreateReceivingAccountRequest } from '@lina-openx/web-lina-pay-sdk'

const created = await createReceivingAccount(credentials, {
  subTenantId: 'id-na-rota',
  account: {
    bankIspb: '00000000',
    agency: '0001',
    accountNumber: '12345-6',
    accountType: 'CACC',
    holderName: 'Loja Exemplo',
    holderDocument: '12345678000199',
  },
} satisfies CreateReceivingAccountRequest)

console.log(created.id, created.createdAt)

13.2 listReceivingAccounts(credentials, payload)

Parâmetros:

• credentials: LinaPayCredentials | TokenCredentials
• payload: { subTenantId: string } (tipo BaseReceivingAccountRequest sem accountId)

HTTP: GET …/:subTenantId/receiving-accounts

Retorna: Promise<ReceivingAccount[]>

13.3 getReceivingAccount(credentials, payload)

Parâmetros:

• credentials: LinaPayCredentials | TokenCredentials
• payload: subTenantId e accountId (obrigatório)

HTTP: GET …/:subTenantId/:accountId

Retorna: Promise<ReceivingAccount>

13.4 updateReceivingAccount(credentials, payload)

Parâmetros:

• credentials: LinaPayCredentials | TokenCredentials
• payload: UpdateReceivingAccountRequest — subTenantId, accountId, account com campos opcionais (parcial sobre o mesmo formato da conta)

HTTP: PATCH …/:subTenantId/:accountId — corpo atual = JSON.stringify(payload) (objeto completo do payload).

Retorna: Promise<ReceivingAccount>

13.5 deleteReceivingAccount(credentials, payload)

Parâmetros:

• credentials: LinaPayCredentials | TokenCredentials
• payload: subTenantId e accountId (obrigatório)

HTTP: DELETE …/:subTenantId/:accountId

Retorna: Promise<ReceivingAccount> (conteúdo de data conforme contrato da API)

13.6 getBankIdentifiers(credentials, payload)

Parâmetros:

• credentials: LinaPayCredentials | TokenCredentials
• payload: GetBankIdentifiersRequest — search e limit opcionais (strings; só são enviados na query quando não vazios)

HTTP: GET …/sub-tenants-accounts/bank-identifiers com query opcional search, limit

Retorna: Promise<BankIdentifier[]>

Exemplo:

import { getBankIdentifiers, type GetBankIdentifiersRequest } from '@lina-openx/web-lina-pay-sdk'

const list = await getBankIdentifiers(credentials, {
  search: 'Ita',
  limit: '20',
} satisfies GetBankIdentifiersRequest)
console.log(list.map((b) => b.ispb))

13.7 getBankIdentifier(credentials, payload)

Parâmetros:

• credentials: LinaPayCredentials | TokenCredentials
• payload: GetBankIdentifierRequest — bankIspb (string não vazia; codificado na URL)

HTTP: GET …/sub-tenants-accounts/bank-identifiers/:bankIspb

Retorna: Promise<BankIdentifier>

Exemplo:

import { getBankIdentifier, type GetBankIdentifierRequest } from '@lina-openx/web-lina-pay-sdk'

const bank = await getBankIdentifier(credentials, { bankIspb: '60701190' } satisfies GetBankIdentifierRequest)
console.log(bank.name, bank.ispb)

14. Jornada Otimizada (linkedJourney)

Conjunto de métodos para a jornada otimizada (Linked Journey): criação de um vínculo único que combina consentimento Data Link e enrollment (JSR) numa só chamada, além de consulta do consentimento e das contas vinculadas. Diferente dos demais controllers, essas funções não são exportadas individualmente — são acessadas através do namespace linkedJourney:

import { linkedJourney } from '@lina-openx/web-lina-pay-sdk'

await linkedJourney.createOptimizedBinding(credentials, payload)
await linkedJourney.getConsentById(credentials, consentId)
await linkedJourney.getAccountsByUserId(credentials, userId)

Todas aceitam credentials como LinaPayCredentials (subtenantId/subtenantSecret, token obtido via IAM) ou TokenCredentials (access_token, usado diretamente como Bearer).

14.1 linkedJourney.createOptimizedBinding(credentials, payload)

Cria, em uma única chamada (POST …/jsr), o vínculo otimizado: consentimento Data Link + enrollment RP. O payload é o mesmo contrato de createEnrollment, validado com Zod (linked-journey.utils); IP do cliente e risk signals são coletados e enviados automaticamente.

Parâmetros:

• credentials: LinaPayCredentials | TokenCredentials
• payload: CreateEnrollmentRequest (sem riskSignals, preenchido internamente):
  • organisationId (string), authorisationServerId (string), redirectUri (string)
  • paymentId (string, opcional)
  • enrollment: document, deviceName, externalId (opcionais) e debtor opcional (accountNumber, accountIssuer, accountIspb, accountType: CACC | SVGS | TRAN)

Retorna: Promise<CreateLinkedJourneyResponse> com id, consentId (opcional) e redirectUrl (opcional)

Erros: payload inválido → LinaPayError; demais erros HTTP/rede seguem o padrão do SDK.

Exemplo:

import { linkedJourney, type CreateLinkedJourneyResponse } from '@lina-openx/web-lina-pay-sdk'

const result: CreateLinkedJourneyResponse = await linkedJourney.createOptimizedBinding(
  {
    subtenantId: 'seu-subtenant-id',
    subtenantSecret: 'seu-subtenant-secret'
  },
  {
    organisationId: 'c8f0bf49-4744-4933-8960-7add6e590841',
    authorisationServerId: 'c8f0bf49-4744-4933-8960-7add6e590841',
    redirectUri: 'https://exemplo.com/redirect',
    enrollment: {
      deviceName: 'Meu Dispositivo',
      document: '12345678901',
      debtor: {
        accountIspb: '00000000',
        accountIssuer: '2558',
        accountNumber: '5271110',
        accountType: 'CACC'
      }
    }
  }
)

console.log('ID:', result.id)
console.log('Redirect URL:', result.redirectUrl)

14.2 linkedJourney.getConsentById(credentials, consentId)

Consulta um consentimento Data Link pelo seu identificador (GET …/consents/:consentId).

Parâmetros:

• credentials: LinaPayCredentials | TokenCredentials
• consentId (string): identificador do consentimento, podendo ser uma URN (ex.: urn:raidiambank:consent:...); é codificado na URL

Retorna: Promise<DataLinkConsentData> com consentId, status, statusUpdateDateTime, permissions, creationDateTime, expirationDateTime e userId (opcional)

Exemplo:

import { linkedJourney } from '@lina-openx/web-lina-pay-sdk'

const consent = await linkedJourney.getConsentById(
  { subtenantId: 'seu-subtenant-id', subtenantSecret: 'seu-subtenant-secret' },
  'urn:raidiambank:consent:77535481-63b5-4e28-becb-0349158f9e35'
)

console.log('Status:', consent.status)

14.3 linkedJourney.getAccountsByUserId(credentials, userId)

Lista as contas Data Link vinculadas a um usuário (GET …/accounts/:userId).

Parâmetros:

• credentials: LinaPayCredentials | TokenCredentials
• userId (string): identificador do usuário no Data Link (UUID); é codificado na URL

Retorna: Promise<DataLinkAccountItem[]>, cada item com accountId, brandName, companyCnpj, type, compeCode, branchCode, number, checkDigit, status, e opcionalmente brandCnpj, balance (DataLinkAccountBalance) e details (DataLinkAccountDetails)

Exemplo:

import { linkedJourney } from '@lina-openx/web-lina-pay-sdk'

const accounts = await linkedJourney.getAccountsByUserId(
  { subtenantId: 'seu-subtenant-id', subtenantSecret: 'seu-subtenant-secret' },
  '283f1e2e-0d99-46e9-a4a6-91e41add490c'
)

accounts.forEach((account) => {
  console.log(`- ${account.brandName} (${account.number}-${account.checkDigit})`)
})

🏗️ Organização de Pastas

src/
├── config/              # Configurações do SDK
│   └── environment.ts  # Configuração de URLs e endpoints
├── controllers/        # Controllers públicos (API do SDK)
│   ├── config.controller.ts
│   ├── consent.controller.ts
│   ├── enrollment.controller.ts
│   ├── participants.controller.ts
│   ├── payment.controller.ts
│   ├── automatic-payments.controller.ts
│   ├── receiving-accounts.controller.ts
│   ├── linked-journey.controller.ts
│   └── tests/          # Testes unitários dos controllers
├── services/           # Serviços de comunicação com APIs
│   ├── auth.service.ts
│   ├── consent.service.ts
│   ├── enrollment.service.ts
│   ├── fido.service.ts
│   ├── participants.service.ts
│   ├── payment.service.ts
│   ├── automatic-payments.service.ts
│   ├── receiving-accounts.service.ts
│   ├── linked-journey.service.ts
│   └── tests/          # Testes unitários dos services
├── types/              # Definições de tipos TypeScript
│   ├── auth.types.ts
│   ├── consent.types.ts
│   ├── enrollment.types.ts
│   ├── fido.types.ts
│   ├── index.ts
│   ├── participants.types.ts
│   ├── payment.types.ts
│   ├── automatic-payment.types.ts
│   ├── receiving-accounts.types.ts
│   └── linked-journey.types.ts
├── utils/              # Utilitários e validações
│   ├── consent.utils.ts
│   ├── enrollment.utils.ts
│   ├── error-handling.utils.ts
│   ├── payment.utils.ts
│   ├── automatic-payment.utils.ts
│   ├── receiving-accounts.utils.ts
│   ├── linked-journey.utils.ts
│   ├── ip.utils.ts
│   ├── validate-credentials.utils.ts
│   └── tests/          # Testes unitários dos utils
└── index.ts            # Ponto de entrada principal

Descrição das Pastas

• config/: Contém configurações globais do SDK, como URLs base e endpoints da API
• controllers/: Camada pública do SDK, expondo métodos que os desenvolvedores utilizam
• services/: Camada de comunicação com as APIs externas, lidando com requisições HTTP
• types/: Definições TypeScript para type-safety em todo o SDK
• utils/: Funções utilitárias para validação, tratamento de erros e outras operações auxiliares
• tests/: Testes unitários organizados por módulo

🛠️ Como Rodar Localmente

Pré-requisitos

• Node.js 18+
• npm, yarn ou pnpm

Instalação das Dependências

npm install

Scripts Disponíveis

# Executar testes em modo watch
npm run dev

# Executar todos os testes
npm run test

# Formatar código
npm run format

# Build do projeto
npm run build

# Executar CI completo (build + lint + test)
npm run ci

Desenvolvimento

1. Clone o repositório:

git clone [email protected]:lina-infratech/ob-data-pull/web-lina-pay-sdk.git
cd web-lina-pay-sdk

2. Instale as dependências:

npm install

3. Execute os testes para verificar se tudo está funcionando:

npm run test

4. Para desenvolvimento com watch mode:

npm run dev

5. Para build do projeto:

npm run build

O build gerará os arquivos compilados na pasta dist/.

Exemplo de Uso Local

Você pode testar o SDK localmente usando o projeto de exemplo na pasta example/:

cd example
npm install
npm run dev

⚠️ Tratamento de Erros

O SDK lança LinaPayError para erros de validação e comunicação. Sempre use try/catch ao chamar os métodos:

import { createConsent, LinaPayError } from '@lina-openx/web-lina-pay-sdk'

try {
  const consent = await createConsent(credentials, payload)
  console.log('Sucesso:', consent.consentId)
} catch (error) {
  if (error instanceof LinaPayError) {
    console.error('Erro do SDK:', error.message)
    console.error('Status Code:', error.statusCode)
  } else {
    console.error('Erro inesperado:', error)
  }
}

📝 Tipos Principais

LinaPayCredentials

interface LinaPayCredentials {
  subtenantId: string
  subtenantSecret: string
}

TokenCredentials

Usado em createAutomaticPaymentRequest e getAutomaticPaymentRequest quando o Bearer já é conhecido (não chama o IAM do SDK).

interface TokenCredentials {
  access_token: string
}

(subtenantId / subtenantSecret não fazem parte deste tipo — ver src/types/auth.types.ts.)

CreateConsentRequest

interface CreateConsentRequest {
  organisationId: string
  authorisationServerId: string
  payment: Payment
  redirectUri?: string
  platform?: 'APP' | 'WEB'
}

CreatePayment

Payload do método createPayment (callback OAuth após consentimento).

interface CreatePayment {
  state: string
  code: string
  idToken: string
  tenantId: string
}

CreatePaymentRequestDTO

Payload do método createPaymentRequest (solicitação de pagamento). O runtime valida com Zod; campos de schedule seguem as regras descritas na seção desse método.

interface CreatePaymentRequestDTO {
  details: string
  txId?: string | string[]
  externalId?: string
  redirectUri: string
  cpfCnpj: string
  value: number
  creditor: Creditor
  schedule?: { /* single | daily | weekly | monthly | custom — ver documentação */ }
}

PaymentRequestCreated

Retorno de createPaymentRequest.

interface PaymentRequestCreated {
  id: string
  redirectUri: string
}

PaymentRequestData

Retorno de getPaymentRequest (detalhes da solicitação após GET …/requests/:id).

interface PaymentRequestData {
  id: string
  createDateTime: string
  lastChangedDateTime: string
  externalComment: string | null
  externalId: string | null
  cpfCnpj: string | null
  redirectUri: string
  tenantId: string
  consentId: string | null
  value: number
  status: string
  creditor: {
    name: string
    personType: string
    cpfCnpj: string
    accountNumber: string
    accountIssuer: string
    accountPixKey: string | null
    accountIspb: string
    accountType: string
  }
  debitor: {
    accountNumber: string
    accountIssuer: string
    accountIspb: string
    accountType: string
  }
  type: string | null
  payments: PaymentRequestPaymentItem[]
  requestExpiresAt?: string | null
  businessCnpj?: string | null
}

PaymentRequestPaymentItem

Elementos do array PaymentRequestData.payments.

interface PaymentRequestPaymentItem {
  id: string
  endToEndId?: string | null
  dueDate: string
  externalComment: string | null
  txId: string | null
  externalPaymentId: string | null
  status: string
  rejectionReason: string | null
  rejectionReasonDetail: string | null
}

Para mais tipos, consulte os arquivos em src/types/.

CreateAutomaticPaymentRequest

Tipo inferido pelo schema Zod em automatic-payment.utils — payload de createAutomaticPaymentRequest.

Resumo: redirectUri no topo; recurringConsent com loggedUser, creditors, recurringConfiguration (automatic ou sweeping); opcionais businessEntity, additionalInformation, debtorAccount, canBeAutomaticallyRevoked. No ramo automatic, é necessário firstPayment ou paymentConfig. Lista completa e enums: §12.1 e ficheiro automatic-payment.utils.ts.

AutomaticPaymentRequestCreated

Retorno de createAutomaticPaymentRequest (objeto data da API).

interface AutomaticPaymentRequestCreated {
  redirectUrl: string
  paymentRequestId: string
}

GetAutomaticPaymentRequest

Parâmetro de consulta de getAutomaticPaymentRequest.

interface GetAutomaticPaymentRequest {
  paymentRequestId: string
}

AutomaticPaymentRequest

Retorno de getAutomaticPaymentRequest (objeto data da API). Estrutura extensa (status, consentimento, credores, recurringConfigurationAutomatic / Sweeping / Vrp, automaticPayments[], subTenant, etc.) — definição completa em src/types/automatic-payment.types.ts.

ReceivingAccount

Retorno típico dos métodos de contas de recebimento (conteúdo de data após unwrap).

interface ReceivingAccount {
  id: string
  bankIspb: string
  agency: string
  accountNumber: string
  accountType: string
  holderName: string
  holderDocument: string
  createdAt: string
  updatedAt: string
}

BaseReceivingAccountDTO

Campos da conta no corpo de criação (e referência para atualização parcial).

interface BaseReceivingAccountDTO {
  bankIspb: string
  agency: string
  accountNumber: string
  accountType: string
  holderName: string
  holderDocument: string
}

Na criação, accountType é validado em runtime como CACC | SLRY | SVGS | TRAN.

CreateReceivingAccountRequest

Payload de createReceivingAccount: subTenantId + account (BaseReceivingAccountDTO).

UpdateReceivingAccountRequest

Payload de updateReceivingAccount: subTenantId, accountId e account: Partial<BaseReceivingAccountDTO>.

BaseReceivingAccountRequest

Usado em listReceivingAccounts ({ subTenantId }) e em getReceivingAccount / deleteReceivingAccount ({ subTenantId, accountId }).

BankIdentifier

Retorno de getBankIdentifiers e getBankIdentifier (conteúdo de data).

interface BankIdentifier {
  name: string
  ispb: string
}

GetBankIdentifiersRequest

Payload de getBankIdentifiers: search e limit opcionais (strings).

GetBankIdentifierRequest

Payload de getBankIdentifier: objeto com bankIspb (string não vazia).

CreateLinkedJourneyResponse

Retorno de linkedJourney.createOptimizedBinding.

interface CreateLinkedJourneyResponse {
  id: string
  consentId?: string | null
  redirectUrl?: string
}

DataLinkConsentData

Retorno de linkedJourney.getConsentById.

interface DataLinkConsentData {
  consentId: string
  status: string
  statusUpdateDateTime: string
  permissions: string[]
  creationDateTime: string
  expirationDateTime: string
  userId?: string
}

DataLinkAccountItem

Elementos do array retornado por linkedJourney.getAccountsByUserId.

interface DataLinkAccountItem {
  accountId: string
  brandName: string
  brandCnpj?: string
  companyCnpj: string
  type: string
  compeCode: string
  branchCode: string
  number: string
  checkDigit: string
  status: string
  balance?: DataLinkAccountBalance
  details?: DataLinkAccountDetails
}

DataLinkAccountBalance / DataLinkAccountDetails / DataLinkMoneyAmount

Subestruturas opcionais de DataLinkAccountItem.

interface DataLinkMoneyAmount {
  amount: string
  currency: string
}

interface DataLinkAccountBalance {
  availableAmount: DataLinkMoneyAmount
  blockedAmount?: DataLinkMoneyAmount
  automaticallyInvestedAmount?: DataLinkMoneyAmount
  date: string
}

interface DataLinkAccountDetails {
  type: string
  subtype: string
  currency: string
  brandName: string
  companyCnpj: string
  compeCode: string
  branchCode: string
  number: string
  checkDigit: string
}

📄 Licença

MIT

🤝 Suporte

Para suporte, entre em contato:

• Email: [email protected]
• Website: https://www.linaopenx.com.br/
• Issues: https://gitlab.com/lina-infratech/ob-data-pull/web-lina-pay-sdk/issues