Payment initiation portal (White label)

The payment initiation portal is a white-label hosted journey that lets you offer immediate, scheduled, and recurring Pix initiation through Open Finance without building the full bank-selection and consent UI yourself. Your site stays in control of checkout while Lina hosts the regulated redirect flow, shortening time-to-market and operational cost.

Prerequisites

Obtain a Bearer access token for your integration using Get your credentials.
Register allowed redirect domains for your sub-tenant so the redirectUri you send in API calls passes validation — see Onboarding and Add a redirect domain.

End-to-end flow

Your backend calls POST /api/v1/payments (Create payment) with the payment payload and a redirectUri that belongs to an allow-listed domain.
The API responds with 201 and a redirectUrl. Send the end user’s browser to that URL to continue in the white-label portal (bank selection, holder authentication, consent, and settlement).
When the journey completes, the portal redirects the browser back to your redirectUri. The query string typically includes paymentLinkId, which is the same identifier as the id returned in step 1 and the paymentRequestId path parameter on Get payment request.
Your backend calls GET /api/v1/payments/requests/{paymentRequestId} to confirm state: request-level status should be CONSUMIDO, and each row in payments[] should show PAGO for settled legs or PENDENTE for future-dated installments.

Automatic Pix (Pix Automático) variant

For automatic payments (recurring consent on the portal), switch to:

POST /api/v1/automatic-payments — Create automatic payment request
GET /api/v1/automatic-payments/request/{automaticPaymentsRequestId} — Get automatic payment request

Statuses and payloads follow the automatic payments OpenAPI contract in specs/hpp/white-label-automatic.yaml in this repository.

White label branding

Branding is driven by sub-tenant configuration (back-end / configuration vs. front-end layout). Align your assets with the following so the portal matches your institution.

Area	What you configure	Notes
Logo	Public URL to your logo asset	Use PNG or SVG in full colour. Layout scales by height: minimum 20px, maximum 32px; for heights above 32px use steps of 4px. Width scales proportionally.
Primary colour	Brand primary	Applied to primary buttons and, where needed, titles. 100% for titles and active controls; 30% tint for inactive items; hover increases brightness by +25 on the HSB scale.
Secondary colour	Brand secondary	Supporting colour for icons, links, and light backgrounds (15% tint for fills). If contrast is weak against your secondary, fall back to neutrals `#DEDEDE` and `#6E6F72` for readable surfaces.
Fonts	Font URL (CSS) and font family name	You may supply a custom webfont; ensure readability in the portal. Default recommendation: Roboto. Use weights 400 (body), 500 (titles and subtitles), and 600 (emphasis).

The Update a sub-tenant API maps these concepts to urlLogo, primaryColor, secondaryColor, urlFont, and nameFont for programmatic updates.

Sequence diagram

Carregando diagrama…

White-label initiation portal — from checkout to redirect back and status polling

Next steps

Create payment — open a payment request and receive redirectUrl.
Get payment request — poll request and installment statuses after redirect.
Create automatic payment request — Pix Automático entry point for the same portal pattern.