Setting up PaymentsOS

Before you can start accepting payments with PaymentsOS, there is some configuration you need to do.

First, make sure you sign up for a PaymentsOS account. If you already have an account, login to your PaymentsOS environment. You can now configure the following:

  • Providers (choose Account > Services). These are the providers you will transact against. A provider configuration is a set of provider API credentials that represents your payment-processing facility with that provider.

  • Business units (choose Account > Business Units). These are logical business entities within PaymentsOS. Payments received from your customers are associated with a business unit. You can set up multiple business units, to match your business structure. When you create a business unit, we will provide you with an app-id, public-key and private-key. You’ll need these business unit credentials when sending any payment related API requests.

There are a few important things you need to be aware of, however. Make sure to read on before doing your setup.

Understanding the Test and Live Environments

PaymentsOS provides both a test and live environment for setting up your integration and processing payments. The test environment is not linked to the live banking networks and thus provides a safe place for you to develop and test your integration. Payments processed in the test environment are not visible in the live environment and vice versa. Similarly, any configuration done in the test environment will not appear in the live environment.

To create a configuration in the environment of your choice, simply switch the toggle in the screen’s top pane to either Test or Live and add your configuration.

Test and Live Toggle

Configuring Providers

A provider configuration is a set of provider API credentials that represents your payment-processing facility with that provider.

Adding Multiple Provider Credentials

Providers often provide you with multiple sets of API credentials. This allows you to send your requests to different provider environments (test or live), countries, or currencies, etc. You’ll need to create a separate provider configuration for each set of provider API credentials.

We recommend using only a provider’s test credentials in the PaymentsOS test environment.

Specific Provider Requirements

Unless you are using a mock provider, bear in mind that each provider you are transacting against may introduce some requirements that you must take into account when invoking any of the PaymentsOS API requests. For example, you may need to pass in some extra data for the request to succeed. For more information, refer to the Provider Integration Guides.

Configuring Business Units

Different parts of your business may require different payment flows. Consider a scenario, for instance, in which your business operates in multiple geographies. Since not all geographies support the same payment provider, you may need to transact against a different provider in each geography.

In PaymentsOS, you can differentiate between different parts of your business using business units. Each business unit represents a logical business entity and its related payment flows.

Associating a Payment Flow with a Business Unit

A payment flow is programmatically associated with a business unit through the API requests that are invoked on behalf of that business unit.

When you add a new business unit, you’ll notice that PaymentsOS requires you to specify a business unit name. PaymentsOS will use the name to create an App ID, which is a unique identifier for your business unit. PaymentsOS will also generate public and private authentication keys when your business unit is saved. You must use the App ID and authentication keys in the API requests made on behalf of the business unit.

Transacting Against Multiple Providers

Payments handled by a business unit may be routed to any of the providers you configure in Account > Services. The provider to which a payment is routed, depends on the business rules you define. If you do not define any business rules, or if there are no rules matching the payment request, then PaymentsOS will route the payment to the default provider defined in your business unit’s configuration.

To add business rules, choose Decision Engine from the left menu, select a business unit and scroll down to Optimize your payment flow.

Defining Business Rules for Alternative Payment Methods

Of course, you may offer your customers the choice of using an alternative (non-card) payment method. In this case, the default provider defined in your business unit’s configuration should support the alternative payment method you’re offering. If the default provider does not support the alternative payment method, then you can create a Business Rule with an Alternative Payment Method condition and route transactions using the alternative payment method to a provider that supports it.

Replacing API Keys

Although API keys can last a lifelong, you may still want to replace them occasionally. When viewing your Business Unit configuration, you will notice that you can easily do so. Just beware that you will need to update your code to work with the new keys, so do this with care.

What’s next?

Now that you’ve setup your PaymentsOS environment, you are ready to start collecting a customer’s card information.

Last modified July 13, 2023