Customizing the Onramp Experience

Introduction

If you’re reading this, you’ve probably already followed the instructions in Default Onramps and have enabled at least one onramp.

Here we’ll learn how to customize the experience further and bring your own.

Before continuing, please make sure you’re using the latest version of the Dynamic SDK packages.

OnrampOptions

Each onramp is represented by an OnrampOption object in the SDK, which has the following properties:

Property	Type	Required	Default	Description
displayName	string	Yes	-	The name of the onramp provider to be displayed in UI. Example: “Coinbase”
iconUrl	string	Yes	-	The icon URL of the onramp provider to be displayed in UI. Example: “https://www.coinbase.com/assets/coinbase-logo-2020-09-09-1024x1024.png”
id	string	Yes	-	The id of the onramp provider, ideally based off its name. Example: “coinbase”
url	string	No	-	The URL of the onramp provider. For iframe mode, this is displayed directly in the UI. For popup mode, this is opened in a new window when the provider is selected. Example: “https://widget.coinbase.com/iframe/onramp?apiKey=YOUR_API_KEY&walletAddress=YOUR_WALLET_ADDRESS”
openMode	’iframe’ | ‘popup’	No	’iframe’	The display mode for the onramp provider. ‘iframe’ - The provider will be displayed in an iframe within the UI ’popup’ - The provider will be opened in a new window when selected
onClick	function	Yes	-	The onClick handler for when the onramp provider is selected. Signature: ({ wallet }: { wallet: Wallet }) => void
description	string	No	-	The description of the onramp provider to be displayed in UI. Example: “Buy crypto with a credit card”
isPaymentMethod	boolean	No	false	Whether the option is for a specific payment method within the onramp provider. If true, the SDK will display the option as a payment method in the UI.

It’s important to note that the onClick handler is not customizable, but rather it takes the current URL defined in the url field and opens it in a new window.

These onrampOptions are accessible via the onrampOptions prop in the overrides prop of the DynamicContextProvider component which provides the current options and allows you to return a new array of options.

<DynamicContextProvider settings={
  overrides: {
    onrampOptions: (defaultOnrampOptions) => defaultOnrampOptions
  }}>
  <DynamicWidget />
</DynamicContextProvider>

Customization Examples

Example 1: Customizing the existing Coinbase Onramp URL

Let’s say you want to customize the current Coinbase onramp URL to include a custom parameter. You can do this by simply returning the same array of onramp options but with the url field updated.

const onrampOptions = (defaultOnrampOptions) => {
  return defaultOnrampOptions.map((option) => {
    if (option.id === "coinbaseOnramp") {
      option.url = `${option.url}&customParam=123`;
    }
    return option;
  });
};

Example 2: Adding a payment method option

Taking Coinbase as an example, you’ll see that there are multiple payment methods available for the onramp. You might want to give these options to the user in the widget.

In this case, you’ll want to return a new array of onramp options with the displayName field set to the payment method name as well as the URL adapted to include the payment method parameter.

const onrampOptions = (defaultOnrampOptions) => {
  return defaultOnrampOptions.map((option) => {
    if (option.id === "coinbaseOnramp") {
      return {
        ...option,
        displayName: "Credit Card",
        id: "coinbaseOnrampCreditCard",
        url: `${option.url}&defaultPaymentMethod=CARD`,
      };
    }
    return option;
  });
};

The result should look like this:

Example 3: Bring Your Own Onramp

Instead of changing the existing onramp options, you can also add your own option, which can be as simple as this:

const onrampOptions = (defaultOnrampOptions) => {
  return [
    ...defaultOnrampOptions,
     {
        id: 'myNewOnramp',
        url: 'https://dynamic.xyz',
        displayName: 'My New Onramp',
        iconUrl: 'https://my-company.com/icon.png',
        openMode: 'popup',
      },
  ];
};

The result should look like this: