Server SDK overview
The Lina Embedded Payments SDK is a server-side library that wraps the account-linking and redirectless Pix payment (JSR) APIs behind a small, typed client. Instead of signing requests, refreshing tokens, and parsing response envelopes by hand, you call a method and get back a typed object.
The SDK ships in four languages that expose the same surface — same client, same services, same method names — so a flow you learn in one language maps one-to-one to the others.
The four SDKs
Every SDK targets a server runtime (your backend), not the end user's
device. All are versioned 0.1.0 and mirror the Node reference
implementation.
| SDK | Runtime | Package |
|---|---|---|
| Node / TypeScript | Node 20+ | @linainfratech/embedded-payments (npm) |
| Java | Java 21 (LTS) | com.linainfratech:embedded-payments-sdk (Maven) |
| Swift | Swift 6 | LinaEmbeddedPayments (SwiftPM) |
| .NET | net8.0 / net10.0 | LinaInfratech.EmbeddedPayments (NuGet) |
See Install & initialize for the exact install command and client setup in each language.
What the SDK covers
The SDK exposes six integration flows across two journeys. Most use the JSR (Jornada Sem Redirecionamento — journey without redirection), where the payer authorizes on their own device with a passkey (FIDO2). Two use the with-redirection journey, where the payer is instead sent to their bank to authorize — no enrollment and no FIDO2:
- Link an account — create and revoke a Pix enrollment (wallet) for a payer. (JSR)
- Pay a QR Code — pay a boleto or Pix QR Code with a linked account. (JSR)
- Pix transfer by key — send a Pix transfer to a Pix key with a linked account. (JSR)
- Instant Pix (JSR) — take an immediate in-app payment, device-signed, no redirect. (JSR)
- Instant Pix — take an immediate payment by redirecting the payer to their bank. (redirect)
- Scheduled Pix — schedule one or recurring
payments — Instant Pix plus a
schedule. (redirect)
The three JSR payment flows above only differ in how they build the consent
— signing on the device and executing with processJsr is shared across all
of them; see Execute a JSR payment.
Architecture at a glance
Three parties take part in every flow: your backend (running the SDK), the Lina API, and the payer's device. The SDK lives entirely on your backend and talks to the Lina API over HTTPS. The device performs the cryptographic FIDO2 ceremony and hands the resulting objects to your backend.
Services and methods
The client exposes five services. Methods that hit /jsr/* routes carry the
Jsr suffix; the "clean" (un-suffixed) names belong to the with-redirection
journey (Instant Pix / Scheduled Pix).
Names below use Node casing — Java drops the
Async suffix, .NET adds Async, and Swift uses try await.
| Method | HTTP | Route | Used in |
|---|---|---|---|
participants.listMostUsed(subTenantId) | GET | /sub-tenants/{id}/participants/most-used | Account linking / Instant & Scheduled Pix |
participants.listRegistered() | GET | /open-integration/participants/registered | Account linking / Instant & Scheduled Pix (fallback) |
pix.getDetails(req) | POST | /pix/details | Pay QR / Pix transfer |
enrollments.createJsr(req) | POST | /jsr/enrollments | Account linking |
enrollments.getDeviceOptionsJsr(req) | POST | /jsr/enrollments/device/options | Account linking |
enrollments.registerDeviceJsr(id, req) | POST | /jsr/enrollments/{id}/device | Account linking |
enrollments.listByUserJsr(cpf, query?) | GET | /jsr/enrollments/users/{cpf} | All payment flows (gate) |
enrollments.revokeJsr(id) | PATCH | /jsr/enrollments/{id} | Account linking (revoke) |
consents.createJsr(req) | POST | /jsr/consents | Pay QR / Pix transfer |
payments.processJsr(req) | POST | /jsr/payments | Pay QR / Pix transfer |
consents.create(req) | POST | /open-integration/consents | Instant & Scheduled Pix |
payments.getRequest(id) | GET | /payments/requests/{id} | Instant & Scheduled Pix |
payments.get(id) / getByExternalId / getByTxId | GET | /payments/... | Instant & Scheduled Pix (queries) |
payments.cancelPayment(id, req) / cancelConsentPayments(id, req) | PATCH | /payments/... | Instant & Scheduled Pix (cancel) |
Every JSR method accepts an optional opts argument — { clientIp?, subTenantId? }
in Node — to override the X-Client-IP header (the payer's device IP,
required on JSR routes) and the sub-tenant per call.
Next steps
- Install & initialize — add the package and create the client in your language.
- Link an account — the enrollment flow every payment depends on.
- Error handling — the typed exception hierarchy and how to catch it.
- JSR (Redirectless) — the raw HTTP API the SDK wraps.