Payment Link In

A Payment Link In accepts a one-off crypto deposit into a merchant wallet. Use it for one-off checkouts, invoices, or top-ups. For ongoing inflows from the same customer or cohort, use Channels instead — Channels stay open indefinitely while a Payment Link In is single-use.

Both creation modes use the same Create Payment endpoint with type=IN. After creation, the merchant chooses how the end-user completes the payment — through BEEM's Hosted Payments Page, or through the merchant's own custom UI.

How you render the customer experience

Most merchants direct the end-user to BEEM's Hosted Payments Page, which renders the entire customer journey. Building a custom UI on top of the BEEM API is also possible — see the note below.

Approach	What you do after Create Payment
Hosted Payments Page	Redirect (or iframe) the end-user to the `redirectUrl` in the response. BEEM renders the asset selection, deposit address, QR, status, and confirmation. You wait for webhooks.
Custom UI	Use the Create Payment response and webhook payloads to render your own page. The full API specification for the custom flow is documented separately — contact your Solutions Manager for access.

Either approach combines with either creation mode below.

Two creation modes

Payment Link In — With Detail

Asset and network are fixed at creation time via payInDetails. The end-user lands directly on the deposit address/QR step. Works with HPP or custom UI.

Payment Link In — Without Detail

Only amount, currency, and reference are set at creation. The end-user picks the asset and network themselves. Works with HPP or custom UI.

Lifecycle

A Payment Link In moves through these statuses. Terminal statuses cannot transition further.

Status	Terminal	Meaning
`PENDING`	No	The link has been created. No payment yet detected on-chain.
`PROCESSING`	No	A transaction has been detected on the blockchain. The payment is being confirmed and credited to the wallet.
`COMPLETE`	Yes	Funds have been received and credited to the wallet in the wallet's currency.
`UNDERPAID`	Yes	Funds have been received and credited, but the customer sent less than the requested amount. See Payment Exceptions.
`EXPIRED`	Yes	The link expired before the end-user completed the payment.
`CANCELLED`	Yes	The payment was cancelled before completion.

The customer journey

Whichever approach you choose, the customer moves through up to four logical steps:

Asset and network selection — the end-user picks what they want to pay with. Skipped in With Detail mode. Rendered by the HPP, or by your own UI from the currencyOptions field on the response.
Deposit address and QR — BEEM provisions an address for the selected asset/network. The HPP shows the address plus a scannable QR; in a custom UI, you read address.address and address.uri from the response (or its update via webhook).
Pending — once the customer sends funds and the transaction is detected on-chain, the payment moves to PROCESSING and you receive transaction-detected and status-change webhooks. The HPP shows the pending screen; in a custom UI, surface the same state.
Complete — once the transaction is confirmed and credited, the payment moves to COMPLETE and you receive transaction-confirmed and status-change webhooks. The HPP shows the success state; in a custom UI, surface confirmation.

See the With Detail or Without Detail sub-pages for the specific screens or API calls each mode involves.

Compliance and holds

Every inbound payment passes through compliance screening. If the payment triggers a screening rule it is held for review and emits a transaction-held webhook. The payment stays in PROCESSING until it clears.

Exceptions

Payment Link In has three documented exception scenarios:

Exception	What happens
Overpayment	The end-user sends more than the requested amount. Status moves to `COMPLETE`, the wallet is credited with the full amount sent including the excess.
Underpayment	The end-user sends less than the requested amount. Status moves to `UNDERPAID`, the wallet is credited with what was actually sent.
Late payment	The end-user sends funds after the link has reached a terminal state — `COMPLETE`, `UNDERPAID`, or `EXPIRED`. The link itself does not change status, but a `transaction-late` webhook is emitted so your operations team can decide what to do with the funds. If conversion is required, late funds settle at the current spot rate since the original quote has expired.

📘
Why late payments can happen to a "completed" link
A Payment Link is single-use in concept, but the underlying deposit address remains live on-chain. The end-user (or their wallet) can technically broadcast a transaction to that address at any time, including after the link is fully resolved. The transaction-late webhook is your only signal that this has occurred. Any required FX conversion uses the spot rate at the time of arrival — the original quote is no longer in force. Handle on the merchant side (refund, credit, or operations review).

See Payment Exceptions for full handling guidance and example webhook payloads.

Webhooks

Five events fire during an IN payment's lifecycle:

layer1:payment:checkout:status-change — status transitions
layer1:payment:checkout:transaction-detected — on-chain transaction first seen
layer1:payment:checkout:transaction-confirmed — transaction reaches required confirmations
layer1:payment:checkout:transaction-held — payment held for compliance screening
layer1:payment:checkout:transaction-late — funds arrived after the link expired

See Payment Link Webhooks for event payloads and recommended handler patterns.

What's next

Payment Link In — With Detail

Step-by-step guide to creating a link with asset and network pre-selected via payInDetails.

Payment Link In — Without Detail

Step-by-step guide to creating a link where the end-user picks the asset on the HPP or in your custom UI.

Payment Link Webhooks

Subscribe to lifecycle events: status changes, on-chain confirmations, holds, and late arrivals.

Payment Exceptions

Handle overpayments, underpayments, late arrivals, and held payments.