Pular para o conteúdo

JSR — Journey without redirection

Lina's initiation APIs for JSR (Journey without redirection / redirectless) are designed to shorten integration time so you can offer a modern payment experience on Open Finance — including Instant Pix and Scheduled Pix after the payer completes a one-time enrollment at their bank.

Automatic Pix (automatic payments) will follow different routes; that flow will be documented separately.

Part 1 — Enrollment (link the device once)

Before any redirectless payment, the end user must complete an enrollment: your app opens a bank redirect once, the user confirms the link at the account holder, then your relying-party page receives OAuth-style parameters in the URL fragment (#), not the query string.

  1. Obtain an access token (same OAuth pattern as the rest of Lina Pay).
  2. Call GET /api/v1/open-integration/participants/registered (or GET /api/v1/sub-tenants/{subTenantId}/participants/most-used for a prioritized list) so the user can pick an institution.
  3. Call POST /api/v1/jsr/enrollments with organisationId, authorisationServerId, nested enrollment data, riskSignals, and redirectUri. The API returns id (treat this as the enrollment identifier for later paths) and redirectUrl where the user completes consent at the bank.
  4. After the bank finishes, the browser lands on your redirectUrl with a fragment such as #code=...&id_token=...&state=.... Parse the fragment and send code, state, and id_token as code, state, and idToken to POST /api/v1/jsr/enrollments/device/options (plus tenantId and platform).
  5. Use the returned FIDO2 registration options with navigator.credentials.create() on the user's device.
  6. POST the WebAuthn credential payload to POST /api/v1/jsr/enrollments/<id>/device (see Register enrollment device). When status is AUTHORISED, enrollment is complete and you can offer redirectless payments for that link.
JSR enrollment — institution selection, bank redirect, FIDO2 device registration

Part 2 — Redirectless payment (after enrollment)

Precondition: an enrollment exists with status AUTHORISED.

  1. The user selects which enrollment to pay with (enrollmentId). Optionally call POST /api/v1/pix/details first to resolve and display a Pix key or QR Code before building the payment payload.
  2. Call POST /api/v1/jsr/consents with enrollmentId and the payment payload — the institution and FIDO relying-party context are already resolved from the enrollment, so they aren't sent again here. The response is 201 with id (the payment request id), consentId, and FIDO2 assertion options (fidoSignOptions).
  3. Trigger navigator.credentials.get() with those options (biometrics, PIN, security key, etc.) and collect the assertion.
  4. Call POST /api/v1/jsr/payments with enrollmentId, paymentRequestId (the id from step 2), riskSignals, and fidoAssertion (the WebAuthn assertion from step 3). Lina authorises and settles with the ASPSP.
  5. In synchronous mode this call retries internally (up to 10 checks) before responding, but the payment may still come back without a final status — confirm with GET /api/v1/payments/requests/{paymentRequestId}, or wait for the webhook. See Authorise payment for the full explanation of the synchronous window, webhook, and polling fallbacks.
  6. Render success or failure from the payment request payload (status such as PAGO or terminal error states).
JSR payment — consent + FIDO assertion without bank redirect

After the payment: webhook, polling, and the settlement window

The synchronous POST /api/v1/jsr/payments call above tries to return a final status directly, but it isn't guaranteed — see How payment status settles on the Authorise payment reference page for the full breakdown of the synchronous retry window, the webhook, Lina's internal polling, and the optional client-side polling endpoint (Get payment from holder).

Payment status values

The status enums below come back on the POST /api/v1/jsr/payments response and on GET /api/v1/payments/requests/{paymentRequestId}. The request-level status describes the overall consent state, while the payment-level status describes each payment inside the request.

Payment request status

StatusMeaning
PENDENTEThe consent has been created but the user has not authorized it yet.
EM_PROCESSAMENTOThe consent is being processed by the account holder.
CONSUMIDOThe consent was authorized and the payment(s) were submitted. This is the terminal happy-path status.
EXPIRADOThe consent expired before the user authorized it.
CANCELADOThe consent was cancelled before completion.
ERRO_NA_DETENTORAThe account holder returned an error while processing the consent.
ERROGeneric error state during consent processing.

Payment status

StatusMeaning
PENDENTEThe payment is scheduled but not settled yet (common for future-dated payments).
EM_PROCESSAMENTOThe payment is being settled by the account holder.
PAGOThe payment was settled successfully. This is the terminal happy-path status.
REJEITADOThe account holder rejected the payment.
EXPIRADOThe payment expired before settlement.
CANCELADOThe payment was cancelled.
ERRO_NA_DETENTORAThe account holder returned an error during settlement.
ERROGeneric error state during payment processing.
PROGRAMADOThe payment is scheduled for a future settlement date.
AGUARDANDO_VALORWaiting on the value to be resolved (for example, from a QR Code) before settlement can proceed.
PRONTO_PARA_ENVIOThe payment is queued and ready to be sent to the account holder.
EXCLUIDOThe payment was deleted before it was sent.

Automatic payments

Automatic Pix uses additional routes and a different sequence diagram. That documentation will be added in a future iteration.

Next steps