⚠️ DEPRECATION WARNING ⚠️

This widget has been deprecated and the repository is currently in the maintenance mode.

Please refer to the Onramper official documentation on how to configure the brand new widget offered by Onramper: https://docs.onramper.com/docs/integration-widget.

You can also try the new widget on this page.

---

Onramper

Instructions of how to integrate the widget in your website here.

This project is created using create-react-app with typescript, here you will find some notes about how to customize or build the widget from the source files. In this repo you will find the source files of Onramper's buy page (widget.onramper.com) and the source files of the widget component (@onramper/widget)

Development

$ cd iframe
$ npm run setup
$ cd ../package
$ npm run setup

Connecting to local server

$ cd package
$ npm run start:local
$ cd ../iframe
$ npm run start:local

Directory structure (only main files listed):

.
├── iframe # Onramper's buy page
│   ├── ...
│   └── src
│       ├── ...
│       ├── App.tsx
│       ├── index.css
│       └── index.tsx 
└── package # Onramper's widget source code
    ├── ...
    ├── dist
    └── src
        ├── ...
        ├── NavContext
        ├── ApiContext
        │   ├── ...
        │   └── api 
        ├── steps
        │   ├── ...
        │   └── Step 
        └── index.tsx

Setup

Install dependencies:

npm install

Developement

Start a developement server:

npm start

Build

Build the buy page as an static site into the ./build folder:

npm run build

Build the widget component source files into the ./dist folder:

npm run build:{prod|dev|demo}

Buy page

File / folder	Description
./	Project generated using create-react-app.
./src/App.tsx ./src/index.css ./src/index.tsx	Buy page files.
./package.json	The @onramper/widget package used in src/App.tsx is a local dependency and the route to the package is defined here.

Widget

Package

File / folder	Description
./src/NavContext	Navigation context. Manages the screens stack and the transitions. Exposes functions to navigate between screens. See more.
./src/ApiContext	Api context. Manages the state of the app and the API calls. Exposes functions to make requests to the api and manage the general state. See more.
./src/ApiContext/api	Module that handles the API calls.
./src/steps/Step	General step component. Used to redirect and display the correct screen according to the next step received from the API.
./src/steps	This folder contains the diferent step screens.
./src/index.tsx	Exports the widget component.

NavContext

The navigation context manages the screens stack and transitions and exposes functions to navigate between screens.

Exports NavContext, NavProvider and NavContainer.

NavProvider: Navigation provider. Wraps the components that will consume the context.
NavContainer: Container of the screens. The component that will be used as main screen should be passed as prop to this component.
NavContext: Navigation context. Used to consume the context.

Functions availables to consume:

Function	Description
nextScreen(screen: React.ReactNode)	Adds screen to the top of the screens stack.
backScreen()	Removes the top screen of the stack.
onlyScreen(screen: React.ReactNode)	Removes all screens and after adds screen to the stack.
replaceScreen(screen: React.ReactNode)	Replaces the top screen of the stack by screen.

ApiContext

The api context manages the state of the widget and the API responses. Exposes functions and variables to manage the general state of the widget and to interact with the api. To learn about the api execution flow, click here.

Consuming ApiContext you can access to 4 objects: collected, apiInterface, data, inputInterface.

inputInterface

Provides functions to update and collect variables.

Function	Description
inputInterface.handleInputChange(name: string, value: any)	Function used to update and add variables to the collected object.

collected

Object that stores all input variables. New variables can be added and/or updated using the inputInterface. Below are shown only some of the parameters availables in the object, see declaration for all initial attributes .

Variable	Description
amount number	Amount user wants to buy.
amountInCrypto boolean	true if the amount is in crypto, false if the amount is in fiat.
selectedCrypto ItemType selectedCurrency ItemType selectedPaymentMethod ItemType selectedGateway GatewayRateOption	Stores the respective selected items. The selectedCrypto, selectedCurrency and the selectedPaymentMethod attributes can be updated if apiInterface.init is called or one of this attributes is changed.
errors error object	Errrors found trying to get the gateways or the rates.

error object

{
    [name]: {
        type: string,
        message: string
    },
    ...
}

name	type	Error description
GATEWAYS	API	Failed request to the api.
GATEWAYS	NO_GATEWAYS	No gateways found for the current parameters (amount, selectedCrypto, selectedCurrency, selectedCountry, amountInCrypto)
GATEWAYS	NO_CRYPTOS	No cryptocurrencies found, this error appears when all the available cryptos are added into the excludeCryptos filter.
RATE	API	Failed request to the api.
RATE	NO_RATES	Found gateways availables but there are no rates availables.
amount	PARAM	There are rates availables for the selected items, but the amount is not enough or it's too much, the message attribute specifies the max or min amount needed to be able to buy crypto in at least one of the available gateways.

apiInterface

Provides functions to interact with the API.

Function	Description
init(country?: string)	Makes a call to get all the options the user have for buy crypto given a country. This function triggers a call to handleCryptoChange, handleCurrencyChange, handlePaymentMethodChange and getRates consecutively. If country is not set then the country parameter is automatically detected by Onramper's API using the user's IP address).
getRates()	Makes a call to get all rates and stores it into data.allRates (see data object). The parameters used to get the rates are selectedCrypto, selectedCurrency, selectedPaymentMethod and amount from the collected object. Each one of this rates, have an attribute nextStep that represents the first step to execute to start the purchase flow.
executeStep(step: NextStep, params: object)	Makes a call to step.url with the params object as a request body. Sends to the api the step with the corresponding step fields filled (params). The response of this call is a new step, also can throw an error if any error is made completing the params object. Read how steps work here.

data

Object that stores the lists of the available items (cryptos, currencies, payment methods and gateways) the user can select and includes functions to update that lists depending on the items selected. Through this object you can also access to the raw responses of the calls made to the api among others. See declaration for all attributes.

Function/variable	Description
availableCryptos ItemType[]	List of cryptos availables to buy in user's country. This is updated if apiInterface.init is called.
availableCurrencies ItemType[]	List of currencies with which you can buy the selected cryptocurrency (collected.selectedCrypto). This list is updated if the selected cryptocurrency is changed.
availablePaymentMethods ItemType[]	List of payment methods availables that can be used for buy the selected cryptocurrency with the selected currency (collected.selectedCurrency). This list is updated if the selected currency is changed.
allRates GatewayRateOption[]	List of available and unavailable gateways. This list is updated if amount, selectedCrypto, selectedCurrency or selectedPaymentMethod attributes from the collected object is changed.
data.handleCryptoChange(crypto?: ItemType) data.handleCurrencyChange(currency?: ItemType) data.handlePaymentMethodChange(paymentMethod?: ItemType)	Functions that updates the items lists (availableCryptos, availableCurrencies, availablePaymentMethods and allRates) and the selected items variables from the collected object if it's necessary.