Payment Links

A payment link is a secure, single-payment URL that lets a counterparty -- the person or business on the other side of the payment -- complete a payment by entering their bank details on a hosted page. Links are issued by the Luqra Now dashboard when a payment is created without the counterparty's bank details on file -- the payment waits in AWAITING_CONFIRMATION until the counterparty submits the page, and only then enters the normal processing flow.

Payment links are a dashboard feature. The API neither creates payment links nor returns link URLs or tokens -- POST /v1/payments requires an existing contact and always creates a direct payment. This guide exists because link payments created in the dashboard still show up in your API reads and webhooks, and integrations should know what to expect from them.

When a link is issued

Requesting money (INBOUND) -- always. Every payment request goes out as a link: the payer opens it, reviews the amount, and confirms the account to be debited. This holds even when the payer is a saved contact with a bank account on file -- whatever they confirm on the link page is what gets debited, and the account on file is only used to pre-fill the form.

Sending money (OUTBOUND) -- only when there is nowhere to send the funds directly:

• The recipient is a saved contact without an active bank account, or
• The recipient is not a saved contact at all (the sender typed just a name and email).

A send to a contact with a bank account on file is a direct payment: it starts in QUEUED and no link is involved.

API-created payments -- never. Payments created via POST /v1/payments start in QUEUED and skip AWAITING_CONFIRMATION entirely.

Creating and sharing a link

The link is shown at the end of the dashboard's send or request flow, with a copy button and a preview of exactly what the counterparty will see. It also stays copyable from the payment's details page for as long as acting on it makes sense -- until the payment reaches a final state or the link expires.

Luqra does not deliver the link. No email or message is sent to the counterparty when a link is created -- you copy the URL and share it yourself, over whatever channel you already use with them. The counterparty does not need a Luqra account: the page is public and works for anyone who has the URL.

Link properties

Property	Behavior
Token	The URL ends in a 256-bit random token (43 URL-safe characters). It is the only secret in the link and cannot be guessed or enumerated.
Expiry	30 days after creation. Fixed -- not configurable, and links cannot be extended or reissued.
Uniqueness	One active link per payment.
Storage	Lookups use only a hash of the token; the raw token is never logged.
Audit	Every open and every submission is recorded with timestamp, IP address, and user agent.
Abuse protection	The public link endpoints are rate limited per token.

Anyone who has the URL can view the payment's details (amount, note, the originator's name and email) and submit bank details against it, so treat the link like a bearer credential: share it only with the intended counterparty over a channel you trust.

What the counterparty sees and does

An active link shows the payment amount, the payment note, who it is from (the originator's name and email), and -- for a known contact or a typed-in recipient -- their own pre-filled details. On a payment request the payer also sees the processing fee, which is added on top of the requested amount and authorized as part of the total; on a send the recipient sees only the amount being sent.

To complete the payment, the counterparty submits:

• Account holder name -- first and last name for a person, company name for a business. Whether the page asks for a person or a business is fixed when the link is created; the counterparty cannot reclassify themselves.
• Account type -- CHECKING or SAVINGS.
• Routing and account number -- typed and confirmed. The routing number is verified against the bank directory before the submission is accepted. A saved contact can instead keep the pre-filled account on file without retyping it.
• Legal address.

Everything submitted on a link page applies to that one payment only. A saved contact's stored name, address, and bank account are never overwritten by a link submission -- possession of a link never grants the ability to change a contact record.

After a valid submission the same URL keeps working as a status page: the counterparty can reopen it to follow the payment until the link expires.

Lifecycle

A link payment starts in AWAITING_CONFIRMATION. Nothing is processed, and no funds move, until the counterparty submits.

Submission moves the payment to QUEUED and fires the payment.queued webhook event. From QUEUED onward the payment follows the standard flow described in Payment Lifecycle.

Cancellation happens in the dashboard and is only possible while the payment is still AWAITING_CONFIRMATION. Cancelling moves the payment to CANCELED and disables the link in the same step -- the already-shared URL immediately stops resolving, as if it never existed.

Expiry does not change the payment's status: an expired link's payment stays AWAITING_CONFIRMATION, and no webhook fires. (The dashboard displays such payments as expired, but that is a display label -- the API keeps reporting AWAITING_CONFIRMATION.) The expired page no longer discloses the payment's details -- it shows only who created the link and the payment direction -- and submissions against it are rejected. Since links cannot be reissued, the way forward is to cancel the payment and create a new one.

How link payments appear in the API

Link payments belong to your organization like any other payment, so they appear in GET /v1/payments and GET /v1/payments/:id -- but the link token itself is never included in any API response.

While a payment is in AWAITING_CONFIRMATION (or was CANCELED from it), the counterparty has not supplied their details yet:

• contact.bankAccount is null when the counterparty is a saved contact.
• The entire contact object is null when the counterparty is not a saved contact.

From QUEUED onward both are always populated, with the bank details the counterparty submitted (masked, like every account number in the API). See Managing Payments for the full response shape.

For webhooks, a link payment announces itself with payment.awaiting_confirmation when it is created, fires payment.queued when the counterparty submits (up to 30 days later), and fires payment.canceled if it is canceled before submission. Link expiry is the one silent path: no event fires, and the payment simply stays in AWAITING_CONFIRMATION. See Webhooks for payload details.