Skip to main content

Custom integration

If providers can't integrate into the MetaMask Fiat On-Ramp using the standard integration, they can apply for a custom integration. This requires the MetaMask On-Ramp team to create a connector dedicated to the provider's system.

The following is a list of requirements the provider API must satisfy.

Coverage data​

Regions​

An endpoint must return the list of regions (countries/states) the provider is supported in, using:

Cryptocurrencies​

An endpoint must return the list of supported cryptocurrencies, including:

  • The cryptocurrency network, identified by its chain ID.
  • The smart contract address (not just the coin ticker).

If a cryptocurrency is only partially supported (for example, not in a specific country with a specific payment method), this information must be available through an endpoint.

Fiat currencies​

An endpoint must return the list of supported fiat currencies, identified by their ISO 4217 codes (for example, USD and SEK).

If a fiat currency is only partially supported (for example, not in a specific country which supports other fiat currencies), this information must be available through an endpoint.

Payment methods​

An endpoint must return the list of supported payment methods.

If a payment method is only partially supported (for example, not in a specific country that supports other payment methods), this information must be available through an endpoint.

Quotes​

An endpoint must allow MetaMask to get a quote for purchase.

The quote endpoint must accept the following parameters:

  • Region (country or state)
  • Cryptocurrency
  • Fiat currency
  • Payment method
  • Amount (expressed in the fiat currency)

The quote returned by the endpoint must contain:

  • The amount of cryptocurrency the user can buy with the specified fiat amount.
  • The amount of fees (processing fee, network fee, partner fee, etc.).
  • The exchange rate.

MetaMask must be able to call the quote endpoint without a password or secret. A public account identifier (for example, metamask-account) may be required by the provider, especially to return correct fees.

Buy limits​

An endpoint must allow MetaMask to get the minimum and maximum valid amount for a combination of payment methods, fiat currencies, and cryptocurrencies.

The limit endpoint must contain enough information to compute minimums and maximums without requiring a single call for each payment method, cryptocurrency, and fiat currency combination. This must include information about any network or provider fees.

Information returned by this endpoint must be sufficient to obtain the exact limit to be used in the web widget.

Buy widget​

The API must allow a buy widget to be built. This is a URL pointing to a responsive web page allowing users to buy cryptocurrencies. This web page can be displayed in a mobile React Native cross-platform WebView.

The widget URL must accept the following parameters:

  • Region (country or state)
  • Cryptocurrency
  • Fiat currency
  • Payment method
  • Amount (expressed in the fiat currency)
  • Ethereum wallet address

The widget must prevent the user from modifying pre-filled information.

The widget URL must accept a callback URL as a parameter, which the user is redirected to after a purchase. The callback is called with a query parameter containing the order ID.

The user must not have to select a button to be redirected and must not have any waiting screen. The user must not be able to avoid being redirected to the callback.

The buying process must be able to be executed on a mobile device or web app without requiring a ConsenSys back end. Getting quotes or displaying the widget must not require any API secret or password.

Order tracking​

The order ID included in the callback must allow MetaMask to track the order status.

MetaMask must be able to track the order status without an API secret, and call the order status without requiring a back end.

The order tracking endpoint must return the following properties:

  • Cryptocurrency
  • Fiat currency
  • Payment method
  • Amount

Based on the order ID included in the callback, it must be possible to generate a URL pointing to a web page of the provider displaying the order status. If this requires the user to be logged into the provider website, and they're currently not, the user must be prompted for their credentials. The user must not end up on an error page if they're not currently logged in.

Analytics and business intelligence​

A MetaMask partner ID must be linked to purchases.

An endpoint must allow listing all purchases associated with MetaMask. This endpoint must be secured (can only be called by ConsenSys/MetaMask).

Testing and QA​

A testing environment must be provided. All production payment methods must be available in the testing environment.