Pular para o conteúdo

Payments

The classic, redirect-based payment flow: list participants, open a consent, and — after the payer authorizes at their bank — either finish the OAuth handshake (createPayment) or create and track a payment request (createPaymentRequest / getPaymentRequest).

Get registered participants

import { getParticipants, type Participant, LinaPayError } from '@lina-openx/web-lina-pay-sdk'

const participants: Participant[] = await getParticipants({
subtenantId: 'your-subtenant-id',
subtenantSecret: 'your-subtenant-secret',
})

Institutions with more than one authorization server appear as multiple entries; institutions with none are filtered out automatically.

Create a consent

Opens a payment consent and returns the redirectUrl the payer follows to authorize at their bank.

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

const consent = await createConsent(
{ subtenantId: 'your-subtenant-id', subtenantSecret: 'your-subtenant-secret' },
{
  organisationId: 'c8f0bf49-4744-4933-8960-7add6e590841',
  authorisationServerId: 'c8f0bf49-4744-4933-8960-7add6e590841',
  payment: {
    redirectUri: 'https://example.com/redirect',
    value: 1500.50,
    creditor: {
      name: 'Jane Doe',
      personType: 'PESSOA_NATURAL',
      cpfCnpj: '12345678901',
      accountNumber: '12345-6',
      accountIssuer: '0001',
      accountPixKey: 'jane@example.com',
      accountIspb: '12345678',
      accountType: 'CACC',
    },
  },
  platform: 'WEB',
},
)

console.log(consent.consentId, consent.redirectUrl)

Add payment.schedule (single | daily | weekly | monthly | custom) to open a scheduled or recurring consent instead of an immediate one.

Finish the payment (OAuth callback)

After the bank redirects back to your redirectUri with state, code, and idToken, exchange them for the finished payment:

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

const payment = await createPayment(
{ subtenantId: 'your-subtenant-id', subtenantSecret: 'your-subtenant-secret' },
{ state, code, idToken, tenantId: 'your-subtenant-id' },
)

console.log(payment.id, payment.status, payment.value)

Create a payment request

A separate flow from createPayment: you send the payment data up front (value, creditor, redirect URI) and get back an id plus a redirectUri to continue at the account holder.

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

const result: PaymentRequestCreated = await createPaymentRequest(
{ subtenantId: 'your-subtenant-id', subtenantSecret: 'your-subtenant-secret' },
{
  details: 'Service payment',
  redirectUri: 'https://example.com/return',
  cpfCnpj: '12345678901',
  value: 150.5,
  creditor: { /* same Creditor shape as createConsent */ } as never,
  schedule: {}, // required key — {} for an on-demand request, or exactly one schedule type
} satisfies CreatePaymentRequestDTO,
)

console.log(result.id, result.redirectUri)

Get a payment request

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

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

console.log(details.status, details.value, details.payments)

Dates come back as ISO strings (not Date instances). payments holds one entry per installment (id, dueDate, status, txId, …).

Cancel a payment request or a single payment

Two distinct cancellation calls — pick the one that matches what you're cancelling:

import { cancelPaymentRequest, cancelPayment } from '@lina-openx/web-lina-pay-sdk'

// Cancel every future installment tied to a consent (consentId)
const cancelled = await cancelPaymentRequest(credentials, {
consentId: 'urn:raidiambank:payment-consent:8e2e32d4-de52-44dd-a947-50607fbd18fc',
subTenantId: 'lina',
cpfCancelledBy: '45684134866',
})

// Cancel a single payment leg (paymentId, usually externalPaymentId)
const cancelledOne = await cancelPayment(credentials, {
paymentId: '0db6efbf-e4d5-4ca9-9498-401d6663efaf',
cpfCancelledBy: '76109277673',
})
FunctionCancels byHTTPExtra header
cancelPaymentRequestconsentIdPATCH /open-integration/consents/{consentId}/payments/cancelsubTenantId
cancelPaymentpaymentIdPATCH /api/v1/open-integration/payments/{paymentId}/cancel—

Both accept LinaPayCredentials or TokenCredentials ({ access_token }) as credentials, and both are also reachable as payments.cancelPaymentRequest / payments.cancelPayment.

List payment requests

Paginated, filterable listing, most recent first:

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

const page = await listAllPaymentRequests(credentials, {
subTenantId: 'lina',
status: ['PENDENTE', 'EM_PROCESSAMENTO'],
startDate: '2026-07-01T00:00:00.000Z',
endDate: '2026-07-20T00:00:00.000Z',
limitPerPage: 10,
page: 1,
})

console.log(page.data.length, page.meta.totalRecords, page.meta.totalPages)

Next steps