Skip to main content

​
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:
PropertyTypeRequiredDefaultDescription
displayNamestringYes-The name of the onramp provider to be displayed in UI.
Example: “Coinbase”
iconUrlstringYes-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”
idstringYes-The id of the onramp provider, ideally based off its name.
Example: “coinbase”
urlstringNo-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
onClickfunctionYes-The onClick handler for when the onramp provider is selected.
Signature: ({ wallet }: { wallet: Wallet }) => void
descriptionstringNo-The description of the onramp provider to be displayed in UI.
Example: “Buy crypto with a credit card”
isPaymentMethodbooleanNofalseWhether 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:
Coinbase Onramp Credit Card

​
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:
My New Onramp

​
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.
CountryCountry CodePayment Methods
AndorraADCARD, CRYPTO_ACCOUNT, FIAT_WALLET
United Arab EmiratesAECRYPTO_ACCOUNT
AlbaniaALCRYPTO_ACCOUNT
ArmeniaAMCRYPTO_ACCOUNT
AngolaAOCRYPTO_ACCOUNT
ArgentinaARCRYPTO_ACCOUNT
AustriaATCARD, CRYPTO_ACCOUNT, FIAT_WALLET
AustraliaAUCARD, CRYPTO_ACCOUNT, FIAT_WALLET
BarbadosBBCRYPTO_ACCOUNT
BangladeshBDCRYPTO_ACCOUNT
BelgiumBECARD, CRYPTO_ACCOUNT, FIAT_WALLET
Burkina FasoBFCRYPTO_ACCOUNT
BulgariaBGCARD, CRYPTO_ACCOUNT, FIAT_WALLET
BahrainBHCRYPTO_ACCOUNT
BeninBJCRYPTO_ACCOUNT
BoliviaBOCRYPTO_ACCOUNT
BrazilBRCARD, CRYPTO_ACCOUNT, FIAT_WALLET
BelarusBYCRYPTO_ACCOUNT
CanadaCACARD, CRYPTO_ACCOUNT, FIAT_WALLET
Republic of the CongoCGCRYPTO_ACCOUNT
SwitzerlandCHCARD, CRYPTO_ACCOUNT, FIAT_WALLET
Ivory CoastCICRYPTO_ACCOUNT
ChileCLCRYPTO_ACCOUNT
CameroonCMCRYPTO_ACCOUNT
ColombiaCOCRYPTO_ACCOUNT
Costa RicaCRCRYPTO_ACCOUNT
CyprusCYCARD, CRYPTO_ACCOUNT, FIAT_WALLET
Czech RepublicCZCARD, CRYPTO_ACCOUNT, FIAT_WALLET
GermanyDECARD, CRYPTO_ACCOUNT, FIAT_WALLET
DenmarkDKCARD, CRYPTO_ACCOUNT, FIAT_WALLET
Dominican RepublicDOCRYPTO_ACCOUNT
AlgeriaDZCRYPTO_ACCOUNT
EcuadorECCRYPTO_ACCOUNT
EstoniaEECARD, CRYPTO_ACCOUNT, FIAT_WALLET
EgyptEGCRYPTO_ACCOUNT
SpainESCARD, CRYPTO_ACCOUNT, FIAT_WALLET
EthiopiaETCRYPTO_ACCOUNT
FinlandFICARD, CRYPTO_ACCOUNT, FIAT_WALLET
FranceFRCARD, CRYPTO_ACCOUNT, FIAT_WALLET
GabonGACRYPTO_ACCOUNT
United KingdomGBCARD, CRYPTO_ACCOUNT, FIAT_WALLET
GeorgiaGECRYPTO_ACCOUNT
GuernseyGGCARD, CRYPTO_ACCOUNT, FIAT_WALLET
GhanaGHCRYPTO_ACCOUNT
GibraltarGICARD, CRYPTO_ACCOUNT, FIAT_WALLET
GreeceGRCARD, CRYPTO_ACCOUNT, FIAT_WALLET
GuatemalaGTCRYPTO_ACCOUNT
Hong KongHKCRYPTO_ACCOUNT
HondurasHNCRYPTO_ACCOUNT
CroatiaHRCARD, CRYPTO_ACCOUNT, FIAT_WALLET
HaitiHTCRYPTO_ACCOUNT
HungaryHUCARD, CRYPTO_ACCOUNT, FIAT_WALLET
IndonesiaIDCRYPTO_ACCOUNT
IrelandIECARD, CRYPTO_ACCOUNT, FIAT_WALLET
IsraelILCRYPTO_ACCOUNT
Isle of ManIMCARD, CRYPTO_ACCOUNT, FIAT_WALLET
IndiaINCRYPTO_ACCOUNT
IcelandISCARD, CRYPTO_ACCOUNT, FIAT_WALLET
ItalyITCARD, CRYPTO_ACCOUNT, FIAT_WALLET
JerseyJECARD, CRYPTO_ACCOUNT, FIAT_WALLET
JamaicaJMCRYPTO_ACCOUNT
JapanJPCRYPTO_ACCOUNT
KenyaKECRYPTO_ACCOUNT
KyrgyzstanKGCRYPTO_ACCOUNT
CambodiaKHCRYPTO_ACCOUNT
South KoreaKRCRYPTO_ACCOUNT
KuwaitKWCRYPTO_ACCOUNT
Cayman IslandsKYCRYPTO_ACCOUNT
KazakhstanKZCRYPTO_ACCOUNT
LebanonLBCRYPTO_ACCOUNT
Saint LuciaLCCRYPTO_ACCOUNT
LiechtensteinLICARD, CRYPTO_ACCOUNT, FIAT_WALLET
Sri LankaLKCRYPTO_ACCOUNT
LithuaniaLTCARD, CRYPTO_ACCOUNT, FIAT_WALLET
LuxembourgLUCARD, CRYPTO_ACCOUNT, FIAT_WALLET
LatviaLVCARD, CRYPTO_ACCOUNT, FIAT_WALLET
MoroccoMACRYPTO_ACCOUNT
MonacoMCCARD, CRYPTO_ACCOUNT, FIAT_WALLET
MoldovaMDCRYPTO_ACCOUNT
North MacedoniaMKCRYPTO_ACCOUNT
MyanmarMMCRYPTO_ACCOUNT
MongoliaMNCRYPTO_ACCOUNT
MaltaMTCARD, CRYPTO_ACCOUNT, FIAT_WALLET
MaldivesMVCRYPTO_ACCOUNT
MexicoMXCRYPTO_ACCOUNT
MalaysiaMYCRYPTO_ACCOUNT
MozambiqueMZCRYPTO_ACCOUNT
NigerNECRYPTO_ACCOUNT
NigeriaNGCRYPTO_ACCOUNT
NicaraguaNICRYPTO_ACCOUNT
NetherlandsNLCARD, CRYPTO_ACCOUNT, FIAT_WALLET
NorwayNOCARD, CRYPTO_ACCOUNT, FIAT_WALLET
NepalNPCRYPTO_ACCOUNT
New ZealandNZCARD, CRYPTO_ACCOUNT
PanamaPACRYPTO_ACCOUNT
PeruPECRYPTO_ACCOUNT
PhilippinesPHCRYPTO_ACCOUNT
PakistanPKCRYPTO_ACCOUNT
PolandPLCARD, CRYPTO_ACCOUNT, FIAT_WALLET
PortugalPTCARD, CRYPTO_ACCOUNT, FIAT_WALLET
ParaguayPYCRYPTO_ACCOUNT
RomaniaROCARD, CRYPTO_ACCOUNT, FIAT_WALLET
SerbiaRSCRYPTO_ACCOUNT
Saudi ArabiaSACRYPTO_ACCOUNT
SudanSDCRYPTO_ACCOUNT
SwedenSECARD, CRYPTO_ACCOUNT, FIAT_WALLET
SingaporeSGCARD, CRYPTO_ACCOUNT, FIAT_WALLET
SloveniaSICARD, CRYPTO_ACCOUNT, FIAT_WALLET
SlovakiaSKCARD, CRYPTO_ACCOUNT, FIAT_WALLET
San MarinoSMCARD, CRYPTO_ACCOUNT, FIAT_WALLET
SenegalSNCRYPTO_ACCOUNT
El SalvadorSVCRYPTO_ACCOUNT
TogoTGCRYPTO_ACCOUNT
ThailandTHCRYPTO_ACCOUNT
TunisiaTNCRYPTO_ACCOUNT
TurkeyTRCRYPTO_ACCOUNT
Trinidad and TobagoTTCRYPTO_ACCOUNT
TaiwanTWCRYPTO_ACCOUNT
UkraineUACRYPTO_ACCOUNT
United StatesUSCARD, CRYPTO_ACCOUNT, FIAT_WALLET, ACH_BANK_ACCOUNT, APPLE_PAY
VietnamVNCRYPTO_ACCOUNT
South AfricaZACRYPTO_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).
⌘I