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:

Sandbox Url: https://api-sandbox-pay.jumia.co.ke
Production Url: https://api-pay.jumia.co.ke

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.co.ke/v2/merchants/{shopConfigId}/purchases

Production Url

https://api-pay.jumia.co.ke/v2/merchants/{shopConfigId}/purchases

Request samples

Payload
curl
java
php
go

Content type

application/json

Copy

Expand all Collapse all


{"description": "JumiaPay order",
"expirationTime": 30,
"amount": 
{"value": 390,
"currency": "NGN",
"fee": 10
},
"merchant": 
{"referenceId": "<YOUR_UNIQUE_MERCHANT_REFERENCE_ID>,",
"token": "<YOUR_UNIQUE_MERCHANT_TOKEN>",
"callbackUrl": "https://example.com/purchase_callback",
"returnUrl": "https://example.com/book/payreturn/5kooig?lastname=Booking"
},
"consumer": 
{"emailAddress": "[email protected]",
"ipAddress": "172.16.0.1",
"country": "NG",
"mobilePhoneNumber": "+2348021234567",
"language": "en",
"firstName": "John",
"lastName": "Doe",
"name": "John Doe",
"dateOfBirth": "1985-04-03",
"identityDocument": 
{"identification": "AA122XYZ",
"type": "national_id_number"
},
"sessionId": "d85cf934-13b3-47ee-92bb-1476388f4850"
},
"basket": 
{"items": 
[
{"name": "Lagos Airport Hotel",
"amount": "230",
"quantity": "1",
"currency": "NGN"
},
{"name": "Lagos Airport Hotel",
"amount": "80",
"quantity": "2",
"currency": "NGN"
}
],
"currency": "NGN",
"shippingAmount": "0"
},
"shippingAddress": 
{"addressLine1": "11 Commercial Avenue Sabo",
"addressLine2": "Yaba",
"city": "Lagos",
"district": "Lagos",
"province": "Lagos",
"zip": "",
"country": "NG",
"name": "Test Booking",
"firstName": "Test",
"lastName": "Booking",
"mobilePhoneNumber": "+2348021234567"
},
"billingAddress": 
{"addressLine1": "11 Commercial Avenue Sabo",
"addressLine2": "Yaba",
"city": "Lagos",
"district": "Lagos",
"province": "Lagos",
"zip": "",
"country": "NG",
"name": "Test Booking",
"firstName": "Test",
"lastName": "Booking",
"mobilePhoneNumber": "+2348021234567"
},
"additionalData": "{value1: value 1, value2: value 2}"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"purchaseId": "AAEAAADoKU7Uu5tJ9YDGV0bgjb4-siGzk4ackv3oao8qsZH3F1SidiKU",
"status": "PENDING",
"links": 
[
{"href": "https://api-jumiapay.jumia.com/checkout/AAEAAADoKU7Uu5tJ9YDGV0bgjb4-siGzk4ackv3oao8qsZH3F1SidiKU",
"method": "GET"
}
],
"jpay_trace_id": "42a20463bbec1f35e4c85139691bfc8f"
}

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.co.ke/merchant/transaction-events

Production Url

https://api-pay.jumia.co.ke/merchant/transaction-events

Request samples

Payload
curl
java
php
go

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": 
[
{"creationDateTime": "2018-04-04T08:59:03Z",
"transactionType": "Purchase",
"newStatus": "Created",
"oldStatus": null,
"transactionId": "AAEAAADpDFehqbrgASaL1jF9DYX6z4t9_bo3Sdb3adFUmCDS_Og3vBc4",
"merchantReferenceId": "1522832343",
"shopConfigurationId": "AAEAAADpDFe_Y8MgoKso3ZVQpqDmASHi3Qv8cdgYMrE-rhBQub5I2fKc",
"paymentInstrumentType": null,
"paymentMethod": null
},
{"creationDateTime": "2018-04-04T08:59:32Z",
"transactionType": "Purchase",
"newStatus": "Confirmed",
"oldStatus": "Created",
"transactionId": "AAEAAADpDFehqbrgASaL1jF9DYX6z4t9_bo3Sdb3adFUmCDS_Og3vBc4",
"merchantReferenceId": "1522832343",
"shopConfigurationId": "AAEAAADpDFe_Y8MgoKso3ZVQpqDmASHi3Qv8cdgYMrE-rhBQub5I2fKc",
"paymentInstrumentType": "BankAccount",
"paymentMethod": "bankTransfer"
},
{"creationDateTime": "2018-04-04T08:59:32Z",
"transactionType": "Purchase",
"newStatus": "Committed",
"oldStatus": "Confirmed",
"transactionId": "AAEAAADpDFehqbrgASaL1jF9DYX6z4t9_bo3Sdb3adFUmCDS_Og3vBc4",
"merchantReferenceId": "1522832343",
"shopConfigurationId": "AAEAAADpDFe_Y8MgoKso3ZVQpqDmASHi3Qv8cdgYMrE-rhBQub5I2fKc",
"paymentInstrumentType": "BankAccount",
"paymentMethod": "bankTransfer"
},
{"creationDateTime": "2018-04-04T09:00:44Z",
"transactionType": "Purchase",
"newStatus": "Completed",
"oldStatus": "Committed",
"transactionId": "AAEAAADpDFehqbrgASaL1jF9DYX6z4t9_bo3Sdb3adFUmCDS_Og3vBc4",
"merchantReferenceId": "1522832343",
"shopConfigurationId": "AAEAAADpDFe_Y8MgoKso3ZVQpqDmASHi3Qv8cdgYMrE-rhBQub5I2fKc",
"paymentInstrumentType": "BankAccount",
"paymentMethod": "bankTransfer"
}
]
}

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.co.ke/merchant/cancel

Production Url

https://api-pay.jumia.co.ke/merchant/cancel

Request samples

Payload
curl
java
php
go

Content type

application/json

Copy

Expand all Collapse all


{"shopConfig": "YOUR_SHOP_KEY",
"purchaseId": "PURCHASE_ID"
}

Response samples

Content type

application/json

Example

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.co.ke/merchant/refund

Production Url

https://api-pay.jumia.co.ke/merchant/refund

Request samples

Payload
curl
java
php
go

Content type

application/json

Example

Copy

Expand all Collapse all


{"shopConfig": "YOUR_SHOP_KEY",
"refundAmount": 5,
"refundCurrency": "NGN",
"description": "Refund for order #9182",
"purchaseId": "AAEAAADpDFehqbrgASaL1jF9DYX6z4t9_bo3Sdb3adFUmCDS_Og3vBc4",