Introduction

Getting Started with Legionpay

This page will help you get started with Legionpay. You'll be up and running in a jiffy!

Welcome to the documentation for our Legionpay openAPI. Our API allows you to seamlessly integrate payments into your application. Before you get started, it's important to note that we have two base URLs, one for development and one for production. You'll need to use the appropriate URL depending on which environment you're working in.

You're on your way to building an awesome Developer Hub! Here's some of the things you'll want to check out.

🚦Base URL

To access the Legionpay API, you will need to use the appropriate base URL based on your environment. Please refer to the following URLs for development and production:

For Development
https://sandbox-open.legionpays.com
For Production
https://open.legionpays.com

In this API documentation, we will be referring to the development base URL https://sandbox-open.legionpays.com as an example. Make sure to replace it with the appropriate base URL according to your specific environment when making API requests.

Note: It's important to use the correct base URL to ensure your API requests are directed to the intended environment and function as expected.

🔑Security

Additionally, for security reasons, every API request needs to include Basic Authorization generated from the merchantId:clientId combination, as well as the signature. To generate this signature, you'll need to generate it based on the provided formula.

Once you have the signature, you can include it in your subsequent API requests to authenticate them.

📝Callback

Whitelist Legionpay IP

In order to ensure seamless communication between your system and Legionpay, we kindly request you to whitelist our IP address.

IP Address to Whitelist: 178.128.110.58

Whitelisting our IP address allows us to securely transmit important data and updates to your system, such as payment notifications and callback information. By whitelisting our IP, you can ensure that these communications are not blocked or treated as potential security threats.

Please add the IP address mentioned above to your whitelist configuration to guarantee uninterrupted communication between your system and Legionpay.

How it Works

Before receiving callback notifications, you need to set up your callback URL and generate a unique callback key in the dashboard. Dashboard
When a relevant event or payment update occurs, our system generates a notification payload containing the necessary information.
The payload is then encrypted to ensure secure transmission of sensitive data.
The encrypted payload is sent to your specified callback URL via a POST request.
To verify the authenticity of the callback, a signature of the encrypted payload is included in the request header as X-SIGNATURE.
Upon receiving the callback, users can decrypt the payload, validate the signature using their generated callback key, and process the payment update accordingly.

Callback Endpoint

To receive the callback notifications, you need to set up an endpoint in your application that can handle incoming POST requests. This endpoint should be accessible from the internet so that our system can send the notifications to it.

Endpoint URL: https://your-domain.com/your-callback-endpoint

Request

Headers

X-SIGNATURE: A signature of the encrypted payload for authentication purposes.

Request Body

The request body will contain a payment, transfer or top up update information.

Response

The Callback endpoint expects a response with an appropriate HTTP status code to acknowledge the receipt of the callback. Any additional information can be included in the response body, but it is not required.

Handling Callbacks

When you receive a callback notification, it is crucial to enable the 1st layer security of callback signature and validate the signature provided in the X-SIGNATURE header to ensure the integrity of the payload. Once validated, you can process the payment update according to your business logic.

If you enable the 1st layer of security for callback, we will send the X-SIGNATURE header.

To validate the signature, here is the formula on how generate it (Typescript)

If you enabled the 2nd layer of protection on this callback, so you need to do 1 more step to validate this X-SIGNATURE

It is recommended to handle any errors or exceptions gracefully and respond with an appropriate HTTP status code to indicate the outcome of processing the callback.

Simulating Callbacks

We understand the importance of testing and verifying your callback functionality to ensure smooth communication between Legionpay and yours. To facilitate this process, we provide a convenient feature in our dashboard that allows you to simulate callbacks for generated payments, transfers and top ups.

After generating a payment through our API, you can access your dashboard and navigate to the menu that you want. Here, you will be able to manually trigger a callback event, simulating the notification that would typically be sent when a payment update occurs.

By simulating callbacks, you can effectively test your callback handling logic, verify the integration of your callback URL, and ensure that your system correctly processes the payment updates received from Legionpay.

In conclusion, we hope this OpenAPI documentation has provided you with all the necessary information and resources to integrate seamlessly with Legionpay. If you ever find yourself lost in the API maze, fear not! Our support team is just a message away, ready to assist you on your coding adventures.

Remember, coding can be serious business, but it's also important to have a little fun along the way. So, go forth, code boldly, and may your errors be as rare as finding a unicorn in your code!

Happy coding and may your APIs always be RESTful and your code bug-free! Cheers!

With Love, Legionpay 🍻