Payment Link Out
Send a one-off crypto withdrawal out of a wallet via the Hosted Payments Page.
A Payment Link Out sends a one-off crypto withdrawal out of a merchant wallet. Use it for refunds, payouts to a saved Contact, treasury moves, and recipient-completes flows where you do not yet know the destination address. Payment Links Out are the only way crypto can leave a BEEM wallet.
Both creation modes use the same Create Payment endpoint with type=OUT. After creation, the merchant chooses how the end-user provides their receiving details — 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. The HPP renders the asset selection, receiving-address input, rate confirmation, and completion screens. 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
Asset, network, and destination address are fixed at creation time via payOutDetails. The destination address can come from a saved Contact, be entered manually by the merchant, or be set programmatically. The end-user skips both asset selection and address input.
Only amount, currency, and reference are set at creation. The merchant shares the link with the recipient, who picks the asset, network, and enters their receiving address themselves on the Hosted Payments Page.
Lifecycle
A Payment Link Out moves through these statuses. Terminal statuses cannot transition further.
| Status | Terminal | Meaning |
|---|---|---|
PENDING | No | The link has been created. Receiving details have not yet been provided. |
PROCESSING | No | Receiving details have been provided (by the end-user on the HPP, or by the merchant via payOutDetails). This state covers any approval wait and the on-chain submission and confirmation period. |
COMPLETE | Yes | The payout has been confirmed on-chain. The wallet balance reflects the debit. |
CANCELLED | Yes | The payout was cancelled before it reached the blockchain — most commonly when an approver rejects the request during the approval review. The wallet is not debited. |
EXPIRED | Yes | The end-user did not complete the receiving details within the expiry window. |
The customer journey
Whichever approach you choose, the customer moves through up to three logical steps:
- Asset and network selection — the end-user picks the asset and network they want to receive. Skipped in With Detail mode. Rendered by the HPP, or by your own UI.
- Receiving address input — the end-user enters the address (and any required tag, e.g. for XRP) where they want the funds sent. BEEM validates the address format and network match before allowing the request to proceed. Skipped in With Detail mode when
payOutDetails.addressis supplied. - Confirmation and submission — the end-user reviews the quoted rate and clicks Accept. BEEM submits the payout on-chain. The HPP shows pending and complete screens; in a custom UI, surface the same states.
See the With Detail or Without Detail sub-pages for the specific screens or API calls each mode involves.
Approvals
If your account has approvals configured, outbound Payment Links are gated on approval before BEEM submits them on-chain. The approval step sits between PENDING and on-chain submission. The payment's status remains PROCESSING while awaiting approval — there is no separate AWAITING_APPROVAL status to watch for.
Approval policies are configurable along two axes:
- Initiator — approvals can be required for Portal-initiated payouts, API-initiated payouts, or both. The two policies are independent.
- Amount threshold — approvals can be required on every payout, or only on payouts above a defined amount.
Approvers act in the Portal:
- Approve — BEEM submits the on-chain transaction immediately. Status moves through
PROCESSINGtoCOMPLETE. - Reject — the payout does not execute. Status moves to
CANCELLEDand the wallet is not debited.
See Approvals for configuration details.
Compliance and holds
Outbound payments pass through compliance screening before submission. 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.
Webhooks
Two events fire during the lifecycle:
layer1:payment:checkout:status-change— status transitions (PENDING→PROCESSING→COMPLETE, orPENDING→EXPIRED)layer1:payment:checkout:transaction-held— payment held for compliance screening
See Payment Link Webhooks for event payloads, scenario sequences, and recommended handler patterns.
What's next
Step-by-step guide to creating a link with asset, network, and destination address pre-selected via payOutDetails.
Step-by-step guide to creating a link where the recipient picks the asset and enters their receiving address.
Subscribe to lifecycle events: status changes and compliance holds.
Handle held payments, expired payouts, and address validation failures.