pub struct TopUpLink {
pub asset: TopUpLinkAsset,
pub created_at: DateTime<Utc>,
pub customer_display: TopUpCustomerDisplay,
pub expires_at: DateTime<Utc>,
pub order_total_amount: Option<TopUpLinkAmount>,
pub redirect_url: Option<HttpsUrl>,
pub top_up_amount: TopUpLinkAmount,
pub top_up_link_id: TopUpLinkId,
pub top_up_url: HttpsUrl,
}Expand description
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.
JSON schema
{
"description": "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`.",
"examples": [
{
"asset": "usdc",
"createdAt": "2026-09-11T20:00:00Z",
"customerDisplay": {
"merchantName": "Example Merchant"
},
"expiresAt": "2026-09-12T20:00:00Z",
"orderTotalAmount": "130.45",
"redirectUrl": "https://www.example-merchant.com/checkout/return?orderId=701-3358192-4471016&sig=8a3f",
"topUpAmount": "100.00",
"topUpLinkId": "topUpLink_6f2e9b41-c0f4-4bf8-a4b2-c105f9453a24",
"topUpUrl": "https://pay.coinbase.com/top-up/topUpLink_6f2e9b41-c0f4-4bf8-a4b2-c105f9453a24"
}
],
"type": "object",
"required": [
"asset",
"createdAt",
"customerDisplay",
"expiresAt",
"topUpAmount",
"topUpLinkId",
"topUpUrl"
],
"properties": {
"asset": {
"description": "The asset credited by the Top-Up Link. Currently, only `usdc` is supported.",
"examples": [
"usdc"
],
"allOf": [
{
"$ref": "#/components/schemas/TopUpLinkAsset"
}
]
},
"createdAt": {
"description": "The UTC ISO 8601 timestamp at which the Top-Up Link was created.",
"examples": [
"2026-09-11T20:00:00Z"
],
"type": "string",
"format": "date-time"
},
"customerDisplay": {
"$ref": "#/components/schemas/TopUpCustomerDisplay"
},
"expiresAt": {
"description": "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.",
"examples": [
"2026-09-12T20:00:00Z"
],
"type": "string",
"format": "date-time"
},
"orderTotalAmount": {
"description": "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.",
"examples": [
"130.45"
],
"allOf": [
{
"$ref": "#/components/schemas/TopUpLinkAmount"
}
]
},
"redirectUrl": {
"description": "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.",
"examples": [
"https://www.example-merchant.com/checkout/return?orderId=701-3358192-4471016&sig=8a3f"
],
"allOf": [
{
"$ref": "#/components/schemas/HttpsUrl"
}
]
},
"topUpAmount": {
"description": "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.",
"examples": [
"100.00"
],
"allOf": [
{
"$ref": "#/components/schemas/TopUpLinkAmount"
}
]
},
"topUpLinkId": {
"$ref": "#/components/schemas/TopUpLinkId"
},
"topUpUrl": {
"description": "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.",
"examples": [
"https://pay.coinbase.com/top-up/topUpLink_6f2e9b41-c0f4-4bf8-a4b2-c105f9453a24"
],
"allOf": [
{
"$ref": "#/components/schemas/HttpsUrl"
}
]
}
}
}Fields§
§asset: TopUpLinkAssetThe asset credited by the Top-Up Link. Currently, only usdc is supported.
created_at: DateTime<Utc>The UTC ISO 8601 timestamp at which the Top-Up Link was created.
customer_display: TopUpCustomerDisplay§expires_at: DateTime<Utc>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.
order_total_amount: Option<TopUpLinkAmount>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.
redirect_url: Option<HttpsUrl>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.
top_up_amount: TopUpLinkAmountThe 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.
top_up_link_id: TopUpLinkId§top_up_url: HttpsUrlThe 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.