Setting up PaymentsOS
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
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.
Activating your accountTo gain access to the Live environment, you must activate your account first. Click here to activate your account.
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.
Running a Quick Test
You can use a mock provider to mock transactions. Simply choose the Mock Provider when adding a provider configuration:
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.
Running a Quick TestIf you’re using a mock provider to mock transactions, create a business unit and select your mock provider from the Default Provider list.
Maximum Number of Business UnitsYou are allowed to create a maximum of 100 business units. Once this limit is reached, you will receive an error indicating that the limit has been exceeded.
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.
Decision EngineUnder the hood, PaymentsOS uses its Decision Engine to direct payments to any of the providers you configured, based on your business rules. Read more about Optimizing Payments for help in understanding each rule category and the requirements you must take into account when developing your integration code.
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.
Not all alternative payment methods are currently supportedWe currently do not support routing for all types of alternative payment methods (though we are continuously extending support for additional ones). If the alternative payment method for which you want to configure a rule is not available for selection in the Alternative Payment Method condition, then you will need to create a separate business unit with a default provider dedicated to handling the payment method used in the transaction.
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.
Generating a new KeyWhen generating a new key, you can choose to have the new key take effect immediately or after 24 hours.
Now that you’ve setup your PaymentsOS environment, you are ready to start collecting a customer’s card information.