Payment Links Overview
Single-use URLs that take your end-user to a Hosted Payments Page to complete a deposit (into a wallet) or a withdrawal (out of a wallet).
A Payment Link is a single-use URL that lets an end-user complete a one-off crypto deposit into a wallet, or a withdrawal out of one. The link is generated by the Create Payment API endpoint. From there, the merchant chooses how to render the customer's experience — either using BEEM's pre-built Hosted Payments Page, or by building a custom UI on top of the API response.
Payment Links are also the only way crypto leaves a wallet. Every outbound flow on BEEM — withdrawal to a saved Contact, to a one-time address, or "send the link and let the recipient enter their own address" — is implemented as an outbound Payment Link.
Two directions
| Direction | What it does | When to use |
|---|---|---|
| Payment Link In | Accepts a one-off deposit into a wallet. | One-off checkouts, invoices, top-ups. For ongoing inflows from the same customer, use Channels instead. |
| Payment Link Out | Sends a one-off withdrawal out of a wallet. | Refunds, payouts to a Contact, treasury moves, recipient-completes flows. There is no alternative — every outbound flow goes through a Payment Link Out. |
Two integration approaches
After calling Create Payment, the merchant directs the end-user to complete the payment. There are two ways to do this:
| Approach | What it is | When to use |
|---|---|---|
| Hosted Payments Page (HPP) | The merchant redirects (or iframes) the end-user to the redirectUrl returned by the API. BEEM renders the asset selection, address/QR, status updates, and confirmation screens. | The standard, recommended approach. Fastest to integrate. |
| Custom UI | The merchant builds their own end-user UI using the BEEM API and webhook payloads. | Possible but more involved — the merchant team takes responsibility for rendering, network selection, QR generation, and live status updates. The full API specification for this approach is documented separately; contact your Solutions Manager for access. |
If you use the HPP, the redirectUrl points to one of these hosts:
| Environment | Host |
|---|---|
| Production | pay.hostedpaymentspage.net |
| Sandbox | pay.sandbox.layer1.com |
Either approach can be combined with either of the creation modes below.
Two creation modes
Either direction can be created in one of two modes. They differ in how much the merchant decides upfront and how much the end-user picks at the point of payment.
| Mode | What the merchant supplies | What the end-user does |
|---|---|---|
| With detail | Asset, network, and (for OUT) the destination address are fixed at creation time via payInDetails / payOutDetails. | Skips the asset/network selection step. Lands directly on the address/QR (IN) or the confirmation step (OUT). |
| Without detail | Only the bare essentials: amount, currency, reference. | Picks the asset and network themselves. For OUT, also enters their own receiving address. |
Use with detail when your application already knows what the end-user will pay with (or where to send to). Use without detail when the end-user makes that choice on the spot.
The three currencies
Every Payment Link involves the same three currencies as a Channel:
| Currency | What it is |
|---|---|
| Display Currency | What the merchant prices the payment in. Shown to the end-user at the point of payment. |
| Paid Currency | The crypto asset that actually moves on-chain. |
| Wallet Currency | What the merchant wallet settles in. |
A merchant pricing in EUR who has the end-user pay 11.57 USDT into a EUR wallet: Display Currency = EUR, Paid Currency = USDT, Wallet Currency = EUR. Conversion is automatic and the rate is recorded against the payment.
Lifecycle
The status field on every payment moves through a small number of states. Terminal statuses cannot transition further. The exact set differs by direction.
| Status | IN | OUT | Terminal | Meaning |
|---|---|---|---|---|
PENDING | ✓ | ✓ | No | Created. For IN, no payment detected yet. For OUT, the end-user has not yet entered their receiving details. |
PROCESSING | ✓ | ✓ | No | For IN, transaction detected on the blockchain. For OUT, asset/address received and the payment is being submitted. This state also covers any approval wait and the on-chain confirmation period. |
COMPLETE | ✓ | ✓ | Yes | Funds credited (IN) or sent (OUT). |
UNDERPAID | ✓ | — | Yes | The customer sent less than expected. Funds are still credited; see Payment Exceptions. |
EXPIRED | ✓ | ✓ | Yes | The end-user did not complete the journey within the expiry window. |
CANCELLED | ✓ | ✓ | Yes | For IN, the payment was cancelled before completion. For OUT, the payout was rejected during approval review — the wallet is not debited. |
Approvals on outbound
If your account has approvals configured, outbound Payment Links are gated on approval before they pay out. The approval step sits between PENDING and on-chain submission, while the status field remains PROCESSING throughout.
Approval policies are configurable along two axes:
- Initiator — Portal-initiated and API-initiated payouts can each be gated independently.
- Amount threshold — approvals can apply to every payout, or only to payouts above a defined amount.
A rejected payout terminates in CANCELLED and the wallet is not debited. See Approvals for the configuration UI and full policy options.
Compliance and holds
Both inbound and outbound payments pass through compliance screening. A payment that triggers a screening rule emits a transaction-held webhook and stays in PROCESSING until it clears review. Most payments clear automatically; held payments remain visible in your operations queue.
Expiry
Every Payment Link has two distinct expiry windows that operate independently:
| Expiry | Default | Configurable | Purpose |
|---|---|---|---|
| Link expiry | 1440 minutes (24 hours) | Yes — set via expiryMinutes on Create Payment | How long the URL itself remains valid. Sets the deadline for the end-user to complete the journey. |
| Quote expiry | 60 minutes | No — fixed at 60 minutes | How long the FX rate quoted for the payment remains valid. Protects the merchant against rate movement between quote and settlement. |
The deposit address stays live after a link is terminalA Payment Link is single-use in concept, but the underlying deposit address remains technically capable of receiving funds even after the link reaches a terminal state. Funds arriving late — whether the link is
COMPLETE,UNDERPAID, orEXPIRED— are detected on-chain and emit atransaction-latewebhook. The original FX quote has long since expired, so if conversion is required, late funds settle at the current spot rate at the time of arrival, not at the rate that was quoted when the link was created. The link itself does not change status; your operations team decides how to handle the funds (typically refund or credit). See Payment Exceptions.
What's next
Accept a one-off deposit into a wallet. Covers both creation modes and both integration approaches.
Send a one-off withdrawal out of a wallet. Covers both creation modes and both integration approaches.
Subscribe to payment lifecycle events for both directions: status changes, on-chain confirmations, holds, and late arrivals.
Handle overpayments, underpayments, late arrivals, and held payments.