This wiki page describes the overall process of setting up a payment gateway and getting it configured on the Maestrano platform. Note that obtaining a payment gateway from a third-party provider usually involves some level of paperwork. Do not hesitate to get in touch with us for help.

1 - Choosing a payment gateway

Maestrano uses a payment abstraction library to communicate with third-party payment gateways. This abstraction library offers a large number of pre-integrated gateways which can be activated on the Maestrano side upon request.

The full list of available payment gateways is available here.

Amongst this list the following payment gateways are readily available on Maestrano. "Readily available" means that no development work or lead time is required to activate these.

The rest of the gateways can be activated upon request. The lead time required to activate these will depend on the gateway itself.

Your preferred gateway is not in the list? Do not hesitate to get in touch with us.

2 - Setting up your payment gateway

After selecting your payment gateway you will need to register an account with the gateway provider. This step is performed directly on the website of the gateway provider.

As part of this process the gateway provider is likely to request the following information:

Identification
Company certificate or company identification details. These are your company details, not the Maestrano ones.
Volume
Expected volume of transactions per month. A good rule of thumb is $150 * number of expected customers per month. This volume is indicative and is used by gateway providers to calculate their financial exposure on your account.
Charging model
E.g. are you charging in advance or in arrears? The Maestrano platform always charges in arrears, meaning that charges are incurred after the service has been consumed by customers. This detail is important. Charging in advance is usually considered as a risk by gateway providers because it increases the probability of disputes on refunds, which eventually translates in increased financial exposure for them.
Merchant account details
- This part is usually the tricky bit because you will have to open an actual Merchant Account with a bank to receive payments. This process involves a fair amount a paperwork. Some payment gateway providers facilitates this process by managing this on your behalf, however this facilitation service is not always available in all countries (e.g. Stripe Atlas)
- If you wish to accept multiple currencies you will need settlement accounts in each currency. Note that in some countries only a very limited number of banks have the capability to perform foreign currency settlement. Do not be surprised if your gateway provider seems to "impose" a certain bank to you.
- For each currency you select your gateway provider will open a merchant facility linked to your merchant account in the given currency
Payment methods
By default all merchant facilities accept Visa and MasterCard. If you want to accept Amex, JCB and Diners Club you need to specify it to your gateway provider.

Note that the above is only a generic description of the overall process. Each gateway provider is likely to have its own on-boarding process and facilitation services.

Facing issues with the setup? Do not hesitate to get in touch with us.

3 - Configuring the gateway on Maestrano Hub

Once your payment gateway is setup you will have access to your merchant account ID and API credentials. If you accept multiple currencies you may receive one merchant account ID per currency account. These details are required to configure your payment gateway on the Maestrano platform.

You are an Express customer? Contact our support team and we will configure the payment gateway for you.

You are an Enterprise customer? You can follow the steps below to setup a payment gateway on a specific tenant.

3.1 Accessing the Tenant configuration page

In order to perform this procedure you need access to the Maestrano Active Admin interface.

Login to the Maestrano Hub Active Admin interface
Go to the tenants screen
On this page search for your tenant and click edit
Scroll down to the Keystore section
Follow the provider-specific configuration instructions below

3.2 Braintree configuration

The keystore configuration should look like this after entering your payment gateway details:

Below is a detailed explanation of what each configuration parameter means:

{
  // configuration namespace
  "payment_gateways": {
    // define all providers in this block
    "providers": {

      // Friendly name for your gateway. You can as well just use "braintree"
      "my_braintree": {
        // Name of the adapter to use. Just set it to "braintree"
        "adapter": "braintree",
        "config": {
          // Enter the merchant ID provided by Braintree
          "merchant_id": "braintree-merchant-id",
          // Enter the public key provided by Braintree
          "public_key": "braintree-public-key",
          // Enter the private key provided by Braintree
          "private_key": "braintree-private-key"
        }
      }
    },
    
    // This configuration block specifies the merchant accounts to use
    // for each currency
    "accounts": {
      // The name below MUST match the name of a provider above
      "my_braintree": {
        // Example of simple mapping currency => merchant account name
        "AED": "name-of-AED-merchant-account",

        // The mapping below specifies which special cards are accepted
        // on top of Visa/MasterCard
        // The "default" parameter specifies the fallback order when
        // the customer credit card currency is not specified
        // In this case USD will be used as the fallback currency for
        // Visa/MasterCard but AUD will be used as the fallback currency
        // for JCB and Amex as USD does not support these cards
        "AUD": {
          "acct": "name-of-AUD-merchant-account",
          "default": 2,
          "jcb": true,
          "american_express": true
        },

        // Another example of simple currency/account mapping
        "CAD": "name-of-CAD-merchant-account",

        // USD is used as the fallback currency for traditional
        // brands (JCB and Amex will go through the AUD merchant
        // account however)
        "USD": {
          "acct": "name-of-USD-merchant-account",
          "default": 1
        }
      }
    }
  }
}

3.3 eWay configuration