Skip to main content

​
Environments

Payment Acceptance has separate Sandbox (testing) and Production (live) environments. Use the host and URLs for your target environment consistently — the REST API, the returned hosted checkout URL, and the embedded component are all environment-specific.
EnvironmentREST API hostEmbedded component script
Sandboxhttps://sandbox.cdp.coinbase.com/platformhttps://payments.coinbase.com/sandbox/payments/components/v1/payment-link.mjs
Productionhttps://api.cdp.coinbase.com/platformhttps://payments.coinbase.com/payments/components/v1/payment-link.mjs
Keep the environment consistent across all three. For example, a Sandbox payment session will not render in the Production component.

​
Overview

​
Redirect flow

Redirect customers to a hosted checkout page.
1

Create a payment session

Call POST /v2/payment-sessions on the host for your environment (see Environments) 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

Load the web component from the URL for your target environment. Use the Sandbox URL for testing and switch to the Production URL when you go live. 
<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

AttributeDescription
layoutSet 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:
EventDescription
renderedFired when the component is ready. Includes installedWallets in detail.
completedPayment completed. Detail includes status: 'success' | 'failure'.
cancelledUser cancelled the payment.
walletActionWallet interaction events (selected, connected, rejected).
pageNavigatedNavigation between views. Detail includes page name.
paymentErrorError occurred. Detail includes error message.
deeplinkDeeplink 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);
});
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;
}
PropertyDefault
--cb-color-background-primarywhite
--cb-color-background-secondarywhite
--cb-color-qr-backgroundwhite
--cb-color-text-primaryblack
--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-icongrey
--cb-color-icon-background-hoverlight gray
--cb-typography-header-font-familySystem
--cb-typography-body-font-familySystem