Payment Gateway

Users can be redirected to handle the payment process in a simple manner, similar to their interaction with traditional payment gateways. The Payment Gateway (PG) always utilizes the latest version of the Payments API and has a neutral design.

For the sake of simplicity, we shall assume that the payment gateway base URL is https://paymentgw.com/

The payment gateway can be used for both payments and for withdrawals of funds, and both for crypto and fiat. Since flows differ slightly, details are provided separately below.

For flows involving the Onboarding wallet, extra parameters are available to further facilitate UX. More information here.

Payments with Crypto

Payments in crypto are specified by including the /payment/crypto string in the redirect. Below we specify the rest of the mandatory and optional parameters.

Mandatory parameters

• web3Address: the public web3 address that will be required to sign the transaction. This parameter is case sensitive, and needs to be provided in checksum format.

• buynowId: identifier of the purchase.

• redirectUrl64: url where the user will be redirected after leaving the PG. It must be encoded in Base64.

Optional parameters

Aimed at enhancing the user experience, the following parameters can also be added using standard URL query string syntax:

• ?l={lang}: sets the default language of the payment gateway. Supported languages: English (US) en, and Spanish (Spain) es.

• ?wallet={wallet}: preselects the wallet that will be used to sign the transaction. Supported values: metaMask, walletConnect, and onboardingWallet.

The following summarizes how to build the URL with the parameters described so far:

https://paymentgw.com/payment/crypto/:web3Address/:buynowId/:redirectUrl64?l={lang}&wallet={wallet}

Payments with Fiat

Payments in fiat are specified by including the /payment/fiat string in the redirect. Below we specify the rest of mandatory and optional parameters.

Mandatory parameters

• web3Address: the public web3 address that will be required to sign the transaction. This parameter is case sensitive, and needs to be provided in checksum format.

• buynowId: identifier of the purchase.

• redirectUrl64: url where the user will be redirected after leaving the PG. It must be encoded in Base64.

Optional parameters

Aimed at enhancing the user experience, the following parameters can also be added using standard URL query string syntax:

• ?l={lang}: sets the default language of the payment gateway. Supported languages: English (US) en, and Spanish (Spain) es.

• ?wallet={wallet}: preselects the wallet that will be used to sign the transaction. Supported values: metaMask, walletConnect, and onboardingWallet.

The following summarizes how to build the URL with the parameters described so far:

https://paymentgw.com/payment/fiat/:web3Address/:buynowId/:redirectUrl64?l={lang}&wallet={wallet}

Fiat Supported countries

Payments in fiat are accepted from all countries in the following list: Australia, Austria, Belgium, Brazil, Bulgaria, Canada, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Gibraltar, Greece, Hong Kong, Hungary, India, Ireland, Italy, Japan, Latvia, Liechtenstein, Lithuania, Luxembourg, Malaysia, Malta, Mexico, Netherlands, New Zealand, Norway, Poland, Portugal, Romania, Singapore, Slovakia, Slovenia, Spain, Sweden, Switzerland, Thailand, United Kingdom, United States and United Arab Emirates

Withdrawals with Crypto

Withdrawals in crypto are specified by including the /withdraw/crypto string in the redirect. Below we specify the rest of the mandatory and optional parameters.

Mandatory parameters

• web3Address: the public web3 address that will be required to sign the transaction. This parameter is case sensitive, and needs to be provided in checksum format.

• redirectUrl64: url where the user will be redirected after leaving the PG. It must be encoded in Base64.

Optional parameters

Aimed at enhancing the user experience, the following parameters can also be added using standard URL query string syntax:

• ?l={lang}: sets the default language of the payment gateway. Supported languages: English (US) en, and Spanish (Spain) es.

• ?wallet={wallet}: preselects the wallet that will be used to sign the transaction. Supported values: metaMask, walletConnect, and onboardingWallet.

• ?buyNowId={id}: used to display withdrawal options for one single traded asset. If not specified, all pending withdrawals in crypto will be displayed to the user, as shown in the following screenshot:

Select withdraw

The following summarizes how to build the URL with the parameters described so far:

https://paymentgw.com/withdraw/crypto/:web3Address/:redirectUrl64?l={lang}&wallet={wallet}&buyNowId={id}

Withdrawals with Fiat

Withdrawals in fiat are specified by including the /withdraw/fiat string in the redirect. Below we specify the rest of the mandatory and optional parameters.

Mandatory parameters

• web3Address: the public web3 address that will be required to sign the transaction. This parameter is case sensitive, and needs to be provided in checksum format.

• redirectUrl64: url where the user will be redirected after leaving the PG. It must be encoded in Base64.

Optional parameters

Aimed at enhancing the user experience, the following parameters can also be added using standard URL query string syntax:

• ?l={lang}: sets the default language of the payment gateway. Supported languages: English (US) en, and Spanish (Spain) es.

• ?wallet={wallet}: preselects the wallet that will be used to sign the transaction. Supported values: metaMask, walletConnect, and onboardingWallet.

The Gateway for fiat withdrawals always displays all the balances available for withdrawal. Therefore, the field buyNowId is not needed as a query parameter when building the URL.

The following summarizes how to build the URL with the parameters described so far:

https://paymentgw.com/withdraw/fiat/:web3Address/:redirectUrl64?l={lang}&wallet={wallet}

Base64 encoding example

The following Javascript code snippet illustrates a simple conversion to Base64, ready to be used as redirectUrl64 parameter in the queries described above.

Embedding a gateway

All described gateways have the option of being embedded into an iFrame. By utilizing this feature, the user experience remains focused within the same browser tab or application, resulting in a less distracting UX.

The iFrame containing the gateway can communicate with the parent window whenever a relevant event or error occurs.

In order to receive these postMessage events on the parent window, an addEventListener method needs to be initiated in the parent. Here's an example of such implementation:

JavaScript

window.addEventListener(
  'message',
  function (event) {
    if (event.origin !== <PAYMENT GATEWAY URL>) return;
    // console.log(event.data)
  },
  false
);

The payload of the message received in the event is a JSON variable with the following structure:

JavaScript

{
    flow: String,        // withdraw, send or payment
    type: String,        // crypto or fiat
    message: String,     // message like 'success', 'error, no payment receipt'...
    <other arguments>    // more information depending on the messagee
}