Checkout

Overview

Redirect flow

Redirect customers to a hosted checkout page.

1. Create a payment session

   Call POST /v2/payment-sessions with your payment details. Include a redirect object in the request body with successUrl and failureUrl to control where customers land after payment.

2. Extract the payment URL

   From the response, get the top-level url field. This is the hosted payment page where customers complete the payment.

3. Redirect customers

   Redirect customers to the url to complete the payment.

4. Handle the redirect

   After payment completion, customers are automatically redirected to your redirect.successUrl or redirect.failureUrl.

Embedded UI

The payment UI can be embedded natively into your website using Coinbase’s <coinbase-payment> web component. This allows customers to complete payments without leaving your checkout page.

Setup

<script 
  type="module"
  src="https://payments.coinbase.com/payments/components/v1/payment-link.mjs"
></script>

<coinbase-payment id="payment-link"></coinbase-payment>

Rendering

Call render() with the paymentSessionId from the POST /v2/payment-sessions response:

const paymentComponent = document.querySelector('#payment-link');
paymentComponent.render({ paymentSessionId });

To re-render with updated payment data, call render() again. To navigate back to the wallet selection view, call back():

paymentComponent.back();

Attributes

Attribute	Description
layout	Set to "single-column" to force the small desktop view regardless of screen size. Set to "default" for the standard 2-column layout when appropriate.

<coinbase-payment layout="single-column"></coinbase-payment>

Events

The component emits Custom Events for handling payment outcomes:

Event	Description
rendered	Fired when the component is ready. Includes installedWallets in detail.
completed	Payment completed. Detail includes status: 'success' | 'failure'.
cancelled	User cancelled the payment.
walletAction	Wallet interaction events (selected, connected, rejected).
pageNavigated	Navigation between views. Detail includes page name.
paymentError	Error occurred. Detail includes error message.
deeplink	Deeplink URL for mobile wallet redirects. Detail includes url.

paymentComponent.addEventListener('completed', (event) => {
  if (event.detail.status === 'success') {
    // Handle successful payment
  }
});

paymentComponent.addEventListener('paymentError', (event) => {
  console.error('Payment error:', event.detail.error);
});

Deeplink handling (iframes)

When the component is rendered inside an iframe, it cannot redirect the browser directly. You must handle the deeplink event to perform the redirect from the parent page:

paymentComponent.addEventListener('deeplink', (event) => {
  window.location.href = event.detail.url;
});

iFrame permissions

If embedding the component inside an iframe, configure the following permissions to enable passkey and clipboard access:

<iframe 
  src="your-checkout-page.html"
  allow="publickey-credentials-get; publickey-credentials-create; clipboard-write"
></iframe>

Theming

Customize the component appearance using CSS custom properties:

coinbase-payment {
  --cb-color-background-primary: #ffffff;
  --cb-color-text-primary: #000000;
  --cb-color-button-primary: #005bd3;
  --cb-color-button-primary-hover: #004bb3;
  --cb-typography-header-font-family: 'Your Font', sans-serif;
  --cb-typography-body-font-family: 'Your Font', sans-serif;
  --cb-border-radius-button-primary: 8px;
}

All CSS custom properties

Property	Default
--cb-color-background-primary	white
--cb-color-background-secondary	white
--cb-color-qr-background	white
--cb-color-text-primary	black
--cb-color-link-hover	-
--cb-color-button-primary	#005bd3 (blue)
--cb-color-button-primary-hover	#005bd3 (blue)
--cb-color-button-primary-text	-
--cb-color-button-border-primary	-
--cb-color-accent-primary	-
--cb-border-radius-button-primary	-
--cb-color-navigation-hover	-
--cb-color-border-primary	-
--cb-color-icon	grey
--cb-color-icon-background-hover	light gray
--cb-typography-header-font-family	System
--cb-typography-body-font-family	System