JumiaPay API

Welcome to JumiaPay API Documentation!

JumiaPay API will allow you to easily start accepting payments online through a secure one step checkout experience.

With that said, start learning how to integrate our API on your application.

Authentication

Authenticate your API calls by including the apikey header of every request you make. API requests made without authentication will fail with the status code 401: Unauthorized.

Note that API keys both for staging and production will be shared by our team via encrypted email.
For more details about this process check out these 'Get Started' steps.

API Endpoints

When calling our API, include the URL to the API service for the corresponding environment:

Available Payment Options

Get Payment Options

Payment Options API is an API responsible for listing all payment options available for a specific shop

path Parameters
shopConfigId
required
string <uuid>

Merchant shop configuration id provided by JumiaPay.

userType
required
string

user type must be either "regular" or "guest"

header Parameters
apikey
required
string

Fill in with the API key shared by our team

Content-Type
required
string
Example: application/json

The Content-Type (only application/json is supported)

Responses

200

Success response if the merchant is active, if not, data list will be empty

400

Bad Request: The request was unacceptable, due to missing required parameter

401

Unauthorized: Missing or invalid apiKey provided

405

HTTP method not supported

500

Something went wrong while communicating with the server

get/merchant/{shopConfigId}/payment-options/{user-type}

Sandbox URL

https://api-sandbox-pay.jumia.com.eg/merchant/{shopConfigId}/payment-options/{user-type}

Production Url

https://api-pay.jumia.com.eg/merchant/{shopConfigId}/payment-options/{user-type}

Request samples

Copy
curl -X POST \
  https://api-staging-pay.jumia.com.ng/merchant/{shopConfigurationId}/payment-options/regular \
  -H 'Content-Type: application/json' \
  -H 'apikey: '<YOUR_API_KEY>' \
}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

Purchases

Create Purchase V2.

The Create Purchase V2 request allows you to process transactions through JumiaPay. For detailed information about how our Purchases feature works, the purchases possible status and how to simulate them, give a look at our Integration Guides.

path Parameters
shopConfigId
required
string <uuid>

Merchant shop configuration id provided by JumiaPay.

header Parameters
apikey
required
string

Fill in with the API key shared by our team

Content-Type
required
string
Example: application/json

The Content-Type (only application/json is supported)

Request Body schema: application/json
description
required
string [ 2 .. 254 ] characters

Brief description of the purchase. This description is for internal use only, it will not be visible to the customer.

amount
required
object

Order amount object

consumer
required
object

Customer's information necessary to create a purchase.

merchant
required
object

Merchant fields object

basket
required
object

Object with product(s) or service(s) data. This data will be shown to the customer in the Cart Detail on JumiaPay website.

expirationTime
integer [ 1 .. 262980 ]

The period of time in minutes provided by the merchant to JumiaPay for the customer to finish his purchase. The customer has 30 minutes if the value is not given by default.

shippingAddress
object

Shipping data to which the products will be delivered.

billingAddress
object

Billing data information.

additionalData
object <= 4096 characters

Additional data with all extra information about the purchase

Responses

201

Created

400

Bad Request: The request was unacceptable, due to missing required parameter

401

Unauthorized: Missing or invalid apiKey provided

403

The merchant does not have access to create new purchases.

404

The resource provided was not found

405

HTTP method not supported

422

The request was well-formed but was unable to be followed due to semantic errors

500

Something went wrong while communicating with JumiaPay

post/v2/merchants/{shopConfigId}/purchases

Sandbox URL

https://api-sandbox-pay.jumia.com.eg/v2/merchants/{shopConfigId}/purchases

Production Url

https://api-pay.jumia.com.eg/v2/merchants/{shopConfigId}/purchases

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "description": "JumiaPay order",
  • "expirationTime": 30,
  • "amount":
    {
    },
  • "merchant":
    {},
  • "consumer":
    {
    },
  • "basket":
    {
    },
  • "shippingAddress":
    {
    },
  • "billingAddress":
    {
    },
  • "additionalData": "{value1: value 1, value2: value 2}"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Verify Status of Purchase

The Verify Status of Purchase request gives you visibility on the status changes of a purchase until its current status.

header Parameters
apikey
required
string

Fill in with the API key shared by our team

Content-Type
required
string
Example: application/json

The Content-Type (only application/json is supported)

Request Body schema: application/json
shopConfig
required
string (ShopConfig)

Merchant token provided by JumiaPay to identify your shop. This parameter can be found on JumiaPay Business, in the ‘ShopConfigurations’ sub-module with the name Shop Key.

transactionId
required
string

transactionId corresponds to the Purchase Id provided by JumiaPay. This parameter is sent on the success response of Create Purchase request.

transactionType
required
string
Value: "Purchase"

Type of the transaction. The allowed value is "Purchase".

Responses

200

Success

400

Bad Request

401

Unauthorized: Missing Shop Config or API Key

post/merchant/transaction-events

Sandbox URL

https://api-sandbox-pay.jumia.com.eg/merchant/transaction-events

Production Url

https://api-pay.jumia.com.eg/merchant/transaction-events

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "shopConfig": "YOUR_SHOP_KEY",
  • "transactionId": "AAEAAADpDFehqbrgASaL1jF9DYX6z4t9_bo3Sdb3adFUmCDS_Og3vBc4",
  • "transactionType": "Purchase"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "success": true,
  • "type": "single",
  • "payload":
    [
    ]
}

Cancel Purchase

The Cancel Purchase request enables you to cancel a purchase when it is in one of the following status:

  • Created: no money has been captured from the customer Payment Instrument yet, which means that the money necessary for the purchase to go forward is still on the customer side.
  • Confirmed or Committed: at this stage, the capture of the money was already done, which means that the money necessary for the purchase to go forward is already on JumiaPay side. Please note that if the purchase is cancelled at this stage, the amount captured from the customer Payment Instrument will not be sent back to his Payment Instrument, but will be released on the customer’s JumiaPay wallet instead.

After a purchase is cancelled, the customer will be able to see it as 'Failed' on his JumiaPay account.

header Parameters
apikey
required
string

Fill in with the API key shared by our team

Content-Type
required
string
Example: application/json

The Content-Type (only application/json is supported)

Request Body schema: application/json