Setup JumiaPay as Payment Option

There are two possible ways for a Business to display JumiaPay as a payment option on his website:

• Integrate JumiaPay Merchant API

JumiaPay Merchant API allows you to easily integrate JumiaPay on your website. Once integrated, you'll be able to accept payments online from your customers through a secure one step checkout experience.

Calling our /merchant/create endpoint will return a link to which you can redirect to load JumiaPay checkout page with the order details. Here your customers will be able to pay your products/services by selecting a payment method, inserting the payment details and completing the payment.

• Install JumiaPay plugins

We offer payment gateway plugins to help you enable JumiaPay as a payment option on your e-Commerce store. Once installed and configured, your customers will be able to select JumiaPay on your website to proceed with the order payment through JumiaPay checkout page. The download and installation of these plugins are free of cost.

JumiaPay enables you to accept the following payment methods in Uganda:

• Mobile Money (Airtel and MTN)
• Cards (Mastercard & Visa)

Pre-requisites:

Before you start, check out these tips to assure a smooth experience:

1. First, you'll need to have a JumiaPay Business account. If you still don't have one, you may create it at no additional cost. Just follow our guidelines on Get Started.

2. Check out our API Documentation or Plugins for detailed information.

3. If your Business has an Android or IOS app, check WebView for Mobile Applications.

4. Don't forget to use your sandbox data while testing your integration with JumiaPay.

5. Contact us at [email protected] in case you have any doubt or need some advice.

API Overview

JumiaPay offers an API that enables you to accept payments online from your customers and verify their status. We also make it possible for you to cancel these payments when needed and refund your customers.

Here follows an overview on JumiaPay API. For more information about the parameters that you should send in each request or about success and error responses check our detailed API Documentation.

Authentication

Authenticate your API calls by including your API secret key in the authorization header of every request you make:

Create Purchase

To initialize a transaction on JumiaPay, call the /merchant/create endpoint from our API.

You'll need to collect and send us some customer information, such as the Email Address, IP Address and Country. You'll also need to send the transaction Total Amount, Currency, some Basket Details like the Product(s) Name, Quantity and Price Amount, an Unique Reference to identify the transaction on your system, the Id provided by us to identify your shop (which you can get by following the instructions on Get Started - Step 3), a Return Url and a Callback Url.

When this API call is successful, a Checkout Url will be returned. By redirecting the customer to this url, you will enable him to access JumiaPay so he can to insert his payment details and complete the payment. Once the customer confirms the payment, he'll be redirected to the website set by you on the purchaseReturnUrl parameter. If you don't set this parameter when calling our API, we won't be able to redirect the customers to your website after the payment is done.

Sending us a purchaseCallbackUrl will enable JumiaPay to call this url and send you an update of the transaction status everytime it changes.

It's very important that you check our Callback response to confirm the transaction status before delivering value to the customer! Be aware that just because the customer reached your website, it doesn't mean the transaction is already successful. The transaction should only be considered successful when it reaches the status 'Completed' on JumiaPay side, never before.

You may find an example of the Callback request body that JumiaPay will send to you here.

Here's a brief explanation of the possible status a transaction can assume:

You can also use our Verify Status of Purchase request to confirm the status of your transactions. Learn more about this on the next section.

Verify Status of Purchase

Calling our /merchant/transaction-events endpoint will give you visibility on the status changes of a transaction until its current status. You initiate this request by using the Transaction Id that we return to you on the Create Purchase success response. You'll also need to send the Id that identifies your shop, which you can get by following our instructions on Get Started - Step 3.

Cancel Purchase

Calling our /merchant/cancel endpoint allows you to cancel a transaction with the following status:

• Created: at this stage, no money has been captured from the customer's payment instrument yet, which means that the money necessary for the transaction to go forward is still on the customer side.

• Confirmed or Committed: at these stages the capture of the money was already done, which means that the money necessary for the transaction to go forward is already on JumiaPay side. Please note that if the transaction is cancelled at this point, the amount captured from the customer's payment instrument will not be sent back to his payment instrument, but will be released on the customer's JumiaPay account instead.

You initiate this request by using the Transaction Id that we return to you on the Create Purchase success response. You'll also need to send the Id that identifies your shop, which you can get by following our instructions on Get Started - Step 3.

Create Refund

Calling our /merchant/refund endpoint enables you to refund transactions made by your Business through JumiaPay. A refund can only be made when the transaction is completed.

To do so, you'll need to send us the refund Amount, the Currency, the Transaction Id, an Unique Reference generated by you to identify the refund, the Id that identifies your shop (which you can get by following our instructions on Get Started - Step 3) and a brief Description of the refund.

Note that:

• The refund amount cannot exceed the transaction amount.
• The currency must be the same as the transaction currency.
• The transaction id can be the one provided by us on the Create Purchase success response or the unique reference that you used to identify the transaction on your system.

How and when your customer is refunded depends on how he made the payment:

• All authorised customer refunds will be debited from your JumiaPay shop account and sent back to the customer's account or source of payment that was originally used to make payment. E.g Mobile Money will be sent back to the customer's mobile money wallet.

Once you send the request to create a refund, we'll update you on whether the refund was successful or not.

You may also check the refunds status on your JumiaPay Business account, on the Merchant module by clicking on your Shop > Refunds.

Here's a brief explanation of the possible status a refund can assume:

Callback

When a purchase transaction is created, JumiaPay will automatically notify you everytime there's a change of its status by using the purchaseCallbackUrl parameter sent on the Create Purchase request. It's very important that you check our Callback response to confirm the transaction status before delivering value to the customer!

Here's an example of the request body that JumiaPay will send to you upon callback:

{
    "transactionEvents": [
        {
            "id": "AAEAAAA6hpLxWNDtbGEu9SKCl8ivNNHs3luQrpBi17C8HGcRtsWf3I5t",
            "creationDateTime": "2018-04-04T09:59:48Z",
            "transactionType": "Purchase",
            "newStatus": "Confirmed",
            "oldStatus": "Created",
            "transactionId": "AAEAAADoKU7Q321mnk6XFV_4zvOamJidaWFOstEyMDX-YSMJBwgC0cTW",
            "merchantReferenceId": "1522835946",
            "shopConfigurationId": "AAEAAADoKU7YItWSEhYpJRb0fV842USafymz4Vs2onKOPsMPlnU9LFrt",
            "paymentInstrumentType": "CreditCard",
            "paymentMethod": "Mastercard",
            "chargeStatus": "Success"
        },
        {
            "id": "AAEAAAA6hpLxWQo_oVfSAqSGXK8LgOjG_5sfMlTCjjQGfpdMz3zTqdQ-",
            "creationDateTime": "2018-04-04T09:59:48Z",
            "transactionType": "Purchase",
            "newStatus": "Committed",
            "oldStatus": "Confirmed",
            "transactionId": "AAEAAADoKU7Q321mnk6XFV_4zvOamJidaWFOstEyMDX-YSMJBwgC0cTW",
            "merchantReferenceId": "1522835946",
            "shopConfigurationId": "AAEAAADoKU7YItWSEhYpJRb0fV842USafymz4Vs2onKOPsMPlnU9LFrt",
            "paymentInstrumentType": "CreditCard",
            "paymentMethod": "Mastercard",
            "chargeStatus": "Success"
        }
    ]
}

Test Data

Use our sandbox to test your integration!

You can test the different transaction status JumiaPay could retrieve by following these guidelines:

You may also test the user experience on JumiaPay checkout by simulating if a payment is successful or not by using specific card schemes:

1. Go to https://www.getcreditcardnumbers.com/ or https://namso-gen.com/ to get valid credit card numbers for testing purposes.

2. If you want to simulate a payment that is pending, use a card number started with 51.

3. If you want to simulate a payment that failed, use a card number started with 52.

4. If you want to simulate a successful payment, use any other card number.

Note that the Expiry Date can be any date in the future and the CVV can be any three digit number.

Errors

Confirm which errors can be returned in each request by checking out our API Documentation.

Plugins

JumiaPay plugins will allow you to easily integrate JumiaPay as a payment gateway on your website, saving you some work and time.

On your website checkout, your customers will be able to select JumiaPay to proceed with their orders payment.

After selecting it and place order, your customers will be redirected to JumiaPay where they can login or create an account. Once the login is made, they'll see the JumiaPay checkout page where they can select a payment method, insert their payment details and complete the payment. After the payment is done, they'll be redirected to your website.

These are the plugins that we currently offer:

• WordPress
• Magento

WordPress

JumiaPay WooCommerce Payment Gateway is currently meant to be used by businesses in Nigeria and Egypt.

Pre-requisites

1. Open a JumiaPay Business account and follow our instructions on how to activate your business and get credentials to proceed with the plugin installation. To do so, follow the steps described on Get Started.

2. Instal and activate the JumiaPay WooCommerce Payment Gateway on your WordPress website. Follow the instructions described on Installation.

Installation

Automatic Installation

1. Login to your WordPress Admin Area.

2. Click on Plugins > Add New.

3. Search for 'JumiaPay WooCommerce Payment Gateway' in the search bar.

4. From the search result you'll see the JumiaPay WooCommerce Payment Gateway, click on the Install Now button.

5. After the installation is complete, activate the plugin.

6. Proceed with the configurations described on Configuration.

Manual Installation

1. Download JumiaPay plugin zip file here.

2. Login to your WordPress Admin Area.

3. Click on Plugins > Add New > Upload Plugin.

4. Click on Choose File to select the plugin zip file from your computer. After the file is chosen, click on the Install Now button.

5. Once the plugin is successfully installed, click on the Activate Plugin button.

6. Proceed with the configurations described on Configuration.

Configuration

1. Go to WooCommerce > Settings and click on General from the top tab.

2. On Currency options set the Currency with the official currency of the country where you're selling (eg. 'Nigerian Naira' for Nigeria and 'Egyptian pound' for Egypt) and the Number of decimals as '2'.

3. Click on the Save Changes button.

4. Then, click on Payments from the top tab and click on JumiaPay from the available list in order to configure this payment option:

   • Enable/Disable: check the box to enable JumiaPay payment option on checkout.

   • Environment: you may select 'Sandbox' or 'Live'. Select 'Sandbox' to test payments done through JumiaPay before going live. Once you're ready to accept real payments on your site, select 'Live'.

   • On Live Settings:

     • Country List: Select the country where you're operating. This plugin is meant to be used in Nigeria or Egypt.
     • Shop Key: Access your live JumiaPay Business account. Then, click on the Shop Configurations module, copy the Shop key and paste it here.
     • Merchant API Key: API key that will identify your Business. This key will be provided by JumiaPay team as soon as you create your JumiaPay Business account follow the onboarding steps and your business gets approved.

   • On Sandbox Settings:

     • Country List: Select the country where you're operating. This plugin is meant to be used in Nigeria or Egypt.
     • Shop Key: Access your JumiaPay Business test account. Then, click on the Shop Configurations module, copy the Shop key and paste it here.
     • Merchant API Key: API key that will identify your Business. This key will be provided by JumiaPay team as soon as you create your JumiaPay Business account, follow the onboarding steps and your business gets approved.

5. Click on the Save Changes button.
6. On WordPress Settings on the left hand side, go to Permalinks and on Common Settings select one of the following options: Day and name, Month and name, Numeric and Post name. For more information about these Permalink Settings, consult the WordPress Support documentation.

7. Click on the Save Changes button.

Accept Payments

After a payment is done by the customer, there is two possible ways for you to check its status on JumiaPay:

• On WordPress, go to WooCommerce > Orders and click on the desired order to see its details. On the right hand side on Order notes, you'll be able to see the transaction status on JumiaPay side.

• On JumiaPay Business, login into your account and on the Merchant module click on your Shop > Purchases to see all your transactions listed and their status. You can also search by a customer email address or a merchant reference to find a specific transaction. By clicking on it you'll be able to see its details.

Here's a brief explanation of the possible status a transaction can assume on JumiaPay:

Cancel Payments

You'll only be able to cancel a transaction if it still is with one of the following status on JumiaPay side:

• Created: at this stage, no money has been captured from the customer's payment instrument yet, which means that the money necessary for the payment to go forward is till on the customer side.

• Confirmed or Commited: at these stages the capture of the money was already done, which means that the money necessary for the payment to go forward is already on JumiaPay side. Please note that if the transaction is cancelled at this point, the amount captured from the customer's payment instrument will not be sent back to his payment instrument, it will be released on the customer's JumiaPay account instead.

If the transaction still presents one of these status and you wish to cancel it, go to WooCommerce > Orders and click on the desired order to see its details. Then, change the order status to 'Cancelled' and update. After you do this, the transaction status will be updated to 'Failed' on JumiaPay side and we'll inform you about the cancellation success or failure on the Order notes.

Create Refunds

In order to refund your customers go to WooCommerce > Orders and click on the desired order to see its details. There you'll find a Refund button. By clicking on it you can see the Amount already refunded and the Total available to refund. If you wish to proceed with a refund via JumiaPay, fill the Refund amount and click on the Refund via JumiaPay button.

You can also refund a customer through your JumiaPay Business account. On the Merchant module, click on your Shop > Purchases to see all your transactions listed, search by the one you want to refund and click on it to see its details. There you'll find a Refund button.

Note that:

• Refund via JumiaPay can only be made if the order was paid via JumiaPay.
• Refund via JumiaPay can only be made if you have sufficient funds on your JumiaPay shop account. To confirm this access to your JumiaPay Business account, click on Your Accounts module and check your shop balance.
• Refund via JumiaPay can only be made if the transaction reached the status 'Completed'.
• Refund amount cannot exceed the Total available to refund amount.

How and when your customer is refunded depends on how he made the payment on JumiaPay:

• All authorised customer refunds will be debited from your JumiaPay shop account and sent back to the customer's account or source of payment that was originally used to make payment. E.g Mobile Money will be sent back to the customer's mobile money wallet.

You'll be able to check the status of your refunds done via JumiaPay by either:

• Access to WordPress, go to WooCommerce > Orders, click on the desired order and check the Order notes on the right hand side.

• Access JumiaPay Business, login into your account and on the Merchant module click on your Shop > Refunds to see all your refunds listed and their status.

Here's a brief explanation of the possible status a refund can assume:

Test Data

Apply the Sandbox Settings described on Configuration to test the JumiaPay integration on your website.

You can test the different transaction status JumiaPay can retrieve by following these guidelines:

You may also test the user experience on JumiaPay checkout by simulating if a payment is successful or not by using specific card schemes:

1. Go to https://www.getcreditcardnumbers.com/ or https://namso-gen.com/ to get valid credit card numbers for testing purposes.

2. If you want to simulate a payment that is pending, use a card number started with 51.

3. If you want to simulate a payment that failed, use a card number started with 52.

4. If you want to simulate a successful payment, use any other card number.

Note that the Expiry Date can be any date in the future and the CVV can be any three digit number.

WebView for Mobile Applications

Businesses with Android or IOS applications can also use JumiaPay checkout to accept online payments by using a WebView. To do so, you can use our Merchant API integration to generate a JumiaPay checkout url and embody it in WebView on your mobile app.

1. Get JumiaPay checkout url

Call our /merchant/create endpoint to create a transaction on JumiaPay and we'll return to your server a JumiaPay checkout url on the success response.

You'll need to collect and send us some customer information, such as the Email Address, IP Address and Country. You'll also need to send the transaction Total Amount, Currency, some Basket Details like the Product(s) Name, Quantity and Price Amount, an Unique Reference to identify the transaction on your system, the Id provided by us to identify your shop (which you can get by following the instructions on Get Started - Step 3), a Return Url and a Callback Url.

This endpoint is a POST request from your server to our API.

2. Display JumiaPay checkout url in a WebView on the mobile app

When the API call is successful, its response will return a checkoutUrl that should be sent to the frontend and loaded in the WebView on your native mobile application.

Note that some of the payment methods available on JumiaPay redirect the customer to other web pages for customers to fill in OTP/PIN and allow payment authorization. Therefore, the WebView should allow redirects, otherwise customers won’t be able to complete their transactions.

After the JumiaPay checkout is loaded in the WebView, you should listen for url redirects in the WebView in order to know your customers actions.

3. Listen for JumiaPay redirection to your Return url

Once the customer confirms the payment, he'll be redirected to the website set by you on the purchaseReturnUrl parameter sent when calling the /merchant/create endpoint.

Note that JumiaPay sends a status parameter (Success/Failure) together with the purchaseReturnUrl, but this status refers to sending the payment confirmation to the payment gateway. This isn't the transaction status, so don't use this parameter to deliver the transaction status to your costumer! The transaction status should be confirmed on JumiaPay callback or by calling our Verify Status of Purchase endpoint (both described below).

At this point, you can have your WebView listening for when JumiaPay redirects to the purchaseReturnUrl to set the handover control from the page sent on purchaseReturnUrl to your native application and continue processing as usual.

3. Check JumiaPay Callback

Sending us a purchaseCallbackUrl when calling the /merchant/create endpoint will enable JumiaPay to call this url and send you an update of the transaction status everytime it changes.

It's very important that you check our Callback response to confirm the transaction status before delivering value to the customer! Be aware that just because the customer reached your purchaseReturnUrl, it doesn't mean the transaction is already successful. The transaction should only be considered successful when it reaches the status 'Completed' on JumiaPay side, never before.

You may find an example of the Callback request body that JumiaPay will send to you here.

Here's a brief explanation of the possible status a transaction can assume:

You can also use our Verify Status of Purchase request to confirm the status of your transactions. Learn more about this here.