Coinbase Top-Up Links API

A Top-Up Link is a shareable hosted URL that lets a payer add funds to their balance. Create a link with **Create a Top-Up Link** and share the returned `topUpUrl` only with the intended payer. The URL identifies the link but does not authorize a top-up; the payer must authenticate and approve it. ## Lifecycle The resource is immutable once created. The link expires 24 hours after creation and funds a single purchase: once a purchase succeeds, the link is spent and cannot be used again. A purchase that fails does not consume the link, so the payer can retry until it expires. A link is not bound to a specific payer. There is no GET: the create response and the `acceptance.top_up_link.created` event are the full resource. ## Amounts - `topUpAmount` is the merchant's fixed suggested net amount for the link's single purchase. The payer can change it in the hosted flow. - `orderTotalAmount` is optional presentation context. It does not replace, change, or cap `topUpAmount`. - The funds-added event reports the actual net amount credited by the purchase that spent the link. It is never cumulative. ## Merchant name Supply `customerDisplay.merchantName` to choose the merchant name for a link's hosted page. The supplied value is limited to 128 Unicode code points before surrounding whitespace is removed. If the name is omitted or empty after trimming, the entity's profile name is used. The create response and creation webhook return the resolved name stored on the immutable link. Later profile changes do not change that name. ## Redirects When `redirectUrl` is supplied, its origin must exactly match an allowed origin. The query key `toppedUpAmount` is reserved because the hosted flow appends it before redirecting the payer. The redirect does not represent success or failure; `toppedUpAmount` may be zero, a partial amount, or the full `topUpAmount`. ## Webhooks Subscribers receive `acceptance.top_up_link.created` when the link is created and `acceptance.top_up_link.funds_added` when a purchase credits funds through the link. Because a link funds a single purchase, it produces at most one funds-added event; deliveries can repeat, so deduplicate on `eventId`.