logo
Documentation Powered by ReDoc

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:

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":
    {
    }
}

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
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.

purchaseId
required
string

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

Responses

200

Success

400

Bad Request

401

Unauthorized: Missing Shop Config or API Key

post/merchant/cancel

Sandbox URL

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

Production Url

https://api-pay.jumia.com.eg/merchant/cancel

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "shopConfig": "YOUR_SHOP_KEY",
  • "purchaseId": "PURCHASE_ID"
}

Response samples

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

Refunds

Create Refund

The Create Refund request allows you to refund purchases made by your business through JumiaPay. A refund can only be made when the purchase is completed.

After a refund is created, the customer will be able to see the record of the refund on his JumiaPay account.

For detailed information about how our Refunds feature works and the refunds possible status, give a look at our Integration Guides.

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.

refundAmount
required
string

Amount to refund. This amount cannot exceed the purchase amount.

The refundAmount can have up to 2 decimal places. A decimal point must be used to separate the integer part from the fractional part of the number. Example: 10000.99

refundCurrency
required
string
Enum: "NGN" "EGP" "GHS" "KES" "MAD" "XOF" "TND" "UGX"

Refund currency corresponds to official ISO 4217 currency codes:

  • Nigeria: NGN
  • Egypt: EGP
  • Ghana: GHS
  • Kenya: KES
  • Morocco: MAD
  • Ivory Coast: XOF
  • Tunisia: TND
  • Uganda: UGX

refundCurrency must be the same as the priceCurrency of the corresponding purchase.

description
required
string

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

purchaseId
required
string

Purchase Id provided by JumiaPay. This parameter is sent on the success response of Create Purchase request. You can either send us this parameter or the purchaseReferenceId.

purchaseReferenceId
required
string <= 255 characters

Merchant’s unique reference id generated by you for the purchase (merchantReferenceId). You can either send us this parameter or the purchaseId.

referenceId
required
string <= 255 characters

Merchant’s unique reference id generated by you for the refund. This id is saved on JumiaPay whether the refund completes or fails.

Responses

200

Success

400

Bad Request

401

Unauthorized: Missing Shop Config or API Key

post/merchant/refund

Sandbox URL

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

Production Url

https://api-pay.jumia.com.eg/merchant/refund

Request samples

Content type
application/json
Example
Purchase Registered in JumiaPay
Copy
 Expand all Collapse all
{
  • "shopConfig": "YOUR_SHOP_KEY",
  • "refundAmount": 5,
  • "refundCurrency": "NGN"