Guides
DocumentationLog In

Integrating Coinbase Pay

This page explains how to trigger the Coinbase Pay experience by embedding a Coinbase Pay button with the Coinbase Pay SDK. When the user presses the Coinbase Pay button, the Coinbase Pay widget launches and is configured with the parameters passed.

A. Create a Coinbase Pay button

Download the Coinbase Pay button assets and add these buttons to your app. Here is a web integration example:

<a id="cbpay-button-container">
  <img src="./buy-with-coinbase.png" />
</a>

Some things to be mindful of:

  • The selector must be unique on the DOM, but the name is not important.
  • The element must be accessible using the querySelector API.
  • The image source should reference one of the Coinbase approved buttons defined in button assets download.

B. Call the initOnRamp method

When the HTML container is ready and has been mounted to the DOM, call initOnRamp from the Coinbase Pay SDK to attach click listeners to the button.

📘

Refer to the initOnRamp parameters.

initOnRamp Example

This is an example of how to implement in React with ready state listeners:

import { useEffect, useState } from 'react';
import { initOnRamp } from '@coinbase/cbpay-js';

function CoinbaseButton() {
    const [isReady, setIsReady] = useState(false);

    useEffect(() => {  
        initOnRamp({
            appId: 'AppIdProvidedByCoinbase',
            target: '#cbpay-button-container',
            widgetParameters: {
                destinationWallet: [{
                    address: '0x1A2C69...',
                    blockchains: ['ethereum', 'algorand'],
             }],
            onReady: () => {
                  // Update loading/ready states.
                  setIsReady(true);
            },
            onSuccess: () => {
                  // handle navigation when user successfully completes the flow
            },
            onExit: () => {
                  // handle navigation from dismiss / exit events due to errors
            },
            onEvent: (event) => {
                  // event stream
            },
            experienceLoggedIn: 'embedded',
            experienceLoggedOut: 'popup',
        });
    }, [])

    // render with button from previous example
    return (
        <BuyWithCoinbaseButton isLoading={!isReady} />
    );
}

initOnRamp Parameters

The following table outlines the parameters supported in the initOnRamp function:

ParameterReq'dTypeDescription
appIdYesStringUnique short-string ID provided to partners by the Coinbase Pay team
destinationWalletYesObjectArray of destinationWallet objects which define blockchain types (blockchains) and destination addresses (address)
targetYesStringQuery selector string for the container into which to embed the Coinbase Pay button
onSuccessNoObjectCallback that is triggered when the OnRamp purchase/send flow has finished
onExitNoObjectCallback when the OnRamp experience exits
onEventNoObjectCallback that emits events from the experience
closeOnExitNoBooleanAutomatically close the Coinbase Pay window when user exits the flow
closeOnSuccessNoBooleanAutomatically close the Coinbase Pay window on successful purchase
experienceLoggedInNoEnumEmbed Coinbase Pay into site/extension or run in popup window for logged in users (embedded,popup,new_tab)
experienceLoggedOutNoEnumEmbed Coinbase Pay into site/extension or run in popup window for logged out users (defaults to logged in option)

👍

Coinbase recommends using a mix of experienceLoggedIn: “embedded” and experienceLoggedOut: “popup” for a more seamless experience. Because for Chrome extensions, the logged out embedded experience opens a popup window (to login), and the extension popup may close, losing the window reference.

destinationWallet Parameters

The destination wallet object accepts the following parameters:

ParameterReq'dTypeDescription
addressYesStringDestination address where the purchased tokens will be sent.
blockchainsNoString[]List of blockchains enabled for the associated address. All tokens available per blockchain are displayed to the user.
assetsNoString[]List of assets enabled for the associated address. They are appended to the available list of tokens for the user to buy or send.

C. Test and Verify

After the Coinbase Pay SDK has been configured and inserted into the application, submit test transactions, and then validate that the funds have been delivered to the destination wallet.

If the SDK call to initOnRamp is misconfigured, then either (1) the button does not render or (2) the Coinbase Pay experience redirects to the Coinbase landing page.


See Also: