Create a Top-Up Link
Creates a Top-Up Link: a shareable hosted URL that lets a payer add funds to their balance. 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.
Provide topUpAmount and asset; orderTotalAmount, redirectUrl, and customerDisplay are optional. When redirectUrl is supplied, its origin must exactly match one of the entity’s configured allowed origins, and the URL must not contain a percent-decoded query key exactly equal to toppedUpAmount. The response includes the hosted topUpUrl to share with the payer. Creating a link is signaled to webhook subscribers by the acceptance.top_up_link.created event, and the purchase that spends the link emits an acceptance.top_up_link.funds_added event.
Supply customerDisplay.merchantName to override the merchant name on this link’s hosted page. The supplied value must not exceed 128 Unicode code points, including surrounding whitespace. Surrounding whitespace is removed before storage. An omitted or empty name after trimming uses the entity’s profile name. The create response and creation webhook always return the resolved name stored on the link.
Authorizations
A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.
Headers
An optional string request header for making requests safely retryable. When included, duplicate requests with the same key will return identical responses. Refer to our Idempotency docs for more information on using idempotency keys.
1 - 128Body
A request to create a Top-Up Link. The entity is inferred from the API key. topUpAmount and asset are required; orderTotalAmount, redirectUrl, and customerDisplay are optional. Unrecognized top-level fields are allowed and ignored.
The merchant-provided initial suggested net amount to add, denominated in asset. The suggestion remains fixed on the created link and is not recomputed from orderTotalAmount or the payer's current available balance. The payer can adjust the amount they add in the hosted flow. Fiat fees are outside this value. Positive and nonzero, with at most two fractional digits.
^(?:0|[1-9]\d*)(?:\.\d{1,2})?$"100.00"
The asset credited by the Top-Up Link. Currently, only usdc is supported.
usdc 1 - 42"usdc"
The total balance, denominated in asset, that the merchant expects the payer to need to complete the order. When supplied, the hosted Top-Up page shows the order total and the payer's current available balance, and computes the remaining shortfall from those values. This live shortfall is presentation context: it is separate from topUpAmount and does not replace, change, or limit that fixed suggestion.
^(?:0|[1-9]\d*)(?:\.\d{1,2})?$"130.45"
Optional absolute HTTPS URL to which the payer is redirected after the top-up completes. The URL's origin must exactly match one of the entity's configured allowed origins: the HTTPS scheme, hostname (case-insensitive), and effective port (with the default HTTPS port normalized to 443) are compared, while the path, query, and fragment are ignored. Wildcard or suffix/subdomain matching is not supported. Existing query parameters and the fragment are preserved. The URL must not contain a percent-decoded query key exactly equal to toppedUpAmount; every occurrence is rejected, including duplicates, while other casing is allowed. This value can contain sensitive merchant parameters; treat it as secret and do not log it.
12 - 2048^https://.*$"https://www.example-merchant.com/checkout/return?orderId=701-3358192-4471016&sig=8a3f"
Display details supplied for the hosted Top-Up page. Only the merchant name is supported. Unrecognized fields are allowed and ignored.
Response
Successfully created Top-Up Link.
A shareable link that lets a payer add funds to their balance through a hosted Top-Up flow. 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. orderTotalAmount and redirectUrl are omitted from the response when they were not supplied at creation; they are never returned as null. customerDisplay contains the resolved merchant name stored at creation, including the entity's profile name when no nonempty override was supplied. The response and creation webhook always include customerDisplay and its merchantName.
The ID of the Top-Up Link, a UUID prefixed by topUpLink_.
^topUpLink_[a-f0-9\-]{36}$"topUpLink_6f2e9b41-c0f4-4bf8-a4b2-c105f9453a24"
The merchant-provided initial suggested net amount to add for the link's single purchase, denominated in asset. The suggestion remains fixed on the link and is not recomputed from orderTotalAmount or the payer's current available balance. The payer can adjust the amount they add in the hosted flow. Fiat fees are outside this value.
^(?:0|[1-9]\d*)(?:\.\d{1,2})?$"100.00"
The asset credited by the Top-Up Link. Currently, only usdc is supported.
usdc 1 - 42"usdc"
Display details resolved at creation and stored on the immutable Top-Up Link. These details are returned in the create response and creation webhook.
The hosted Top-Up page URL. Share this URL only with the intended payer. The URL identifies the Top-Up Link but does not authorize a purchase; the payer must authenticate and approve the purchase.
12 - 2048^https://.*$"https://pay.coinbase.com/top-up/topUpLink_6f2e9b41-c0f4-4bf8-a4b2-c105f9453a24"
The UTC ISO 8601 timestamp after which the link can no longer be used, 24 hours after creation. A link that has already funded a purchase is spent before this time.
"2026-09-12T20:00:00Z"
The UTC ISO 8601 timestamp at which the Top-Up Link was created.
"2026-09-11T20:00:00Z"
The total balance, denominated in asset, that the merchant expects the payer to need to complete the order, as supplied at creation. When present, the hosted Top-Up page shows the order total and the payer's current available balance, and computes the remaining shortfall from those values. This live shortfall is separate from topUpAmount and does not replace or change that fixed suggestion. It does not limit the amount the payer can add. Omitted when not supplied at creation.
^(?:0|[1-9]\d*)(?:\.\d{1,2})?$"130.45"
The absolute HTTPS URL to which the payer is redirected after the top-up completes, as supplied at creation. Omitted when not supplied at creation. This value can contain sensitive merchant parameters; treat it as secret and do not log it.
12 - 2048^https://.*$"https://www.example-merchant.com/checkout/return?orderId=701-3358192-4471016&sig=8a3f"