Customizing the Onramp Experience

Recommended: JavaScript SDK with React Hooks

For new React apps, we recommend the JavaScript SDK with React Hooks (@dynamic-labs-sdk/react-hooks) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the React quickstart (JavaScript SDK) to get started.

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.

React

<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.

React

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.

React

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:

React

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:

Coinbase Onramp Supported Countries and Payment Methods

Below is a comprehensive list of all countries and payment methods supported by Coinbase onramp. This information can help you understand the global reach and payment options available when setting up Coinbase onramp for your application. You can also fetch the latest version of this list from the Coinbase Onramp API.

Supported Countries and Payment Methods

Country	Country Code	Payment Methods
Andorra	AD	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
United Arab Emirates	AE	CRYPTO_ACCOUNT
Albania	AL	CRYPTO_ACCOUNT
Armenia	AM	CRYPTO_ACCOUNT
Angola	AO	CRYPTO_ACCOUNT
Argentina	AR	CRYPTO_ACCOUNT
Austria	AT	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Australia	AU	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Barbados	BB	CRYPTO_ACCOUNT
Bangladesh	BD	CRYPTO_ACCOUNT
Belgium	BE	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Burkina Faso	BF	CRYPTO_ACCOUNT
Bulgaria	BG	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Bahrain	BH	CRYPTO_ACCOUNT
Benin	BJ	CRYPTO_ACCOUNT
Bolivia	BO	CRYPTO_ACCOUNT
Brazil	BR	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Belarus	BY	CRYPTO_ACCOUNT
Canada	CA	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Republic of the Congo	CG	CRYPTO_ACCOUNT
Switzerland	CH	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Ivory Coast	CI	CRYPTO_ACCOUNT
Chile	CL	CRYPTO_ACCOUNT
Cameroon	CM	CRYPTO_ACCOUNT
Colombia	CO	CRYPTO_ACCOUNT
Costa Rica	CR	CRYPTO_ACCOUNT
Cyprus	CY	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Czech Republic	CZ	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Germany	DE	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Denmark	DK	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Dominican Republic	DO	CRYPTO_ACCOUNT
Algeria	DZ	CRYPTO_ACCOUNT
Ecuador	EC	CRYPTO_ACCOUNT
Estonia	EE	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Egypt	EG	CRYPTO_ACCOUNT
Spain	ES	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Ethiopia	ET	CRYPTO_ACCOUNT
Finland	FI	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
France	FR	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Gabon	GA	CRYPTO_ACCOUNT
United Kingdom	GB	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Georgia	GE	CRYPTO_ACCOUNT
Guernsey	GG	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Ghana	GH	CRYPTO_ACCOUNT
Gibraltar	GI	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Greece	GR	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Guatemala	GT	CRYPTO_ACCOUNT
Hong Kong	HK	CRYPTO_ACCOUNT
Honduras	HN	CRYPTO_ACCOUNT
Croatia	HR	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Haiti	HT	CRYPTO_ACCOUNT
Hungary	HU	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Indonesia	ID	CRYPTO_ACCOUNT
Ireland	IE	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Israel	IL	CRYPTO_ACCOUNT
Isle of Man	IM	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
India	IN	CRYPTO_ACCOUNT
Iceland	IS	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Italy	IT	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Jersey	JE	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Jamaica	JM	CRYPTO_ACCOUNT
Japan	JP	CRYPTO_ACCOUNT
Kenya	KE	CRYPTO_ACCOUNT
Kyrgyzstan	KG	CRYPTO_ACCOUNT
Cambodia	KH	CRYPTO_ACCOUNT
South Korea	KR	CRYPTO_ACCOUNT
Kuwait	KW	CRYPTO_ACCOUNT
Cayman Islands	KY	CRYPTO_ACCOUNT
Kazakhstan	KZ	CRYPTO_ACCOUNT
Lebanon	LB	CRYPTO_ACCOUNT
Saint Lucia	LC	CRYPTO_ACCOUNT
Liechtenstein	LI	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Sri Lanka	LK	CRYPTO_ACCOUNT
Lithuania	LT	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Luxembourg	LU	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Latvia	LV	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Morocco	MA	CRYPTO_ACCOUNT
Monaco	MC	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Moldova	MD	CRYPTO_ACCOUNT
North Macedonia	MK	CRYPTO_ACCOUNT
Myanmar	MM	CRYPTO_ACCOUNT
Mongolia	MN	CRYPTO_ACCOUNT
Malta	MT	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Maldives	MV	CRYPTO_ACCOUNT
Mexico	MX	CRYPTO_ACCOUNT
Malaysia	MY	CRYPTO_ACCOUNT
Mozambique	MZ	CRYPTO_ACCOUNT
Niger	NE	CRYPTO_ACCOUNT
Nigeria	NG	CRYPTO_ACCOUNT
Nicaragua	NI	CRYPTO_ACCOUNT
Netherlands	NL	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Norway	NO	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Nepal	NP	CRYPTO_ACCOUNT
New Zealand	NZ	CARD, CRYPTO_ACCOUNT
Panama	PA	CRYPTO_ACCOUNT
Peru	PE	CRYPTO_ACCOUNT
Philippines	PH	CRYPTO_ACCOUNT
Pakistan	PK	CRYPTO_ACCOUNT
Poland	PL	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Portugal	PT	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Paraguay	PY	CRYPTO_ACCOUNT
Romania	RO	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Serbia	RS	CRYPTO_ACCOUNT
Saudi Arabia	SA	CRYPTO_ACCOUNT
Sudan	SD	CRYPTO_ACCOUNT
Sweden	SE	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Singapore	SG	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Slovenia	SI	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Slovakia	SK	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
San Marino	SM	CARD, CRYPTO_ACCOUNT, FIAT_WALLET
Senegal	SN	CRYPTO_ACCOUNT
El Salvador	SV	CRYPTO_ACCOUNT
Togo	TG	CRYPTO_ACCOUNT
Thailand	TH	CRYPTO_ACCOUNT
Tunisia	TN	CRYPTO_ACCOUNT
Turkey	TR	CRYPTO_ACCOUNT
Trinidad and Tobago	TT	CRYPTO_ACCOUNT
Taiwan	TW	CRYPTO_ACCOUNT
Ukraine	UA	CRYPTO_ACCOUNT
United States	US	CARD, CRYPTO_ACCOUNT, FIAT_WALLET, ACH_BANK_ACCOUNT, APPLE_PAY
Vietnam	VN	CRYPTO_ACCOUNT
South Africa	ZA	CRYPTO_ACCOUNT

Payment Method Types

CARD: Credit/debit card payments
CRYPTO_ACCOUNT: Payments from existing crypto accounts
FIAT_WALLET: Payments from fiat wallet balances
ACH_BANK_ACCOUNT: Automated Clearing House bank transfers (US only)
APPLE_PAY: Apple Pay mobile payments (US only)

The United States has the most comprehensive payment method support, including all available payment types. Most European countries support CARD, CRYPTO_ACCOUNT, and FIAT_WALLET, while many other regions are limited to CRYPTO_ACCOUNT only.

Coinbase Onramp Supported Currencies

Each country has a list of supported assets/currencies that can be purchased. You can check this by calling the Coinbase Onramp API with the countries parameter (see the API reference here).

useOnramp - Programmatic onramp triggering from your UI
usePayWithDynamic - Unified payment flow with all funding options
Crypto.com - Detailed Crypto.com onramp integration guide
MoonPay - Detailed MoonPay onramp integration guide

Implementation Guides

SDK Reference

Customizing the Onramp Experience

Recommended: JavaScript SDK with React Hooks

Introduction

OnrampOptions

Customization Examples

Example 1: Customizing the existing Coinbase Onramp URL

Example 2: Adding a payment method option

Example 3: Bring Your Own Onramp

Coinbase Onramp Supported Countries and Payment Methods

Payment Method Types

Coinbase Onramp Supported Currencies

Recommended: JavaScript SDK with React Hooks

​Introduction

​OnrampOptions

​Customization Examples

​Example 1: Customizing the existing Coinbase Onramp URL

​Example 2: Adding a payment method option

​Example 3: Bring Your Own Onramp

​Coinbase Onramp Supported Countries and Payment Methods

​Payment Method Types

​Coinbase Onramp Supported Currencies

​Related

Introduction

OnrampOptions

Customization Examples

Example 1: Customizing the existing Coinbase Onramp URL

Example 2: Adding a payment method option

Example 3: Bring Your Own Onramp

Coinbase Onramp Supported Countries and Payment Methods

Payment Method Types

Coinbase Onramp Supported Currencies

Related