Linked journey (Smart Pix) — single-redirect data and payment consent

The linked journey creates the Open Finance data consent and the Sweeping recurring consent in a single API call, so the payer authenticates once at the account holder instead of going through two separate journeys.

Before this journey existed, offering Smart Pix with account visibility meant running a data-sharing journey (to read accounts and balances) and a payment journey (to open the recurring consent) — two redirects, two authorisations, two sets of identifiers to reconcile. Here a single POST /api/v1/linked-journey/automatic-payments returns one redirectUrl, and after the payer approves it you can read both the shared account data and the payment contract.

This journey is restricted to Sweeping — transfers between accounts owned by the same holder. For the product rules and the non-linked variant, see Smart Pix.

What a single call does

The API performs these steps server-side before responding:

1. Creates the data consent at Data Link (POST /api/v1/consents) with a fixed permission set defined by the server.
2. Reads the created consent back to obtain the Data Link userId.
3. Creates the internal payment request.
4. Creates the Sweeping recurring consent at the account holder, attaching the data consent to the request.
5. Returns redirectUrl (for the holder redirect) and dataConsentId.

Prerequisites

1. Obtain an OAuth 2.0 access token as described in Get your credentials. Every route in this journey requires the role epp-user or epp-sub-tenants.
2. Complete Onboarding so redirect domains are allow-listed for your sub-tenant.
3. Call Get registered participants so the payer can choose an institution — this is where the organisationId and authorisationServerId required by this journey come from.

Sweeping only

Stage 0 — Create the journey and redirect the payer

1. Call Create optimized automatic payment with organisationId, authorisationServerId, and a nested recurringConsent carrying recurringConfiguration.sweeping. The payer CPF in recurringConsent.loggedUser.document.identification is required — it feeds the data consent.
2. From 201 Created, persist data.id, data.dataConsentId, and data.flowId server-side.
3. Send the payer to data.redirectUrl to authenticate and approve both consents at the account holder.
4. After approval, the holder redirects the browser to the redirectUri you sent. That URL must be owned and operated by your application (allow-listed on the sub-tenant); Lina does not host it.

Stage 1 — Retrieve the consent and the payer accounts

1. Call Get data consent with the dataConsentId you stored, until data.status is AUTHORISED. Read data.userId from the response.
2. Call Get user accounts with that userId to list the payer accounts, balances, and details — use them to let the payer pick the account that will fund the transfers.
3. Call Get payment request with path {automaticPaymentsRequestId} = data.id until data.consentStatus is AUTHORISED. Read data.consentId from that response — it is the recurringConsentId you need in Stage 2.

Stage 2 — Initiate and track transfers

1. With the contract authorised, call Create recurring payment using recurringConsentId = the data.consentId you read in Stage 1. No new redirect is needed. Persist the returned payment id.
2. Poll Get recurring payment for data.status. Settlement is asynchronous: the payment is first acknowledged as RECEBIDO, moves through EM_PROCESSAMENTO, and only then reaches PAGO or a terminal failure (REJEITADO, ERRO_NA_DETENTORA, ERRO). On failure, read rejectionReason and isRetryAllowed. Where available, prefer Webhooks over tight polling.
3. Repeat this stage for every later transfer under the same contract — the payer is never redirected again.

The transfer rules themselves (limits, same-holder restriction, consent lifecycle) are the ones described in Smart Pix.

Error handling

Every error response uses the same contract: message (array of strings), type, errorCode, traceId, and statusCode.

API reference

Use the Linked journey (Smart Pix) API group in the sidebar for full request and response schemas.